<?xml version="1.0" encoding="UTF-8"?>
<topic version="5.2" xml:id="specificities"
       xmlns="http://docbook.org/ns/docbook">
  <info>
    <title>Implementation specificities</title>
  </info>

  <note>
    <title>What is an implementation specificity?</title>

    <para>It's basically a feature which is implemented by <xi:include
    href="intro.xml" xpointer="dbasm"
    xmlns:xi="http://www.w3.org/2001/XInclude"/> in way which is <emphasis>not
    100% conforming</emphasis> to <link
    xlink:href="https://tdg.docbook.org/tdg/5.2/"
    xmlns:xlink="http://www.w3.org/1999/xlink"><citetitle>DocBook 5.2: The
    Definitive Guide</citetitle></link> (<abbrev>TDG</abbrev>). The reasons
    for this are:</para>

    <simplelist>
      <member>either the <abbrev>TDG</abbrev> does not document the feature
      precisely enough (example: <xref
      linkend="specificities_relationships"/>),</member>

      <member>or the feature, though really useful, is missing from the
      <abbrev>TDG</abbrev> (example: <xref
      linkend="specificities_add_attributes"/>).</member>
    </simplelist>
  </note>

  <bridgehead renderas="sect5"
  xml:id="specificities_add_metadata">Adding/replacing meta-information to the
  realized document</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Elements <tag class="element">structure</tag>/<tag
      class="element">info</tag> and <tag class="element">module</tag>/<tag
      class="element">info</tag> <emphasis>do not contribute</emphasis> to the
      meta-information of the corresponding realized element.</para>
    </listitem>

    <listitem>
      <para>Only element <tag class="element">merge</tag> may used to add or
      replace child elements in the <tag class="element">info</tag> of the
      corresponding realized element.</para>
    </listitem>

    <listitem>
      <para>Element <tag class="element">merge</tag> may have both a <tag
      class="attribute">resourceref</tag> attribute and child elements.</para>
    </listitem>
  </itemizedlist>

  <bridgehead renderas="sect5"
  xml:id="specificities_add_attributes">Adding/replacing common attributes to
  the realized document</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Common attributes (<tag class="attribute">annotations</tag>, <tag
      class="attribute">dir</tag>, <tag class="attribute">remap</tag>, <tag
      class="attribute">revisionflag</tag>, <tag class="attribute">role</tag>,
      <tag class="attribute">trans:idfixup</tag>, <tag
      class="attribute">trans:linkscope</tag>, <tag
      class="attribute">trans:suffix</tag>, <tag
      class="attribute">version</tag>, <tag class="attribute">xml:base</tag>,
      <tag class="attribute">xml:id</tag>, <tag
      class="attribute">xml:lang</tag>, <tag
      class="attribute">xreflabel</tag>) found on <tag
      class="element">module</tag> or <tag class="element">structure</tag>
      <emphasis>do not contribute</emphasis> to the realized document.</para>
    </listitem>

    <listitem>
      <para>Only common attributes found on <tag class="element">merge</tag>
      are copied to the corresponding realized element, <emphasis>possibly
      replacing the same common attributes already set on the
      resource</emphasis>.</para>

      <para>Example (no <tag class="attribute">resourceref</tag>):</para>

      <programlisting>&lt;module renderas="section" xml:id="sect01-module"&gt;
  &lt;merge <emphasis role="bold">xml:id="sect01"</emphasis>&gt;</programlisting>

      <para>gives realized section:</para>

      <programlisting language="xml">&lt;section <emphasis role="bold">xml:id="sect01"</emphasis>&gt; ...</programlisting>

      <para>Example (with <tag class="attribute">resourceref</tag>):</para>

      <programlisting language="xml">&lt;module renderas="section" resourceref="t1"&gt;
  &lt;merge <emphasis role="bold">xml:id="sect01"</emphasis>&gt; ...</programlisting>

      <para>where resource <literal>t1</literal> contains:</para>

      <programlisting language="xml">&lt;topic version="5.2" <emphasis
          role="bold">xml:id="t1"</emphasis> ...</programlisting>

      <para>gives realized section:</para>

      <programlisting language="xml">&lt;section version="5.2" xml:base="... t1.xml" <emphasis
          role="bold">xml:id="sect01"</emphasis>&gt; ...</programlisting>
    </listitem>
  </itemizedlist>

  <bridgehead renderas="sect5" xml:id="specificities_relationships">Generating
  links using element <tag class="element">relationships</tag></bridgehead>

  <itemizedlist>
    <listitem>
      <para>The <tag class="element">instance</tag> child elements of a <tag
      class="element">relationships</tag> elements are copied to all the <tag
      class="element">relationship</tag> child elements of a <tag
      class="element">relationships</tag> elements. Example:</para>

      <programlisting language="xml">&lt;relationships type="seealso sequence"&gt;
  &lt;instance linkend="tut1"/&gt;

  &lt;relationship&gt;
    &lt;association&gt;&lt;/association&gt;
    &lt;instance linkend="tut2"/&gt;
  &lt;/relationship&gt;

  &lt;relationship type="path"&gt;
    &lt;association&gt;Quick start&lt;/association&gt;
    &lt;instance linkend="tut3"/&gt;
  &lt;/relationship&gt;
