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:
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:
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: EditReference Replace by Reference, Edit Reference Insert Reference Before, Edit Reference Insert Reference After.