2. The DocBook tool bar

Toggle emphasisToggle emphasis[bold]Toggle literalConvert to plain textAdd linkSet IDDecrease nesting levelIncrease nesting levelChange list typeAdd listAdd paraAdd list itemAdd footnoteAdd noteAdd programlistingAdd imageAdd MathML equationAdd chapter or sectionAdd tableTable editor

The DocBook tool bar starts with a number of “text style” toggles. These toggles emulate the behavior of the Bold, Italic, Underline, etc, toggles found in the tool bars of almost all word-processors. More information about text style toggles in About “text style” toggles in XMLmind XML Editor - Online Help.

Figure 1. Toggles found at the beginning of the DocBook tool bar
Toggles found at the beginning of the DocBook tool bar

In the above screenshot, the caret is inside an emphasis element and the user clicked the arrow button next to a “italic text style” toggle.

Toggle emphasis

“Toggle” element emphasis. Next to this toggle is found an arrow button displaying a menu containing additional checkboxes for the following elements: firstterm, citetitle, replaceable, trademark, trademark[registered].

Toggle emphasis[bold]

“Toggle” element emphasis[bold]. Next to this toggle is found an arrow button displaying a menu containing additional checkboxes for the following elements: abbrev, guilabel, guibutton, guimenuitem, guisubmenu, guimenu, keycap, keysym.

Toggle literal

“Toggle” element literal. Next to this toggle is found an arrow button displaying a menu containing additional checkboxes for the following elements: filename, sgmltag[element], sgmltag[attribute], sgmltag[attvalue].

Change case

Displays a menu letting the user change the character case of selected text. If a single node is selected, this converts the character case of all the text contained in this node. If there is no selection of any kind, this converts the character case from caret position to end of word, then it moves the caret to the next word.

lowercase

All characters are converted to lowercase characters. Keyboard shortcut: Esc+l.

UPPERCASE

All characters are converted to uppercase characters. Keyboard shortcut: Esc+u.

Capitalize Each Word

First character of a word is converted to an uppercase character. The other characters are converted to lowercase characters. Keyboard shortcut: Esc+c.

Convert to plain text

Convert implicit or explicit selection to plain text.

Add link

Displays menu letting the user add a link to your document.

link[linkend] (DocBook 4: link)

Converts the selection, if any, to an “internal link”; simply inserts an empty “internal link” at caret position otherwise. An internal link is a link element having a linkend attribute.

link[href] (DocBook 4: ulink)

Converts the selection, if any, to an “external link”; simply inserts an empty “external link” at caret position otherwise. An external link is a link element having an xlink:href attribute (DocBook 4: an ulink element having an url attribute).

[Important]

In the context of a modular document (e.g. a book comprising chapters, each chapter being contained in its own file), do not create external links between modules (e.g. chapters). Instead create internal links between modules.

xref

Inserts an xref element at caret position.

olink

Converts the selection, if any, to an olink element (that is, a link between different DocBook documents); simply inserts an empty olink element at caret position otherwise.

Set ID

This button displays a menu having 2 entries: Set ID and List Anchors and Links.

The List Anchors and Links menu entry displays a dialog box letting the user search and select anchors (that is, any element having an ID) and links. Its Copy button copies selected ID or link target to the clipboard.

Figure 2. The "List Anchors and Links" dialog box
The "List Anchors and Links" dialog box
Decrease nesting level

Convert a paragraph to a list item and a list item to a paragraph, the new element having a lesser nesting level than the original one. This button automatically splits lists when needed to.

This is the inverse command of "Increase nesting level". More Information below.

Increase nesting level

Convert a paragraph to a list item and a list item to a paragraph, the new element having a greater nesting level than the original one. This button automatically creates lists or merges adjacent lists when needed to.

Note that the two above buttons strictly alternate between paragraphs and list items. This means that you'll often have to click a button twice in a row. For example, in order to create a nested list, first click anywhere inside a list item and then click "Increase nesting level" twice. First click converts the list item to a plain paragraph contained in the preceding list item. Second click converts this paragraph to the first item of a new nested list.

