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_1\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_1\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_1\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_1\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_1\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