DAPS 2.0

Quick Start Guide

Authors: Tanja Roth, Christopher-Julian Zwickl, and Stefan Knorr
Publication date: October 10, 2014

DAPS helps technical writers author and publish documentation written in DocBook XML. DAPS is command-line based software for Linux* and released as open-source.

The DAPS Quick Start Guide is a short introduction to DAPS for technical writers. It includes step-by-step instructions for key editing and publishing tasks.

1 Target Audience

This document is intended for users who want to make efficient use of DocBook XML for editing and publishing their documentation—be it documentation sets, individual books, or articles. Key knowledge of XML and DocBook is required, as well as key knowledge of using the Bash Shell (or command line interfaces in general).

2 Supported DocBook Versions

Currently, DAPS supports only DocBook 4.x. Support for DocBook 5.x is planned for version 2.0.

3 System Requirements

DAPS itself is a lean solution that does not require a lot of system resources. However, it does use components that may need a stronger processor and more RAM, for instance for creating PDF output files.

3.1 Hardware Requirements

RAM

The required amount of RAM mostly depends on the volume of your documentation projects. For creation of PDF output, 2 GB of RAM are recommended.

CPU

If you have multiple or very large documentation projects, a machine with multiple cores is recommended.

Hard Disk Space

The disk space consumed mostly depends on the amount of your documentation sources and the number of output formats you want to generate.

3.2 Software Requirements

DAPS runs on any modern Linux system. It has not been attempted to port DAPS to Windows* or Mac OS X* yet.

When installing DAPS as an RPM package (on any SUSE-based system), dependencies on other software packages are automatically resolved during installation.

For installing the DAPS sources on other Linux distributions, refer to the DAPS User Guide Section “Software Requirements”, Chapter 1, System Requirements and Installation, User Guide where the respective requirements are covered in detail.

3.3 Additional Software

In addition to DAPS, you need the following software:

To add further components like version management or a workflow mechanism for your projects, use DAPS in combination with the following software:

  • Any version management system, like CVS, Subversion, Mercurial or Git.

  • Docmanager, a command-line tool for adding and retrieving the meta information of all files belonging to a documentation project. Docmanager is especially useful for larger, collaborative projects where it helps you keep track of owners (authors) and editing statuses of all files. However, Docmanager requires hosting your documentation files on a Subversion server.

Together with the software components mentioned above, DAPS can be used as a fully-fledged authoring and content management system for documentation projects based on DocBook.

3.4 Directory Structure

For DAPS to work out of the box, it requires a certain organization of your DocBook XML files and images within your documentation directory. For details, refer to Section 5.2, “Directory Structure”. You can generate the necessary structure with the DAPS initialization script, daps-init. For instructions on how to make existing DocBook projects compatible with DAPS, refer to Section 12, “Migration of Existing DocBook Projects”.

4 Installation

The DocBook Authoring and Publishing Suite can be installed and used on any Linux distribution. Currently, DAPS is available as an RPM package for the openSUSE distribution. Eventually, packages for other distributions may become available. In the meantime, you can download a TAR archive with the DAPS sources and install them on any distribution as described in Section “Installing DAPS on Other Linux Distributions”, Chapter 1, System Requirements and Installation, User Guide.

4.1 Installing DAPS on openSUSE

There are a few ways to install DAPS on openSUSE. To always stay up-to-date with the latest version of DAPS install the daps package from the Documentation:Tools repository as outlined below.

Procedure 1: Installing DAPS via 1-Click Install
  1. Open your browser and go to http://software.opensuse.org/.

  2. Enter daps.

  3. On the resulting page, click daps › Show other versions › Show unstable packages.

  4. Look for the version from the repository Documentation:Tools and click the 1-Click Install link next to it. A window called YaST–1-Click Install should appear.

  5. Follow the instructions and click Next, Trust, and finally Finish.

If you are already well-versed in the usage of openSUSE, you can of course also add the Documentation:Tools repository with either zypper or YaST.

You may also use the daps package that shipped with your version of openSUSE. However, you then might miss the latest features and bug fixes in DAPS.

4.2 Installing DAPS on Other Linux Distributions

Please refer to the DAPS User Guide for instructions on how to install DAPS on other Linux distributions: Section “Installing DAPS on Other Linux Distributions”, Chapter 1, System Requirements and Installation, User Guide.

4.3 Installing and Configuring the FO Formatter

For installation and configuration of an FO formatter (for generating PDF output), refer to its installation instructions (or to your system administrator). For FOP, you usually only need to install the respective FOP package. However, not all FOP packages contain hyphenation pattern files.

5 Defining Documentation Projects

