DAPS Documentation › User Guide › Generating Output Formats

Applies to DAPS 3.1

4 Generating Output Formats #

4.1 Validating Your XML Sources
4.2 Basic Syntax for Generating Output
4.3 Supported Output Formats
4.4 Advanced Output Options
4.5 Pretty XML Formatting
4.6 Putting the current Date and Time into the Target Document

This chapter covers the following topics:

Validating your XML files
Basic command syntax for generating output formats
Output formats you can generate with DAPS
Generating partial builds of your documentation
Specifying the MAIN file at the command line (instead of using a DC file)

4.1 Validating Your XML Sources #

Generating any output requires that your XML files are valid. As soon as any output command is executed, DAPS automatically runs a validation check first. If it fails, DAPS returns the parser errors, including information about the type of error, the respective file name and the line number where the error occurred. In addition, DAPS shows the path to the profiled XML sources and the total number of errors.

Example 4.1: Parser Output For Validation Errors (`xref` to unknown ID) #

daps_user_concept.xml:60: element xref: validity error:
IDREF attribute linkend references an unknown ID "itl.daps.user.inst.other.req"
Document /local/svn/daps-svn/daps/doc/build/.profiled/x86-amd64-em64t_osuse_/
MAIN.DAPS.xml does not validate
make: *** [validate] Error 3

Note: Validating is Done in Build Directory

Validation is always done in the build directory and in the profiled sources, as indicated by the path above (/local/[...]/build/.profiled/[...]/MAIN.DAPS.xml). However, you need to fix the validation error in the sources located in your xml directory, otherwise the fixes will not take effect. Profiling is similar to conditional text. For details, refer to the chapter about modularizing document projects in the DAPS User Guide.

Using profiling in your DocBook sources makes validation unreliable. Furthermore, validating XML files within a book or set often exceeds validation of the current XML file, as links (xref elements) or XIncludes need to be resolved, too.

DAPS can handle all those cases because of the built-in xmllint validator. By default, remark elements and XML comments are ignored during validation. However, if you intend to create a (draft) output including remarks or comments, you need to include them for validation—see the example commands below.

To validate all files that belong to your documentation project, DAPS only needs to know which DC file to use. Use the -d option to specify it.

Validating All XML Files in a Book, Article or Set

tux:~> daps -d PATH_TO_DC_FILE validate

If the XML files are not valid, DAPS will return the parser errors. If validation was successful, DAPS returns: All files are valid.

Validating Files Including remark Elements

tux:~> daps -d PATH_TO_DC_FILE validate --remarks

Validating Files Without Checking Cross References (xref)

tux:~> daps -d PATH_TO_DC_FILE validate --norefcheck

This option only affects DocBook 5 sources and is ignored when processing DocBook 4.

4.2 Basic Syntax for Generating Output #

DAPS supports a number of different output formats, including also “exotic” formats like man pages or simple text. Table 4.1 gives an overview.

You can build several output formats (without them interfering with each other in the build directory), build your complete documentation project (set, book, or article), or only a part of it (for example, a specific chapter).

Independent of the individual output format you want to create, you need to specify the DC file to use:

tux:~> daps -d PATH_TO_DC_FILE OUTPUT_FORMAT

For example:

tux:~> daps -d DC-daps-example pdf

At the end of the transformation process, DAPS shows a message where to find the generated output.

4.3 Supported Output Formats #

The following table lists the main output formats and their characteristics, and the DAPS subcommands to generate them. Refer to Section 4.2 for the commands' basic syntax.

Table 4.1: DAPS Output Commands and Formats #

Subcommand	Output/Note
pdf	Creates a color PDF. Open the result in a PDF viewer. Requires an FO formatter.
pdf --grayscale	Creates a black-and-white PDF. Open the result in a PDF viewer. Requires an FO formatter. All color images are automatically converted to grayscale images. If you need a PDF for a printing shop, add the `--cropmarks` option. Creation of crop marks is currently only supported by the XEP FO formatter.
html	Creates a subdirectory containing individual HTML files for all chapters of a book (including also preface, glossary or appendix files). The HTML files are named according to the ID of the respective root element. Open the generated `index.html` file in a Web browser to view the generated HTML from the starting point (ROOTID of the top-level element). Images and CSS files are only linked in the resulting directory that contains the HTML files. To copy these files to the same location as the HTML files, use the `--static` option. This is useful for creating distributable HTML builds.
html --single	Creates a single HTML file, named after the DC file used to create the output. Open the generated `*.html` file in a Web browser. Single HTML files are more convenient for full text searches. Images and CSS files are only linked in the resulting directory that contains the HTML files. To copy these files to the same location like the HTML files, use the `--static` option. This is useful for creating distributable HTML builds.
epub	Creates an EPUB 2 document. Open the resulting file in a portable e-book reader (or with a software like Calibre). If you need an EPUB 3 document, add the `--epub3` option.
mobi	Creates an Amazon Kindle e-book in Mobipocket format. Open the resulting file in a portable e-book reader (or with a software like Calibre). Requires Calibre. DAPS first generates an EPUB file which is then converted to `*.mobi` format with Calibre.
webhelp	Creates a DocBook Web Help output. Open the resulting `index.html` file in a Web browser to view the generated document from the starting point (ROOTID of the top-level element). Experimental feature. Requires the most recent version of the DocBook stylesheets. DocBook Web Help consists of HTML pages with an additional pane, featuring a table of contents and a search function. The table of contents can be expanded and collapsed, and is automatically synchronized with the contents pane. The search function orders the search results so that the most relevant results are listed first.
text	Creates an ASCII text output. Open the resulting file in a text editor. All images are removed from the output, but their location is indicated in the text by the respective image base name printed in square brackets. A table of contents is automatically generated and is inserted at the beginning of the text document.
man	Creates one or multiple man pages. To create man pages, your XML files must contain at least one `refentry`—be it in a `chapter`, `appendix`, or collected in a `reference` element. When processing a DocBook document with multiple `refentry` elements (regardless where they appear), DAPS generates one man page file per `refentry` element. All other parts of the document will be ignored.

