loading table of contents...

2.3.3.5. Inclusion-nodes

Inclusion-nodes allow you to define inclusions on the content-structure level. Another type of inclusions are inline-inclusions. See "Inclusions" in the tutorial for more information on the difference of structural- and inline-inclusions.
A structural inclusion allows you to insert a node at a position within the content-tree, although the actual physical position of the node within the content-tree is somewhere else. For example, assume you have created a section "Installation instructions" in the reference manual part of your documentation. Now, you could want to insert the installation instructions also in the tutorial part of your documentation, but without removing the installation instruction from the reference manual. Furthermore you do not want to create a copy of the installation instructions, because if you have to change the instructions you would have to update two nodes. A good solution for this problem is to insert a section-inclusion node within the tutorial at the position where the installation instructions section shall appear. This section-inclusion node can then reference the "Installation instructions" section within your reference documentation. Following illustration depicts this solution:
illustrate_struct_inclusion

Figure 2.3.9. Structural inclusion example

Be aware that with using structural inclusion, the same node can appear at different positions within the content tree-structure, but it is not allowed to have the same node more than once in an exported publication. The reason for this is, that a node could itself contain objects (e.g. images, tables, sub-sections, ...) that have an alias name or ID value assigned. Therefore, if a content-node appears more than once in a publication, the publication could contain objects with the same identifier at different locations. If such an object would be referenced, the target of the reference would be ambiguous. In the example given above, this would occur if a publication would be exported that contains the reference manual part as well as the tutorial part. In this case, if a sub-section of the "Installation instructions" section is referenced, it is no longer clear whether the sub-section within the reference manual or the sub-section within the tutorial shall be referenced.
Depending on the type of the included node, two types of structural inclusions exist: section- and content-inclusions. A section-inclusion is an inclusion-node that references a section-node. A content-inclusion is an inclusion-node that references a content-node.
A section-inclusion can be inserted at all positions where a section could be inserted. A content-inclusion can be inserted at all positions where a content-node could be inserted.
An inclusion-node can have its own title, which will (if existent) overwrite the title of the referenced node. Given the example above, you could e.g. include the "Installation instructions" section of your reference documentation in your tutorial with the changed title "First step: Installation".
Furthermore, an inclusion-node can have an applicability expression assigned, i.e. depending of the filter setting of your publication and output configuration, an inclusion-node could be filtered out.
Detailed information on how to insert an inclusion-node is given in Section 2.3.4.1, “Inserting and editing nodes”