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

  <tip trans:idfixup="suffix" trans:suffix="_tip" xml:id="install_xxe"
       xmlns:trans="http://docbook.org/ns/transclusion">
    <title>What if you just want to quickly experiment with DocBook assemblies
    and topics?</title>

    <para xml:id="download_xxe">The simplest is to download and install
    XMLmind XML Editor Evaluation Edition from <link
    xlink:href="https://www.xmlmind.com/xmleditor/download.shtml"
    xmlns:xlink="http://www.w3.org/1999/xlink">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
    xlink:href="https://www.xmlmind.com/xmleditor/_distrib/doc/assembly/dbasm_convert_menu.html"
    xmlns:xlink="http://www.w3.org/1999/xlink"><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 <xi:include href="intro.xml" xpointer="dbasm"
  xmlns:xi="http://www.w3.org/2001/XInclude"/> 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 xlink:href="../../docsrc/manual/manual.xml"
  xmlns:xlink="http://www.w3.org/1999/xlink"><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 xlink:href="../../docsrc/manual/intro.xml"
  xmlns:xlink="http://www.w3.org/1999/xlink"><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
    xlink:href="https://docbook.sourceforge.net/"
    xmlns:xlink="http://www.w3.org/1999/xlink">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 xlink:href="http://www.w3.org/TR/xsl/"
    xmlns:xlink="http://www.w3.org/1999/xlink"> 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
    xlink:href="https://xmlgraphics.apache.org/fop/"
    xmlns:xlink="http://www.w3.org/1999/xlink">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>
</topic>
