Chapter 5. Limitations and implementation specificities
Prev |  | Next

# Chapter 5. Limitations and implementation specificities

## 5.1. Limitations

- Attribute `type` of element `structure` is ignored.

- Element `relationships` is supported. However attribute `type` of elements `relationships` and `relationship` is still ignored.

Related information

- Section 5.2, “Implementation specificities”

## 5.2. Implementation specificities

### What is an implementation specificity?

It's basically a feature which is implemented by XMLmind Assembly Processor in way which is not 100% conforming to DocBook 5.2: The Definitive Guide (TDG). The reasons for this are:

either the TDG does not document the feature precisely enough (example: the section called “Generating links using element `relationships`”),
or the feature, though really useful, is missing from the TDG (example: the section called “Adding/replacing common attributes to the realized document”).

###### Adding/replacing meta-information to the realized document

- Elements `structure`/`info` and `module`/`info` do not contribute to the meta-information of the corresponding realized element.

- Only element `merge` may used to add or replace child elements in the `info` of the corresponding realized element.

- Element `merge` may have both a `resourceref` attribute and child elements.

###### Adding/replacing common attributes to the realized document

- Common attributes (`annotations`, `dir`, `remap`, `revisionflag`, `role`, `trans:idfixup`, `trans:linkscope`, `trans:suffix`, `version`, `xml:base`, `xml:id`, `xml:lang`, `xreflabel`) found on `module` or `structure` do not contribute to the realized document.

- Only common attributes found on `merge` are copied to the corresponding realized element, possibly replacing the same common attributes already set on the resource.

  Example (no `resourceref`):

      <module renderas="section" xml:id="sect01-module">
        <merge xml:id="sect01">

  gives realized section:

      <section xml:id="sect01"> ...

  Example (with `resourceref`):

      <module renderas="section" resourceref="t1">
        <merge xml:id="sect01"> ...

  where resource `t1` contains:

      <topic version="5.2" xml:id="t1" ...

  gives realized section:

      <section version="5.2" xml:base="... t1.xml" xml:id="sect01"> ...

###### Generating links using element `relationships`

- The `instance` child elements of a `relationships` elements are copied to all the `relationship` child elements of a `relationships` elements. Example:

      <relationships type="seealso sequence">
        <instance linkend="tut1"/>

        <relationship>
          <association></association>
          <instance linkend="tut2"/>
        </relationship>

        <relationship type="path">
          <association>Quick start</association>
          <instance linkend="tut3"/>
        </relationship>
      </relationships>

  is equivalent to:

      <relationships>
        <relationship type="seealso">
          <association></association>
          <instance linkend="tut2"/>
          <instance linkend="tut1"/>
        </relationship>

        <relationship type="path">
          <association>Quick start</association>
          <instance linkend="tut3"/>
          <instance linkend="tut1"/>
        </relationship>
      </relationships>

- For now, attribute `type` of elements `relationships` and `relationship` does not contribute to the realized document. However notice in above example how first token (`seealso` in above example) found in `relationships/@type` is “inherited” by the `relationship` child elements not having this attribute (first `relationship` child in above example). Also note that tokens other than the first one (`sequence` in above example) are not “inherited”.

- Element `relationships` may have just `instance` child elements and no `relationship` child elements. Example:

      <relationships type="seealso">
        <instance linkend="tut1"/>
        <instance linkend="tut2"/>
      </relationships>

  is equivalent to:

      <relationships>
        <relationship type="seealso">
          <association></association>
          <instance linkend="tut1"/>
          <instance linkend="tut2"/>
        </relationship>
      </relationships>

- The `linking` attribute of element `instance` is supported with the following values: `sourceonly`, `targetonly`, `normal`, `none`, with the same semantics as the corresponding `linking` attribute of DITA.

- The links are generated at the end of the realized modules in the form of an `itemizedlist` having attribute `remap="relationships"` and starting with a `title` child element. The text of this `title` comes from `relationship`/`association`.

- An empty `association` may be used to specify the default title for a group of links. This default title is "`Related information`" (translated to the language —`xml:lang`— of the realized module).

- No links are generated at the end of realized modules having attribute `contentonly="true"`.

