<?xml version="1.0" encoding="UTF-8" standalone="no"?><book version="5.2" xmlns="http://docbook.org/ns/docbook"><info><title xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">XMLmind Assembly Processor Manual</title><author xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">
        <personname><firstname>Hussein</firstname><surname>Shafie</surname></personname>

        <affiliation>
          <orgname>XMLmind Software</orgname>

          <address><street>35 rue Louis Leblanc</street>,
<postcode>78120</postcode> <city>Rambouillet</city>,
<country>France</country>,
Phone: <phone>+33 (0)</phone>9 52 80 80 37,
Web: <otheraddr><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.xmlmind.com/xmleditor">www.xmlmind.com/xmleditor</link></otheraddr>
Email: <email>xmleditor-support@xmlmind.com</email> (public mailing list)</address>
        </affiliation>
      </author><pubdate xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">April 18, 2026</pubdate><abstract xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">
        <para>Explains how to install, use and embed XMLmind Assembly
        Processor.</para>
      </abstract></info><chapter version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/intro.xml" xml:id="intro">
  <info>
    <title>What is XMLmind Assembly Processor?</title>
  </info>

  <para><productname xml:id="dbasm---dqrdtx">XMLmind Assembly
  Processor</productname> is a <trademark>Java</trademark> software component
  and a command-line utility (called <command>assembly</command>) which
  processes a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/ch06">DocBook v5.1+ <tag class="element">assembly</tag></link> and all the referenced topics in order
  to create the equivalent “flat”, monolithic, document (e.g. a DocBook v5.2
  <tag class="element">book</tag>). This equivalent document is called the
  <firstterm>realized</firstterm> document.</para>

  <para>The realized document is then transformed to other formats (PDF, HTML,
  etc), normally, as if it were created by hand, using the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docbook.sourceforge.net/release/xsl/current/doc/">DocBook XSL
  stylesheets</link>.</para>

  <para><productname xml:id="dbasm---dqrdty">XMLmind Assembly
  Processor</productname> includes <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/xinclude-11/">XInclude 1.1</link> and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://documents.docbook.org/transclusion">DocBook Transclusion</link>
  processors, which allows to create modular DocBook v5.1+ documents without
  facing limitations.</para>

  <para><productname xml:id="dbasm---dqrdtz">XMLmind Assembly
  Processor</productname> is free, open source, software,
  which like the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docbook.sourceforge.net/">DocBook XSL stylesheets</link>,
  is licensed under the terms of the MIT License.</para>
</chapter><chapter xml:id="installation"><info><title xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">Installing XMLmind Assembly Processor</title></info><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/requirements.xml" xml:id="requirements">
  <info>
    <title>System requirements</title>
  </info>

  <para>Make sure that you have a <trademark>Java</trademark> 11+ runtime
  installed on your machine. To check this, please open a command window and
  type "<command>java -version</command>" followed by <keysym>Enter</keysym>.
  You should get something looking like this:</para>

  <screen>C:\&gt; java -version
openjdk version "26" 2026-03-17
OpenJDK Runtime Environment (build 26+35-2893)
OpenJDK 64-Bit Server VM (build 26+35-2893, mixed mode)</screen>
</section><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/install.xml" xml:id="install_procedure">
  <info>
    <title>Installation</title>
  </info>

  <para>Simply unzip
  <filename>assembly-<replaceable>X_Y_Z</replaceable>.zip</filename> in any
  directory.</para>

  <para>After that, you can run command-line utility
  <command>assembly</command> by simply executing
  <filename><replaceable>assembly_install_dir</replaceable>/bin/assembly.bat</filename>
  (<filename><replaceable>assembly_install_dir</replaceable>/bin/assembly</filename>
  on the Mac and on Linux).</para>

  <screen>C:\&gt; mkdir XMLmind