The easiest way to set up a new documentation project from scratch is to use the DAPS initialization script daps-init. For instructions how to do so, refer to Procedure 2, “Using daps-init. The script automatically creates the Key Files and Directory Structure that you need to get started with DAPS.

5.1 Key Files

The following key files define a documentation project so that it can be processed by DAPS:

MAIN File

A DocBook XML file containing the starting point (the highest-level object) of your documentation project (for example, book or article). For larger documentation projects, it is good practice to name the file MAIN-PROJECTNAME.xml, but you can use any other file name as well.

Doc Config (DC) File

A configuration file defining a number of parameters for your documentation deliverable (for example, the MAIN file, layout variants, or which profiling information to use). Of the multiple parameters that can be set in the DC file, the only one required is MAIN, pointing to the XML file that you want to process. Usually, you create one DC file per book or article. For a documentation set (a collection of books), multiple DC files can be defined. This allows you to set different parameters and different values for individual books in the set.

5.2 Directory Structure

For DAPS to work out of the box, your XML files and images must be organized in a specific structure within your documentation directory. Example 1, “Directory Structure” shows the required structure including the key files for a DAPS documentation project. You can also create multiple documentation directories for individual documentation projects, but they all need the substructure outlined below.

Example 1: Directory Structure
YOUR_DOC_DIR/1
  |--DC*2
     |--images/
     |   |--src/3
     |      |--dia/
     |      |--eps/
     |      |--fig/
     |      |--pdf/
     |      |--png/
     |      |--svg/
     |--xml/4
         |--MAIN*.xml5
    

1

Working directory for the respective documentation project.

2

DC file defining the documentation project.

3

Top-level directory for any original images that you want to use in the documentation project. Contains subdirectories for images in various formats. Any images to be referenced in the XML sources must be put in the respective subdirectories. For information about referencing images, refer to Section 9.4, “Referencing Images”.

4

Directory holding the XML files for the documentation project. If you declare entities in an external file (for example, in entity-decl.ent), put the entity declaration file here, too.

5

The MAIN file of the documentation project. It contains references to other books, chapters, appendices, etc.

6 A Documentation Project From Scratch

Use daps-init to set up a new documentation project from scratch. The initialization script automatically creates the key files and directory structure you need to get started with DAPS. View the available options with the command daps-init --help. By default, the script creates a book as example document.

Procedure 2: Using daps-init
  1. Create a directory that you want to use as your documentation directory:

    tux > mkdir DOC_DIR 
  2. Create the default directory structure for DAPS (containing an example book):

    tux > daps-init --docdir PATH_TO_DOC_DIR 

    With the -r option, you can also set another root element, such as article, for example. To create the default directory structure with an article example:

    tux > daps-init --docdir PATH_TO_DOC_DIR -r article
  3. In case the specified directory does not exists, DAPS asks whether to create it. Proceed by pressing y or n.

  4. To see what the output of the XML example file looks like, follow the instructions on the screen. For example, the following command specifies the DC* file (DC-daps-example) to use and the output format (color PDF) to create:

    tux > daps -d PATH_TO_DOC_DIR/DC-daps-example pdf

    For creation of the PDF, DAPS uses FOP by default (if no other formatter is specified) and applies the default DocBook stylesheets (if no custom layout options are defined). At the end of the transformation process, DAPS shows a message where to find the generated PDF. By default, all contents generated by DAPS is located in the build subdirectory. It is automatically created within your documentation directory.

  5. Check your documentation directory for the new files: The text file DC-daps-example is annotated and gives you a rough idea which options can be defined in a DC file. For having a look at the XML source code of the book or article, change to the xml subdirectory and open the file MAIN-DC-daps-example.xml in a text or XML editor.

7 Editing DocBook XML Files