- The `linkend` attribute of element `instance` may contain the `xml:id` of a resource or the `xml:id` of a module. Example:

      <relationships>
        <instance linkend="tut1"/>
        <instance linkend="tut2-module"/>
      </relationships>

  is equivalent to:

      <relationships>
        <instance linkend="tut1-module"/>
        <instance linkend="tut2-module"/>
      </relationships>

  for an `assembly` containing:

      <resource xml:id="tut1" href="tut1.xml"/>
      <resource xml:id="tut2" href="tut2.xml"/>
      <resource xml:id="tut3" href="tut3.xml"/>
      ...

      <module xml:id="tut1-module" resourceref="tut1">
      <module xml:id="tut2-module">
        <info>
          <title>Going further with FooBar</title>
        </info>
        <module resourceref="tut2" contentonly="true"/>
        <module resourceref="tut3" contentonly="true"/>
      </module>

###### Elements `filterin` and `filterout` versus profiling using the DocBook XSL stylesheets

- The use of the `outputformat` attribute and/out `filterin` and `filterout` elements in an `assembly` and the use of conditional processing (profiling) by the means of the DocBook XSL stylesheets is orthogonal.

  It's certainly possible to have an assembly making use of the `outputformat` attribute and containing `filterin` and `filterout` elements and also to pass the equivalent of XSLT stylesheet parameters `profile.`attr_name`=`attr_value`` (that is, a profile) to XMLmind Assembly Processor. However, in this case, XMLmind Assembly Processor will not apply this profile to the assembly itself prior to processing the assembly.

  The `-profile` command-line option allows to apply a profile to the realized document (and not to the assembly itself) before checking the realized document for cross-reference errors. This option is not useful unless the `-check` option is also used.

###### Controlling chunking

- Module or output attribute `chunk=`false`` may be used to add a `<?dbhtml stop-chunking>` processing-instruction to the corresponding realized element. The other `chunk` attribute values `true` and `auto` are not supported.

- Output attribute `file=``dir`/`basename``` may be used to add a `<?dbhtml dir="`dir`" filename="`basename`">` processing-instruction to the corresponding realized element.

###### Other specificities

- If `module`/@`contentonly`=`true` and `module`/@`omittitles`=`true` then the root element, `title`, `titleabbrev`, `subtitle` and `info` elements[2] are stripped and the remaining raw content can be placed where the stripped elements are not allowed. For example, the remaining content can be added to the end of a section element taken from another resource.

  ### Important

  If `module`/@`contentonly`=`true` then you'll almost certainly want to add attribute `omittitles`=`true` to this `module`. Having attribute `module`/@`contentonly`=`true` and no `module`/@`contentonly` attribute (or `module`/@`omittitles`=`false`) corresponds to very rare use cases.

- A `module` in a larger `structure` can set its `resourceref` attribute to the value of the `xml:id` of a modular `structure` element in the same assembly to incorporate it. However, because DocBook 5.2: The Definitive Guide is not clear about how this should be done, this feature is implemented in the most basic way.

  Example:

      <structure xml:id="chapter1-structure" resourceref="chap1">
        <module resourceref="topic1" renderas="section">
          <module resourceref="topic2" renderas="section"/>
        </module>
      </structure>

      <structure xml:id="chapter2-structure" resourceref="chap2">
        <module resourceref="topic3" renderas="section">
          <module resourceref="topic4" renderas="section"/>
        </module>
      </structure>

      <structure renderas="book">
        <merge>
          <title>Name of the book</title>
        </merge>
        <module resourceref="chapter1-structure"/>
        <module resourceref="chapter2-structure"/>
      </structure>

  is equivalent to:

      <structure renderas="book">
        <merge>
          <title>Name of the book</title>
        </merge>
        <module resourceref="chap1">
          <module resourceref="topic1" renderas="section">
            <module resourceref="topic2" renderas="section"/>
          </module>
        </module>
        <module resourceref="chap2">
          <module resourceref="topic3" renderas="section">
            <module resourceref="topic4" renderas="section"/>
          </module>
        </module>
      </structure>

- The `href` attribute of a `resource` element may have a fragment. However a fragment is supported only if the resource is a native DocBook v5+ document which does not need to be transformed.

