| 43. include | ||
|---|---|---|
 | Chapter 6. Commands written in the Java™ programming language |  |
| 43. include | ||
|---|---|---|
| | Chapter 6. Commands written in the Java™ programming language | |
Parameter syntax:
'into' | ('replace'|'before'|'after' [ implicit_selection ]?)
[ '[multipleInstances]' ]?
[ referenced_document_URL reference_id [ '[absoluteReference]' ]? ]?Pastes a reference into element containing caret, at caret position.
Pastes a reference replacing text selection or selected nodes.
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.
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.
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).
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
| |  | |
| 42.2. Filtering the text pasted in the document |  | 44. insert |