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

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.

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>
Adding/replacing common attributes to the realized document
  • All common attributes (annotations, dir, remap, revisionflag, role, version, xml:base, xml:id, xml:lang, xreflabel) found on a module or structure are copied to the corresponding realized element, possibly replacing the same common attributes already set on the resource. Example:

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

    where resource t1 contains:

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

    gives realized section:

    <section version="5.1" xml:base="... t1.xml" xml:id="sect01"> ...
Adding/replacing metadata to the realized document
  • If a module or structure has both info and merge child elements then both child elements contribute to the metadata of the corresponding realized element.

  • Elements info and merge may used to replace, but also to add, child elements to the info of the corresponding realized element.

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

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.

Miscellaneous
  • 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"/>