For the two above buttons to function, any of the following conditions should be met:

  • A sequence of list items must be explicitly selected.

  • A list must be explicitly selected. This is equivalent to selecting all its items.

  • A sequence of blocks starting with a paragraph must be explicitly selected.

  • A paragraph must be implicitly selected. In order to implicitly select a paragraph, suffice to click anywhere inside it. However if this paragraph is the first child of a list item, then it's the list item which is implicitly selected.

  • A list item must be implicitly selected. In order to implicitly select a list item, suffice to click anywhere inside it.

[Tip]

When a paragraph is to be converted to a new list using this "Increase nesting level" button, there is a quick and simple way to specify the kind of list to be created:

  • If the paragraph is empty, simply type "*", "-", "1.", "a.", "A.", "i.", "I.", optionally followed by space characters, in it.

  • If the paragraph is not empty, type "*", "-", "1.", "a.", "A.", "i.", "I.", followed by at least one space character, at the very beginning of it.

These “prefixes” are used to create respectively: itemizedlist, itemizedlist, orderedlist, orderedlist[loweralpha], orderedlist[upperalpha], orderedlist[lowerroman], orderedlist[upperroman], as if the "Change list type" menu below was automatically used.

Change list type

Displays a menu allowing the user to change the type of the current list.

Additional menu entry "Continue Numbering", which is rendered as a checkbox, sets the continuation attribute of an ordered list to continues when this attribute is absent and removes this attribute otherwise. Additional menu entry "Inherit Numbering", which is rendered as a checkbox, sets the inheritnum attribute of an ordered list to inherit when this attribute is absent and removes this attribute otherwise.

The list must be explicitly or implicitly selected. In order to implicitly select a list, suffice to click anywhere inside it.

[Note]Known problems

Except for the simplest cases, "Continue Numbering" is not correctly rendered in the styled view of the document. For example, "Continue Numbering" has no visual effect on orderedlist elements having an orderedlist ancestor.

The reason of this limitation is that the implementation of "Continue Numbering" leverages standard CSS counters. However, when you'll convert your document to other formats such as HTML, PDF, DOCX, etc, there are no such limitations and "Continue Numbering" should give you the expected results.

Add list

Displays a menu allowing the user to select a type of list (itemizedlist, orderedlist, variablelist). The chosen list is added after node selection or after caret at a location where it is valid to do so.

Add para

Add a para element after node selection or after caret at a location where it is valid to do so.

Add list item

Add a listitem or varlistitem element after current list item. For this command to work, suffice to click anywhere inside an itemizedlist, orderedlist or variablelist element.

Add footnote

Displays a menu allowing the user to insert a footnote or a reference to a footnote (footnoteref) at caret position.

If a reference to a footnote is already selected, the footnoteref menu entry lets the user choose the ID of the footnote to be referenced.

Add note

Displays a menu allowing the user to add different kinds of admonitions after node selection or after caret at a location where it is valid to do so.

Add programlisting

Displays a menu allowing the user to add different kinds of elements containing preformatted text after node selection or after caret at a location where it is valid to do so.

Menu entry "Normalize Whitespace" normalizes whitespace in implicitly or explicitly selected program listing. Normalizing whitespace means: expanding tab characters to a number of space characters and removing the space characters which are common to the beginning of all text lines (that is, removing the superfluous “indentation” in the program listing, if any).

Add image

Displays a menu letting the user add different kinds of images and figures after node selection or after caret at a location where it is valid to do so.

[Note]Adding an image map to your document

The following menu items allow to add the equivalent of an HTML image map to your DocBook documents.

mediaobject(callout)

Add an image map containing internal links typically pointing to the calloutlist element found at the end of the inserted imageobjectco element. See also command "Link callouts".

mediaobject(imagemap) (DocBook V5+ only)

Add an image map containing external links typically pointing to Web pages.

Once any of the above menu items has been used, right-click anywhere inside the newly inserted imageobjectco element and select "Edit Image Map" from the contextual popup menu to display an image map editor. This image map editor allows to add “hot areas” to your image. More information in Section 17, “The "Edit Image Map" dialog box” in XMLmind XML Editor - Online Help.

Add MathML equation (DocBook V5+ only)

Displays a menu letting the user add various kinds of MathML equations after node selection or after caret at a location where it is valid to do so.

Add media object

This toolbar button is present only when a DocBook v5.1+ document is opened. Displays a menu containing the following items:

inlinemediaobject(audio)

Inserts an inlinemediaobject containing an audioobject at caret position.

