6.2. Include tool
Prev | 6. Tools | Next

### 6.2. Include tool

### Note

The Include tool is hidden by default. You need to enable it by checking "Enable the Include Tool" in Options → Preferences, Features section.

#### 6.2.1. Working with ``XML variables''

The Include tool is designed to make it quick and easy inserting ``XML variables'' in your documents.

XML variables are often-used contents: product names, product versions, copyright information, addresses, phone numbers, etc, you need to reference in almost all your documents.

XML variables are best modelled by elements having a weak semantic and which may be inserted almost anywhere in a document. In the case of XHTML, this element is `span`. In the case of DocBook, this element is `phrase`.

XML variables are generally collected in a single, centralized, ``pseudo-document'', created for this sole purpose.

You'll insert references to XML variables, and not copies, in your actual documents.

By working this way, if one day, the value of an ``XML variable'' changes, you don't need to manually update all the documents making use of this value.

Unlike the Copy As Reference/Paste (Ctrl+Shift+C/Ctrl+V) approach described in the tutorial, which is a generic way to compose any kind of modular documents, the Include tool is specialized in XML variables. For example, do not attempt to use this tool to insert in a modular book the references to its chapters.

#### 6.2.2. Using the Include tool

First of all, specify the filename or URL of the document containing all your XML variables.

This is done once for all. Up to 5 documents may be added to the list displayed by the "Contained in document" combobox. Specified documents are remembered in order to be reused in subsequent editing sessions.

- Use the button to add a filename or URL to the list displayed by the "Contained in document" combobox.

- Use the "Contained in document" combobox to select the document containing your XML variables.

- Use the button to remove currently selected document from this list.

  If you attempt to add an invalid (non-XML or non well-formed) or useless (contains no elements having an ID) document to the list, you'll be informed of this fact just once and the document will nevertheless be added to the list. In such case you'll have to use the button to explicitly remove it from the list.

After that, the tool works in two steps:

1. Click on one of the following buttons:

   Replace by Reference

     (See Edit → Reference → Replace by Reference for a complete description of the command.)

   Insert Reference Before

     (See Edit → Reference → Insert Reference Before for a complete description of the command.)

   Insert Reference

     (See Edit → Reference → Insert Reference for a complete description of the command.)

   Insert Reference After

     (See Edit → Reference → Insert Reference After for a complete description of the command.)

   This first action just fills the list below these buttons with all the allowed arguments (element ``identifiers'' and/or "`-`") for the selected command.

   This list will only show elements:

   - directly contained (that is, not themselves included) in the document selected by the "Contained in document" combobox,

   - AND which may be copied as reference (generally this means that such element has an ID),

   - AND allowed by the schema given the chosen command and the current selection.

   The root element, when listed, is specified as "-".

2. Choose the identifier of the element (or "-") from the list or type it in the text field. It is this second action which actually triggers the command.

Procedure for specifying an argument for one of the commands described above:

- The identifier of the element (or "`-`") is selected by clicking on it in the list. A single click is sufficient.

- Alternatively, the identifier of the element (or "`-`") can be specified using the text field above the list:

  1. Type the identifier of the element (or "`-`") in the field.

  2. Press Enter or click on the OK button.

  ### Tip

  This text field supports auto-completion.

  The auto-completion feature can be configured using the Options dialog box.

- Type Esc or click on the Cancel button to cancel current command and to clear the form.

Prev | Up | Next
6.1. Edit tool | Home | 6.3. Attributes tool