C:\&gt; cd XMLmind
C:\XMLmind&gt; unzip assembly-2_0_5.zip
C:\XMLmind&gt; dir assembly-2_0_5
... &lt;DIR&gt; bin
... &lt;DIR&gt; doc
... &lt;DIR&gt; docsrc
... &lt;DIR&gt; legal
...
C:\XMLmind&gt; assembly-2_0_5\bin\assembly.bat
assembly: ERROR: too few command-line arguments
Usage: assembly [option]* in_assembly_file out_docbook_file|-
...</screen>
<itemizedlist remap="relationship" spacing="compact"><title remap="association">See also</title><listitem remap="instance"><para><xref linkend="requirements"/></para></listitem></itemizedlist></section><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/install_files.xml" xml:id="install_files">
  <info>
    <title>Contents of the installation directory</title>
  </info>

  <variablelist>
    <varlistentry>
      <term><filename>bin/</filename></term>

      <term><filename>bin/assembly</filename></term>

      <term><filename>bin/assembly.bat</filename></term>

      <listitem>
        <para>Contains the <command>assembly</command> command-line utility.
        Use shell script <filename>assembly</filename> on Linux and on the
        Mac. Use <filename>assembly.bat</filename> on Windows.</para>

        <note>
          <title>JAXP limits</title>

          <para>This directory also contains file
          <filename>jaxp.properties</filename> which is referenced by the
          <filename>assembly</filename> scripts. As of Java™ version 24, the
          standard Java XML processing limits (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oracle.com/en/java/javase/24/docs/api/java.xml/module-summary.html#IN_ISFPtable">JAXP limits</link>) are
          very restrictive and no longer allow to load large XML documents.
          Therefore this file is needed to increase Java XML processing
          limits.</para>
        </note>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><filename>doc/</filename></term>

      <term><filename>doc/index.html</filename></term>

      <listitem>
        <para>Contains the documentation of <productname xml:base="intro.xml" xml:id="dbasm---dqrdu0">XMLmind Assembly
  Processor</productname>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><filename>docsrc/</filename></term>

      <term><filename>docsrc/manual.xml</filename></term>

      <listitem>
        <para>Contains the DocBook v5.2 source of the documentation of
        <productname xml:base="intro.xml" xml:id="dbasm---dqrdu1">XMLmind Assembly
  Processor</productname>. File
        <filename>docsrc/manual.xml</filename> contains an assembly. You may
        want to use this sample DocBook v5.2 assembly to experiment with the
        <command>assembly</command> command-line utility.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><filename>legal/</filename></term>

      <term><filename>legal.txt</filename></term>

      <listitem>
        <para>Contains legal information about <productname xml:base="intro.xml" xml:id="dbasm---dqrdu2">XMLmind Assembly
  Processor</productname> and
        about third-party components used in <productname xml:base="intro.xml" xml:id="dbasm---dqrdu3">XMLmind Assembly
  Processor</productname>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><filename>lib/<replaceable>*</replaceable>.jar</filename></term>

      <listitem>
        <para>All the <trademark class="trade">Java</trademark> class
        libraries needed to run <productname xml:base="intro.xml" xml:id="dbasm---dqrdu4">XMLmind Assembly
  Processor</productname>:</para>

        <itemizedlist>
          <listitem>
            <para><filename>assembly.jar</filename> contain the code of
            <productname xml:base="intro.xml" xml:id="dbasm---dqrdu5">XMLmind Assembly
  Processor</productname>.</para>
          </listitem>

          <listitem>
            <para><filename>xmlresolver.jar</filename> contains <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link>, an
            enhanced XML resolver with XML Catalog support</para>

            <para>This component is needed only if your assembly loads XML
            documents having a DTD (e.g. transform DITA topics to DocBook
            topics).</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><filename>src/</filename></term>

      <term><filename>src/build.xml</filename></term>

      <listitem>
        <para>Contains the <trademark>Java</trademark> source code of
        <productname xml:base="intro.xml" xml:id="dbasm---dqrdu6">XMLmind Assembly
  Processor</productname>.
        <filename>src/build.xml</filename> is an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://ant.apache.org/">ant</link> build file which
        allows to rebuild <filename>lib/assembly.jar</filename>.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</section></chapter><chapter version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/quick_start.xml" xml:id="quick_start">
  <info>
    <title>Getting started</title>
  </info>

  <tip xml:id="install_xxe_tip">
    <title>What if you just want to quickly experiment with DocBook assemblies
    and topics?</title>

    <para xml:id="download_xxe_tip">The simplest is to download and install
    XMLmind XML Editor Evaluation Edition from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.xmlmind.com/xmleditor/download.shtml">https://www.xmlmind.com/xmleditor/download.shtml</link>.</para>

    <para>You can then open this document —"<citetitle>XMLmind Assembly
    Processor Manual</citetitle>", an assembly found in
    <filename><replaceable>assembly_install_dir</replaceable>/docsrc/manual.xml</filename>—
    in XMLmind XML Editor and use menu <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.xmlmind.com/xmleditor/_distrib/doc/assembly/dbasm_convert_menu.html"><menuchoice>
        <guimenu>Assembly</guimenu>

        <guisubmenu>Convert Document</guisubmenu>
      </menuchoice></link> to convert it to any format you want.</para>

    <figure>
      <title>This assembly <filename>manual.xml</filename> opened in XMLmind
      XML Editor</title>

      <mediaobject>
        <imageobject>
          <imagedata contentwidth="12cm" fileref="images/xxe_assembly_menu.png"/>
        </imageobject>
      </mediaobject>
    </figure>
  </tip>

  <para>In order to explain how <productname xml:base="intro.xml" xml:id="dbasm---dqrdu7">XMLmind Assembly
  Processor</productname> is used, we'll convert this
  document —"<citetitle>XMLmind Assembly Processor Manual</citetitle>", an
  assembly found in
  <filename><replaceable>assembly_install_dir</replaceable>/docsrc/manual.xml</filename>—
  first to multi-page HTML and then to PDF.</para>

  <para>You'll find in
  <filename><replaceable>assembly_install_dir</replaceable>/docsrc/convert_manual.bat</filename>
  (Windows) and in
  <filename><replaceable>assembly_install_dir</replaceable>/docsrc/convert_manual.sh</filename>
  (Linux, Mac) a copy of the commands used in this chapter.</para>

  <para>Assembly <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../../docsrc/manual/manual.xml"><filename>manual.xml</filename></link>
  contains a <tag class="element">structure</tag> specifying a book. The
  content of the chapters and sections of this book is obtained from topics
  such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../../docsrc/manual/intro.xml"><filename>intro.xml</filename></link>,
  <filename>requirements.xml</filename>, <filename>install.xml</filename>,
  etc.</para>

  <programlisting language="xml">&lt;structure renderas="book" xml:id="manual"&gt;
  &lt;merge&gt;
    &lt;title&gt;XMLmind Assembly Processor Manual&lt;/title&gt;
    &lt;author&gt;
      &lt;personname&gt;...&lt;/personname&gt;
      ...
  &lt;/merge&gt;
  &lt;module renderas="chapter" resourceref="intro"/&gt;
  &lt;module renderas="chapter" xml:id="installation"&gt;
    &lt;merge&gt;
      &lt;title&gt;Installing XMLmind Assembly Processor&lt;/title&gt;
    &lt;/merge&gt;
    &lt;module renderas="section" resourceref="requirements"/&gt;
    &lt;module renderas="section" resourceref="install"/&gt;
    ...
&lt;/structure&gt;</programlisting>

  <example xml:id="convert_manual_to_html">
    <title>Converting <filename>manual.xml</filename> to multi-page
    HTML</title>

    <para>First, generate a “flat”, monolithic, book out of assembly
    <filename>manual.xml</filename>. This equivalent “flat” document is called
    the <firstterm>realized</firstterm> document.</para>

    <screen>C:\XMLmind\assembly-2_0_5\docsrc&gt; ..\..\bin\assembly<co linkends="html_example_step1-1" xml:id="html_example_step1-1-co"/>¬
  -v<co linkends="html_example_step1-2" xml:id="html_example_step1-2-co"/> -format web<co linkends="html_example_step1-3" xml:id="html_example_step1-3-co"/>¬
  manual.xml out\manual_realized_web.xml<co linkends="html_example_step1-4" xml:id="html_example_step1-4-co"/></screen>

    <calloutlist>
      <callout arearefs="html_example_step1-1-co" xml:id="html_example_step1-1">
        <para>The assembly processor command-line utility is called
        <command>assembly</command> and is found in
        <filename><replaceable>assembly_install_dir</replaceable>/bin/</filename>.</para>
      </callout>

      <callout arearefs="html_example_step1-2-co" xml:id="html_example_step1-2">
        <para>Option <literal>-v</literal><indexterm class="singular">
            <primary sortas="v">-v, command-line option</primary>
          </indexterm> turns on the verbosity of
        <command>assembly</command>.</para>
      </callout>

      <callout arearefs="html_example_step1-3-co" xml:id="html_example_step1-3">
        <para>Option <literal>-format web</literal><indexterm class="singular">
            <primary sortas="format">-format, command-line option</primary>
          </indexterm> instructs <command>assembly</command> to target the
        "<literal>web</literal>" output format. Because the structure found in
        assembly <filename>manual.xml</filename> ends with:</para>

        <programlisting language="xml">    ...
  &lt;module renderas="index"&gt;
    <emphasis role="bold">&lt;filterout outputformat="web"/&gt;</emphasis>
  &lt;/module&gt;
&lt;/structure&gt;</programlisting>

        <para>this is used to exclude the index from the generated HTML
        pages.</para>
      </callout>

      <callout arearefs="html_example_step1-4-co" xml:id="html_example_step1-4">
        <para>The realized book is created in
        <filename>out/manual_realized_web.xml</filename>. You may want to open
        this file in a text or XML editor to see by yourself that it looks
        very much like a hand-written DocBook book.</para>
      </callout>
    </calloutlist>

    <para>Finally, convert <filename>out/manual_realized_web.xml</filename> to
    multi-page HTML using the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docbook.sourceforge.net/">DocBook XSL
    stylesheets.</link></para>

    <screen>C:\XMLmind\assembly-2_0_5\docsrc&gt; java -cp C:\...\saxon.jar¬
  com.icl.saxon.StyleSheet¬
  -o ..\..\doc\manual\index.html out\manual_realized_web.xml<co linkends="html_example_step2-1" xml:id="html_example_step2-1-co"/>¬
  C:\...\docbook-xsl-ns-1.79.1\html\chunk.xsl<co linkends="html_example_step2-2" xml:id="html_example_step2-2-co"/>¬
  base.dir=../../doc/manual/<co linkends="html_example_step2-3" xml:id="html_example_step2-3-co"/>¬
  chunk.section.depth=0¬
  section.autolabel=1¬
  section.label.includes.component.label=1¬
  use.id.as.filename=1</screen>

    <calloutlist>
      <callout arearefs="html_example_step2-1-co" xml:id="html_example_step2-1">
        <para><filename>out/manual_realized_web.xml</filename> is the file to
        be transformed to multi-page HTML.</para>
      </callout>

      <callout arearefs="html_example_step2-2-co" xml:id="html_example_step2-2">
        <para><filename>html/chunk.xsl</filename> is the XSLT stylesheet used
        to generate multi-page HTML.</para>
      </callout>

      <callout arearefs="html_example_step2-3-co" xml:id="html_example_step2-3">
        <para><parameter>base.dir</parameter>,
        <parameter>chunk.section.depth</parameter>, etc, are all parameters
        passed to the XSLT stylesheet. The HTML files are created in
        <filename>../../doc/manual/</filename> as specified by
        <parameter>base.dir</parameter>.</para>
      </callout>
    </calloutlist>

    <tip>
      <title>What if an assembly contains several structure?</title>

      <para>Assembly <filename>manual.xml</filename> contains only a single
      structure. However, an assembly may contain several structure. By
      default, <command>assembly</command> processes first found structure.
      Option
      <literal>-struct <replaceable>structure_ID</replaceable></literal><indexterm class="singular">
          <primary sortas="struct">-struct, command-line option</primary>
        </indexterm> allows to specify the <tag class="attribute">xml:id</tag>
      of the structure to be processed. In the case of the above example, we
      could have invoked "<literal>assembly -struct manual</literal>" because
      the structure found in assembly <filename>manual.xml</filename> starts
      with:</para>

      <programlisting>&lt;structure renderas="book" <emphasis role="bold">xml:id="manual"</emphasis>&gt;
  ...</programlisting>
    </tip>
  </example>

  <example xml:id="convert_manual_to_pdf">
    <title>Converting <filename>manual.xml</filename> to PDF</title>

    <para>First, generate a “flat”, monolithic, book out of assembly
    <filename>manual.xml</filename>. The realized book is created in
    <filename>out/manual_realized.xml</filename>.</para>

    <screen>C:\XMLmind\assembly-2_0_5\docsrc&gt; ..\..\bin\assembly -v¬
  manual.xml out\manual_realized.xml</screen>

    <para>Second, transform <filename>out/manual_realized.xml</filename>
    to<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xsl/"> XSL-FO</link> (a standard page
    description format) using XSLT stylesheet
    <filename>fo/docbook.xsl</filename>.</para>

    <screen>C:\XMLmind\assembly-2_0_5\docsrc&gt; java -cp C:\...\saxon.jar¬
  com.icl.saxon.StyleSheet¬
  -o out\manual_realized.fo out\manual_realized.xml¬
  C:\...\docbook-xsl-ns-1.79.1\fo\docbook.xsl¬
  paper.type=A4¬
  section.autolabel=1¬
  section.label.includes.component.label=1¬
  variablelist.as.blocks=1¬
  ulink.show=0¬
  shade.verbatim=1</screen>

    <para>Finally, convert the XSL-FO file to PDF using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlgraphics.apache.org/fop/">Apache FOP</link>. The PDF file
    is created in <filename>../../doc/manual/manual.pdf</filename>.</para>

    <screen>C:\XMLmind\assembly-2_0_5\docsrc&gt; C:\...\fop-2.9\fop¬
  -fo out\manual_realized.fo¬
  -pdf ..\..\doc\manual\manual.pdf</screen>
  </example>
