| # XMLmind XML Editor - Online Help |

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