&lt;/relationships&gt;</programlisting>

      <para>is equivalent to:</para>

      <programlisting language="xml">&lt;relationships&gt;
  &lt;relationship type="seealso"&gt;
    &lt;association&gt;&lt;/association&gt;
    &lt;instance linkend="tut2"/&gt;
    &lt;instance linkend="tut1"/&gt;
  &lt;/relationship&gt;

  &lt;relationship type="path"&gt;
    &lt;association&gt;Quick start&lt;/association&gt;
    &lt;instance linkend="tut3"/&gt;
    &lt;instance linkend="tut1"/&gt;
  &lt;/relationship&gt;
&lt;/relationships&gt;</programlisting>
    </listitem>

    <listitem>
      <para>For now, attribute <tag class="attribute">type</tag> of elements
      <tag class="element">relationships</tag> and <tag
      class="element">relationship</tag> does not contribute to the realized
      document. However notice in above example how first token (<tag
      class="attvalue">seealso</tag> in above example) found in
      <literal>relationships/@type</literal> is “inherited” by the <tag
      class="element">relationship</tag> child elements not having this
      attribute (first <tag class="element">relationship</tag> child in above
      example). Also note that tokens other than the first one (<tag
      class="attvalue">sequence</tag> in above example) are not
      “inherited”.</para>
    </listitem>

    <listitem>
      <para>Element <tag class="element">relationships</tag> may have just
      <tag class="element">instance</tag> child elements and no <tag
      class="element">relationship</tag> child elements. Example:</para>

      <programlisting language="xml">&lt;relationships type="seealso"&gt;
  &lt;instance linkend="tut1"/&gt;
  &lt;instance linkend="tut2"/&gt;
&lt;/relationships&gt;</programlisting>

      <para>is equivalent to:</para>

      <programlisting language="xml">&lt;relationships&gt;
  &lt;relationship type="seealso"&gt;
    &lt;association&gt;&lt;/association&gt;
    &lt;instance linkend="tut1"/&gt;
    &lt;instance linkend="tut2"/&gt;
  &lt;/relationship&gt;
&lt;/relationships&gt;</programlisting>
    </listitem>

    <listitem>
      <para>The <tag class="attribute">linking</tag> attribute of element <tag
      class="element">instance</tag> is supported with the following values:
      <tag class="attvalue">sourceonly</tag>, <tag
      class="attvalue">targetonly</tag>, <tag class="attvalue">normal</tag>,
      <tag class="attvalue">none</tag>, with the same semantics as <link
      xlink:href="https://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/langRef/attributes/commonMapAttributes.html#topicref-atts__linking"
      xmlns:xlink="http://www.w3.org/1999/xlink">the corresponding <tag
      class="attribute">linking</tag> attribute of DITA</link>.</para>
    </listitem>

    <listitem>
      <para>The links are generated at the end of the realized modules in the
      form of an <tag class="element">itemizedlist</tag> having attribute
      <literal>remap="relationships"</literal> and starting with a <tag
      class="element">title</tag> child element. The text of this <tag
      class="element">title</tag> comes from <tag
      class="element">relationship</tag>/<tag
      class="element">association</tag>.</para>
    </listitem>

    <listitem>
      <para>An empty <tag class="element">association</tag> may be used to
      specify the default title for a group of links. This default title is
      "<literal>Related information</literal>" (translated to the language
      —<tag class="attribute">xml:lang</tag>— of the realized module).</para>
    </listitem>

    <listitem>
      <para>No links are generated at the end of realized modules having
      attribute <literal>contentonly="true"</literal>.</para>
    </listitem>

    <listitem>
      <para>The <tag class="attribute">linkend</tag> attribute of element <tag
      class="element">instance</tag> may contain the <tag
      class="attribute">xml:id</tag> of a resource <emphasis>or the <tag
      class="attribute">xml:id</tag> of a module</emphasis>. Example:</para>

      <programlisting language="xml">&lt;relationships&gt;
  &lt;instance linkend="tut1"/&gt;
  &lt;instance linkend="tut2-module"/&gt;
