Chapter 2. Getting started with XMLmind XML Editor
Prev | Part I. Getting started | Next

## Chapter 2. 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 File → New, select DocBook v5+|Chapter, then click OK.

Figure 2.1. 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.2. The node path bar

The node path bar shown above indicates that the caret[3] 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 2.3. 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 2.4. 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 Edit → Convert (Ctrl+T)[4] 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 Edit → Insert After (Ctrl+J). Doing this activates the Edit tool. Type the first few letters of the name of the element you want to insert, then press Enter.

Figure 2.5. 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 2.1. Edit tool commands

Command | Shortcut[4] | Description
--- | --- | ---
Replace | Ctrl+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 Before | Ctrl+H (I like Insert; H is before I) | Insert a newly created element before the node selection.
Insert | Ctrl+I (I like Insert) | Insert a newly created element at caret position[a].
Insert After | Ctrl+J (I like Insert; J is after I) | Insert a newly created element after the node selection.
Convert | Ctrl+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 `para`s.
Convert [wrap] | Ctrl+Shift+T | A variant of command Convert. It 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.
[a] If the element containing the caret is not explicitly selected. If an element is explicitly selected, this command inserts a newly created child element after last child element.

#### 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. And 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.

- Repeatedly press Ctrl+↑, while keeping an eye on the node path bar, until you select the desired ancestor element. (Press Ctrl+↓ if you have gone too far.)

- Repeatedly click inside an element while holding the Ctrl key down, without moving the mouse, until you select the desired ancestor element.

- Directly click on the label of the desired element in the node path bar.

- Click on the content generated for the element you want to select: the section number in the case of the `title` of a `section`, the bullet in the case of a `listitem`, etc.

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

Figure 2.6. Explicitly selected `section`

#### Selecting multiple nodes

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

The node selection can be extended to preceding sibling using Select → Extend Selection to Preceding Sibling (Esc ←) and to following sibling using Select → Extend Selection to Following Sibling (Esc →). All the child nodes of an element can be selected using Select → Select 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

- We have already seen that the DocBook toolbar contains a number of buttons which invoke the Convert command. Most the other buttons (Add para, Add table, Add image, etc) invoke the add command.

  Figure 2.7. The "Add table" toolbar button

  The add command is very different from the three Insert commands. The add command will find out, where after the caret position, a given element may be inserted. If an insertion position is found, the add command will then insert this given element.

  For example, let's suppose that you want to insert an `itemizedlist` after the first `para` of the first `section`. Click anywhere inside the `para`, really anywhere, including inside any of its descendant elements (like its `emphasis` child element), and press the Add itemizedlist button of the DocBook toolbar.

- The Edit → Copy (Ctrl+C), Edit → Cut (Ctrl+X), Edit → Paste (Ctrl+V), Edit → Delete (Backspace, Del or Ctrl+K) commands work as expected for both the node and the text selection.

  Note that in addition to the Paste command (which replaces the explicit selection by the contents of the clipboard or which inserts the contents of the clipboard at caret position when there is no explicit selection), you also have Edit → Paste Before (Ctrl+U) and Edit → Paste After (Ctrl+W) commands.

  Also notice that the current content of the clipboard is displayed at the bottom/left of the main window.

  Figure 2.8. The Clipboard tool

- Pressing Ctrl+Enter anywhere inside a list item (whatever its element type) or a paragraph allows to quickly add the same element after it.

- Pressing Enter anywhere inside a paragraph splits this paragraph in two parts at caret position. This is the most common form of command Edit → Split (Esc Enter).

- Pressing Backspace at the beginning of a paragraph preceded by an element of the same type, merges the two elements. Same behavior if you press Del at the end of paragraph followed by an element of the same type. These are the most common forms of command Edit → Join (Esc Backspace).

- Pressing Ins allows to quickly add a text node. This is mainly useful in the following situation: you are typing some text in a `para`. You insert a `literal` at caret position and continue typing some text inside the newly inserted `literal`.

  Figure 2.9. Before pressing the Ins key

  Now you want to resume typing text inside the `para`. You press Ins to quickly add a text node after the `literal` and then type text in the newly inserted text node.

  Figure 2.10. After pressing the Ins key

- Press Ctrl+SPACE to insert a non-breaking space at caret position.

### 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 2.11. 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 Tools → Edit 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 back 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 `chapter`s separately (because coworkers are working on other `chapter`s of the same `book` or simply because working on small documents is more convenient). How to assemble the separate `chapter`s to form the `book`?

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

2. Use File → New, 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 Edit → Reference → Copy 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 Edit → Paste(Ctrl+V) to replace this empty `chapter` by a reference to the `chapter` contained in the separate document.

Figure 2.12. 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[6].

If you open the modular `book` and want to edit one of its `chapter` modules, click anywhere in an included `chapter` and then use Edit → Reference → Edit 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 Edit → Reference → Edit Referencing Document (Ctrl+Shift+B).

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

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

[5] Nodes having the same parent element.

[6] 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`.

Prev | Up | Next
3. Acknowledgments | Home | Part II. Reference