Chapter 2. Tutorial: basics
Prev |  | Next

## Chapter 2. Tutorial: basics

### What you'll not learn by reading this tutorial

This tutorial will not teach you how to use most nifty features of XXE:

- how to use the Ins key or the Enter key to quickly insert text nodes and elements,

- how to change an image displayed in the document view by dragging and dropping a graphics file onto it,

- how to quickly insert or move columns by using the table editor,

- etc.

Most of these smart tricks are listed in chapter Being productive with XXE. Other features are specific to the type of the document being edited (XHTML, DocBook, DITA, etc) and therefore, are documented in the online help which comes with the XXE configuration associated to the document type.

No, this tutorial will just teach you the most basic way to do things. On the other hand, what you'll learn here will work for any type of document, and not only for XHTML.

This tutorial assumes that the reader has a minimal knowledge of XML (that is, the reader knows what is an element, an attribute, etc) and a minimal knowledge of HTML or XHTML (that is, the reader knows that `p` is the tag for a paragraph, that `ul` is a list, etc).

It is recommended that, using XXE, the reader repeats each action described in this tutorial. (On Mac, use the Command key instead of the Control key, except for Ctrl-Tab and Ctrl-Space.)

## 1. Starting XXE

- If you have installed an auto-installable Windows distribution (`xxe-perso-3_6_1-setup.exe`), XXE can be started by double-clicking on the icon of `xxe.exe` or by using the "XMLmind XML Editor" shortcut added to the Start menu.

  If you have installed a zipped distribution, XXE can be started by typing `xxe` (or `xxe.bat`) from the command prompt, optionally followed by the name of one or several XML documents.

  Example:

      C> xxe C:\xxe-perso-3_6_1\doc\user\userguide.xml

- On Unix, XXE can be started by typing `xxe` from an xterm, optionally followed by the name of one or several XML documents.

  Example:

      $ xxe &

## 2. Creating a new document

Use File|New and choose a document template from the following dialog box.

Figure 2.1. The File|New dialog box

