The Include tool is hidden by default. To display it, you need to use Options→Preferences, General|Features section and check "Enable the Include tool".

Inserting boilerplate content

We have explained in the previous lesson, Creating a modular document, that Copy As Reference/Paste may be used to to include in document B some content found in document A.

This feature is often used to include “boilerplate” content in a document: company name, product name, copyright statement, etc. By working this way, if one day, the value of a boilerplate text changes, you'll not have to manually update all the documents making use of this value.

Such boilerplate content is typically created in a document of its own (e.g. boilerplate.xml), so it can be easily shared between different documents and between different authors.

Remember that Copy As Reference works only if the node selection is a single element having an ID. So what to do if you just want to include some text, for example, the name of your product? In such case, you'll have to wrap this text in an element. For that, choose an element which has no specific semantics. This element is: phrase for DocBook, ph or text for DITA and span for XHTML. Example:

<phrase xml:id="awb">ACME Widget Builder</phrase>

The problem of boilerplate content appears to be solved:

1. Create your boilerplate.xml file. This is done once for all.
2. Use Copy As Reference ( Ctrl+Shift-C) to copy a reference from boilerplate.xml.
3. Use Paste (Ctrl-V) to paste this reference in the document you are authoring.

However if you repeat steps 2 and 3 one hundred times a day, you'll quickly find very tedious switching from one document to the other. Fortunately, the Include tool has been specially designed to handle the special case of boilerplate content.

Let's suppose you want to include the name of your product in SampleChapter.xml, here's what you'll have to do:

1. Use the button to specify once and for all the filename or URL of the document containing your boilerplate content . In the above screenshot, this document is boilerplate.xml.
2. Use Ctrl+Shift-I ( Edit→Reference→Insert Reference) to display the Include tool.
3. Type the ID of the element for which you want to insert a reference. Typing the first few letters is generally sufficient as the Include text field supports auto-completion.
4. Press Enter to insert the reference at caret position.

Note that the Include tool is not limited to inserting phrase references at the caret position. You can use it to insert all sorts of boilerplate content: paragraphs, tables, admonitions, etc. Therefore it also implements the following commands: Edit→Reference→Replace by Reference, Edit→Reference→Insert Reference Before, Edit→Reference→Insert Reference After.

Watch the screencast