</chapter><chapter version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/command_line.xml" xml:id="command_line">
  <info>
    <title>Command-line options</title>
  </info>

  <para>The <command>assembly</command> command-line utility (found in
  <filename><replaceable>assembly_install_dir</replaceable>/bin/</filename>)
  is auto-documented. Suffice to execute:</para>

  <screen>C:\assembly\bin&gt; assembly</screen>

  <para>in order to display the following help.</para>

  <bridgehead xml:id="command_line_usage">Usage</bridgehead>

  <synopsis><command>assembly</command> <replaceable>option</replaceable>* <replaceable>in_assembly_file</replaceable> <replaceable>out_docbook_file</replaceable>|<option>-</option></synopsis>

  <para>Processes a structure found in assembly file
  <replaceable>in_assembly_file</replaceable> and creates realized DocBook
  document in <replaceable>out_docbook_file</replaceable>.</para>

  <para>If <replaceable>out_docbook_file</replaceable> is specified as
  "<literal>-</literal>", then <replaceable>in_assembly_file</replaceable> is
  simply checked for errors.</para>

  <para>Options are:</para>

  <variablelist>
    <varlistentry>
      <term><option>-struct
      <replaceable>structure_id</replaceable></option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="struct">-struct, command-line option</primary>
          </indexterm>Specifies the <tag class="attribute">xml:id</tag> of the
        structure to be processed.</para>

        <para>By default, it's the first found structure.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-format
      <replaceable>output_format</replaceable></option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="format">-format, command-line option</primary>
          </indexterm>Specifies the target output format.</para>

        <para>By default, it's the default format of the processed structure
        if any, and the "<firstterm>implicit format</firstterm>" otherwise.
        The "implicit format" matches <tag class="element">output</tag>, <tag class="element">filterin</tag>, <tag class="element">filterout</tag>
        elements without any <tag class="attribute">outputformat</tag>
        attribute.</para>

        <para>Multiple output formats separated by "<literal>;</literal>" may
        be specified. For example, "<literal>EPUB;expert</literal>" means
        output format is "<literal>EPUB</literal>" <emphasis>or</emphasis>
        "<literal>expert</literal>".</para>
      </listitem>
    </varlistentry>

    <varlistentry xml:id="option_check">
      <term><option>-check</option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="v">-check, command-line option</primary>
          </indexterm>Check realized document for cross-reference errors,
        missing image resources, etc. This option reports warnings, not
        errors. Thus this option does not prevent the realized document from
        being saved to disk.</para>

        <note>
          <para>If your document requires <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sagehill.net/docbookxsl/Profiling.html">conditional
          processing</link> (that is, <firstterm>profiling</firstterm>), then
          the check step may report false errors. These false errors are
          caused by the fact that the conditional processing step has not been
          applied to the realized document prior to the check step.</para>

          <para>Example: two of the chapters referenced by assembly
          <filename>book.xml</filename> have
          <literal>xml:id="install"</literal>. First chapter has also
          <literal>os="windows"</literal>. Second chapter has also
          <literal>os="mac"</literal>.</para>

          <para>If you run <literal>assembly -check book.xml -</literal>,
          you'll get a duplicate ID warning caused by
          <literal>xml:id="install"</literal>.</para>

          <para>On the other hand, if you run
          <literal>assembly -check -profile os windows book.xml -</literal>,
          you'll not have this duplicate ID error. Why that? Because by
          applying profile <literal>os="windows"</literal>, second chapter
          (having <literal>os="mac"</literal>) is excluded from the realized
          document prior to checking it.</para>
        </note>
      </listitem>
    </varlistentry>

    <varlistentry xml:id="option_profile">
      <term><option>-profile <replaceable>attribute_name</replaceable>
      <replaceable>attribute_value</replaceable> </option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="version">-profile, command-line option</primary>
          </indexterm>Specifies a profiling attribute. One or more
        <option>-profile</option> options allows to specify the profile
        applied to the realized document prior to checking it. Specifying one
        or more <option>-profile</option> options is not useful unless you
        also use the <link linkend="option_check"><option>-check</option>
        option</link>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-v</option></term>

      <term><option>-vv</option></term>

      <term><option>-vvv</option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="v">-v, command-line option</primary>
          </indexterm><indexterm class="singular">
            <primary sortas="vv">-vv, command-line option</primary>

            <see>-v, command-line option</see>
          </indexterm><indexterm class="singular">
            <primary sortas="vvv">-vvv, command-line option</primary>

            <see>-v, command-line option</see>
          </indexterm>Turn verbosity on. More Vs means more verbose.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-version</option></term>

      <listitem>
        <para><indexterm class="singular">
            <primary sortas="version">-version, command-line option</primary>
          </indexterm>Print version number and exit.</para>
      </listitem>
    </varlistentry>
  </variablelist>

  <sidebar xml:id="using_xml_catalogs">
    <title>Using XML catalogs to resolve entities and URIs</title>

    <para>An assembly may reference <firstterm>virtual topics</firstterm>.
    Let's call virtual topics, topics which are not expressed in DocBook v5.1+
    and which need to be converted on the fly to DocBook v5.1+ before being
    added to the realized document. This facility is implemented by the means
    of the <tag class="element">transform</tag> element and the <tag class="attribute">grammar</tag> or <tag class="attribute">transform</tag>
    attributes of the <tag class="element">output</tag> element.</para>

    <para>These virtual topics often start with a <tag>DOCTYPE</tag>. DITA
    example:</para>

    <programlisting>&lt;!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN"
