43. include

Parameter syntax:

'into' | ('replace'|'before'|'after' [ implicit_selection ]?)
[ '[multipleInstances]' ]?
[ referenced_document_URL reference_id [  '[absoluteReference]' ]? ]?
into

Pastes a reference into element containing caret, at caret position.

replace

Pastes a reference replacing text selection or selected nodes.

before or after

Pastes a reference before of after selected nodes.

Commands copyAsInclusion (generally bound to keystroke Shift+Ctrl+C) and paste (generally bound to keystroke Ctrl+V) are used to compose modular documents.

When parameters referenced_document_URL and reference_id are not specified, command include is basically an alternative user interface for composing modular documents. It displays a dialog box, similar to the Include tool, allowing the user to choose which reference to insert.

When parameters referenced_document_URL and reference_id are specified, command include may be used in macro-commands to automate tasks.

referenced_document_URL

The URL of the document containing the nodes to be referenced. May be relative or absolute. If it is a relative URL, it is relative to the URL of the including document.

Note that the fact referenced_document_URL is absolute or relative is orthogonal to the [absoluteReference] option.

URLs which need an XML catalog in order to be resolved are also supported here (see last example below). In such case, the [absoluteReference] option is ignored and the including document references the included document using as is the specified URL.

reference_id

A string identifying the nodes to be referenced:

  • DITA-style ID for DITA documents (e.g. my_topic, my_topic/my_paragraph),

  • standard ID or "-" for other document types.

    If you want to include the root element of a document, you must refer to it by its ID if it has one (see the section1.xml example below) or as "-" otherwise (see the section2.xml example below).

[absoluteReference]

When this option is specified, the including document references the included document using an absolute URL. By default, a URL relative to the including document is used.

Note that the effect of this option does not depend on whether referenced_document_URL is itself absolute or not.

The [multipleInstances] option is a hint which indicates that the reference created by the command may be found several times, at different places, in the including document. Example: when you include a chapter in a book, there is no need to specify [multipleInstances], but when you include boilerplate text like a product name or a company name, then it is recommended to specify [multipleInstances]. This is why the Include tool in XMLmind XML Editor - Online Help always uses option [multipleInstances] to create the references it pastes in a document.

Examples:

include into
include after[implicitElement]
include after[implicitElement][multipleInstances]
include replace[implicitNode]
include into file:/home/john/doc/boilerplate.xml product_name
include before[implicitElement] ../common/Copyright.xhtml copyright [absoluteReference]
include into http://www.acme.com/docs/licence.xml disclaimer [absoluteReference]
include into [multipleInstances] ../common/licence.xml disclaimer

include after section1.xml s1
include after section2.xml -

include into boilerplate:common/trademarks.xml super_foo