inlinemediaobject(video)

Inserts an inlinemediaobject containing an videobject at caret position.

mediaobject(audio)

Adds a mediaobject containing an audioobject after node selection or after caret at a location where it is valid to do so.

mediaobject(video)

Adds a mediaobject containing an videoobject after node selection or after caret at a location where it is valid to do so.

More information in Section 16, “The media player dialog box” in XMLmind XML Editor - Online Help.

[Tip]Do not forget to select the DocBook XSL stylesheets generating XHTML 5 rather than plain HTML

If your document contains audio and video elements, do not forget to select the DocBook XSL stylesheets generating XHTML 5 prior to using DocBookConvert DocumentConvert to HTML. This setting is done once for all using OptionsCustomize ConfigurationCustomize Document Conversion Stylesheets in XMLmind XML Editor - Online Help.

Add section

Displays a menu allowing the user to add chapter or section elements after node selection or after caret at a location where it is valid to do so.

Add table

Displays a menu allowing the user to add different kinds of tables after node selection or after caret at a location where it is valid to do so.

Table editor

See Section 2.1, “Table editor”.

2.1. Table editor

The following table editing commands fully support CALS tables as well as HTML tables. Most table editing commands can be repeated by using EditRepeat (Ctrl+A).

Note that using this table editor, or simply saving a document, or checking a document for validity, guarantees that the cols attribute of a tgroup is up to date. That is, you may forget about the cols attribute, XMLmind XML Editor will always compute it for you.

ButtonMenu itemDescription

Table column

For a command in this menu to work, click anywhere inside a cell (or explicitly select a cell or an element having a cell ancestor).

Insert BeforeInsert a column before column containing specified cell.
Insert AfterInsert a column after column containing specified cell.
CutCut to the clipboard the column containing specified cell.
CopyCopy to the clipboard the column containing specified cell.
Paste BeforePaste copied or cut column before column containing specified cell.
Paste AfterPaste copied or cut column after column containing specified cell.
DeleteDelete the column containing specified cell.
Sort Rows

Sort all the rows of the table according to the string values of the cells of the “selected column”. (The “selected column” is the column containing specified cell.)

A dialog box is displayed allowing to specify the following sort options:

Order

Dictionary is the language-specific alphabetical order. Example: (Charles, best, Albert) is sorted as (Albert, best, Charles).

Numeric. The string value of a cell is expected to start with a number. Example: (+15.0%, 1.50%, -20%) is sorted as (-20%, 1.50%, +15.0%).

Lexicographic is the order of Unicode characters. Example: (Charles, best, Albert) is sorted as (Albert, Charles, best).

Dictionary and Numeric orders will cause this menu item to fail, unless the language of the table can be determined (i.e. lookup for the lang attribute).

Direction

Ascending means: A to Z, low to high. Descending means: Z to A, high to low.

Note that:

  • Header/footer rows (i.e. thead) are never sorted.

  • The contents of row groups (i.e. tbody) are sorted separately.

Table row

For a command in this menu to work, click anywhere inside a cell (or explicitly select a cell or an element having a cell ancestor) or explicitly select a row.

Insert BeforeFor

Insert a row before row containing specified cell.

[Note]

Note that row editing commands are enabled, not only by implicitly or explicitly selecting a table cell or any of its descendants, but also by explicitly selecting a table row.

Insert AfterInsert a row before row containing specified cell.
CutCut to the clipboard the row containing specified cell.
CopyCopy to the clipboard the row containing specified cell.
Paste BeforePaste copied or cut row before row containing specified cell.
Paste AfterPaste copied or cut row after row containing specified cell.
DeleteDelete the row containing specified cell.

Table cell

For a command in this menu to work, click anywhere inside a cell (or explicitly select a cell or an element having a cell ancestor).

Increment Column SpanIncrement the number of columns spanned by specified cell.
Decrement Column SpanDecrement the number of columns spanned by specified cell.
Increment Row SpanIncrement the number of rows spanned by specified cell.
Decrement Row SpanDecrement the number of rows spanned by specified cell.
Set Color

Displays a dialog box allowing to give a background color to specified cell.

[Note]

Unlike the other entries of this menu, this entry allows to give a background color, not only to specified cell, but also to one or more of any of the following explicitly selected elements: row, entry, tr, td, th.