"http://docs.oasis-open.org/dita/v1.2/os/topic.dtd"&gt;
&lt;topic id="topic"&gt;
  &lt;title&gt;A DITA Topic&lt;/title&gt;
  ...</programlisting>

    <para>Unless you specify an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xerces.apache.org/xml-commons/components/resolver/resolver-article.html">XML catalog</link> pointing to
    a local copy of <filename>topic.dtd</filename>,
    <command>assembly</command> will download this DTD from
    <uri>http://docs.oasis-open.org/dita/v1.2/os/topic.dtd</uri>, which may
    take a while or even fail.</para>

    <para>XML catalogs are specified by the means of environment variable
    <envar>XML_CATALOG_FILES</envar><footnote>
        <para>Or equivalent <trademark>Java</trademark> system property
        <property>xml.catalog.files</property>.</para>
      </footnote>. This variable contains a semicolon-delimited list of
    catalog files or URIs. Windows example:</para>

    <screen>C:\&gt;set XML_CATALOG_FILES=..\..\ditac\schema\catalog.xml</screen>
  </sidebar>
</chapter><chapter xml:id="limitations_and_specificities"><info><title xml:base="file:/home/hussein/src/assembly/docsrc/manual/manual.xml" xml:lang="en-US">Limitations and implementation specificities</title></info><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/limitations.xml" xml:id="limitations">
  <info>
    <title>Limitations</title>
  </info>

  <itemizedlist>
    <listitem>
      <para>Attribute <tag class="attribute">type</tag> of element <tag class="element">structure</tag> is ignored.</para>
    </listitem>

    <listitem>
      <para>Element <tag class="element">relationships</tag> is supported.
      However attribute <tag class="attribute">type</tag> of elements <tag class="element">relationships</tag> and <tag class="element">relationship</tag> is still ignored.</para>
    </listitem>
  </itemizedlist>