&lt;/relationships&gt;</programlisting>

      <para>is equivalent to:</para>

      <programlisting language="xml">&lt;relationships&gt;
  &lt;instance linkend="tut1-module"/&gt;
  &lt;instance linkend="tut2-module"/&gt;
&lt;/relationships&gt;</programlisting>

      <para>for an <tag class="element">assembly</tag> containing:</para>

      <programlisting language="xml">&lt;resource <emphasis role="bold">xml:id="tut1"</emphasis> href="tut1.xml"/&gt;
&lt;resource xml:id="tut2" href="tut2.xml"/&gt;
&lt;resource xml:id="tut3" href="tut3.xml"/&gt;
...

&lt;module <emphasis role="bold">xml:id="tut1-module"</emphasis> <emphasis
          role="bold">resourceref="tut1"</emphasis>&gt;
&lt;module <emphasis role="bold">xml:id="tut2-module"</emphasis>&gt;
  &lt;info&gt;
    &lt;title&gt;Going further with FooBar&lt;/title&gt;
  &lt;/info&gt;
  &lt;module resourceref="tut2" contentonly="true"/&gt;
  &lt;module resourceref="tut3" contentonly="true"/&gt;
&lt;/module&gt;</programlisting>
    </listitem>
  </itemizedlist>

  <bridgehead renderas="sect5"
  xml:id="specificities_filtering_versus_profiling">Elements <tag
  class="element">filterin</tag> and <tag class="element">filterout</tag>
  versus profiling using the DocBook XSL stylesheets</bridgehead>

  <itemizedlist>
    <listitem>
      <para>The use of the <tag class="attribute">outputformat</tag> attribute
      and/out <tag class="element">filterin</tag> and <tag
      class="element">filterout</tag> elements in an <tag
      class="element">assembly</tag> and the use of conditional processing
      (profiling) by the means of the <link
      xlink:href="https://sourceforge.net/projects/docbook/"
      xmlns:xlink="http://www.w3.org/1999/xlink">DocBook XSL
      stylesheets</link> is orthogonal.</para>

      <para>It's certainly possible to have an assembly making use of the <tag
      class="attribute">outputformat</tag> attribute and containing <tag
      class="element">filterin</tag> and <tag class="element">filterout</tag>
      elements and also to pass the equivalent of XSLT stylesheet parameters
      <literal>profile.<replaceable>attr_name</replaceable>=<replaceable>attr_value</replaceable></literal>
      (that is, a profile) to <xi:include href="intro.xml" xpointer="dbasm"
      xmlns:xi="http://www.w3.org/2001/XInclude"/>. However, in this case,
      <emphasis><xi:include href="intro.xml" xpointer="dbasm"
      xmlns:xi="http://www.w3.org/2001/XInclude"/> will not apply this profile
      to the assembly itself prior to processing the
      assembly</emphasis>.</para>

      <para>The <link linkend="option_profile"><option>-profile</option>
      command-line option</link> allows to apply a profile to the
      <emphasis>realized document</emphasis> (and not to the assembly itself)
      before checking the realized document for cross-reference errors. This
      option is not useful unless the <link
      linkend="option_check"><option>-check</option> option</link> is also
      used.</para>
    </listitem>
  </itemizedlist>

  <bridgehead renderas="sect5" xml:id="specificities_chunking">Controlling
  chunking</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Module or output attribute <tag class="attribute">chunk=<tag
      class="attvalue">false</tag></tag> may be used to add a <tag
      class="pi">dbhtml stop-chunking</tag> processing-instruction to the
      corresponding realized element. The other <tag
      class="attribute">chunk</tag> attribute values <tag
      class="attvalue">true</tag> and <tag class="attvalue">auto</tag> are not
      supported.</para>
    </listitem>

    <listitem>
      <para>Output attribute <tag class="attribute">file=<tag
      class="attvalue"><replaceable>dir</replaceable>/<replaceable>basename</replaceable></tag></tag>
      may be used to add a <tag
      class="pi">dbhtml dir="<replaceable>dir</replaceable>" filename="<replaceable>basename</replaceable>"</tag>
      processing-instruction to the corresponding realized element.</para>
    </listitem>
  </itemizedlist>

  <bridgehead renderas="sect5" xml:id="specificities_misc">Other
  specificities</bridgehead>

  <itemizedlist>
    <listitem>
      <para>If <tag class="element">module</tag>/@<tag
      class="attribute">contentonly</tag>=<tag class="attvalue">true</tag> and
      <tag class="element">module</tag>/@<tag
      class="attribute">omittitles</tag>=<tag class="attvalue">true</tag> then
      the root element, <tag class="element">title</tag>, <tag
      class="element">titleabbrev</tag>, <tag class="element">subtitle</tag>
      <emphasis role="underline">and <tag
      class="element">info</tag></emphasis> elements<footnote>
          <para>Not just <quote>the root element and titles</quote> as
          specified in the DocBook Definitive Guide.</para>
        </footnote> 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.</para>

      <important>
        <para>If <tag class="element">module</tag>/@<tag
        class="attribute">contentonly</tag>=<tag class="attvalue">true</tag>
        then you'll almost certainly want to add attribute <tag
        class="attribute">omittitles</tag>=<tag class="attvalue">true</tag> to
        this <tag class="element">module</tag>. Having attribute <tag
        class="element">module</tag>/@<tag
        class="attribute">contentonly</tag>=<tag class="attvalue">true</tag>
        and no <tag class="element">module</tag>/@<tag
        class="attribute">contentonly</tag> attribute (or <tag
        class="element">module</tag>/@<tag
        class="attribute">omittitles</tag>=<tag class="attvalue">false</tag>)
        corresponds to very rare use cases.</para>
      </important>
    </listitem>

    <listitem>
      <para>A <tag class="element">module</tag> in a larger <tag
      class="element">structure</tag> can set its <tag
      class="attribute">resourceref</tag> attribute to the value of the <tag
      class="attribute">xml:id</tag> of a modular <tag
      class="element">structure</tag> element in the same assembly to
      incorporate it. However, because <link
      xlink:href="https://tdg.docbook.org/tdg/5.2/structure#element.db.structure"
      xmlns:xlink="http://www.w3.org/1999/xlink"><citetitle>DocBook 5.2: The
      Definitive Guide</citetitle></link> is not clear about how this should
      be done, this feature is implemented in the most basic way.</para>

      <para>Example:</para>

      <programlisting language="xml">&lt;structure xml:id="chapter1-structure" resourceref="chap1"&gt;
  &lt;module resourceref="topic1" renderas="section"&gt;
    &lt;module resourceref="topic2" renderas="section"/&gt;
  &lt;/module&gt;
