Chapter 4. Command-line options
Prev   Next

Chapter 4. Command-line options

The assembly command-line utility (found in assembly_install_dir/bin/) is auto-documented. Suffice to execute:

C:\assembly\bin> assembly

in order to display the following help.

Usage

assembly option* in_assembly_file out_docbook_file|-

Processes a structure found in assembly file in_assembly_file and creates realized DocBook document in out_docbook_file.

If out_docbook_file is specified as "-", then in_assembly_file is simply checked for errors.

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.

Using XML catalogs to resolve entities and URIs

An assembly may reference virtual topics. Let's call virtual topics, topics which are not expressed in DocBook v5.1+ and which need to be converted on the fly to DocBook v5.1+ before being added to the realized document. This facility is implemented by the means of the transform element and the grammar or transform attributes of the output element.

These virtual topics often start with a DOCTYPE. DITA example:

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN"
"http://docs.oasis-open.org/dita/v1.2/os/topic.dtd">
<topic id="topic">
  <title>A DITA Topic</title>
  ...

Unless you specify an XML catalog pointing to a local copy of topic.dtd, assembly will download this DTD from http://docs.oasis-open.org/dita/v1.2/os/topic.dtd, which may take a while or even fail.

XML catalogs are specified by the means of environment variable XML_CATALOG_FILES[1]. This variable contains a semicolon-delimited list of catalog files or URIs. Windows example:

C:\>set XML_CATALOG_FILES=..\..\ditac\schema\catalog.xml

[1] Or equivalent Java™ system property xml.catalog.files.

Prev   Next
Chapter 3. Getting started Home Chapter 5. Limitations and implementation specificities