As DAPS does not include any editor software, you are completely free in the choice of your XML editor. While you can use your text editor of choice, it is helpful if the editor supports editing XML in accordance with the schema you use. A number of open source editors can be extended with plug-ins for automatic tag insertion and completion, insertion of xref elements and for checks if the XML document is well-formed. If you are already familiar with vi or Emacs, you can configure them to support XML editing mode. If you prefer an editor with a graphical user interface, jEdit (http://www.jedit.org/) is a good choice.

If you have worked with DocBook before, you know about the typical top-level elements for documents, book and article. For larger documentation projects, another typical top-level element is set (a collection of books).

To define the individual components of a book, use structural elements such as part, chapter, preface or appendix. Chapters are usually subdivided into sections (section elements or sect1, sect2 etc.). Smaller structural units are para (for paragraphs), or list elements such as orderlist, itemizedlist, or variablelist.

If you have set up your documentation project from scratch with daps-init, you can explore the example documents that are installed within the directory structure. They show the most commonly used DocBook XML constructs.

8 Validation

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 2: 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

9 Image Handling

Depending on the output format you generate with DAPS (PDF or HTML, for example), the source images you provide and reference in your XML sources are automatically transformed into the appropriate output formats. For example, SVG images are converted to PNG for HTML builds, or color images to grayscale for black-and-white PDFs. You only need to decide which file format to use as source format. Of course, this decision depends on the purpose of the image.

9.1 Supported Image Types

DAPS supports the following types of images:

  • DIA

  • EPS (experimental)

  • FIG

  • JPEG

  • PDF (experimental)

  • PNG

  • SVG

9.2 Organization of the images Directory

DAPS requires you to use a specific directory structure for images. All images that you reference from your DocBook files must be stored in a subdirectory of the project directory named images/src/file_extension. For instance, PNG files must be stored under images/src/png. If you used daps-init to set up your project, the appropriate directories should already exist. For a longer reference to the directory structure, see Section 5.2, “Directory Structure”.

9.3 File Name Requirements

Unique Image Names

Always store just one file with a particular name within the images/src folder of a project. As DAPS tries to create any missing image formats from original images, it will otherwise not know which one of the duplicate files to use for converting to the missing formats.

Additionally, having a file called example.png and another called example.svg in the same documentation project will often lead to questions like: Which file to use where? Do both files display the same content? Are both files current, or is one outdated?

When invoking DAPS with the parameter -v, a warning will be printed whenever a file name appears twice within a project. To specifically check for image name clashes upfront, use the daps warn-images subcommand.

No Spaces In File Names

Avoid spaces in file names because the make command in DAPS has trouble understanding them. Use underscores (_) or hyphens (-) instead. Camel-cased file names (aCamelCasedFileName) or file names only differing in upper or lower case spelling can lead to problems if multiple file systems are used anywhere in the process chain between generation and publishing of the output formats.

It is a good idea to find a consistent file naming scheme. For instance, when documenting software, it might prove helpful to include the name of the application at the beginning of the file name or to use prefixes like screenshot_ and diagram_ to separate between different types of images.

9.4 Referencing Images

Provided your images are located in the required default directory, DAPS automatically finds the path to your images. Therefore, referencing images in your XML sources is very straightforward: you do not need to include any path in the fileref attribute—the file name is enough.

Furthermore, DocBook allows you to reference more than one image to distinguish between different output formats. For example, you can add two references pointing to the same file, but using different images widths for PDF and HTML output. Use the role attribute to specify the output format, for example fo or html.

Example 3: Image Reference in an XML File
<figure>
  <title>Main Window</title>
  <mediaobject>
    <imageobject role="fo">
      <imagedata fileref="screenshot.png" width="70%"/>
    </imageobject>
    <imageobject role="html">
      <imagedata fileref="screenshot.png" width="75%"/>
    </imageobject>
  </mediaobject>
</figure>

10 Basic DAPS Syntax

Before introducing the key daps commands to create output formats from your XML documents, let's get familiar with the basic syntax of the daps command:

tux > daps [--global-options] subcommand [--command-options] [arguments]

Example 4, “DAPS Syntax” shows an example command that generates HTML output. Global options are used to specify the level of verbosity, and the Doc Config file for creating the output.

Example 4: DAPS Syntax
daps1 --debug2 -d3 DC-daps-example html4 --static5

1

Main command: daps

2

Global Option --debug: Sets the highest verbosity level (number of messages shown during the transformation process from XML to HTML).

3

Global Option -d: Defines the relative or absolute path to the Doc Config file. In this example, daps is called in the same directory that holds the Doc Config file.

4

Subcommand html: Defines the output format to create.

5

Command option --static: Tells DAPS to copy CSS and image files to the same location like the HTML files. For more information, see Table 1, “DAPS Output Commands and Formats”.

Tip
Tip: Specifying the DC File

For execution of most commands, DAPS needs to know which DC file to use. There are several ways to let DAPS know about this:

  • Your documentation directory contains only one DC file. In that case, DAPS automatically uses the corresponding file.

  • You have specified a default DC file to use in ~/.daps/config (as a value for DOCCONF_DEFAULT). In that case, DAPS automatically uses the corresponding file, unless you specify a different one on the command line.

  • Specify a DC file on the command line with the global option -d. For example:

    tux > daps -d PATH_TO_DC_FILE color-pdf

Generally, DAPS can be executed with or without options. To view the global options and the available subcommands, use the command:

tux > daps --help 

For a short help text on a specific subcommand, use:

tux > daps --help  subcommand 

For example, if you want more information about generating HTML output, run:

tux > daps --help html 

The following section introduces the key daps commands needed to create output formats from XML files. All examples are based on the example files that are provided by the DAPS initialization script. For more information, refer to Section 6, “A Documentation Project From Scratch”.

11 Output Formats

By default, the DocBook stylesheets are used for generating output formats. But DAPS also allows you to customize your output formats in a very flexible way. For more details, refer to Chapter 9, Customizing Layout of the Output Formats, User Guide.

11.1 Basic Syntax for Generating Output

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

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 color-pdf

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

If your current directory is not the documentation directory where the DC file is located, also specify the (absolute or relative) path to the DC file. For example:

tux > daps -d /svn/daps/example/DC-daps-example pdf

11.2 Generating Different Output Formats

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

Table 1: DAPS Output Commands and Formats

Subcommand

Output/Note

pdf

Creates a color PDF (without any crop marks). Open the result in a PDF viewer.

Requires an FO formatter.

pdf --grayscale

Creates a black-and-white PDF, suitable for hand-off to a printing shop. Open the result in a PDF viewer.

Requires an FO formatter. All color images are automatically converted to grayscale images. To also include crop marks, 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 like 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 document. Open the result in a portable e-book reader (or with a software like Calibre).

mobi

Creates an Amazon Kindle e-book in Mobipocket format. Open the result 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 generated index.html file in a Web browser to view the generated HTML from the starting point (ROOTID of the top-level element).

Experimental feature. Requires a very 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 weights the search results so that the most relevant results are listed first.

txt

Creates an ASCII text output. Open the result 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 available 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.

11.3 Advanced Output Options

Instead of always building your complete documentation project (set, book, or article), DAPS also allows you to build an individual chapter or part. If you want the output format to include remark elements or to be marked as a draft version, you can tell DAPS to do so.

11.3.1 Partial Builds

The starting point of your documentation project is usually the root element defined in the MAIN file that is referenced in the respective Doc Config. Alternatively, specify a ROOTID on the command line by using the --rootid option. This also allows you to build only a part of your documentation project by using the ID of a book, article, glossary, appendix, part, or chapter element.

For example, if you have set up your working environment with daps-init and an example book, use the following command to build the first chapter of the book (without the book's title page, table of contents etc.):

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

11.3.2 Output with Remarks or Draft Watermark

For publishing a pre-release version of a document that you can send to a proofreader for review, use the --draft command option to mark the document as draft version. For example, use the following command to build a color PDF that has a DRAFT watermark printed on each page:

tux > daps -d DC-daps-example pdf --draft

If you used remark elements in your XML files (for editorial remarks or questions to the proofreader), include the remarks in the output with the --remarks option:

tux > daps -d DC-daps-example pdf --remarks

When generating PDFs with FOP, the contents of the remark elements is shown in italics within the text. XEP supports conversion of remark elements into PDF annotations. This feature is enabled in DAPS by default, but if you want XEP to treat remark elements like FOP does, you can change the respective DAPS parameter. In HTML, HTML-single and EPUB output, the contents of the remark elements is shown in red within the text.

If metadata to a file has been set, DAPS can also include the metadata for each file in the output format:

tux > daps -d DC-daps-example pdf --meta
Note
Note: Availability of Advanced Output Options

Advanced output options are only supported for selected formats:

  • --meta: Only available in HTML, HTML-single, and PDF.

  • --draft and --remarks: Only available in HTML, HTML-single, PDF, and EPUB output.

Using the --remarks and --meta options automatically turns draft mode on.

By default, DAPS adds a string to the base name of the output file to flag output formats generated with special options. Example file names are daps-example_draft_en.pdf or daps-example_remarks_draft_en.pdf.

12 Migration of Existing DocBook Projects

To migrate existing DocBook projects so that you can manage and publish them with DAPS, follow the step-by-step instructions in Appendix A, Migration of Existing DocBook Projects, User Guide.

13 For More Information

This guide gave you a short introduction toDAPS and guided you through the key tasks. To discover more, refer to the other manuals available on DAPS at https://sourceforge.net/p/daps/home/Home/.

For general discussions and technical support, join the forum at https://sourceforge.net/p/daps/discussion/. You do not need a user account at http://sourceforge.net for this.

For bugs or enhancement requests, please open a ticket at https://sourceforge.net/p/daps/tickets/add. A user account at http://sourceforge.net is recommended, but you may also open tickets anonymously.

For a complete DocBook reference see DocBook: The Definitive Guide (http://www.docbook.org/tdg/en/html/docbook.html).

For an overview of the key terms used in the context of DAPS and DocBook, refer to Glossary, User Guide.

If you encounter problems with DAPS, check Chapter 11, Troubleshooting, User Guide for a list of common problems and their solution.

Print this page