- XMLmind Assembly Processor uses a built-in XInclude 1.1 processor rather than the XInclude 1.0 implementation provided by the XML parser (that is, Xerces). Note that for now, this built-in XInclude 1.1 processor only supports the XPointer element() scheme.

Related information

- Section 5.1, “Limitations”

### 5.2.1. About filtering

- Element `filterin` is best explained by an example:

      <module resourceref="MyTopic"/>
      <filterin os="mac" userlevel="beginner;intermediate"/>

  The above example means: exclude from the contents of realized topic `MyTopic` all the elements having a `os` attribute not containing `mac` and also exclude all the elements having a `userlevel` attribute not containing `beginner` or `intermediate`.

  For those who know the DocBook XSL stylesheets, this is equivalent to passing parameters `profile.os=mac` and `profile.userlevel=beginner;intermediate` to the profiling stylesheets.

  For example, if resource `MyTopic` points to a topic containing:

      <para xml:id="p1" os="windows">Paragraph #1.</para>
      <para xml:id="p2" os="mac;linux">Paragraph #2.</para>
      <para xml:id="p3" userlevel="advanced;expert">Paragraph #3.</para>
      <para xml:id="p4" userlevel="intermediate;advanced">Paragraph #4.</para>

  then paragraph `p1` and `p3` are excluded from the realized document while paragraphs `p2` and `p4` are not.

- Element `filterout` is best explained by an example:

      <module resourceref="MyTopic"/>
      <filterout os="mac" userlevel="beginner;intermediate"/>

  The above example means: exclude from the contents of realized topic `MyTopic` all the elements having a `os` attribute containing `mac` and no other value and also exclude all the elements having a `userlevel` attribute containing `beginner` and/or `intermediate` and no other value.

  For example, if resource `MyTopic` points to a topic containing:

      <para xml:id="p1" os="mac">Paragraph #1.</para>
      <para xml:id="p2" os="mac;linux">Paragraph #2.</para>
      <para xml:id="p3" userlevel="beginner">Paragraph #3.</para>
      <para xml:id="p4" userlevel="intermediate;advanced">Paragraph #4.</para>

  then paragraph `p1` and `p3` are excluded from the realized document while paragraphs `p2` and `p4` are not.

- It's possible to have both `filterin` and `filterout` elements for the same effectivity attribute. Example:

      <module resourceref="MyTopic"/>
      <filterin os="windows;mac"/>
      <filterout os="linux"/>

  For example, if resource `MyTopic` points to a topic containing:

      <para xml:id="p1" os="linux">Paragraph #1.</para>
      <para xml:id="p2" os="mac;linux">Paragraph #2.</para>
      <para xml:id="p3" os="android">Paragraph #3.</para>
      <para xml:id="p4" os="android;windows">Paragraph #4.</para>
      <para xml:id="p5" os="android;linux">Paragraph #5.</para>

  then paragraph `p1`, `p3` and `p5` are excluded from the realized document while paragraphs `p2` and `p4` are not.

- Just like `output` elements, `filterin` and `filterout` elements are considered in order and relevant filters are combined. A `filterin` or `filterout` element is relevant if it does not have an `outputformat` attribute or if its `outputformat` attribute matches the output format passed as a parameter to the assembly processor.

- The sequence of `filterin` and `filterout` elements “inherited” from ancestor `structure` and `module`s and/or directly added to a `module` is combined to form a single `filterin` element and a single `filterout` element. The resulting single `filterin` element and single `filterout` element are applied to the `module`. Example:

      <filterin os="windows"/>
      <filterout userlevel="beginner;intermediate"/>
      <filterin os="mac;linux"/>
      <filterout os="linux"/>
      <filterin userlevel="intermediate;advanced"/>

  The above sequence is equivalent to:

      <filterin os="windows;mac" userlevel="intermediate;advanced"/>
      <filterout os="linux" userlevel="beginner"/>

[2] Not just “the root element and titles” as specified in the DocBook Definitive Guide.

Prev |  | Next
Chapter 4. Command-line options | Home | Chapter 6. Embedding XMLmind Assembly Processor in a Java™ application