&lt;/structure&gt;

&lt;structure xml:id="chapter2-structure" resourceref="chap2"&gt;
  &lt;module resourceref="topic3" renderas="section"&gt;
    &lt;module resourceref="topic4" renderas="section"/&gt;
  &lt;/module&gt;
&lt;/structure&gt;

&lt;structure renderas="book"&gt;
  &lt;merge&gt;
    &lt;title&gt;Name of the book&lt;/title&gt;
  &lt;/merge&gt;
  &lt;module resourceref="chapter1-structure"/&gt;
  &lt;module resourceref="chapter2-structure"/&gt;
&lt;/structure&gt;</programlisting>

      <para>is equivalent to:</para>

      <programlisting language="xml">&lt;structure renderas="book"&gt;
  &lt;merge&gt;
    &lt;title&gt;Name of the book&lt;/title&gt;
  &lt;/merge&gt;
  &lt;module resourceref="chap1"&gt;
    &lt;module resourceref="topic1" renderas="section"&gt;
      &lt;module resourceref="topic2" renderas="section"/&gt;
    &lt;/module&gt;
  &lt;/module&gt;
  &lt;module resourceref="chap2"&gt;
    &lt;module resourceref="topic3" renderas="section"&gt;
      &lt;module resourceref="topic4" renderas="section"/&gt;
    &lt;/module&gt;
  &lt;/module&gt;
&lt;/structure&gt;</programlisting>
    </listitem>

    <listitem>
      <para>The <tag class="attribute">href</tag> attribute of a <tag
      class="element">resource</tag> 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.</para>
    </listitem>

    <listitem>
      <para><xi:include href="intro.xml" xpointer="dbasm"
      xmlns:xi="http://www.w3.org/2001/XInclude"/> uses a built-in <link
      xlink:href="https://www.w3.org/TR/xinclude-11/"
      xmlns:xlink="http://www.w3.org/1999/xlink">XInclude 1.1</link> processor
      rather than the XInclude 1.0 implementation provided by the XML parser
      (that is, <link xlink:href="http://xerces.apache.org/"
      xmlns:xlink="http://www.w3.org/1999/xlink">Xerces</link>). Note that for
      now, this built-in XInclude 1.1 processor only supports the <link
      xlink:href="https://www.w3.org/TR/xptr-element/"
      xmlns:xlink="http://www.w3.org/1999/xlink">XPointer element()
      scheme</link>.</para>
    </listitem>
  </itemizedlist>
</topic>
