1. Getting started with XMLmind XML Editor

Note

Everything explained here applies not only to DocBook, but also to all the other document types (XHTML, DITA, your custom schema, etc) supported by XMLmind XML Editor.

Creating a document

Use FileNew, select DocBook v5+|Chapter, then click OK.

Figure 1. A newly created chapter

A newly created chapter

The text you see, Chapter 1, 1, etc, is automatically generated and cannot be modified. The square patterns you see are text placeholders.

Type the title of your chapter in the first placeholder. Click on (or tab to) second placeholder and type the title of the first section. Do the same for the first paragraph of the first section.

How do you know where you are? Answer: always keep an eye at the node path bar.

Figure 2. The node path bar

The node path bar

The node path bar shown above indicates that the caret[1] is located inside a text node contained in a para element, itself contained in a section element, itself contained in a chapter element.

The text selection

Select some text by dragging the mouse over it, as you would do it in any text editor.

Figure 3. The text selection

The text selection

You can now convert this text to an emphasis element. For that, select the emphasis item from the menu of the toolbar button shown below.

Figure 4. The "Convert to emphasis" toolbar button

The "Convert to emphasis" toolbar button

You'll not find all the elements you want in this menu. For example, you'll not find citetitle or uri. In the general case, you'll have to use the EditConvert (Ctrl+T)[2] command to convert the selection. More on this command later.

The node selection

The implicit element selection

Let's suppose you want to add a programlisting element after the para element. Click anywhere inside the para element, except inside its emphasis child element. Even if you don't see anything special about it, this para is now implicitly selected. This means that all the commands you may invoke will use this para as their subject.

Use EditInsert After (Ctrl+J). Doing this activate the Edit tool. Type the first few letters of the name of the element you want to insert, then press Enter.

Figure 5. The Edit tool

The Edit tool

A programlisting element has been inserted after the para element. The caret is inside it. You can type some text in it right away.

Note that you have used command Insert After and not command Insert.

Table 1.  Edit tool commands

CommandShortcut[2]Description
ReplaceCtrl+R (R like Replace)

Replace the node selection by a newly created element.

Example: you want to replace the title child element of a section by the more comprehensive info element. You cannot delete the title child element because the content model of a section specifies that a section must start with a title or an info. However you can replace the title by an info.

Insert BeforeCtrl+H (I like Insert; H is before I)

Insert a newly created element before the node selection.

InsertCtrl+I (I like Insert)

Insert a newly created element at caret position.

Insert AfterCtrl+J (I like Insert; J is after I)

Insert a newly created element after the node selection.

ConvertCtrl+T (T like Transform)

If a single element is selected, convert this element to another element which has a compatible content. Example: convert an itemizedlist to an orderedlist.

If multiple nodes are selected, wrap a newly created parent element around this nodes. Example: wrap a blockquote around several selected paras.

Convert [wrap]Ctrl+Shift+T

A variant of command Convert. Always wraps a newly created parent element around the selected nodes.

Example: a single para is selected. Convert allows to convert it to a simpara or a programlisting. Convert [wrap] allows to wrap a blockquote around it.


The explicit node selection

Let's suppose that you want now to insert a second section after the first one. If the programlisting is implicitly selected, using Insert After, you'll be able to insert a subsection after it, but this is not what you want to do. If you click inside the para to implicitly select it and use Insert After, the Edit tool will not suggest section at all.

You need to explicitly select the first section in order to be able to insert a second section after it. There are many ways to do that.

Note that unlike the implicitly selected element, explicitly selected nodes have a red box drawn around them.

Figure 6. Explicitly selected section

Explicitly selected section

Selecting multiple nodes

A number of commands, Convert, Copy, Cut, Paste, Delete, etc, can be applied to multiple sibling[3] nodes.

The node selection can be extended to preceding sibling using SelectExtend Selection to Preceding Sibling (Esc ) and to following sibling using SelectExtend Selection to Following Sibling (Esc ). All the child nodes of an element can be selected using SelectSelect All Children (Esc ) .

Alternatively, you can extend the node selection using the mouse by clicking elsewhere (in the direction you want to extend the selection) while holding down the Ctrl and Shift keys.

Other commonly used commands

Specifying element attributes

Implicitly or explicitly select an element and use the Attributes tool to add or modify one or more of its attributes. For example, select the chapter root element, click in the cell containing the value of its status attribute (found in Value, the right column of the attribute table), type draft and then press Enter.

Figure 11. The Attributes tool

The Attributes tool

However, in most case, you'll want to use the small form found at the top of the attribute table. Example: give an ID to the first section:

  1. Select the section.

  2. Press ToolsEdit Attribute (Ctrl+E). This activates the Attributes tool.

  3. Type in the first text field (attribute name) the first few letters of the name of the attribute you want to add or modify. Example: type "xml:id".

  4. Press Enter to select the name and move the keyboard focus to the second text field (attribute value).

  5. Type the value of the attribute. Example: type "introduction".

  6. Press Enter to apply the change and move the keyboard focus to the document view. After that, you can resume the normal editing of your document.

Composing a modular document

Let's suppose you are authoring a book but want to edit its chapters separately (because coworkers are working on other chapters of the same book or simply because working on small documents is more convenient). How to assemble the separate chapters to form the book?

  1. Open the document containing the chapter in XMLmind XML Editor.

  2. Use FileNew, select DocBook v5+|Book, then click OK. This will create the book master document. Now you need to include your chapter document module in the master document.

  3. Switch to the document view containing the chapter by clicking on its tab.

  4. Select the chapter root element and press EditReferenceCopy as Reference (Ctrl+Shift+C).

    Command Copy as Reference allows to copy to the clipboard a reference to the root element of a document or to any element having an ID.

  5. Switch back to the document view containing the book by clicking on its tab.

  6. Select the first, empty, chapter of the newly created book.

  7. Use EditPaste(Ctrl+V) to replace this empty chapter by a reference to the chapter contained in the separate document.

Figure 12. A modular book including a chapter found in a separate document

A modular book including a chapter found in a separate document

Notice how the chapter included in the book is displayed. It has a dimmed blue-gray background, which means that it cannot be edited from within the book document[4].

If you open the modular book and want to edit one of its chapter modules, click anywhere in an included chapter and then use EditReferenceEdit Referenced Document (Ctrl+Shift+E). This will switch you to the (editable) document view containing the chapter. From here, you can switch back to the master document view by using EditReferenceEdit Referencing Document (Ctrl+Shift+B).



[1] The caret is also called the insertion cursor.

[2] On the Mac, use the Command key instead of the Ctrl key.

[3] Nodes having the same parent element.

[4] The contents of the included chapter cannot be directly modified from within the master document view. However you can freely modify the contents of the book. For example, you can remove the chapter reference from the book or you can cut and paste it elsewhere in the book.