Chapter 5. Limitations and implementation specificities

• 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”

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

• 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"> ...

• 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>

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

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

• 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”