Chapter 3. Getting started
Prev |  | Next

# Chapter 3. Getting started

### What if you just want to quickly experiment with DocBook assemblies and topics?

The simplest is to download and install XMLmind XML Editor Evaluation Edition from https://www.xmlmind.com/xmleditor/download.shtml.

You can then open this document —"XMLmind Assembly Processor Manual", an assembly found in ``assembly_install_dir`/docsrc/manual.xml`— in XMLmind XML Editor and use menu Assembly → Convert Document to convert it to any format you want.

Figure 3.1. This assembly `manual.xml` opened in XMLmind XML Editor

In order to explain how XMLmind Assembly Processor is used, we'll convert this document —"XMLmind Assembly Processor Manual", an assembly found in ``assembly_install_dir`/docsrc/manual.xml`— first to multi-page HTML and then to PDF.

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

Assembly `manual.xml` contains a `structure` specifying a book. The content of the chapters and sections of this book is obtained from topics such as `intro.xml`, `requirements.xml`, `install.xml`, etc.

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

Example 3.1. Converting `manual.xml` to multi-page HTML

First, generate a “flat”, monolithic, book out of assembly `manual.xml`. This equivalent “flat” document is called the realized document.

    C:\XMLmind\assembly-2_0_5\docsrc> ..\..\bin\assembly(1)¬
      -v(2) -format web(3)¬
      manual.xml out\manual_realized_web.xml(4)

(1) | The assembly processor command-line utility is called assembly and is found in ``assembly_install_dir`/bin/`.
(2) | Option `-v` turns on the verbosity of assembly.
(3) | Option `-format web` instructs assembly to target the "`web`" output format. Because the structure found in assembly `manual.xml` ends with:
        ...
      <module renderas="index">
        <filterout outputformat="web"/>
      </module>
    </structure>
this is used to exclude the index from the generated HTML pages.
(4) | The realized book is created in `out/manual_realized_web.xml`. 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.

Finally, convert `out/manual_realized_web.xml` to multi-page HTML using the DocBook XSL stylesheets.

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

(1) | `out/manual_realized_web.xml` is the file to be transformed to multi-page HTML.
(2) | `html/chunk.xsl` is the XSLT stylesheet used to generate multi-page HTML.
(3) | `base.dir`, `chunk.section.depth`, etc, are all parameters passed to the XSLT stylesheet. The HTML files are created in `../../doc/manual/` as specified by `base.dir`.

### What if an assembly contains several structure?

Assembly `manual.xml` contains only a single structure. However, an assembly may contain several structure. By default, assembly processes first found structure. Option `-struct `structure_ID`` allows to specify the `xml:id` of the structure to be processed. In the case of the above example, we could have invoked "`assembly -struct manual`" because the structure found in assembly `manual.xml` starts with:

    <structure renderas="book" xml:id="manual">
      ...

Example 3.2. Converting `manual.xml` to PDF

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

    C:\XMLmind\assembly-2_0_5\docsrc> ..\..\bin\assembly -v¬
      manual.xml out\manual_realized.xml

Second, transform `out/manual_realized.xml` to XSL-FO (a standard page description format) using XSLT stylesheet `fo/docbook.xsl`.

    C:\XMLmind\assembly-2_0_5\docsrc> 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

Finally, convert the XSL-FO file to PDF using Apache FOP. The PDF file is created in `../../doc/manual/manual.pdf`.

    C:\XMLmind\assembly-2_0_5\docsrc> C:\...\fop-2.9\fop¬
      -fo out\manual_realized.fo¬
      -pdf ..\..\doc\manual\manual.pdf

Prev |  | Next
Chapter 2. Installing XMLmind Assembly Processor | Home | Chapter 4. Command-line options