Alternatively, use File|Open as Template and choose an existing XML document. A copy of this existing XML document will be emptied to serve as the skeleton of your new document. For example, use this command to select `userguide.xml` (User's Guide in DocBook format) file contained in the ``doc/user`/` subdirectory of your XXE distribution.

In this tutorial, we have chosen to create a XHTML page (strict DTD).

The newly created document (`Untitled.html`) looks like this:

The ``blobs'' are placeholders for text. Click on the first placeholder and type the title of your XHTML page. Click on the second placeholder and type a few words.

Click again anywhere on the title and then anywhere in the first paragraph. You'll notice that, at the top of the window, just below the tool bar icons, the node path bar changes its label.

The node path bar shows where is the caret (also called insertion cursor).

The node path bar does so by displaying the name of the node (anonymous text node `#text`) containing the caret preceded by the name of each of its ancestors elements in the containment hierarchy (element `p` contained in element `body` contained in element `html`).

## 3. Inserting elements

In this section, we'll get familiar with the following commands:

1. Insert before element

2. Insert inside element, at caret location

3. Insert after element

These commands are accessible using the Edit menu bar menu, using the Edit tool ``tab'' or using keyboard shortcuts, but in this tutorial we'll limit ourselves to using the Edit popup menu. Therefore the notation Edit|Insert means "click anywhere in the document view using the right mouse button and select menu item Insert in the Edit popup menu".

Figure 2.2. The Edit popup menu

Click anywhere inside the paragraph and execute Edit|Insert Before. The keyboard focus is given to the Edit tool. This pane now lists all the elements you can insert before a `p` and therefore, is ready to use.

Figure 2.3. The Edit tool listing all elements you can insert before a `p`

Select `h1` from the list (a single click on the list item is sufficient). The newly inserted element has a red border around it. Do not care about that, just type the text of the heading and the red border will go away.

Click inside the `p` before a word and execute Edit|Insert, the same element chooser dialog pops up listing all the inline elements you can insert inside a `p`. Select `strong` from the list and type a few words in bold font.

Your document should look like this:

This time, use Edit|Insert After and add a `ul` (unordered list) after the `p`. Type the text of the first list item (`li`).

If you are in the `strong` element -- check it with the node path bar -- click in the `p` outside the bold words because inserting an `ul` inside a `p` after a `strong` is not allowed in XHTML.

Click to get rid of the red border, then using what you have learned, add two more `li`s: one before the first `li` you have created, the second after it.

## 4. Selecting elements

Editing commands are applied to the selection.

XXE supports three types of selection:

- The text selection, found in all text editors and word processors.

- The node selection, which can contain one or several nodes.

- The implicit element selection.

Some commands can be applied to any type of selection, for example: Edit|Convert. Other are more restrictive, for example: Edit|Insert Before can be applied to the implicit element selection or to an explicit single node selection.

### 4.1. The implicit element selection

The element containing the caret is implicitly selected. Therefore you can apply commands to it without making any special effort.

This is one of XXE nicest feature, even if it needs to be learned because it has no equivalent in the word processor world.

In the first section of this tutorial, you have already used the implicit element selection to insert an `h1` before the `p` and an `ul` after it.

### 4.2. The text selection

Selecting text in XXE is not different from selecting text in any text editor. Click in the middle of the `h1` and drag the mouse across the document until the middle of the second `li` is reached.

### 4.3. The node selection

#### 4.3.1. Most general method

Now we want to add a `pre` (preformatted text) after the `ul`.

We have learned that clicking inside the a `li` implicitly selects it therefore we know how to add a new `li` after this one but how to select its parent, the `ul`, to add a `pre` after it?

For that we need to use explicit element selection. Click inside any `li` and then click on word `ul` inside the node path bar.

This explicitly selects the corresponding node in the document view.

Note that explicitly selected nodes are drawn with a red border around them.

Alternatively, click inside any `li` and type Ctrl-Up 3 times: first time to select the `#text` node, second time to select the `li`, third time to select the `ul`.

Now that `ul` is selected, use Edit|Insert After to add a `pre` after it.

Type 2 lines of text in this `pre`. Do not be worried by the ``carriage return icon'' always displayed by XXE if the last character of a `#text` node is a newline character.

#### 4.3.2. Directly selecting a node

Clicking near some text moves the caret inside the text and no node is explicitly selected.

Instead of simply clicking, try to Ctrl-click on the first `p`. A `#text` node is explicitly selected and the node path bar tells you which one.

Selecting a `#text` node is rarely what you want to do. You'll often need to Ctrl-click again without moving the mouse. This will select to parent of the selected `#text`, that is, the `p`. Ctrl-clicking again without moving the mouse would select the parent of the `p` which is a `body` and so on. When doing a series of Ctrl-clicks, always look at the node path bar to know precisely where you are. Also, do not Ctrl-click several times too fast otherwise the editor will think you are double-clicking or triple-clicking and therefore, selecting elements that way would not work.

Click on the first `p` to cancel the selection because we are going to study another method to select it. Now try to Ctrl-click, not inside the text itself, but in the blank space at the right of the text of first `p`. Notice that one Ctrl-click is sufficient to directly select the whole `p`.

Similarly, you can directly select a node when a non-editable ``decor'' has been generated for it. For example, simply click on the bullet of a `li` to select it. This type of non-editable decor is very common, for example: the image displayed for a figure, the number of a section, the border of a table, a node icon or element name in the tree view, etc.

#### 4.3.3. Selecting a node range

What if you want to put first `p` and `ul` inside a `blockquote`? The answer is select both of them first and then use Edit|Convert (described below in this tutorial).

With XXE it is possible to select a node range, that is, adjacent children of the same parent element.

Select first `p` using any of the methods described above.

Then Ctrl+Shift-click anywhere on the `ul`.

Note that extending the node selection is easy because you do not have to be precise. The reason is that there is no ambiguity about what to select: a `#text` or a `li` is not a sibling of first `p`, only the `ul` is a sibling of first `p`.

Alternatively, you could have typed Esc then Right to extend node selection to the `ul`.

Now use Edit|Convert and choose `blockquote`.

## 5. Navigating through elements

### 5.1. Using Tab to go from a `#text` to the other, just like in a form

The Tab key may be used to move the caret from the current `#text` to the beginning of the next one. Shift-Tab moves the caret from the current `#text` to the beginning of the previous one.

Click on the `title` and use Tab and Shift-Tab to move the caret from one `#text` to the other.

What if you really want to insert a Tab character into a `pre` (or any element which allows Tab characters to be inserted in the text flow just as any ordinary character)? The answer is: type Ctrl-Tab instead of Tab.

### 5.2. XXE makes a difference between the end of a `#text` node and the beginning of the `#text` node next to it

The simplest way to move the caret is of course to use the Left or Right arrow keys.

Click on the first `p` to the left of the `strong` and press on the Right key to move the caret in the direction of the `strong`.

Just before reaching the `strong` element, you'll notice that pressing on the Right key has caused no perceptible caret movement. Then after this ``dead'' Right key, the caret seems to move as expected.

Go back to the left using the Left arrow and at the `p`/`strong` boundary, you'll notice a ``dead'' Left key then the caret seems to move as expected.

Note that on the `p`/`strong` boundary, the caret makes no visible movement but the node path bar displays different paths (`html`·`body`·`p`·`#text` and `html`·`body`·`p`·`strong`·`#text`).

Use menu command View|Add to add a low-level, hierarchical, view called the tree view, at left of the styled view.

Figure 2.4. Both tree and styled Views side by side

Repeat what you have done with the Right and Left arrow keys and you'll notice that with the tree view, there is a visible caret movement from the end of the `p`·`#text` to the beginning of the `strong`·`#text` and vice-versa.

Close the tree view by clicking anywhere inside it and by using View|Close.

This ``dead'' key behavior also occurs when using the Del and Backspace keys.

Click on the first `p` to the left of the `strong` and type on the Del key several times. Notice what happens on the `p`/`strong` boundary. Then use Edit|Undo as many times as needed to undo this typing.

Click inside the `strong` and type on the Backspace key several times. Notice what happens on the `p`/`strong` boundary. Then use Edit|Undo as many times as needed to undo this typing.

## 6. Copy, cut, paste, delete

### 6.1. Copy, cut, paste, delete applied to the text selection

The text selection is used not only to specify a range of characters but also a range of nodes and child elements contained in a common ancestor element.

When applied to the text selection, the Edit|Copy menu command copies all the characters and nodes in the specified range to the system clipboard. It is then possible to paste these characters and nodes in any other application including XXE itself.

Select the characters displayed in bold font from the first `p`, copy them to the clipboard using Edit|Copy, click on the `title` and paste the copied characters using the Edit|Paste.

After copying the text selection, you'll notice that, near the Clipboard Content button, the status bar displays `#text`: a piece of text is stored in the clipboard.

Note that if you have not been precise when selecting text, the status bar may display `strong` (you have copied the whole `strong` element to the clipboard) or it may display `[2]` (you have copied 2 nodes to the clipboard: the `strong` element and a piece of text next to it).

Edit|Cut and Edit|Delete basically work the same: they delete all the characters and nodes in the range specified by text selection. The only difference is that Edit|Cut copies the characters and nodes in the specified range to the clipboard.

Of course, elements and nodes are deleted only if the DTD or schema constraining the document allows to do so. In this is not the case, selected characters are removed from such elements and nodes and that's it.

### 6.2. Copy, cut, paste, delete applied to the node selection

The Copy, Cut, Paste, Delete commands can be applied to a node range or to the implicitly selected element.

Two more Paste commands are available: Paste before and Paste after. These commands can only be applied to a single explicitly selected node or to the implicitly selected element.

Select the first `li` (implicit selection is fine for that). Use the Edit|Cut to move it to the clipboard. Select the last `li`. Use the Edit|Paste After to paste the `li` stored in the clipboard after the last `li`.

After copying the first `li`, you'll notice that the status bar displays `li`: a list item element is stored in the clipboard.

Note that when the clipboard contains a node range, the status bar displays the number of nodes of the range. For example, copy all list items to the clipboard and you'll see:

## 7. Splitting and joining elements

### 7.1. Simple Split and Join

Click in the middle of the `strong` contained in the first `p`. Type Enter. The `p` is split in two parts, each part being a `p`, as expected in any word processor.

Now type Backspace at the beginning of the second part. The two parts are joined to form our original single paragraph.

Typing Del at the end of the first part would have given the same result.

This is also a handy method for inserting elements. Type Enter at the end of the `p`.

Type some text in the newly created paragraph. Type Enter at the beginning of newly created `p`. This creates another `p` before it.

Use Edit|Undo three times to undo the creation of last two paragraphs.

### 7.2. Split and Join generalized

The Split and Join commands bound to Enter, Backspace or Del keystrokes are very handy but they can only be applied to paragraphs.

What if we want to split the list in two parts in order to insert a paragraph before the second part?

Move the caret at the beginning of the last list item and explicitly select the whole list using the node path bar.

Now execute Edit|Split. This command splits the explicitly selected element at caret position, which gives us two adjacent lists.

The generalized form of Join is the inverse command of Split. Command Join joins explicitly selected element to its preceding sibling, an element of same type.

Note that the generalized form of Split and Join are the only commands that cannot be applied to the implicitly selected element.

Explicitly select the second `ul` and execute Edit|Join. The two adjacent lists are now joined to form our original single list.

Undo last Join because we really want to split the list in two parts.

- Add a `p` before the second `ul`, type some text in it.

- Copy text "List item #1" (as usual, by dragging the mouse and by pressing Ctrl-C) and paste it (by pressing Ctrl-V) in the empty last `li` of first `ul`.

- Add another `li` before the only `li` of second `ul`, for example by clicking in the `li`, using Edit|Copy and then using Edit|Paste Before.

- Change all the text of the two list items of the second `ul`, for example by selecting "List item #1" as usual and by typing a few words.

Our XHTML document now looks like this.

## 8. Replacing elements

The Edit|Replace command is equivalent to deleting the node selection or implicitly selected element and inserting a new element or `#text` which replaces the deleted nodes.

This command is useful because it is often not allowed to delete the selection: doing so would create an invalid document.

Select the `pre`. Insert a `table` after it.

table(head_column), ..., table(head_row_column) are preconfigured table templates. Most of the time, you'll choose one of these but for this exercise, we'll choose table which is the simplest table possible in XHTML.

The table is created with a single `tr` (row) containing a single `th` (a ``heading'' cell where text is displayed using a bold font). This is often what you want for the skeleton of `table` but not always.

This very simple table has no borders, even if the footprint of a cell is displayed using a very light gray. This would make the screenshots of this tutorial hard to read. Therefore we'll immediately add a border to this table.

Select the `table` (using the node path bar) if it is not already the case. The Attributes tool should be already displayed, otherwise click on the corresponding tab.

First row of the attribute table is for attribute `border`. Click inside the attribute value cell at the right of the attribute name cell containing `border`, type `1` and press Enter.

Now the table has a nice black border. (We'll learn how to use the Attributes tool later in this tutorial.)

Exercise:

1. Select the `th` contained in the `tr` (implicit selection is fine for that). Using Edit|Replace, replace it with a `td` (a plain cell).

2. Select this `td`. Use Edit|Insert After to add another `td` after it.

3. Using the node bar path, select the `tr` containing the two cells . Use Edit|Copy to copy it to clipboard.

4. Use Edit|Paste After to paste a copy of the `tr` after currently selected `tr`.

5. Type some text in each cell.

## 9. Converting elements

### 9.1. Convert applied to the text selection

Select a non-bold word in the first `p`.

Use the Edit|Convert to convert it to `em` (emphasis).

Remember that text selection is used not only to specify a range of characters but also a range of nodes and child elements contained in a common ancestor element. This feature is very useful when doing a conversion. For example: select text from word "`paragraph`" to word "`XMLmind`".

Use the Edit|Convert to convert it to `button`.

Use Edit|Undo to undo the last conversion.

### 9.2. Convert applied to the node selection

Converting a `#text` node rather than an equivalent text selection is often more convenient.

Select the `#text` node contained in the first cell of the table. Note that explicit node selection is needed to do that: implicit element selection selects the `td` not the `#text` inside it.

Used Edit|Convert to convert it to `em`.

Unlike Edit|Replace which creates an empty new element, Edit|Convert transfers the content of the selection to the new element which is the result of the conversion.

More precisely, in the case of the node selection:

- When several nodes or a single non-element node are selected, all these nodes are given a new parent element which is the result of the conversion.

  We have already seen two examples of this behavior. First one is when we ``wrapped'' a `p` and a `ul` into a `blockquote`. Second one is just above.

- When a single element is selected, all its children (but not its attributes) are transferred to the result of the conversion.

  What follows is an example of this second behavior. Here we want to ``morph'' single selected element which is an `ul` to an `ol`.

Select the first `ul`.

Used Edit|Convert to convert it to an `ol` (ordered list).

This operation is valid because the `ul` parent, a `body`, accepts `ul`s as well as `ol`s at this place and because the element content of this `ul` is ``compatible'' with an `ol`.

## 10. Editing element attributes

Use Tools|Edit Attribute (keyboard shortcut Ctrl-E) to edit the attributes of the selected element. This action displays and gives the keyboard focus to the Attributes tool. Alternatively, if this pane is already displayed, you can click inside it and use it right away.

Figure 2.5. The Attributes tool with the `rowspan` attribute of a `td` being edited

There are two methods for adding or changing the attributes of the (explicitly or implicitly) selected element:

1. Using the attribute form (the upper side of the Attributes tool).This should be the method of choice for persons who prefer to use the keyboard.

2. Using the attribute table (the lower side of the Attributes tool). This should be the method of choice for persons who prefer to use the mouse.

The ``minus'' button of the attribute form can be used to remove an attribute. Removing an attribute directly from the attribute table is possible too: simply right-click on the attribute row and use the displayed popup menu.

The content of the attribute table can be described as follows:

- All attributes set for the selected element are displayed by the table.

- All possible attributes for the selected element, even those not set, are also displayed by the table.

  Attributes which have not been set are displayed in gray. Attributes which have been set are displayed in black.

- Attributes are listed sorted in alphabetical order.

- The names of required attributes are displayed using a bold font.

- The names of fixed attributes are displayed using an italic font.

Exercise:

- Select second `td` in the `table`. Set its `align` attribute to `center`.

- Set its `rowspan` attribute to `2`.

- Set its `valign` attribute to `middle`.

- Add an extra `td` after it to make the `table` look more balanced.

### 10.1. Required attributes in newly created elements

It is important to remember that, by default, XXE automatically gives a placeholder value ("`???`") to required attributes of newly created elements. This means that you have to replace this placeholder value by the actual one as soon as the element has been created.

Add a `p` after the `table` using Edit|Insert After and insert an `img` in it using Edit|Insert.

The `img` has two required attributes `src` and `alt`. XXE has set those attributes to string `???`. Use the Attributes tool to give these attributes an actual value.

For this `img`, we used ``XXE_install_dir`/doc/user/tutorial/xxe.gif` and `XMLmind logo` for `alt` (directory ``XXE_install_dir`/doc/user/tutorial/`, generally `C:\Program Files\XMLmind_XML_Editor\doc\user\tutorial\`, contains all the files used in this tutorial) .

The useless `#text` node has been removed by explicitly selecting it and using Edit|Delete.

## 11. Checking document validity

You cannot check the validity of a document without an associated DTD, W3C XML Schema or RELAX NG schema. When editing a document not constrained by a grammar, XXE guarantees that what you'll create will be well-formed without making any special effort.

This section, like most of this tutorial, describes the behavior of XXE when editing documents constrained by a grammar.

Checking document validity is automatically performed each time you save your document.

Unless you use Edit|Force Deletion, XXE will never allow editing commands that would make the document structurally invalid (a document where some elements have invalid child elements or attribute names).

Therefore explicitly checking document validity is rarely needed. You may have to use the Tools|Check Validity command when:

1. You have loaded an invalid document and you are fixing it. After each editing command, you want to know if it is fixed now.

2. XXE creates elements where the value of required attributes, if any, is invalid: unless configured differently, the required attributes are given `???` as a placeholder value.

After explicitly or implicitly checking document validity, its validity status is displayed at the left of the status bar.

Figure 2.6. After forcing the deletion of all the items of a list, "Untitled.html" is structurally invalid.

The Validity tool ``tab'' displays validity error messages if any.

Figure 2.7. Validity error message displayed after forcing the deletion of all the items of a list.

The color of the message reflects the severity of the error. Clicking on the number of an error message selects the element where the validity error was found.

Prev |  | Next
Chapter 1. Install | Home | Chapter 3. Tutorial: creating a modular document