Inclusions (rst)

• only use .. include:: if the included matter appears > 1 time
• target the included matter with a label-type link target above the .. include:: directive (which doesn’t support the :name: option)
• name files for included matter with underscore (_) as the first character and locate in [source]/common/docproject/utilities
• at this time, thanks to indentation issues, using rst inclusion in commands is effectively infeasible

To include a unit of *.rst inside another *.rst document, use the .. include:: directive.

Inclusion of code (e.g., data file) is done with .. htmlinclude:: or .. literalinclude::, either of which will treat the inclusion as pre-formatted markup (observes white space and line breaks) to be syntax-highlighted; neither of these are discussed here.

Building an inclusion used only once would be anomalous and is to be avoided.

The guidelines above are elaborated below.

Location

Please locate all inclusions, whether applicable to/used by only one code or more than one, in this location

[source]/common/docproject/utilities

Feel free to include a code name in the fragment file name (e.g., “_flac3_specific_material.rst”) if the content merits.

This is needed so that: a) all inclusions may be found in one place and b) so that all inclusions, which are “common” by their nature, are found in the common area of code — and are thus available to any document set, regardless of its configuration.

Name

Please, always name an inclusion unit with an underscore “_” at the start of its name. This is required because:

• files that start with “_” (that is, inclusions) are excluded from the doc set build list, by design, because an inclusion doc should only be processed as content sucked into another document, not as a source document in its own right.
• the convention makes it easy to identify an inclusion as an inclusion when reading the “host” source document that includes it.

No Anchors! And CAREFUL with Links

Do not put link targets inside included content. Reason: a link that jumps into an inclusion cannot be controlled with regard to the intended destination document. If docs A, B, and C all have an inclusion that has a link target in it, any attempt to link from doc D to that target will always “land” in the last-processed of documents A, B, and C. If a link needs to be built to go to the included content within a specific host document, put a label-type link target (format: .. _targetlabel:) in front of the .. include:: directive in the host document:

.. _this-is-the-link-target:

.. include:: /common/docproject/utilities/_cyclesequence.rst

Note the .. include:: directive does not support the :name: option (which makes sense, because it would present the very problem under present discussion).

Not required, but helpful: put this comment on the first line of inclusion files:

.. this is an included document; do not put anchors in this file

With regard to hyperlinks within an inclusion that jump somewhere else: for that link to always work, it must be certain that its target will appear in any and every document set that may be built with that inclusion. If there is any chance that that is not true (or someday will not be true), better to avoid building the link.

Inclusion in Commands or FISH

Don’t try this. It almost certainly won’t work. The use of indentation levels to create parent-child relationships in keywords won’t support inclusions.