Name

assembly — Process DocBook assembly Elements

Synopsis

assembly [OPTIONS ] ASSEMBLY DOCBOOK_OUTPUT

OPTIONS are:

-struct structure_id

Specifies the xml:id of the structure to be processed.

By default, it's the first found structure.

-format OUTPUT_FORMAT

Specifies the target output format.

By default, it's the default format of the processed structure if any, and the “implicit format” otherwise. The "implicit format" matches output, filterin, filterout elements without any outputformat attribute.

Multiple output formats separated by ; may be specified. For example, EPUB;expert means output format is EPUB or expert.

-check

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.

Note

If your document requires conditional processing (that is, profiling), 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.

Example: two of the chapters referenced by assembly book.xml have xml:id="install". First chapter has also os="windows". Second chapter has also os="mac".

If you run assembly -check book.xml -, you'll get a duplicate ID warning caused by xml:id="install".

On the other hand, if you run assembly -check -profile os windows book.xml -, you'll not have this duplicate ID error. Why that? Because by applying profile os="windows", second chapter (having os="mac") is excluded from the realized document prior to checking it.

-profile ATTRIBUTE_NAME ATTRIBUTE_VALUE

Specifies a profiling attribute. One or more -profile options allows to specify the profile applied to the realized document prior to checking it. Specifying one or more -profile options is not useful unless you also use the -check option.

-v, -vv, -vvv

Turn verbosity on. More Vs means more verbose.

-version

Print version number and exit.

What is XMLmind Assembly Processor?

XMLmind Assembly Processor is a Java™ software component and a command-line utility (called assembly) which processes a DocBook v5.1 assembly and all the referenced topics in order to create the equivalent “flat”, monolithic, document (e.g. a DocBook v5.1 book). This equivalent document is called the realized document.

The realized document is then transformed to other formats (PDF, HTML, etc), normally, as if it were created by hand, using the DocBook XSL stylesheets.

As of v0.9.3, XMLmind Assembly Processor includes XInclude 1.1 and DocBook Transclusion processors, which allows to create modular DocBook v5.1 documents without facing limitations.

XMLmind Assembly Processor is free, open source, software, which like the DocBook XSL stylesheets, is licensed under the terms of the MIT License.

Why create DocBook assemblies and topics?

DocBook 5.1 introduces two new elements: assembly and topic. 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.

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.

What is a Topic?

A topic element is a semantically neutral container having a content model similar the one of the chapter element.

A topic element is always stored in its own file.

In terms of content, a topic element is expected to deal with a single topic and to be very loosely coupled, if not at all, to other topic elements. For example, avoid creating cross-references (xref, link) between topic A and topic B.

In this tutorial, we'll use assembly elements which reference topic elements exclusively. In fact, any DocBook container (chapter, section, appendix, 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.

What is an Assembly?

A DocBook 5.1 assembly specifies how to create a plain, “normal”, DocBook document (e.g. a book) out of contents “pulled” from topic files.

The “normal” DocBook document created by the means of an assembly is called the realized document.

The main elements of an assembly are structure and module:

  • A structure element specifies the contents of the realized document. It contains a number of possibly nested module elements.

  • A module element specifies which contents is to be “pulled” from the topic file and how this contents is then copied into the realized document.

Limitations

  • Attribute type of element structure is ignored.

  • Element relationships is supported. However attribute type of elements relationships and relationship is still ignored.

For More Information