<itemizedlist remap="relationship" spacing="compact"><title remap="association">Related information</title><listitem remap="instance"><para><xref linkend="specificities"/></para></listitem></itemizedlist></section><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/specificities.xml" xml:id="specificities">
  <info>
    <title>Implementation specificities</title>
  </info>

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

    <para>It's basically a feature which is implemented by <productname xml:base="intro.xml" xml:id="dbasm---dqrdu8">XMLmind Assembly
  Processor</productname> in way which is <emphasis>not
    100% conforming</emphasis> to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/"><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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/langRef/attributes/commonMapAttributes.html#topicref-atts__linking">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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceforge.net/projects/docbook/">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 <productname xml:base="intro.xml" xml:id="dbasm---dqrdu9">XMLmind Assembly
  Processor</productname>. However, in this case,
      <emphasis><productname xml:base="intro.xml" xml:id="dbasm---dqrdua">XMLmind Assembly
  Processor</productname> 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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/structure#element.db.structure"><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><productname xml:base="intro.xml" xml:id="dbasm---dqrdub">XMLmind Assembly
  Processor</productname> uses a built-in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/xinclude-11/">XInclude 1.1</link> processor
      rather than the XInclude 1.0 implementation provided by the XML parser
      (that is, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://xerces.apache.org/">Xerces</link>). Note that for
      now, this built-in XInclude 1.1 processor only supports the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/xptr-element/">XPointer element()
      scheme</link>.</para>
    </listitem>
  </itemizedlist>
<itemizedlist remap="relationship" spacing="compact"><title remap="association">Related information</title><listitem remap="instance"><para><xref linkend="limitations"/></para></listitem></itemizedlist><section version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/filtering.xml" xml:id="filtering">
  <info>
    <title>About filtering</title>
  </info>

  <itemizedlist>
    <listitem>
      <para>Element <tag class="element">filterin</tag> is best explained by
      an example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterin os="mac" userlevel="beginner;intermediate"/&gt;</programlisting>

      <para>The above example means: <emphasis>exclude</emphasis> from the
      contents of realized topic <tag class="attvalue">MyTopic</tag> all the
      elements having a <tag class="attribute">os</tag> attribute not
      containing <tag class="attvalue">mac</tag> and also exclude all the
      elements having a <tag class="attribute">userlevel</tag> attribute not
      containing <tag class="attvalue">beginner</tag> or <tag class="attvalue">intermediate</tag>.</para>

      <para>For those who know the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/">DocBook XSL
      stylesheets</link>, this is equivalent to passing parameters
      <literal>profile.os=mac</literal> and
      <literal>profile.userlevel=beginner;intermediate</literal> to the
      profiling stylesheets.</para>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

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

      <para>then paragraph <tag class="attvalue">p1</tag> and <tag class="attvalue">p3</tag> are excluded from the realized document while
      paragraphs <tag class="attvalue">p2</tag> and <tag class="attvalue">p4</tag> are not.</para>
    </listitem>

    <listitem>
      <para>Element <tag class="element">filterout</tag> is best explained by
      an example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterout os="mac" userlevel="beginner;intermediate"/&gt;</programlisting>

      <para>The above example means: exclude from the contents of realized
      topic <tag class="attvalue">MyTopic</tag> all the elements having a <tag class="attribute">os</tag> attribute containing <tag class="attvalue">mac</tag> and no other value and also exclude all the
      elements having a <tag class="attribute">userlevel</tag> attribute
      containing <tag class="attvalue">beginner</tag> and/or <tag class="attvalue">intermediate</tag> and no other value.</para>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

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

      <para>then paragraph <tag class="attvalue">p1</tag> and <tag class="attvalue">p3</tag> are excluded from the realized document while
      paragraphs <tag class="attvalue">p2</tag> and <tag class="attvalue">p4</tag> are not.</para>
    </listitem>

    <listitem>
      <para>It's possible to have both <tag class="element">filterin</tag> and
      <tag class="element">filterout</tag> elements for the same effectivity
      attribute. Example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterin os="windows;mac"/&gt;
&lt;filterout os="linux"/&gt;</programlisting>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

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

      <para>then paragraph <tag class="attvalue">p1</tag>, <tag class="attvalue">p3</tag> and <tag class="attvalue">p5</tag> are
      excluded from the realized document while paragraphs <tag class="attvalue">p2</tag> and <tag class="attvalue">p4</tag> are
      not.</para>
    </listitem>

    <listitem>
      <para>Just like <tag class="element">output</tag> elements, <tag class="element">filterin</tag> and <tag class="element">filterout</tag>
      elements are considered in order and relevant filters are combined. A
      <tag class="element">filterin</tag> or <tag class="element">filterout</tag> element is relevant if it does not have
      an <tag class="element">outputformat</tag> attribute or if its <tag class="element">outputformat</tag> attribute matches the output format
      passed as a parameter to the assembly processor.</para>
    </listitem>

    <listitem>
      <para>The sequence of <tag class="element">filterin</tag> and <tag class="element">filterout</tag> elements “inherited” from ancestor <tag class="element">structure</tag> and <tag class="element">module</tag>s
      and/or directly added to a <tag class="element">module</tag> is combined
      to form a single <tag class="element">filterin</tag> element and a
      single <tag class="element">filterout</tag> element. The resulting
      single <tag class="element">filterin</tag> element and single <tag class="element">filterout</tag> element are applied to the <tag class="element">module</tag>. Example:</para>

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

      <para>The above sequence is equivalent to:</para>

      <programlisting>&lt;filterin os="windows;mac" userlevel="intermediate;advanced"/&gt;
&lt;filterout os="linux" userlevel="beginner"/&gt;</programlisting>
    </listitem>
  </itemizedlist>
</section></section></chapter><chapter version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/embed.xml" xml:id="embed">
  <info>
    <title>Embedding XMLmind Assembly Processor in a Java™ application</title>
  </info>

  <procedure>
    <step>
      <para>Add
      <filename><replaceable>assembly_install_dir</replaceable>/lib/assembly.jar</filename>
      to your <envar>CLASSPATH</envar>.</para>

      <para>Optionally, if your assembly loads XML documents having a DTD
      (e.g. transform DITA topics to DocBook topics), also
      add<filename><replaceable>assembly_install_dir</replaceable>/lib/xmlresolver.jar</filename>
      to your <envar>CLASSPATH</envar>. File
      <filename>xmlresolver.jar</filename> contains <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/"/> an enhanced XML resolver
      with XML Catalog support.</para>
    </step>

    <step>
      <para>Create an instance of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/assembly/Processor.html">Processor</link>:</para>

      <programlisting>Processor processor = new Processor();</programlisting>

      <important>
        <para>Do not share this instance between different threads, as this
        class is <emphasis>not</emphasis> thread-safe.</para>
      </important>

      <para>If you don't want the error, warning and progress messages to be
      displayed on <literal>System.err</literal> and to
      <literal>System.out</literal>, implement interface <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/util/Console.html">Console</link> and pass an
      instance of your implementation to the constructor.</para>
    </step>

    <step>
      <para>Parameterize the processor by invoking either <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/assembly/Processor.html#configure(java.lang.String[])">configure(String[])</link> or
      individual configuration methods such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/assembly/Processor.html#setProcessedStructId(java.lang.String)">setProcessedStructId(String)</link>,
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/assembly/Processor.html#setOutputFormat(java.lang.String)">setOutputFormat(String)</link>,
      etc. Example:</para>

      <programlisting>int l = -1;
try {
    l = processor.configure(args);
} catch (IllegalArgumentException e) {
    <emphasis>// FATAL ERROR. DO SOMETHING HERE.</emphasis>
}

<emphasis>// PARSE THE REMAINING ARGUMENTS, IF ANY, 
// STARTING AT INDEX l.</emphasis></programlisting>
    </step>

    <step>
      <para>Finally invoke method <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/assembly/Processor.html#process(java.net.URL,java.io.File)">process(URL, File)</link>.
      Pass this method the input assembly URL and the output realized document
      save file.</para>

      <programlisting>try {
    if (!processor.process(inURL, outFile)) {
        <emphasis>// FATAL ERROR. DO SOMETHING HERE.
        // ERRORS HAVE BEEN DISPLAYED ON THE <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../api/com/xmlmind/util/Console.html">Console</link>.</emphasis>
    }
} catch (IOException e) 
    // FATAL ERROR. DO SOMETHING HERE.
}</programlisting>
    </step>
  </procedure>
