File assembly.xml of Package xmlmind-assembly
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="/usr/share/xml/docbook/schema/rng/5.1/docbook.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="/usr/share/xml/docbook/schema/rng/5.1/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<refentry version="5.1" xml:id="assembly"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://docbook.org/ns/docbook">
<info>
<authorgroup>
<author>
<personname>
<firstname>Hussein</firstname>
<surname>Shafie</surname>
</personname>
<affiliation>
<orgname>XMLmind Software</orgname>
</affiliation>
<contrib>Developer</contrib>
</author>
<author>
<personname>
<firstname>Thomas</firstname>
<surname>Schraitle</surname>
</personname>
<contrib>Manpage</contrib>
</author>
</authorgroup>
</info>
<refmeta>
<refentrytitle>assembly</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">assembly</refmiscinfo>
</refmeta>
<refnamediv>
<refname>assembly</refname>
<refpurpose>Process DocBook <tag>assembly</tag> Elements</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<cmdsynopsis><command>assembly</command>
<arg choice="opt">OPTIONS </arg>
<arg choice="plain">ASSEMBLY</arg>
<arg choice="plain">DOCBOOK_OUTPUT</arg>
</cmdsynopsis>
<para><replaceable>OPTIONS</replaceable> are:</para>
<variablelist>
<varlistentry>
<term><option>-struct
<replaceable>structure_id</replaceable></option></term>
<listitem>
<para>
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>Specifies the target output format.</para>
<para>By default, it's the default format of the processed structure
if any, and the <quote><firstterm>implicit format</firstterm></quote> 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>
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">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 <command>assembly -check book.xml -</command>,
you'll get a duplicate ID warning caused by
<literal>xml:id="install"</literal>.</para>
<para>On the other hand, if you run
<command>assembly -check -profile os windows book.xml -</command>,
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>
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>Turn verbosity on. More Vs means more verbose.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-version</option></term>
<listitem>
<para>Print version number and exit.</para>
</listitem>
</varlistentry>
</variablelist>
</refsynopsisdiv>
<refsect1 xml:id="sec.intro">
<title>What is XMLmind Assembly Processor?</title>
<para>XMLmind Assembly Processor is a <trademark>Java</trademark> software
component and a command-line utility (called <command>assembly</command>)
which processes a <link xlink:href="http://tdg.docbook.org/tdg/5.1/ch06.html"
>DocBook v5.1 <tag>assembly</tag></link> and all the referenced topics in
order to create the equivalent <quote>flat</quote>, monolithic, document
(e.g. a DocBook v5.1 <tag>book</tag>). This equivalent document is called
the <firstterm>realized document</firstterm>.</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
xlink:href="http://docbook.sourceforge.net/"
>DocBook XSL stylesheets</link>.</para>
<para>As of v0.9.3, XMLmind Assembly Processor includes <link
xlink:href="https://www.w3.org/TR/xinclude-11/">XInclude 1.1</link> and
<link xlink:href="http://docbook.org/docs/transclusion/"
>DocBook Transclusion</link> processors, which allows to create modular
DocBook v5.1 documents without facing limitations. </para>
<para>XMLmind Assembly Processor is free, open source, software, which like
the DocBook XSL stylesheets, is licensed under the terms of the MIT License.
</para>
</refsect1>
<refsect1 xml:id="sec.why.dbassemblies">
<title>Why create DocBook assemblies and topics?</title>
<para>DocBook 5.1 introduces two new elements: <tag>assembly</tag> and
<tag>topic</tag>. These elements allows to author large, modular,
documents. Such documents are generally created and maintained over years by
a team of technical writers rather than by a single person. Such documents
generally share a large number of topics. That is, in such documents, most
topics may be seen as reusable parts. </para>
<para> For example, let's suppose a automobile manufacturer created two
assemblies. The first one is a repair manual for automobile model A
comprising 753 topics and the second one is a repair manual for automobile
model B comprising 825 topics. These two repair manuals are expected to have
a large number of topics in common, for example a topic explaining how to
replace the battery of the car.</para>
</refsect1>
<refsect1 xml:id="sec.what-is-a-topic">
<title>What is a Topic?</title>
<para>A <link xlink:href="http://tdg.docbook.org/tdg/5.1/topic.html">topic
element</link> is a semantically neutral container having a content model
similar the one of the chapter element. </para>
<para> A <tag>topic</tag> element is always stored in its own file. </para>
<para> In terms of content, a <tag>topic</tag> element is expected to deal with a single
topic and to be very loosely coupled, if not at all, to other <tag>topic</tag>
elements. For example, avoid creating cross-references (xref, link) between
topic A and topic B. </para>
<para> In this tutorial, we'll use <tag>assembly</tag> elements which
reference <tag>topic</tag> elements exclusively. In fact, any DocBook
container (<tag>chapter</tag>, <tag>section</tag>, <tag>appendix</tag>, etc)
may act as a topic—some contents dealing about a single topic stored in its
one file— and as such, be referenced in assemblies.</para>
</refsect1>
<refsect1 xml:id="sec.what-is-an-assembly">
<title>What is an Assembly?</title>
<para> A DocBook 5.1 <tag
xlink:href="http://tdg.docbook.org/tdg/5.1/assembly.html">assembly</tag>
specifies how to create a plain, <quote>normal</quote>, DocBook document (e.g. a book)
out of contents <quote>pulled</quote> from topic files. </para>
<para> The <quote>normal</quote> DocBook document created by the means of an
assembly is called the <emphasis>realized document</emphasis>. </para>
<para>The main elements of an <tag>assembly</tag> are <tag>structure</tag>
and <tag>module</tag>:</para>
<itemizedlist>
<listitem>
<para>A <tag xlink:href="http://tdg.docbook.org/tdg/5.1/structure.html"
>structure</tag> element specifies the contents of the realized document.
It contains a number of possibly nested module elements.</para>
</listitem>
<listitem>
<para>A <tag xlink:href="http://tdg.docbook.org/tdg/5.1/module.html"
>module</tag> element specifies which contents is to be
<quote>pulled</quote> from the topic file and how this contents is then
copied into the realized document.</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 xml:id="sec.limitations">
<title>Limitations</title>
<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>
</refsect1>
<refsect1 xml:id="sec.moreinfo">
<title>For More Information</title>
<itemizedlist>
<listitem>
<para><link xlink:href="http://xmlmind.com/tutorials/DocBookAssemblies/index.html">DocBook Assemblies and Topics for the Impatient</link> from <personname>
<firstname>Hussein</firstname><surname>Shaffei</surname>
</personname>; most of this manpage is coming from this source.
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://tdg.docbook.org/tdg/5.1/ch06.html">DocBook Assemblies</link>
from <citetitle>The Definitive Guide</citetitle>.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>