The number of output formats may be extended in the future, depending on the output formats that are supported by DocBook stylesheets. For an overview of all output formats, run daps help. The available output formats are listed below Subcommands › Generate Books.

By default, DAPS uses the regular DocBook stylesheets, but DAPS also allows you to customize your output formats in a very flexible way. For details, refer to Chapter 9, Customizing Layout of the Output Formats.

4.4 Advanced Output Options #

In the following, find some example commands for special use cases, like doing partial builds of your documentation project or specifying no further parameters than the MAIN file for an output. In the last case, you can do completely without a DC file.

For more advanced output options like including remarks or draft watermarks in the output, creating one big XML file or creating distributable archives, refer to Chapter 7, Review and Translation Processes.

Building Only Parts of a Documentation Project

tux:~> daps -d DC-daps-example pdf --rootid=cha.template.examples

Instead of always building your complete documentation project (set, book, or article), DAPS also allows you to build only individual parts. The “starting point” of your documentation project is usually defined by the root element of the MAIN file that is referenced in the respective Doc Config. To build only a part of your documentation project, use the --rootid option to specify the ID of an individual book, article, glossary, appendix, part, or chapter.

Specifying the MAIN File on the Command Line

tux:~> daps -m PATH_TO_MAIN_FILE

If you do not need to specify any further parameters than the MAIN file, you can do completely without a DC file. With the -m option you can specify the MAIN file defining your document. The options -m and -d exclude each other.

Opening the Output Directly in a PDF Viewer

tux:~> evince $(daps -d DC-daps-example pdf) &

Use the syntax above to open the PDF output directly in a PDF viewer (for example, Evince).

Getting More Information about the Build Process

By default DAPS, only provides the path to the resulting file as output. To set higher verbosity levels, use the global options -v, -vv, -vvv, and --debug.

Output verbosity ranges from -v (print one line of results) to -vvv (print all commands, very verbose). For example, the following command will print all files created during the build process:

tux:~> daps -vv -d DC-daps-example pdf

For debug output, use the following command:

tux:~> daps --debug -d DC-daps-example pdf

Specifying the Number of Parallel Jobs During the Build Process

By default DAPS uses as many jobs as there are CPU cores available. Use the option --jobs to define the number of parallel jobs used for the build process. Higher numbers will lower the build time, but will also increase CPU load. For example, the following command will use 16 jobs for the build process:

tux:~> daps --jobs=16 -d DC-daps-example pdf

4.5 Pretty XML Formatting #

It can be useful to have properly formatted XML sources. A homogeneous formatting facilitates collaboration and makes diffs more readable. If done consistently, xmlformat reduces the amount of changes that need to be stored in version control systems which leads to smaller repositories.

Prettify all project XML files

tux:~> daps -d DC-daps-example xmlformat

Prettify a specific XML file

tux:~> daps -d DC-daps-example xmlformat --file=xml/example.xml

Prettify only parts of a book

tux:~> daps -d DC-daps-example xmlformat --rootid=cha.template.examples

Important: `xmlformat` Alters Source XML Files

This command reformats your XML files in place, replacing their contents with the reformatted XML. To keep the files with the previous formatting, make a backup before running daps xmlformat.

4.6 Putting the current Date and Time into the Target Document #

To get information about the build date and time, you can use the <?dbtimestamp> tag. The processing instruction <?dbtimestamp> is processed by daps, when the document is built. The date and time will then show up in the final document, based on how you've set the date/time format.

Example 4.2: Example for implementing the dbtimestamp tag in an XML File: #

<para>Current date: <?dbtimestamp?>.</para>

The format of the date/time can be customized via the format parameter.

Example 4.3: Example for implementing the dbtimestamp tag with a customized format: #

<para>Current date: <?dbtimestamp format="A, d B Y"?>.</para>

For further information about the format elements look at this site: http://www.sagehill.net/docbookxsl/Datetime.html

Print this page