</chapter><appendix version="5.2" xml:base="file:/home/hussein/src/assembly/docsrc/manual/changes.xml" xml:id="changes">
  <info>
    <title>History of changes</title>
  </info>

  <bridgehead xml:id="v2.0.5">v2.0.5 (April 18, 2026)</bridgehead>

  <itemizedlist>
    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrduc">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 26
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v2.0.4">v2.0.4 (September 24, 2025)</bridgehead>

  <itemizedlist spacing="compact">
    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdud">XMLmind Assembly
  Processor</productname> now requires Java™
      11+ in order to compile and run.</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdue">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 25
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v2.0.3">v2.0.3 (June 27, 2025)</bridgehead>

  <itemizedlist spacing="compact">
    <listitem>
      <para>Updated <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.3.3.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v2.0.2">v2.0.2 (March 31, 2025)</bridgehead>

  <itemizedlist spacing="compact">
    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.3.0.</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrduf">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 24
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v2.0.1">v2.0.1 (August 19, 2024)</bridgehead>

  <itemizedlist spacing="compact">
    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.2.5.</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdug">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 22
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v2.0.0">v2.0.0 (February 21, 2024)</bridgehead>

  <para>Now supports processing <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/">DocBook 5.2</link> documents
  (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oasis-open.org/docbook/docbook/v5.2/os/docbook-v5.2-os.html">new <abbrev>OASIS</abbrev>
  Standard: "<citetitle>The DocBook Schema Version
  5.2</citetitle>"</link>).</para>

  <important>
    <para>Some of the following changes are <emphasis>breaking
    changes</emphasis>, so make sure to read <link linkend="porting_to_dbasm2">"How to “port” your assemblies to
    <productname xml:base="intro.xml" xml:id="dbasm---dqrduh">XMLmind Assembly
  Processor</productname> v2"</link>.</para>
  </important>

  <para>The following changes were made after reading the clarifications found
  in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/"><citetitle>DocBook 5.2: The
  Definitive Guide</citetitle></link>:</para>

  <itemizedlist>
    <listitem>
      <para>Support of attribute <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/resource"><tag class="element">resource</tag></link>/@<tag class="attribute">transform</tag> when attribute <tag class="element">resource</tag>/@<tag class="attribute">grammar</tag> is
      not specified.</para>
    </listitem>

    <listitem>
      <para>Attribute <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/output"><tag class="element">output</tag></link>/@<tag class="attribute">grammar</tag> has been removed from DocBook 5.2.
      <productname xml:base="intro.xml" xml:id="dbasm---dqrdui">XMLmind Assembly
  Processor</productname> still supports it for
      compatibility with DocBook 5.1 but reports a warning when <tag class="element">output</tag>/@<tag class="attribute">grammar</tag> is
      specified.</para>
    </listitem>

    <listitem>
      <para>A <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/module"><tag class="element">module</tag></link> in a larger <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/structure"><tag class="element">structure</tag></link> 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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/structure#element.db.structure"><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>
    </listitem>

    <listitem>
      <para>When attribute <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/assembly"><tag class="element">assembly</tag></link>/@<tag class="attribute">version</tag> is missing, <productname xml:base="intro.xml" xml:id="dbasm---dqrduj">XMLmind Assembly
  Processor</productname> now
      generates a realized document having a root element with attribute <tag class="attribute">version</tag>=<tag class="attvalue">5.2</tag>. In
      previous versions, the value of added <tag class="attribute">version</tag> attribute was <tag class="attvalue">5.1</tag>.</para>
    </listitem>

    <listitem>
      <para><anchor xml:id="merge_meta_information"/><emphasis role="bold">Breaking change</emphasis>. 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. Only element <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/merge"><tag class="element">merge</tag></link> may used to add or replace child
      elements in the <tag class="element">info</tag> of the corresponding
      realized element.</para>
    </listitem>

    <listitem>
      <para><anchor xml:id="merge_common_attributes"/><emphasis role="bold">Breaking change</emphasis>. Common attributes (<tag class="attribute">xml:id</tag>, <tag class="attribute">xml:lang</tag>,
      <tag class="attribute">xreflabel</tag>, etc) found on <tag class="element">module</tag> or <tag class="element">structure</tag>
      <emphasis>do not contribute</emphasis> to the realized document. Only
      common attributes found on <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/merge"><tag class="element">merge</tag></link> are copied to the corresponding
      realized element, possibly replacing the same common attributes already
      set on the resource.</para>
    </listitem>

    <listitem>
      <para><anchor xml:id="contentonly_implies_omittitles"/><emphasis role="bold">Breaking change</emphasis>. In previous versions, attribute
      <tag class="element">module</tag>/@<tag class="attribute">contentonly</tag>=<tag class="attvalue">true</tag>
      always implied <tag class="element">module</tag>/@<tag class="attribute">omittitles</tag>=<tag class="attvalue">true</tag>.
      While being almost always what's the author wants to do, this does not
      correspond to the documentation of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.2/merge"><tag class="element">merge</tag></link> element.</para>
    </listitem>
  </itemizedlist>

  <para><anchor xml:id="porting_to_dbasm2"/><emphasis role="bold">How to
  “port” your assemblies to <productname xml:base="intro.xml" xml:id="dbasm---dqrduk">XMLmind Assembly
  Processor</productname>
  v2:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>Convert your <tag class="element">structure</tag>/<tag class="element">info</tag> (resp. <tag class="element">module</tag>/<tag class="element">info</tag>) to <tag class="element">structure</tag>/<tag class="element">merge</tag> (resp. <tag class="element">module</tag>/<tag class="element">merge</tag>). See
      corresponding <link linkend="merge_meta_information">breaking
      change</link>.</para>

      <para>What follows used to work with <productname xml:base="intro.xml" xml:id="dbasm---dqrdul">XMLmind Assembly
  Processor</productname> v1:</para>

      <programlisting>&lt;module renderas="section"&gt;
  <emphasis role="bold">&lt;info&gt;</emphasis>&lt;title&gt;Title of the section&lt;/title&gt;<emphasis role="bold">&lt;/info&gt;</emphasis> ...</programlisting>

      <para>The following change is needed to make it work with <productname xml:base="intro.xml" xml:id="dbasm---dqrdum">XMLmind Assembly
  Processor</productname> v2:</para>

      <programlisting>&lt;module renderas="section"&gt;
  <emphasis role="bold">&lt;merge&gt;</emphasis>&lt;title&gt;Title of the section&lt;/title&gt;<emphasis role="bold">&lt;/merge&gt;</emphasis> ...</programlisting>
    </listitem>

    <listitem>
      <para>If you want to specify the <tag class="attribute">xml:id</tag> of
      the realized element corresponding to a <tag class="element">module</tag> having no <tag class="attribute">resourceref</tag> attribute, add this <tag class="attribute">xml:id</tag> to the <tag class="element">merge</tag>
      child element of the <tag class="element">module</tag> and not to the
      <tag class="element">module</tag> itself. See corresponding <link linkend="merge_common_attributes">breaking change</link>.</para>

      <para>What follows used to work with <productname xml:base="intro.xml" xml:id="dbasm---dqrdun">XMLmind Assembly
  Processor</productname> v1:</para>

      <programlisting>&lt;module renderas="section" <emphasis role="bold">xml:id="section_id"</emphasis>&gt; 
  &lt;merge&gt;&lt;title&gt;Title of the section&lt;/title&gt;&lt;/merge&gt; ...</programlisting>

      <para>The following change is needed to make it work with <productname xml:base="intro.xml" xml:id="dbasm---dqrduo">XMLmind Assembly
  Processor</productname> v2:</para>

      <programlisting>&lt;module renderas="section"&gt; 
  &lt;merge <emphasis role="bold">xml:id="section_id"</emphasis>&gt;
    &lt;title&gt;Title of the section&lt;/title&gt;
  &lt;/merge&gt; ...</programlisting>
    </listitem>

    <listitem>
      <para>Add attribute <tag class="attribute">omittitles</tag>=<tag class="attvalue">true</tag> to your <tag class="element">module</tag>s
      having <tag class="attribute">contentonly</tag>=<tag class="attvalue">true</tag>. See corresponding <link linkend="contentonly_implies_omittitles">breaking change</link>.</para>

      <para>What follows used to work with <productname xml:base="intro.xml" xml:id="dbasm---dqrdup">XMLmind Assembly
  Processor</productname> v1:</para>

      <programlisting>&lt;module renderas="section"&gt;
  &lt;info&gt;&lt;title&gt;Title of the section&lt;/title&gt;&lt;/info&gt;
  &lt;module <emphasis role="bold">omittitles=true</emphasis> resourceref="t1" /&gt; ...</programlisting>

      <para>The following change is needed to make it work with <productname xml:base="intro.xml" xml:id="dbasm---dqrduq">XMLmind Assembly
  Processor</productname> v2:</para>

      <programlisting>&lt;module renderas="section"&gt;
  &lt;merge&gt;&lt;title&gt;Title of the section&lt;/title&gt;&lt;/merge&gt;
  &lt;module <emphasis role="bold">omittitles=true</emphasis> <emphasis role="bold">contentonly=true</emphasis> resourceref="t1" /&gt; ...</programlisting>
    </listitem>
  </itemizedlist>

  <para><emphasis role="bold">Other enhancements:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.2.3.</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdur">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 21
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.3.3">v1.3.3 (September 15, 2023)</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.2.1.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.3.2">v1.3.2 (July 13, 2023)</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.2.0.</para>
    </listitem>

    <listitem>
      <para>Modified the language fixup of the XInclude 1.1 implementation in
      order to support the <literal>lang</literal> attribute in lieu of or in
      addition to the <literal>xml:lang</literal> attribute. This allows to
      use this XInclude 1.1 implementation to process DocBook 4 or XHTML
      documents. (Note that this XInclude 1.1 implementation already supported
      the <literal>id</literal> attribute in lieu of the
      <literal>xml:id</literal> attribute.)</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.3.1">v1.3.1 (April 20, 2023)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdus">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 20
  platforms.</para>

  <bridgehead xml:id="v1.3.0">v1.3 (March 8, 2023)</bridgehead>

  <itemizedlist>
    <listitem>
      <para><emphasis role="bold">Bug fix:</emphasis> made the language fixup
      of the XInclude 1.1 implementation more conforming to the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/xinclude-11/#language">specification</link>.</para>
    </listitem>

    <listitem>
      <para>Upgraded <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link> to version
      5.1.1.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.2.0">v1.2 (December 5, 2022)</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Replaced the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xerces.apache.org/xml-commons/">Apache Commons
      Resolver</link> (<filename>lib/resolver.jar</filename>) by the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://xmlresolver.org/">XMLResolver</link>
      (<filename>lib/xmlresolver.jar</filename>).</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdut">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 19
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.1.1">v1.1.1 (April 12, 2022)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrduu">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 18
  platforms.</para>

  <bridgehead xml:id="v1.1.0">v1.1 (November 15, 2021)</bridgehead>

  <itemizedlist>
    <listitem>
      <para>Some internal changes were needed to make <productname xml:base="intro.xml" xml:id="dbasm---dqrduv">XMLmind Assembly
  Processor</productname> compatible with XMLmind XML
      Editor v10+.</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrduw">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>on Java™ 17 platforms;</para>
        </listitem>

        <listitem>
          <para>on macOS Monterey (version 12.0), including on Macs having an
          Apple M1 (ARM-based) processor;</para>
        </listitem>

        <listitem>
          <para>on Windows 11.</para>
        </listitem>
      </itemizedlist>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.0.12">v1.0.12 (May 14, 2021)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdux">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 16
  platforms.</para>

  <bridgehead xml:id="v1.0.11">v1.0.11 (November 30, 2020)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrduy">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 15
  platforms.</para>

  <bridgehead xml:id="v1.0.10">v1.0.10 (July 23, 2020)</bridgehead>

  <itemizedlist>
    <listitem>
      <para><emphasis role="bold">Bug fix:</emphasis> <productname xml:base="intro.xml" xml:id="dbasm---dqrduz">XMLmind Assembly
  Processor</productname> reported "<literal>missing
      child element &lt;info&gt;</literal>" warning for assembly elements like
      <literal>&lt;module renderas="index"/&gt;</literal>.
      (<literal>&lt;module renderas="index"/&gt;</literal> is realized as a
      DocBook <tag class="element">index</tag> element and an <tag class="element">index</tag> element is not required to start with an
      <tag class="element">info</tag> element or to have a title.)</para>
    </listitem>

    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv0">XMLmind Assembly
  Processor</productname>, which passed all
      non-regression tests, is now officially supported on Java™ 14
      platforms.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.0.9">v1.0.9 (February 26, 2020)</bridgehead>

  <para>The <filename>itemizedlist</filename> which is automatically generated
  to represent relationships between topics has now attribute
  <literal>spacing="compact"</literal>.</para>

  <bridgehead xml:id="v1.0.8">v1.0.8 (January 16, 2020)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv1">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 13
  platforms.</para>

  <bridgehead xml:id="v1.0.7_01">v1.0.7_01 (May 17, 2019)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv2">XMLmind Assembly
  Processor</productname> now requires a Java 8+ runtime
  in order to compile and run.</para>

  <bridgehead xml:id="v1.0.7">v1.0.7 (March 25, 2019)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv3">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 12
  platforms.</para>

  <bridgehead xml:id="v1.0.6">v1.0.6 (November 27, 2018)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv4">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 11
  platforms.</para>

  <bridgehead xml:id="v1.0.5">v1.0.5 (August 21, 2018)</bridgehead>

  <para>Minor internal changes needed to make <productname xml:base="intro.xml" xml:id="dbasm---dqrdv5">XMLmind Assembly
  Processor</productname> compatible
  with XMLmind XML Editor v8.2.</para>

  <bridgehead xml:id="v1.0.4">v1.0.4 (May 22, 2018)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv6">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 10
  platforms.</para>

  <bridgehead xml:id="v1.0.3">v1.0.3 (February 24, 2018)</bridgehead>

  <para>Minor internal changes needed to make <productname xml:base="intro.xml" xml:id="dbasm---dqrdv7">XMLmind Assembly
  Processor</productname> compatible
  with XMLmind XML Editor v8.</para>

  <bridgehead xml:id="v1.0.2_01">v1.0.2_01 (December 11, 2017)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv8">XMLmind Assembly
  Processor</productname>, which passed all
  non-regression tests, is now officially supported on Java™ 9
  platforms.</para>

  <bridgehead xml:id="v1.0.2">v1.0.2 (June 09, 2017)</bridgehead>

  <para>Changed "Licensor" from "Pixware SARL" to "XMLmind Software" in all
  licenses.</para>

  <bridgehead xml:id="v1.0.1">v1.0.1 (March 06, 2017)</bridgehead>

  <para><emphasis role="bold">Bug fixes:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>Info elements copied from the assembly to the realized document
      were not given proper <tag class="attribute">xml:base</tag> and <tag class="attribute">xml:lang</tag> attributes.</para>

      <para>In practice, due to this bug, it was not possible to successfully
      convert to other formats an assembly where some <tag class="element">info</tag> elements contained <tag class="element">imagedata</tag>.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v1.0.0">v1.0.0 (December 22, 2016)</bridgehead>

  <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdv9">XMLmind Assembly
  Processor</productname> v1.0 is the first version to
  fully support processing <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tdg.docbook.org/tdg/5.1/ch06.html">DocBook 5.1 assemblies</link>.
  This includes <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/xinclude-11/">XInclude 1.1</link>, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.org/docs/transclusion/">DocBook Transclusion</link> and
  assembly features such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tdg.docbook.org/tdg/5.1/relationships.html"><tag class="element">relationships</tag></link> and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tdg.docbook.org/tdg/5.1/transforms.html"><tag class="element">transforms</tag></link>.</para>

  <para><emphasis role="bold">Enhancements:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>Element <tag class="element">relationships</tag> is now processed.
      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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/langRef/attributes/commonMapAttributes.html#topicref-atts__linking">the corresponding <tag class="attribute">linking</tag> attribute of DITA</link>. Attribute <tag class="attribute">type</tag> of elements <tag class="element">relationships</tag> and <tag class="element">relationship</tag> is still ignored.</para>
    </listitem>
  </itemizedlist>

  <para><emphasis role="bold">Bug fixes:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>The <tag class="element">revhistory</tag> child of the <tag class="element">structure</tag> element was ignored.</para>
    </listitem>
  </itemizedlist>

  <para><emphasis role="bold">Incompatibilities:</emphasis></para>

  <itemizedlist>
    <listitem>
      <para>Attribute <tag class="attribute">omittitles</tag> now discards
      <tag class="element">title</tag>, <tag class="element">titleabbrev</tag>, <tag class="element">subtitle</tag>
      from the included resource. Previously, setting this attribute to <tag class="attvalue">true</tag> discarded all the metadata just like
      <literal>contentonly="true"</literal>.</para>
    </listitem>

    <listitem>
      <para>In <tag class="element">structure</tag> and in <tag class="element">module</tag>, <tag class="element">info</tag> and <tag class="element">merge</tag> are used in the same way. These elements may
      be used to add or replace metadata in the realized <tag class="element">structure</tag> or <tag class="element">module</tag>.</para>
    </listitem>

    <listitem>
      <para>The implementation of <tag class="element">filterin</tag> and <tag class="element">filterout</tag> is completely different from what it was
      in previous versions. More information in <xref linkend="filtering"/>.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v0.9.4">v0.9.4 (February 16, 2016)</bridgehead>

  <itemizedlist>
    <listitem>
      <para><productname xml:base="intro.xml" xml:id="dbasm---dqrdva">XMLmind Assembly
  Processor</productname> can now check the realized
      document for cross-reference errors, missing image resources, etc. This
      is done by passing new <option>-check</option> option to the
      <command>assembly</command> command-line.</para>

      <para>Note that if your document requires <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sagehill.net/docbookxsl/Profiling.html">conditional processing</link>
      (that is, <firstterm>profiling</firstterm>), then this check step may
      report false errors. These false errors are caused by the fact that the
      conditional processing step has not been applied to the realized
      document prior to the check step.</para>

      <para>New option <option>-profile</option> allows to specify a profiling
      attribute. Therefore passing one or more <option>-profile</option>
      options to the <command>assembly</command> command-line allows to apply
      a profile to the realized document prior to checking it.</para>

      <para>Example: two of the chapters referenced by assembly
      <filename>book.xml</filename> have <literal>xml:id="install"</literal>.
      First chapter has also <literal>os="windows"</literal>. Second chapter
      has also <literal>os="mac"</literal>.</para>

      <para>If you run <literal>assembly -check book.xml -</literal>, you'll
      get a duplicate ID warning caused by
      <literal>xml:id="install"</literal>.</para>

      <para>On the other hand, if you run
      <literal>assembly -check -profile os windows book.xml -</literal>,
      you'll not have this duplicate ID error. Why that? Because by applying
      profile <literal>os="windows"</literal>, second chapter (having
      <literal>os="mac"</literal>) is excluded from the realized document
      prior to checking it.</para>
    </listitem>

    <listitem>
      <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.org/docs/transclusion/">DocBook 5 Transclusion
      Processor</link>: removed <tag class="attribute">targetptr</tag> from
      the IDREF-list.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v0.9.3">v0.9.3 (February 03, 2016)</bridgehead>

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

    <listitem>
      <para>Now uses a built-in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.org/docs/transclusion/">DocBook 5 Transclusion
      Processor</link> to process <tag class="attribute">trans:idfixup</tag>,
      <tag class="attribute">trans:suffix</tag> and <tag class="attribute">trans:linkscope</tag> attributes possibly set on <tag class="element">xi:include</tag> elements.</para>
    </listitem>
  </itemizedlist>

  <bridgehead xml:id="v0.9.2">v0.9.2 (January 22, 2016)</bridgehead>

  <para>Bug fix: in some cases, a processing-instruction was moved (in the
  realized document) to the beginning of the element containing it and this,
  no matter its actual location within this parent element.</para>

  <bridgehead xml:id="v0.9.1">v0.9.1 (September 8, 2015)</bridgehead>

  <para>Minor internal changes.</para>

  <bridgehead xml:id="v0.9.0">v0.9.0 (June 24, 2015)</bridgehead>

  <para>First release.</para>
</appendix><index xml:id="back_of_book_index"><info/></index></book>