Chapter 5. Limitations and implementation specificities

Table of Contents

5.1. Limitations
5.2. Implementation specificities
5.2.1. About filtering

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.

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.

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 modules 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.