<?xml version="1.0" encoding="UTF-8"?>
<topic version="5.2" xml:id="command_line"
       xmlns="http://docbook.org/ns/docbook">
  <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
          xlink:href="http://www.sagehill.net/docbookxsl/Profiling.html"
          xmlns:xlink="http://www.w3.org/1999/xlink">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
    xlink:href="https://xerces.apache.org/xml-commons/components/resolver/resolver-article.html"
    xmlns:xlink="http://www.w3.org/1999/xlink">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>
</topic>
