31. include
Prev | Chapter 6. Commands written in the Java™ programming language | Next

## 31. include

Parameter syntax:

    'into' | ('replace'|'before'|'after' [ implicit_selection ]?)
    [ 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, see the corresponding tutorial section in the User's Guide.

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.

Examples:

    include into
    include after[implicitElement]
    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 after section1.xml s1
    include after section2.xml -

    include into boilerplate:common/trademarks.xml super_foo

Prev | Up | Next
30. extractObject | Home | 32. insert