DAPS 1.0

User Guide

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 User Guide is a comprehensive guide for technical writers using DAPS. It guides through creating, editing, managing and publishing your documents— be it a short article by a single author or a large documentation project written by multiple authors.

Authors: Tanja Roth and Stefan Knorr
Contributors: Thomas Schraitle and Frank Sundermeyer
Publication date: 10/10/2014, Revision: 3677
About This Guide
Target Audience
Available Documentation
Feedback
Documentation Conventions
About the Making of This Document
1 System Requirements and Installation
1.1 System Requirements
1.2 Installation
2 Conceptual Overview
2.1 Supported DocBook Versions
2.2 Key Features
2.3 DAPS Configuration
2.4 Defining Documentation Projects
2.5 Directory Structure
2.6 Basic DAPS Syntax
3 Editing DocBook XML
3.1 Basic Structural Elements
3.2 Choice of Editor
3.3 Spell Checking
3.4 Checking Links to Web Pages
3.5 Profiling—Support for Document Variants
3.6 For More Information
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
5 Image Handling
5.1 Supported Image Types
5.2 Source Images and Generated Images
5.3 File name Requirements
5.4 Referencing Images
5.5 DAPS Commands for Managing Images
6 Modularizing Documentation Projects
6.1 Splitting up Documents into XIncludes
6.2 Declaring Entities in a Separate File
6.3 Profiling—Support for Document Variants
6.4 Combining Entities and Profiling
7 Review and Translation Processes
7.1 Including Remarks, Metadata or Draft Watermarks in the Output
7.2 Creating XML Bigfiles and Profiled XML Sources
7.3 Creating Distributable Archives
8 Packaging and Deploying Your Documentation
8.1 Creating a TAR Archive with All Sources (Including Graphics)
8.2 Generating a Distributable HTML Archive
8.3 Generating a Color PDF
8.4 Generating a JSP TAR Archive
8.5 Generating Desktop, Document, or Page Files
9 Customizing Layout of the Output Formats
9.1 Modifying Individual XSLT Processor Parameters
9.2 Customizing the DocBook Stylesheets
10 Configuring DAPS
11 Troubleshooting
11.1 Installation and First Steps
11.2 Generating Output
11.3 Miscellaneous
Glossary
A Migration of Existing DocBook Projects
B Editor-specific Information
B.1 Emacs—Macros for Inserting DocBook Elements
B.2 jEdit—Spell Check on the Fly
C Documentation Updates
C.1 Next (DAPS 2.0)
C.2 2013-10-10 (Maintenance Release)
D GNU Licenses
D.1 GNU General Public License
D.2 GNU Free Documentation License

Copyright © 2006–2014 SUSE, LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE or Novell trademarks, see the Novell Trademark and Service Mark list http://www.novell.com/company/legal/trademarks/tmlist.html. Linux* is a registered trademark of Linus Torvalds. All other third party trademarks are the property of their respective owners. A trademark symbol (®, ™ etc.) denotes a SUSE or Novell trademark; an asterisk (*) denotes a third party trademark.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE, LLC, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.

About This Guide

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.

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).

For the DocBook versions supported by DAPS, refer to Section “Supported DocBook Versions”, Quick Start Guide .

2 Available Documentation

This guide contains links to additional documentation resources. The following manuals are available for DAPS:

DAPS Quick Start Guide

The DAPS User Guide is a comprehensive guide for technical writers using DAPS. It guides through creating, editing, managing and publishing your documents— be it a short article by a single author or a large documentation project written by multiple authors.

User Guide

The DAPS User Guide is a comprehensive guide for technical writers using DAPS. It guides through creating, editing, managing and publishing your documents— be it a short article by a single author or a large documentation project written by multiple authors.

3 Feedback

We want to hear your comments and suggestions about DocBook Authoring and Publishing Suite (including this guide and the other documentation included with DAPS).

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.

Patches and user contributions are welcome!

4 Documentation Conventions

The following typographical conventions are used in this manual:

  • /etc/passwd: directory names and file names

  • placeholder: replace placeholder with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

5 About the Making of This Document

This documentation is written in DocBook (see http://www.docbook.org) and generated by DAPS.

1 System Requirements and Installation

This chapter describes:

  • on which computers DAPS will work,

  • how to install DAPS on openSUSE, and

  • how to build and install DAPS on other Linux* distributions.

1.1 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.

1.1.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.

1.1.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.

To install the DAPS sources on other Linux distributions (with configure, make, and make install), make sure the following packages or tools are installed on your system. Else, the installation scripts will fail.

  • bash, version 4.0 or higher

  • checkbot (this software is sometimes packaged as perl-checkbot)

  • convert (included in the ImageMagick package)

  • Dia

  • DocBook 4

  • DocBook 4 Stylesheets (usually a separate package)

  • exiftool (also packaged as libimage-exiftool-perl)

  • fam

  • ghostscript (also packaged as ghostscript-library)

  • Inkscape

  • make

  • optipng

  • poppler-tools (also packaged as poppler-utils)

  • python

  • python-xml

  • sgml-skel

  • TransFig

  • xmlcatalog (usually part of the package libxml2, libxml-utils, or libxml-tools)

  • xmllint (usually part of the package libxml2, libxml-utils, or libxml-tools)

  • xsltproc (if not available as a separate package, it may be included in libxslt)

During the installation procedure, the convert script informs you about any further missing software packages. Refer to Procedure 1.2, “Installing the DAPS Sources” for more information.

1.1.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.

1.2 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 1.2.2, “Installing DAPS on Other Linux Distributions”.

1.2.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.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.

1.2.2 Installing DAPS on Other Linux Distributions

For installation on other Linux distributions, the DAPS sources are available as a TAR archive. They can be installed with configure, make, and make install.

Procedure 1.2: Installing the DAPS Sources

Before starting the installation, check the DAPS System Requirements and make sure all required packages and tools are installed.

  1. Go to http://sourceforge.net/projects/daps/files/ and download the DAPS source TAR archive, daps-version_number.tar.bz2.

  2. Unpack the TAR archive:

    tux > tar -xvf daps-version_number.tar.bz2
  3. Change to the newly created daps subdirectory and start the configure script:

    tux > ./configure

    If you want to adjust the DAPS installation paths:

    1. View the available options with

      tux > ./configure --help
    2. Run the configure script with the desired option.

    The script checks your system for any software relevant to DAPS and the DAPS installation process. It also creates a makefile that will be used during installation. Based on the analysis, the script shows a summary that includes the following information:

    • the DAPS installation paths,

    • an overview of DAPS features that will be available on your system if you install DAPS now, and

    • which software is still missing to enable the remaining DAPS features.

  4. Check the summary carefully.

  5. Install missing packages, if necessary. After installing new packages, repeat Step 3 and check the summary again.

  6. If everything is prepared according to your wishes, enter:

    tux > make
  7. Start the installation process with:

    tux > sudo make install

2 Conceptual Overview

This chapter describes:

  • the features that make DAPS stand out: from creating multiple output formats to automatically profiling documents,

  • how to configure DAPS, and

  • the basics of working with DAPS.

  • the basic syntax of daps commands.

2.1 Supported DocBook Versions

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

2.2 Key Features

DAPS supports technical writers in the editing, translation and publishing process of DocBook XML files (in the following, simply referred to as XML files):

Output Formats (Single-source Publishing)

DAPS lets you publish your XML sources in a number of different output formats, for example: HTML, HTML-single, PDF, EPUB, Web Help, text, and man pages. For details, refer to Chapter 4, Generating Output Formats.

Custom Layouts

By default, DAPS uses the DocBook stylesheets to generate the output formats. But DAPS also supports custom layouts for your documentation projects (or for individual books within your set).

Apart from that, DAPS allows you to change individual layout parameters by passing string parameters to xsltproc for HTML or PDF builds —without even touching the stylesheets. For details about custom layouts, refer to Chapter 9, Customizing Layout of the Output Formats.

Editor Macros

For Emacs, DAPS includes a set of macros for easy insertion of complex DocBook elements like variablelist, figure, table or indexterm. Instead of inserting the child elements successively, you will get a skeleton that includes all required child elements and is ready to be filled with contents. For details, refer to Section B.1, “Emacs—Macros for Inserting DocBook Elements”.

Validating

Validating XML files within in a book or set exceeds validation of the current XML file, as links (xref elements) or XIncludes need to be resolved, too. With DAPS, you can check validity of all files that belong to a documentation project with a single command. For details, refer to Section 4.1, “Validating Your XML Sources”.

Spell Check

DAPS supports spell checking of your XML sources with aspell from the command line. Depending on the XML editor you use, you can also integrate a custom aspell dictionary into your editor. For details, refer to Section 3.3, “Spell Checking” and Section B.2, “jEdit—Spell Check on the Fly”.

Link Checker

To make sure that all external links in your XML sources are still available (and do not give a 404 error or similar), DAPS also includes a link checker (based on checkbot). Use it to create a report of all links that caused some kind of warning or error. For details, refer to Section 3.4, “Checking Links to Web Pages”.

Image Handling

DAPS provides sophisticated image handling support. For example, it can transform images referenced in your XML files into different formats, list all source images referenced in your XML files, list any missing images or list the generated images used for the various output formats. You can also forward those lists to your preferred image viewer to conveniently browse through the images, or check if all image names are unique. For details, refer to Chapter 5, Image Handling.

Profiling (Conditional Text)

If you have similar products to document and want to generate multiple documentation variants from your XML files, you can do so with the help of conditional text (or profiling, as it is called in DocBook). For example, you can profile certain parts of your XML texts for different (processor) architectures, operating systems, vendors or target groups. DAPS supports profiling. Use the PROF* keys defined in /etc/daps/config to define which information should be included in the output. For details, refer to Chapter 6, Modularizing Documentation Projects.

Review and Translation Processes

DAPS offers a number of features to simplify review and translation processes. By adding or removing a single parameter, you can generate output that contains remarks for writers, reviewers, and translators, as well as the final output version in which remarks are suppressed. You can also generate preview versions of your documentation with a DRAFT watermark appearing on the output. If you use Docmanager in addition to DAPS, you can annotate your XML files with meta information (like workflow status). DAPS offers an option to also display this meta-information in the generated output. For handing over your files to review or translation, DAPS can create TAR archives of the XML sources and graphics. For details, refer to Chapter 7, Review and Translation Processes.

Packaging and Deployment

For deploying the documentation as RPM packages and integrating it into KDE and GNOME desktop environments as well as into Web user interfaces (via JSP), DAPS offers a number of options to produce the corresponding output: For example, you can create source packages, HTML TAR archives, color PDFs and desktop and document files with the daps package-* commands. For details refer to Chapter 8, Packaging and Deploying Your Documentation.

2.3 DAPS Configuration

DAPS can be customized to a large degree: per system, per user, and per document. The configuration file /etc/daps/config lists all parameters that can be configured, including a short description for each parameter. Parameters are always defined as KEY="VALUE" pairs. Any parameter can be set in various locations, which are listed below in ascending order with regards to their hierarchy. If conflicting values are set for the same parameter, the value defined in the next higher hierarchy level takes precedence. Values defined on the command line always take precedence over values set in any other locations.

  • /etc/daps/config (system-wide configuration file)

  • ~/.daps/config (user-specific configuration file)

  • DC (doc config) file of the documentation project (for settings specific to a document or documentation set)

  • on the fly at the command line by specifying options to a daps command.

2.4 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 “Using daps-init ”, Quick Start Guide. The script automatically creates the Key Files and Directory Structure that you need to get started with DAPS.

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.

2.4.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.

In the following sections, find examples for MAIN and DC files, together with background information on some key parameters that can be used in DC files. The examples are sorted according to use cases:

2.4.2 Single Deliverables (Article or Book)

The most elementary case of a documentation project is probably a white paper or article. Typically, its content can be contained in a single XML file with article as the root element. In this case, this single XML file would be the MAIN file as it specifies the highest-level object in your documentation project (article). Apart from document title and body, the file can contain other information such as a legal notice, release information, author data etc. An article may be structured into sections (by use of section elements or sect1, sect2 etc.).

Tip
Tip: Creating an Example Document

Procedure “Using daps-init ”, Quick Start Guide allows you to automatically set up an example article or book, together with a DC file. The examples below are based on the output of daps-init, but vary deliberately in some details to show key parameters that you might want to add or change.

Find a simple example in Example 2.1.

Example 2.1: MAIN file of an Article (DocBook 4.x)
<?xml version="1.0" encoding="UTF-8"?>
[...]

<article lang="en" id="art.template">
 <title>Article Template</title>
 <subtitle>generated by DAPS</subtitle>
 <articleinfo>
  <releaseinfo>Version 0.1</releaseinfo>
  <releaseinfo>Revision: 0</releaseinfo>
  <releaseinfo>
   Build Date: <?dbtimestamp format="B d, Y"?>
  </releaseinfo>
  <legalnotice>
   <para>
    <ulink url="http://www.gnu.org/licenses/fdl-1.3-standalone.html">
    GNU Free Documentation License</ulink>
   </para>
  </legalnotice>
 </articleinfo>
 <abstract>
  <para>
   You may use this file as a template. For a complete DocBook reference
   see <citetitle>DocBook: The Definitive Guide</citetitle>, available at
   <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
  </para>
 </abstract>
 <sect1 id="sec.template.examples">
  <title>Examples: The most commonly used DocBook XML constructs</title>
  <para>
   I am a paragraph in a section 1.
  </para>
  <sect2 id="sec.template.examples.lists">
   <title>Lists</title>
   <para>
    This section 2 showcases 3 types of lists.
   </para>
   [...]
  </sect2>
 </sect1>
</article>

Let us assume, the XML file shown in Example 2.1 is named MAIN-DAPS-example-article.xml and you want to publish it using the default DocBook layout. To generate output, you usually create a DC file per article or book, specifying a number of parameters such as the MAIN file or which layout 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. Therefore, a very basic DC file for the article in Example 2.1, “MAIN file of an Article (DocBook 4.x)” could look as follows:

Example 2.2: Basic DC File for an Article
## Doc config file for the DAPS example article
## See /etc/daps/config for documentation of the settings below
##

## Mandatory Parameter
MAIN="MAIN-DAPS-example-article.xml" 

Specifies the XML MAIN file. It contains the highest-level object (root element) of your documentation project. The MAIN file must be located in YOUR_DOC_DIR/xml/. Therefore, you only need to specify the MAIN's file name in the DC file (no path).

The example above is a bit artificial, though: If you do not want to specify any further parameters (apart from the MAIN file), you can also set the MAIN parameter as a command line option when generating the output format. In that case, you can do completely without a DC file. For details, refer to Chapter 4, Generating Output Formats.

In case your documentation project consists of a single book, instead of an article (as assumed before), the basic setup of MAIN file and DC file is similar:

Example 2.3: MAIN file of a Book (DocBook 4.x)
<?xml version="1.0" encoding="UTF-8"?>
[...]

<book id="book.template" lang="en">
 <bookinfo>
  <title>Book Template</title>
  <subtitle>generated by daps</subtitle>
  <productname>Book Template</productname>
   <legalnotice>
   <para>
    <ulink url="http://www.gnu.org/licenses/fdl-1.3-standalone.html">
    GNU Free Documentation License</ulink>
   </para>
  </legalnotice>
 </bookinfo>
 <chapter id="cha.template.examples">
  <title>Examples: the most commonly used DocBook XML constructs</title>
  <abstract>
   <para>
    You may use this file as a template. For a complete reference on DocBook
    see <citetitle>&tdg;</citetitle>, available at
    <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
   </para>
  </abstract>
  <para>
   I am a paragraph in a chapter.
  </para>
  <sect1 id="sec.template.examples.lists">
   <title>Lists</title>
   <para>
    This is a section 1.
   </para>
  </sect1>
 </chapter>
</book>

In the above example, the book's contents are also contained in a single XML file, however, this time with book as the root element. In contrast to an article, books can contain more structural levels: they are usually divided into chapter elements (that may contain sections and subsections) as outlined in Example 2.3. In addition to chapters, books may also contain other structural elements such as preface, glossary, and appendix. A further additional structural level is called part. For a complete reference, see DocBook: The Definitive Guide, available at http://www.docbook.org/tdg/en/html/docbook.html.

Let us assume the XML file shown in Example 2.3, “MAIN file of a Book (DocBook 4.x)” is named MAIN-DAPS-example-book.xml and you want to publish it in a custom layout. To generate output, you would create a DC file pointing to the MAIN file of the book, and additionally specify a set of custom stylesheets.

Example 2.4: DC File For a Book with Custom Layout
## Doc config file for the DAPS example book
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN-DAPS-example-book.xml" 1

## Optional Parameters

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/custom/xslt" 2

1

Specifies the XML MAIN file. It contains the highest-level object (root element) of your documentation project. The MAIN file must be located in YOUR_DOC_DIR/xml/. Therefore, you only need to specify the MAIN's file name in the DC file (no path).

2

For a custom layout, use the STYLEROOT parameter to specify the (absolute or relative) path to the directory containing the custom stylesheets. Using absolute paths is recommended for DC files.

2.4.3 Multiple Deliverables: Articles or Books in a Set

If your documentation project consists of multiple books in a set, the MAIN file is the one that contains the set element. In the following example, the components of the set (individual books) are not part of the MAIN file, but have been put into separate document files ( book*.xml ), that are then assembled in the MAIN file using XIncludes. Note that this is not specific to sets—it is mainly a means of modularizing your documents. You can also use XIncludes for splitting up books, articles or chapters into separate files. For more information, refer to Section 6.1, “Splitting up Documents into XIncludes” and Physical Divisions: Breaking a Document into Separate Files (http://www.docbook.org/tdg51/en/html/ch02.html).

Example 2.5: MAIN file of a Set (DocBook 4.x)
<?xml version="1.0" encoding="UTF-8"?>
[...]

<set lang="en">
 <title>DAPS Documentation</title>
 <xi:include href="book_daps_user.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/>
 <xi:include href="book_daps_quickstarts.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/>
 <!--<xi:include href="book_daps_developer.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/>-->
</set>

For a documentation set (a collection of books), multiple DC files can be defined. This allows you to set different parameters and values for individual books in the set. By specifying a different ROOTID in the DC file, you define which book of the set is to be built. You can also specify different layouts or output modes (such as draft or annotated versions) for individual books in the same documentation set.

The following two DC files are those of the DAPS Quick Start Guide and the DAPS User Guide— both guides belong to the same documentation set, but use different layouts.

Example 2.6: DC File For a Book in a Set
## Doc config file for DAPS Quick Start Guide
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" 1

## Optional Parameters
## ROOTID
## If MAIN contains a set with several books and/or articles, use
## a separate DC-file for each book/article and set ROOTID to
## the id of the respective <book>/<article> element of the document
## This will enable you to build individual books/articles rather than
## the whole set
## See http://www.docbook.org/tdg/en/html/set.html for more information
## on sets
ROOTID="art.daps.quick" 2

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/flyer" 3
#FALLBACK_STYLEROOT="" 4
HTML_CSS="./daps.css" 5
EPUB_CSS="./daps.css" 5

1

Specifies the XML MAIN file. It contains the highest-level object (root element) of your documentation project. The MAIN file must be located in YOUR_DOC_DIR/xml/. Therefore, you only need to specify the MAIN's file name in the DC file (no path).

2

Defines the root ID of the element to be used for creating an output format. Usually, you specify the root ID of a book or article element here.

In this example, art.daps.quick is the root ID of the DAPS Quick Start Guide, contained in MAIN.DAPS.xml.

3

For a custom layout, use the STYLEROOT parameter to specify the (absolute or relative) path to the directory containing the custom stylesheets. Using absolute paths is recommended for DC files.

In this example, the parameter specifies the path to a directory with SUSE-specific stylesheets for the flyer layout that is used by the DAPS Quick Start Guide.

4

Allows you to define a fallback which is used in case the custom stylesheets defined with STYLEROOT cannot be accessed. In case neither the stylesheets specified with STYLEROOT nor with FALLBACK_STYLEROOT can be accessed, DAPS uses the default DocBook layout.

In this example, no fallback is specified and the parameter is disabled.

5

If not specified, DAPS will use the default DocBook stylesheets for production of HTML and EPUB. For custom CSS styles, specify the (absolute or relative) path to the respective CSS file. Using absolute paths is recommended for DC files.

In this example, custom CSS files are specified for both HTML and EPUB output.

Example 2.7: DC File For Another Book in the Same Set
## Doc config file for DAPS User Guide
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" 1

## Optional Parameters
## ROOTID
## If MAIN contains a set with several books and/or articles, use
## a separate DC-file for each book/article and set ROOTID to
## the id of the respective <book>/<article> element of the document
## This will enable you to build individual books/articles rather than
## the whole set
## See http://www.docbook.org/tdg/en/html/set.html for more information
## on sets
ROOTID="book.daps.user" 2

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/" 3
#FALLBACK_STYLEROOT="" 4
HTML_CSS="./daps.css" 5
EPUB_CSS="./daps.css" 5

## Formatter
# Specify which PDF formatter to use. Currently only fop or xep are supported

FORMATTER="xep" 6

##Draft Mode
# Turns on DRAFT watermarks in PDF or HTML builds when set to "yes"
# Is ignored for any other output format and has no effect on profiling.
# This value can be set to "yes" using the -d switch on the command line
# Also see COMMENTS and REMARKS
#
DRAFT="yes" 7

1

Specifies the XML MAIN file. It contains the highest-level object (root element) of your documentation project. The MAIN file must be located in YOUR_DOC_DIR/xml/. Therefore, you only need to specify the MAIN's file name in the DC file (no path).

2

Defines the root ID of the element to be used for creating an output format. Usually, you specify the root ID of a book or article element here.

In this example, book.daps.user is the root ID of the DAPS User Guide, contained in MAIN.DAPS.xml.

3

For a custom layout, use the STYLEROOT parameter to specify the (absolute or relative) path to the directory containing the custom stylesheets. Using absolute paths is recommended for DC files.

In this example, the parameter specifies the path to a directory with SUSE-specific stylesheets that is used by the DAPS User Guide.

4

Allows you to define a fallback which is used in case the custom stylesheets defined with STYLEROOT cannot be accessed. In case neither the stylesheets specified with STYLEROOT nor with FALLBACK_STYLEROOT can be accessed, DAPS uses the default DocBook layout.

In this example, no fallback is specified and the parameter is disabled.

5

If not specified, DAPS will use the default DocBook stylesheets for production of HTML and EPUB. For custom CSS styles, specify the (absolute or relative) path to the respective CSS file. Using absolute paths is recommended for DC files.

In this example, custom CSS files are specified for both HTML and EPUB output.

6

Specifies the PDF formatter to use.

For supported formatters, refer to Section “Software Requirements”, Quick Start Guide. In this example, XEP is specified as PDF formatter.

7

When set to yes, a DRAFT watermark appears in PDF or HTML outputs of the document.

If your documentation project contains cross-references between the individual books in a set, it is useful to define an additional DC file —without the ROOTID parameter. Use this (generic) DC to generate HTML outputs containing all hyperlinks between the individual books (or for creating file lists of all source files and images used in the set). Find an example DC file in Example 2.8, “DC File for a Set”.

Example 2.8: DC File for a Set
## Doc config file for the DAPS Documentation Set
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" 1

## Optional Parameters
## ROOTID
## If MAIN contains a set with several books and/or articles, use
## a separate DC-file for each book/article and set ROOTID to
## the id of the respective <book>/<article> element of the document
## This will enable you to build individual books/articles rather than
## the whole set
## See http://www.docbook.org/tdg/en/html/set.html for more information
## on sets
#ROOTID="" 2

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/" 3
#FALLBACK_STYLEROOT="" 4
HTML_CSS="./daps.css" 5
EPUB_CSS="./daps.css" 5

## enable sourcing
export DOCCONF=$BASH_SOURCE 6

1

Specifies the XML MAIN file. It contains the highest-level object (root element) of your documentation project. The MAIN file must be located in YOUR_DOC_DIR/xml/. Therefore, you only need to specify the MAIN's file name in the DC file (no path).

2

Defines the root ID of the element to be used for creating an output format. Usually, you specify the root ID of a book or article element here.

In this example, no ROOTID is set. This allows to build the complete documentation set, with the output containing all hyperlinks between the individual books.

3

For a custom layout, use the STYLEROOT parameter to specify the (absolute or relative) path to the directory containing the custom stylesheets. Using absolute paths is recommended for DC files.

In this example, the parameter specifies the path to a directory with SUSE-specific stylesheets.

4

Allows you to define a fallback which is used in case the custom stylesheets defined with STYLEROOT cannot be accessed. In case neither the stylesheets specified with STYLEROOT nor with FALLBACK_STYLEROOT can be accessed, DAPS uses the default DocBook layout.

In this example, no fallback is specified and the parameter is disabled.

5

If not specified, DAPS will use the default DocBook stylesheets for production of HTML and EPUB. For custom CSS styles, specify the (absolute or relative) path to the respective CSS file. Using absolute paths is recommended for DC files.

In this example, custom CSS files are specified for both HTML and EPUB output.

6

When set to yes, a DRAFT watermark appears in PDF or HTML outputs of the document.

6

Enabling this parameter allows you to source the DC file on the Bash with DAPS. Sourcing a DC file (formerly called ENV file) was necessary to work with the documentation environment provided by susedoc, DAPS's predecessor.

2.5 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 2.9 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 2.9: Required 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

On the topmost level of your documentation directory, store the DC file defining your documentation project. You can store multiple DC files here (for multiple books belonging to the same documentation project, or DC files for various documentation projects). For more information, refer to Section 2.4.1, “Key Files”.

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 basic information about referencing images, refer to Section “Referencing Images”, Quick Start Guide.

4

Directory holding the XML MAIN file and all other XML files for the documentation project. If you declare entities in one or more external files (for example, in entity-decl.ent), put the entity declaration files here, too.

5

The MAIN file of the documentation project. It contains the starting point (the highest-level object) of your documentation project. For more information, refer to Section 2.4.1, “Key Files”.

2.5.1 The build Directory

To strictly discriminate between all source content added by users and the content generated by DAPS, DAPS uses a build directory. When generating output from your documentation project for the first time, DAPS adds a build directory to your documentation directory. It is located parallel to the xml and images subdirectories. (If desired, the name and path of the build directory can be changed with the parameter BUILD_DIR in /etc/daps/config or ~/.daps/config.)

The build directory is structured as follows:

Example 2.10: Build Directory
YOUR_DOC_DIR 1
  |--build/ 2
     |--NAME_OF_DC1/ 3
     |--NAME_OF_DC2/ 3
     |--.images/ 4
     |--.profiled/ 5
     |--.tmp/ 6

1

Working directory for the respective documentation project.

2

Directory that holds all contents build by DAPS.

3

For each of your documentation deliverables, DAPS creates a subdirectory, named after the respective DC from which you build the book, article or set. All formats that have been generated from the DC (PDF, HTML, TXT, EPUB etc.) can be found there. A log subdirectory stores log files for each output format that has been generated by DAPS.

4

Directory holding the images created by DAPS.

5

Directory holding the profiled XML sources created by DAPS.

6

Directory holding temporary files created by DAPS (for example, the FO files).

2.6 Basic DAPS Syntax

Before moving forward, let's get familiar with the basic syntax of the daps command:

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

Example 2.11, “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 2.11: DAPS Syntax
tux > 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 4.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 

3 Editing DocBook XML

This chapter describes:

  • how to choose an editor for editing DocBook XML files,

  • how to check the contents of your DocBook files for mistakes, and

  • how to adapt your documentation to fit multiple similar product versions at once

3.1 Basic Structural Elements

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.

3.2 Choice of Editor

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.

XML elements can be nested deeply. Constructs like variablelist, table or image often have a lot of child elements—some of them required, some optional. If you have an editor with schema support, it will tell you which elements are allowed at the current cursor position, but nevertheless it is cumbersome if you need to insert the child elements of complex XML constructs consecutively.

Most editors allow you to define or record macros which you can use for automatically inserting empty skeletons for a complex XML construct. For Emacs, DAPS already includes macros for adding DocBook elements. For details, refer to Section B.1, “Emacs—Macros for Inserting DocBook Elements”.

3.3 Spell Checking

DAPS comes with a spell checker that is optimized for DocBook documents: Tags and attributes are excluded from the check so that you can focus on the content of the document. The spell checker is based on aspell and can be run from the command line. By default, it starts in interactive mode, but you can also run it in batch mode where it dumps a sorted list of misspelled words to standard output. DAPS also allows you to specify a custom dictionary and the language to use for spelling.

In the following, find some examples on how to spell check with DAPS. All options discussed below can be combined with each other, except for --file and --rootid which exclude each other.

Note
Note: spellcheck Options and XIncludes

All options discussed below can be combined with each other, except for --file and --rootid which exclude each other.

The spellcheck command always follows xi:includes, even when using the --file option.

Spell Checking Files in a Documentation Project
tux > daps -d PATH_TO_DC_FILE spellcheck

Spell checks all files in the documentation project with the default dictionary (en_US). One by one, the files are opened in interactive mode and checked with aspell. To abort spell checking of the current file, press X. The spell check continues with the next file in the project.

Uses the ROOTID defined in the specified DC file as starting point. You can restrict the spell check to parts of the set, such as a book, article, glossary, appendix, part, or chapter element. To do so, specify the ID of the respective element with the --rootid option:

tux > daps -d PATH_TO_DC_FILE spellcheck --rootid=ID 
Spell Checking a Single XML File
tux > daps -d PATH_TO_DC_FILE spellcheck --file PATH_TO_XML_FILE 

Checks the specified file with the default dictionary. Suggests alternative spellings for each misspelled word and waits for user interaction.

Spell Checking XML Files in Languages Other than English
tux > daps -d PATH_TO_DC_FILE spellcheck --lang=LANG \
[--file PATH_TO_XML_FILE]

Checks the specified documentation project or file with the dictionary for LANG (make sure the specified aspell dictionary is installed). Suggests alternative spellings for each misspelled word and waits for user interaction. The language code used for the --lang option is the same that is used for the LANG environment variable and matches the directory names in /usr/share/locale.

Spell Checking XML Files in Batch Mode
tux > daps -d PATH_TO_DC_FILE spellcheck --list \
[--file PATH_TO_XML_FILE]

Checks the specified documentation project or file. Returns a list of misspelled words to standard output. You can use the --list option to easily collect a list of words that are unknown to aspell and use this output as basis for a custom aspell word list or dictionary.

Spell Checking XML Files with an Additional Custom Dictionary
tux > daps -d PATH_TO_DC_FILE spellcheck --extra-dict=PATH_TO_CUSTOM_DICT \
[--file PATH_TO_XML_FILE]

Checks the specified documentation project or file with the default dictionary plus the additional custom dictionary specified with --extra-dict.

For your convenience, you can integrate daps-susespell (plus a custom aspell dictionary, if needed) into your XML editor, so that spelling is checked on the fly during editing. Consult your editor's documentation on how to integrate a custom dictionary. If you use jEdit, proceed as outlined in Section B.2, “jEdit—Spell Check on the Fly”.

To make sure that all external links (such as http, https and ftp links) in your XML sources are valid (and do not give a 404 error or similar), DAPS also includes a link checker (based on checkbot, see man 1 checkbot for more information). It searches for the url attribute in ulink elements and checks links included there. Use it to create a report of all links that caused some kind of warning or error.

Note
Note: checklink follows XIncludes

The checklink command always follows xi:includes, even when using the --file option.

Checking Links in a Documentation Project
tux > daps -d PATH_TO_DC_FILE checklink

Uses the ROOTID defined in the specified DC file as starting point. Checks the ulink elements in all files belonging to the documentation project. The resulting HTML report *checkbot-localhost.html can be opened in a browser, see Figure 3.1, “Example Output of daps checklink.

If your DC file references a documentation set, you probably do not want to check all files belonging to the set. You can restrict the check to parts of the set, such as a book, article, glossary, appendix, part, or chapter element. To do so, specify the ID of the respective element with the --rootid option:

tux > daps -d PATH_TO_DC_FILE checklink --rootid=ID 
Checking Links in a Single XML File
tux > daps -d PATH_TO_DC_FILE checklink --file=PATH_TO_XML_FILE 

Checks the ulink elements in the specified file. At the end of the check, DAPS returns an HTML file with a list of all links which caused some kind of warning or error. Open the resulting checkbot-localhost.html file in a browser.

Tip
Tip: Opening the Link Check Report

To directly open the link check report, use the DAPS command output as an argument for a browser, for example the command-line Web browser w3m:

tux > w3m -dump $(daps -d PATH_TO_DC_FILE checklink)

3.5 Profiling—Support for Document Variants

Similar products often share a considerable amount of features and differ in details only. It is therefore convenient to apply the same approach to the documentation of similar products or product families: Share most of the XML source code and only differentiate text snippets where necessary. DocBook allows you to create documentation variants from the same pool of XML sources by means of profiling.

In DocBook XML files you can mark some elements as conditional by using profiling attributes. When processing the files to generate output, specify which conditions apply to the output. The stylesheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one XML file and select at production time which information to include in the output.

For details, refer to Section 6.3, “Profiling—Support for Document Variants”.

3.6 For More Information

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

Useful tips and tricks around using DocBook and the DocBook stylesheets can be found in The DoCookBook—Recipes for DocBook Developers and Writers, available at http://doccookbook.sourceforge.net/.

4 Generating Output Formats

This chapter describes:

  • how to validate your XML files,

  • the basic command syntax for generating output formats,

  • which output formats you can generate with daps and which commands to use, and

  • how to do partial builds of your documentation or how to specify 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

Validation within your XML editor is bound to fail, as soon you use profiling in your DocBook sources. Profiling is similar to conditional text, for details, refer to Section 6.3, “Profiling—Support for Document Variants”. 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 due to 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 Your 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 Your Files Including Remark Elements
tux > daps -d PATH_TO_DC_FILE validate --remarks
Validating Your Files Including XML Comments (<!--Comment-->)
tux > daps -d PATH_TO_DC_FILE validate --comments

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 color-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 (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.

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 further advanced output options like including remarks, metadata 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 Your Documentation Project
tux > daps -d DC-daps-example color-pdf --rootid=cha.template.examples

Instead of always building your complete documentation project (set, book, or article), DAPS also allows you do 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 to build only a part of your documentation project by using the ID of a book, article, glossary, appendix, part, or chapter element.

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.

5 Image Handling

This chapter describes:

  • which types of images are supported by DAPS and how to use them,

  • the distinction between source images and generated images, and the image directory structure required by DAPS,

  • the file name requirements for source images,

  • how to reference images in your DocBook files,

  • and how to manage source images and generated images with DAPS commands.

5.1 Supported Image Types

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.

DAPS supports the following types of images:

  • DIA

  • EPS (experimental)

  • FIG

  • JPEG

  • PDF (experimental)

  • PNG

  • SVG

Image formats can be categorized into pixel-based image formats (also called bitmap formats) and vector-based image formats. In pixel-based image formats the data describes the characteristics of each pixel. In contrast to that, vector-based image formats contain a geometric description that can be rendered smoothly. Vector-based images are resolution-independent—they can be displayed or printed as large or small as you wish without showing pixel artifacts.

From the supported image types listed above, only PNG is a pixel-based image format.

Important
Important: Limited PDF and EPS Image Support

Support for PDF and EPS image formats in DAPS is limited. Currently, both formats are only supported in combination with the XEP formatter. Using either format might also lead to longer document creation times.

5.1.1 DIA

DIA is a vector image format which means it is resolution-independent. Images in this format can be displayed or printed as large or small as you wish without showing pixel artifacts. The format is suited especially well to creating diagrams. DIA files are XML files that are automatically compressed when saving, thus they are often quite small.

To create DIA files, there is a software of the same name: Dia (https://live.gnome.org/Dia). Dia is a diagram editor which can be used to draw entity-relationship diagrams, UML diagrams, and flowcharts.

Dia makes it very easy to connect elements, to add text and to use simple fill and border colors. Although it can import SVG files as shapes, it is not useful for freely drawing shapes itself. Complex or effect-laden vector illustrations and information graphics are hard to create with Dia.

5.1.2 EPS

The Encapsulated Postscript (EPS) format is a general purpose vector image format. As a Postscript-based format, it is similar to PDF. There is currently no mainstream Linux image editor software that creates EPS files natively, although a number of applications can export into it.

Where feasible, use SVG files instead of EPS files. EPS might occasionally serve as an exchange format with contributors that use Adobe* graphics software.

5.1.3 FIG

FIG is a vector image format that can be created with the software Xfig (http://www.xfig.org). The support for FIG files can help when working with legacy images. However, it is recommended to use SVG format for new illustrations and DIA for new diagrams.

5.1.4 PDF

The Portable Document File format is a general purpose, page-based fixed-layout document format. PDF is a Postscript-based format. There is a large number of Linux software that can export PDF files natively. PDF files can also be used as an exchange format with contributors that are unable to export to SVG.

5.1.5 PNG

The Portable Network Graphics format can be used if you wish to use a raster (point-based) image. A good example for when to use PNG files are screenshots and photographs.

PNG files can be created with a number of applications, including the GIMP graphics editor.

Tip
Tip: Make PNG Files Smaller with daps optipng

To decrease the file size of PNG images without altering their look, use daps optipng. It removes unused colors and alpha channels.

To run optipng over an entire book's PNG images:

tux > daps -d PATH_TO_DC_FILE optipng

5.1.6 SVG

The Scalable Vector Graphics format is a general purpose, vector image format. SVG is an XML format which can be displayed in most browsers and edited in many graphics programs.

Important
Important: Use Plain SVG Format

Some SVG editors offer the choice of saving your file in a custom SVG-based format or in Plain SVG (standard SVG). In this case, always use the plain version. Custom SVG formats might not be compatible with the components used by DAPS for processing SVG files.

A good open source SVG editor is Inkscape (http://inkscape.org/), which is available for most operating systems. You can also create SVG files from many Adobe products, for instance, from Illustrator*. SVG is the preferred vector image format for DAPS.

5.2 Source Images and Generated Images

DAPS strictly discriminates between source images (any images that have been created outside of DAPS) and images that are generated by DAPS.

This clear disctinction is also visible in the file system: source images are stored in a different directory than generated images.

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 2.5, “Directory Structure”.

From your source images, DAPS automatically generates appropriate image formats for each output format. They are stored in build/.images/ within the project directory. If an image referenced from your DocBook files is changed, DAPS will notice when trying to build and generate new versions of the image automatically.

For gaining an overview of source images or generated images, and for managing both, DAPS provides different subcommands. For details, refer to Section 5.5, “DAPS Commands for Managing Images”.

5.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.

5.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 5.1: 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>

5.5 DAPS Commands for Managing Images

DAPS offers a number of subcommands for managing images in a documentation project. By default, the output of the subcommands is a list of image file names (including the absolute path), all printed in one line with the file names separated by blanks, see Example 5.2. This default output format is useful for piping (or copying and pasting) the output for use with another command.

Example 5.2: Default Output of an Image-related DAPS Command
PATH/images/src/dia/example_dia1.dia PATH/images/src/png/example_png1.png PATH/images/src/png/example_png2.png PATH/images/src/png/example_png3.png PATH/images/src/svg/example_svg.svg PATH/images/src/fig/example_fig1.fig ...

For better on-screen reading (or for copying the output to an e-mail, for example), use the --pretty parameter. It adds a line break after each file name, so that only one file name is shown per line—see Example 5.3.

Example 5.3: Pretty-printed Output of an Image-related DAPS Command
tux > daps -d PATH_TO_DC_FILE projectgraphics --pretty
PATH/images/src/dia/example_dia1.dia
PATH/images/src/png/example_png1.png
PATH/images/src/png/example_png2.png
PATH/images/src/png/example_png3.png
PATH/images/src/svg/example_svg.svg
PATH/images/src/fig/example_fig1.fig ...
Tip
Tip: Use Pretty-Printed Output for Counting

To count the number of images listed in a given output, you can also combine the --pretty parameter with the wc command:

tux > daps -d PATH_TO_DC_FILE projectgraphics --pretty | wc -l

For Example 5.3, the command above would return the value

5

.

5.5.1 Working with Source Images

To find out which images are used/not used in a project or referenced in a DocBook file but missing from the file system, DAPS offers subcommands that check your project for such issues.

Apart from that, you can check your source images for non-unique names and reduce the size of your PNGs with an optimizer that recompresses the files to a smaller size.

Listing All Graphics Referenced in a Documentation Project
tux > daps -d PATH_TO_DC_FILE  projectgraphics

Lists all graphics used by the DocBook files that are referenced in the current DC file.

Listing Missing Graphics in a Documentation Project
tux > daps -d PATH_TO_DC_FILE  missinggraphics

Lists all graphics that are referenced in your DocBook files, but could not be found in the file system. In case there are any missing graphics, you will not be able to build your project.

Checking for Superfluous Graphics
tux > daps -d PATH_TO_DC_FILE remaininggraphics

Lists all graphics that are not referenced in your DocBook files, but are available in the images/scr subdirectories. This command is useful if you want to clean up your source images and want to know which images are no longer needed for the documentation project.

Important
Important: Use a set to Check for Superfluous Graphics

If you are storing multiple DC files in the same project folder, use the DC file of a set for this check. As it contains all articles and books in the project folder, this makes sure that any graphics found during the check are indeed unnecessary.

Checking for Non-Unique Graphic File Names
tux > daps -d PATH_TO_DC_FILE warn-images

Checks the images/src subdirectories for non-unique base names. For more information, refer to Section 5.3, “File name Requirements”.

Reducing the File Size of PNG Graphics
tux > daps -d PATH_TO_DC_FILE optipng

Recompresses any PNG files in the images/src/png directory with the PNG optimizer optipng without reducing the image quality.

5.5.2 Working with Generated Images

As with source images, DAPS can create lists of images that have been generated for use with the various output formats. You can also remove all images generated for a certain DC file, if needed.

Listing All Color Images Generated by DAPS
tux > daps -d PATH_TO_DC_FILE xmlgraphics

Lists all color images of the specified documentation project that have been generated by DAPS.

Listing All Grayscale Images Generated by DAPS
tux > daps -d PATH_TO_DC_FILE xmlgraphics-bw

Lists all grayscale images of the specified documentation project that have been generated by DAPS.

Deleting All Generated Images for a Documentation Project
tux > daps -d PATH_TO_DC_FILE clean-images

Deletes all images generated for a certain DC file. This is only necessary in rare cases, for example, when a file previously had an incorrect timestamp or when you have changed your global DAPS configuration. In that cases, DAPS might wrongly assume that an already generated file should be inserted into your output format when in reality the file should be re-generated.

6 Modularizing Documentation Projects

This chapter describes:

  • how to modularize documents by splitting them into XIncludes,

  • how to use a consistent set of entities throughout a documentation project,

  • how to create document variants by using profiling, and

  • how to combine profiling and entities.

6.1 Splitting up Documents into XIncludes

Instead of putting the contents of a complete article or book into the MAIN file, DocBook allows you to divide the text into separate document files. They are then assembled in the MAIN file using XIncludes as shown in Example 2.5, “MAIN file of a Set (DocBook 4.x)”. XIncludes can be used for splitting up sets, books, articles or chapters into separate files. For more information, refer to Physical Divisions: Breaking a Document into Separate Files (http://www.docbook.org/tdg51/en/html/ch02.html).

XIncludes do not cause any problems with DAPS and are fully supported. For example, daps commands like checklink or spellcheck, for example) also follow XIncludes.

6.2 Declaring Entities in a Separate File

If you declare entities in the document type declaration of individual XML files, it becomes cumbersome to keep a consistent set of entities when maintaining a large number of documents for a product. For large documentation projects, it is therefore useful to put all entity declarations into a separate file and then reference that file in the individual XML files.

Example 6.1: Separate Entity File entity-decl.ent
<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY exampleuser "tux">
<!ENTITY exampleuserII "wilber">
<!ENTITY examplegroup "users">
[...]
Example 6.2: Referencing A Separate Entity File
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
[
  <!ENTITY % entities SYSTEM "entity-decl.ent"> 1
  %entities; 2
]> 
<chapter>
<title>Managing User Accounts</title>
[...]

1

Reference to the separate entity declaration file (with the <!ENTITY> keyword).

2

Loads the external entity file declared in the previous line.

For more information, refer to Modular DocBook Files: Shared text entities (http://www.sagehill.net/docbookxsl/ModularDoc.html).

Separate entity files do not cause any problems with DAPS— during generation of output, the entities will be treated equally to entities declared in individual XML files.

It is also possible to use multiple entity files by including them into the separate entity file that is referenced in the XML file.

Example 6.3: Referencing Entity Files Within an Entity File
<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY exampleuser "tux">
<!ENTITY exampleuserII "wilber">
<!ENTITY examplegroup "users">
[...]
<ENTITY % network-entities SYSTEM "network-decl.ent"> 1
%network-entities; 2
<ENTITY % more-entities SYSTEM "another-decl.ent"> 1
%more-entities; 2

1

Reference to the separate entity declaration file (with the <!ENTITY> keyword).

2

Loads the external entity file declared in the previous line.

6.3 Profiling—Support for Document Variants

Similar products often share a considerable amount of features and differ in details only. It is therefore convenient to apply the same approach to the documentation of similar products or product families: Share most of the XML source code and only differentiate text snippets where necessary. DocBook allows you to create documentation variants from the same pool of XML sources by means of profiling.

In DocBook XML files you can mark some elements as conditional by using profiling attributes. When processing the files to generate output, specify which conditions apply to the output. The stylesheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one XML file and select at production time which information to include in the output.

6.3.1 Introduction to DocBook Profiling

DocBook offers profiling attributes for various purposes as illustrated in Table 26.1. Profiling attributes (http://www.sagehill.net/docbookxsl/Profiling.html). Currently, not all of them are supported by DAPS. For details, refer to Section 6.3.2, “Using Profiling with DAPS”.

Generally, profiling attributes can be used on a large number of elements—from high-level elements like book or chapter down to low-level elements like para. With the phrase element, you can even profile inline elements, like one sentence within a paragraph.

Based on the conditions that you want to apply, select one or more profiling attributes and add them to the text snippets that are conditional. The tagged snippets will only be included in the output if the required condition is fulfilled. Any content that is valid for all conditions does not need any profiling attributes. The respective content will always be included in the output formats generated from the XML sources. You are free in defining the attribute values (condition="foo"), but they must be used consistently in all files belonging to a documentation project.

Example 6.4, “Product-specific Profiling (One Attribute)” shows how to profile product-specific information in a software description. Let us assume we have to write documentation for the fictional software Frog Sound Recordings. The software is available in two editions: a basic edition for home users and a professional edition for enterprise customers. Both editions share common features, but some features are only available in the basic or the professional edition, respectively.

Example 6.4: Product-specific Profiling (One Attribute)
<simplelist>
  <member>Common Feature 1</member>
  <member>Common Feature 2</member>
  <member>Common Feature 3</member>
  <member condition="basic">Basic Feature 1</member>
  <member condition="prof">Professional Feature 1</member>
  <member condition="prof">Professional Feature 2</member>
</simplelist>

When generated for the basic edition or for the professional edition, respectively, the example source code would result in the following output:

Table 6.1: Output of Example 6.4

Basic Edition

Professional Edition

Common Feature 1

Common Feature 2

Common Feature 3

Basic Feature 1

Common Feature 1

Common Feature 2

Common Feature 3

Professional Feature 1

Professional Feature 2

If the profiling attributes are not processed during output, the source code in Example 6.4, “Product-specific Profiling (One Attribute)” would result in the following (identical) output for both editions:

Table 6.2: Output of Example 6.4 (Without Profiling)

Basic Edition

Professional Edition

Common Feature 1

Common Feature 2

Common Feature 3

Basic Feature 1

Professional Feature 1

Professional Feature 2

Common Feature 1

Common Feature 2

Common Feature 3

Basic Feature 1

Professional Feature 1

Professional Feature 2

Let's suppose the professional edition of the software is also available as OEM (original equipment manufacturer) version by the vendor OEM Company. It contains additional features that are only available in the OEM version:

Example 6.5: Product-specific Profiling (Multiple Attributes)
<simplelist>
  <member>Common Feature 1</member>
  <member>Common Feature 2</member>
  <member>Common Feature 3</member>
  <member condition="basic">Basic Feature 1</member>
  <member condition="prof">Professional Feature 1</member>
  <member condition="prof">Professional Feature 2</member>
  <member condition="prof" vendor="oemcompany">OEM Feature 1</member>
</simplelist>

When generated for the professional edition or for the professional edition in the OEM version, respectively, the example source code would result in the following output:

Table 6.3: Output of Example 6.5

Professional Edition

Professional Edition (OEM Version)

Common Feature 1

Common Feature 2

Common Feature 3

Professional Feature 1

Professional Feature 2

Common Feature 1

Common Feature 2

Common Feature 3

Professional Feature 1

Professional Feature 2

OEM Feature 1

6.3.2 Using Profiling with DAPS

To create multiple documentation variants of the same pool of DocBook files with DAPS, the following requirements need to be fulfilled:

For a comprehensive example showing all requirements in detail, refer to Section 6.3.2.4, “Profiling Example”.

6.3.2.1 XML Files: Profiling Attributes

In your DocBook XM files, only use profiling attributes that are supported by DAPS—refer to Table 6.4, “Profiling Attributes (DocBook) and Profiling Parameters (DAPS)”. In DAPS, each profiling attribute has a corresponding profiling parameter to be used in the DC file. The profiling parameters define which profiling attributes and values to interpret during generation of output.

Table 6.4: Profiling Attributes (DocBook) and Profiling Parameters (DAPS)

Attribute Name

Use

Profiling Parameter

arch

Computer or chip architecture, such as i386.

PROFARCH

condition

No preassigned semantics, general purpose attribute.

PROFCONDITION

os

Operating system.

PROFOS

vendor

Product vendor.

PROFVENDOR

6.3.2.2 MAIN file: Processing Instruction

To activate generation of profiled output in DAPS, the following processing instruction (PI) must be included in the header of the MAIN file, before the root element:

<?xml-stylesheet
  href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" 
  type="text/xml" ?>

The MAIN file of a documentation project is the one that is referenced by the MAIN parameter in the DC file. If the processing instruction is missing in the MAIN file, any profiling parameters in the DC file will be ignored during generation of the output.

Tip
Tip: Include PI in All XML Files

For any documentation projects that need profiling, we advise to include the PI in all XML files. Otherwise you might forget to move the PI in case of restructuring the XML sources. Having the PI in all XML files does not hurt: Generation of profiled output is only triggered if your DC files contain profiling parameters.

6.3.2.3 DC Files: Profiling Parameters

Depending on the profiling attributes used in your XML files, a DC file may contain multiple profiling parameters, see Table 6.4, “Profiling Attributes (DocBook) and Profiling Parameters (DAPS)”. Profiling parameters define which of the profiling attributes should be interpreted by DAPS when generating output. For each profiling parameter, set the respective attribute values for which you want to filter during the profiling process. The spelling of the values must be the same that is used in the XML files.

6.3.2.4 Profiling Example

In the following, find a comprehensive example that shows the basic DAPS profiling requirements in more detail. It is based on the examples in Section 6.3.1, “Introduction to DocBook Profiling” about the fictional software Frog Sound Recordings which is available in a basic edition, a professional edition and a professional OEM edition, shipped by an OEM vendor. The following example shows all files that you need to consider (XML files, MAIN file, and DC file).

Example 6.6: XML File With Profiling Attributes
<?xml version="1.0" encoding="utf-8"?>
[...] 
 
<chapter id="frog.features">
 [...]
 <simplelist>
   <member>Common Feature 1</member> 1
   <member>Common Feature 2</member> 1
   <member>Common Feature 3</member> 1
   <member condition="basic">Basic Feature 1</member> 2
   <member condition="prof">Professional Feature 1</member> 3
   <member condition="prof">Professional Feature 2</member> 3
   <member condition="prof" vendor="oemcompany">OEM Feature 1</member> 4
 </simplelist> 
 [...]
</chapter>

1

Unprofiled listitems. The common features 1-3 are available in all software editions or versions.

2

Listitem profiled with attribute condition and attribute value basic. Basic Feature 1 is only available in the basic software edition for home users.

3

Listitem profiled with attribute condition and attribute value prof. Professional Feature 1 and Professional Feature 2 are only available in the professional software edition for enterprise customers.

4

Listitem profiled with two attributes: Attribute condition with attribute value prof and attribute vendor with attribute value oemcompany. OEM Feature 1 is only available in the professional OEM software edition for enterprise customers.

Example 6.7: MAIN file With PI for Profiling
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet  
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" 
 type="text/xml"
 title="Profiling step"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>  

<!--the following article is contained in the file art_frog.xml-->

<article lang="en" id="art.frog"> 
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
 [...]
</article>

If the processing instruction (PI) is missing, any profiling parameters in the DC file will be ignored.

Example 6.8: DC File with Profiling for Home Edition
## Doc Config File for Frog Sound Recordings
## (Home Edition)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="basic" 2
[...]

1

MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”.

2

DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="basic" are included in the output.

Example 6.9: DC File with Profiling for Professional Edition
## Doc Config File for Frog Sound Recordings
## (Professional Edition)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="prof" 2
[...]

1

MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”.

2

DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="prof" are included in the output.

Example 6.10: DC File with Profiling for Professional Edition (OEM Version)
## Doc Config File for Frog Sound Recordings 
## (Professional Edition, OEM Version)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="prof" 2
PROFVENDOR="oemcompany" 3
[...]

1

MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”.

2

DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="prof" are included in the output.

3

DAPS profiling parameter for the vendor profiling attribute. It defines that XML elements tagged with vendor="oemcompany" are included in the output.

6.4 Combining Entities and Profiling

For maximum flexibility in generating documentation variants from the same source, DAPS also supports the combination of entities and profiling. As you already learned in Section 6.2, “Declaring Entities in a Separate File”, it is useful for modularization purposes to declare entities in a separate file and to re-use it in multiple documentation projects. For multiple use of entities like &productname; or &productnumber;, declare them in a separate file and add profiling within the entities as shown in Example 6.11, “Separate Entity File with Profiling Attributes”. During generation of output, DAPS then automatically replaces the entities with different values during output, depending on the context.

Example 6.11: Separate Entity File with Profiling Attributes

<!--the following declarations are contained in the file entity-decl.ent -->

<!ENTITY productname  
 '<phrase cond="basic">Frog Sound Recordings (Basic)</phrase>
  <phrase cond="prof">Frog Sound Recordings (Professional)</phrase>
  <phrase cond="prof" vendor="oemcompany">Gecko Sound Recording (Professional)</phrase>'>

<!ENTITY productnumber  
 '<phrase cond="basic">1.0</phrase>
  <phrase cond="prof">4.2</phrase>
  <phrase cond="prof" vendor="oemcompany">4.21</phrase>'>

After declaring the entities as shown in Example 6.11 you can use them throughout your documents. For DAPS to process them correctly, you only need to introduce the entities once as shown in Example 6.12, “XML File with &productname; and &productnumber; Entities”.

  1. Insert one of the respective elements setinfo, bookinfo, or articleinfo in your set, book, or article.

  2. Within setinfo, bookinfo, or articleinfo, add both a productname and productnumber element.

  3. Use the &productname; and &productnumber; entity within the respective elements.

Then use them in the text wherever you need them.

Example 6.12: XML File with &productname; and &productnumber; Entities

<?xml version="1.0" encoding="utf-8"?>

<?xml-stylesheet 
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" 
 type="text/xml" 
 title="Profiling step"?> 1

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent"> 
%entities; 
 ]> 2
 
<!--the following article is contained in the file art_frog.xml-->

<article lang="en" id="art.frog"> 
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
  <articleinfo> 3
   <productname>&productname;</productname> 4
   <productnumber>&productnumber;</productnumber> 5
 </articleinfo>
  <abstract>
   <para> 
    &productname; &productnumber; is a software for recording, editing, 6
    and mixing audio data.
   </para> 
  </abstract>
 [...]
</article>

1

Processing instruction (PI) in the header of the MAIN file. If it is missing, any profiling parameters in the DC file will be ignored.

2

Reference to the separate entity declaration file (with a parameter entity).

3

Element articleinfo.

4

Element productname and entity &productname;.

5

Element productnumber and entity &productnumber;.

6

Paragraph containing the entities &productname; and &productnumber;.

In any output format, the entities (4, 5, 6) will automatically be replaced with different values, depending on the profiling parameters contained in the DC file that you use for generating the output. For an example, refer to Table 6.5. It shows output variants that can be generated from the XML code in Example 6.12 plus the entity declaration in Example 6.11 by using different DC files.

Table 6.5: Output Variants of Example 6.12

DC File

Output

DC File with Profiling for Home Edition

Frog Sound Recordings (Basic) 1.0 is a software for recording, editing, and mixing audio data.

DC File with Profiling for Professional Edition

Frog Sound Recordings (Professional) 4.2 is a software for recording, editing, and mixing audio data.

DC File with Profiling for Professional Edition (OEM Version)

Gecko Sound Recordings (Professional) 4.21 is a software for recording, editing, and mixing audio data.

7 Review and Translation Processes

This chapter describes how to simplify review and translation processes with DAPS:

  • by including remarks, metadata or draft watermarks in the output,

  • by transforming the multiple DocBook files in your project into one big XML file, or

  • by creating distributable archives (XML sources, images, or various output formats)

7.1 Including Remarks, Metadata or Draft Watermarks in the Output

DAPS offers a number of features to simplify review and translation processes. For example, you can insert remark elements in the source code (for editorial remarks or questions to the proofreader) and generate an output format that either includes or suppresses these remarks. You can also generate preview versions of your documentation with a DRAFT watermark appearing on the HTML or PDF output.

If you use Docmanager in addition to DAPS, you can flag your XML files with meta-information (like workflow status). DAPS offers an option to also display this meta-information in the generated output.

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.

Find a few example commands below:

Including Remarks in the Output
tux > daps -d PATH_TO_DC_FILE color-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.

Building PDFs with a DRAFT Watermark
tux > daps -d PATH_TO_DC_FILE color-pdf --draft

Generates a PDF that has a DRAFT watermark printed on each page.

Including Metadata in the Output
tux > daps -d PATH_TO_DC_FILE color-pdf --meta

If metadata to a file has been set, DAPS includes the metadata for each file in the output format.

Note
Note: Restrictions of the --meta Option

As the --meta relies on certain mechanisms and SVN properties, including metadata in the output only works under the following conditions:

By default, the HTML and HTML-single outputs then show filename, file maintainer and workflow status, and additionally the ID of the chapter, appendix or prefix, if available. The PDF output shows filename and the ID of the chapter, appendix or prefix, if available.

7.2 Creating XML Bigfiles and Profiled XML Sources

Instead of sending multiple XML files to a proofreader for review, you can also transform all files included in your book or set into one huge DocBook XML file (bigfile). If you want to hand over profiled XML sources (instead of the original XML sources that may apply to several products), DAPS also allows for this—see the command overview below.

Creating an XML Bigfile
tux > daps -d PATH_TO_DC_FILE bigfile

DAPS resolves all XIncludes (replaces them with the referenced content) to create the bigfile. A message is shown where to find the generated output.

Creating Profiled XML Sources
tux > daps -d PATH_TO_DC_FILE dist-xml

If you use profiling attributes to manage document variants, DAPS creates a TAR archive with profiled XML files from your set. For details about profiling in DocBook and how to use it with DAPS, refer to Section 6.3, “Profiling—Support for Document Variants”.

Note
Note: Output Limitations

The output of dist-xml does not contain any graphics and the XML sources may not validate after being unpacked. To create TAR archives containing graphics and a complete, valid set of XML sources, use the command package-src. For further details, run daps package-src --help or refer to Chapter 8, Packaging and Deploying Your Documentation.

7.3 Creating Distributable Archives

For handing over your files to review or translation, or for distributing your output formats in a convenient way, DAPS can automatically create TAR archives of the XML sources, various output formats and/or graphics. DAPS uses bz2 for high compression of the archives and keeps the directory structure when generating the tar files.

If you have a huge documentation project of which only individual books or files are to be translated, you can mark the respective files as to be translated with Docmanager.

Find some example commands below.

Creating a Graphics TAR Archive
tux > daps -d PATH_TO_DC_FILE dist-graphics

Creates a TAR archive of all graphics that are referenced in the XML sources of the specified documentation project. The graphics will be included in their original format.

tux > daps -d PATH_TO_DC_FILE dist-graphics-png

Creates a TAR archive of all graphics that are referenced in the XML sources of the specified documentation project. All graphics will be converted to PNG format.

Creating a TAR Archive For Localization
tux > daps -d PATH_TO_DC_FILE locdrop

Use this command only if you manage your documentation project with Docmanager and have set the respective SVN properties to mark any files that are to be localized.

The command is especially helpful if not all files in your documentation project need to be translated, but only a subset of them (for example, one of several books in a set). It generates 3 TAR archives: one containing the graphics, one containing all XML files that need to be localized, and one containing the remaining files of the set. The remaining files are needed for solving any cross-references between translated and untranslated content during generation of output.

Creating TAR Archives with Different Output Formats
tux > daps -d PATH_TO_DC_FILE dist-html

Generates HTML output of the specified documentation project (including HTML files, any graphics, and your CSS file defining the HTML layout) and packs the output into a TAR archives.

tux > daps -d PATH_TO_DC_FILE dist-htmlsingle

Generates a single-file HTML output and packs the HTML file, any graphics, and your CSS file) into a TAR archive.

For further options related to creating distributable archives with DAPS, run daps --help.

8 Packaging and Deploying Your Documentation

This chapter describes:

  • how to create TAR archives with all source files, including graphics,

  • how to generate distributable HTML archives,

  • how to generate a color PDF,

  • how to generate JSP TAR archives for integration of your documentation into Web user interfaces (via JSP),

  • how to generate page, desktop, or document files for integration of your documentation in KDE and GNOME desktop environments.

Create source packages, HTML TAR archives, color PDFs, or JSP TAR archives with the daps package-* commands. By adding the respective options, you can additionally create page files, document files or desktop files for GNOME or KDE desktop environments.

8.1 Creating a TAR Archive with All Sources (Including Graphics)

Use the following command to create a distributable TAR archive containing the sources of the complete set, including the graphics:

tux > daps -d PATH_TO_DC_FILE package-src

8.2 Generating a Distributable HTML Archive

To generate HTML output and to automatically pack the HTML files, any graphics, and your CSS file into a TAR archive, use the following command:

tux > daps -d PATH_TO_DC_FILE package-html

8.3 Generating a Color PDF

Use the following command:

tux > daps -d PATH_TO_DC_FILE package-pdf

To tell DAPS which the formatter to use for creation of the PDF, add the option --formatter. For example, for FOP use:

tux > daps -d PATH_TO_DC_FILE package-pdf --formatter=fop

8.4 Generating a JSP TAR Archive

To create all archives and files needed for packaging a JSP document, use the following command:

tux > daps -d PATH_TO_DC_FILE package-jsp

8.5 Generating Desktop, Document, or Page Files

To create files that you can use for the help system of the GNOME and KDE desktop environments, use one of the following options:

  • For the GNOME help system Yelp: --pagefiles

  • For former Yelp versions: --documentfiles

  • For the KDE3 help system: --desktopfiles

For example, to create a distributable HTML archive plus the files for GNOME yelp, use the following command:

tux > daps -d PATH_TO_DC_FILE package-html --pagefiles

9 Customizing Layout of the Output Formats

This chapter includes:

  • how to modify individual XSLT processor parameters,

  • an external reference to a book that deals with common customizations to the DocBook stylesheets.

9.1 Modifying Individual XSLT Processor Parameters

If you use the default DocBook layout and want to adjust individual parameters, you can use the --xsltparam option. It will pass on values for an XSLT parameter directly to the XSLT processor, which is useful to temporarily overwrite style sheet parameters such as margins, for example.

For larger or more complex modifications, such as adjustments of the title page layout, for example, it is advisable to develop your own set of stylesheets instead.

For a list of XSLT parameters to modify, refer to one of the following parameter references at http://docbook.sourceforge.net/release/xsl/current/doc/index.html:

Example 9.1: Adjusting the Layout of Variablelists

By default, the DocBook stylesheets display the contents of a variablelist as a table. To change this temporarily, set the parameter variablelist.as.table to the value 0 by executing the following command:

daps html --xsltparam1 "'2--stringparam variablelist.as.table3 04'"2

1

As value of --xsltparam, add one or more xsltproc parameters in the form of "'--stringparam PARAM_NAME VALUE'".

2

You must quote the string with double and single quotes.

3

Name of the parameter to adjust.

4

Value for 3. It will be passed on unmodified to the XSLT processor call that creates the .fo file or HTML from the profiled XML sources.

9.2 Customizing the DocBook Stylesheets

Useful tips and tricks around using DocBook and the DocBook stylesheets can be found in The DoCookBook—Recipes for DocBook Developers and Writers, available at http://doccookbook.sourceforge.net/.

10 Configuring DAPS

This chapter covers:

  • how to customize DAPS behavior by adjusting or creating a local configuration file,

  • an example of a system-wide DAPS configuration file, including annotations about all parameters that you can modify.

DAPS can be customized to a large degree: per system, per user, and per document. The configuration file /etc/daps/config lists all parameters that can be configured, including a short description for each parameter. Parameters are always defined as KEY="VALUE" pairs. Any parameter can be set in various locations, which are listed below in ascending order with regards to their hierarchy. If conflicting values are set for the same parameter, the value defined in the next higher hierarchy level takes precedence. Values defined on the command line always take precedence over values set in any other locations.

  • /etc/daps/config (system-wide configuration file)

  • ~/.daps/config (user-specific configuration file)

  • DC (doc config) file of the documentation project (for settings specific to a document or documentation set)

  • on the fly at the command line by specifying options to a daps command.

For adjusting a few parameters that you want to set to custom values, do not edit the system-wide DAPS configuration file. Instead, check if the file ~/.daps/config already exists. If not, create the file and modify it as described below:

  1. Open both ~/.daps/config and /etc/daps/config in a text editor.

  2. Select which parameters you want to modify.

  3. Copy only those to ~/.daps/config.

    Note
    Note: Parameter Incompatibilities Between Configuration Files

    If copying all parameters from /etc/daps/config to ~/.daps/config, this will raise the risk of parameter incompatibilities as soon as you update to a higher DAPS version. As the settings in the custom DAPS configuration file will override the settings in /etc/daps/config by default, any parameter incompatibilities between the files may lead to unexpected behavior of DAPS.

  4. Save ~/.daps/config and test if your changes lead to the expected results.

Example 10.1: Example of /etc/daps/config (DAPS 1.0)
###########################
# DAPS configuration file #
###########################
#
# Copyright (C) 2011,2012 fsundermeyer@opensuse.org
# Authors: fsundermeyer@opensuse.org
#

#------------------------------------------------------------
# Customizing:
#
# Override any setting below in
# $HOME/.daps/config
# or on the commandline
#------------------------------------------------------------
#
# The environment is set up using the following hierachy
# (1 == always wins)
#
# 1. Command line
#    - either as a real option
#    - or as variable declaration (FOO=bar)
#
# 2. DC-file
# 3. $USER_RC (user config file)
# 4. $DAPSROOT/etc/system-profile

## Key:         ASPELL_EXTRA_DICT
## ----------------------
## Description: Additional dictionary for spell checker
## Type:        Absolute path to distionary
## Default:     ""
#
# Specify an additional (custom) dictionary
ASPELL_EXTRA_DICT=""

## Key:         ASPELL_LANG
## ----------------------
## Description: Language for spell checker
## Type:        String
## Default:     en_US
#
# NOTE:  Language to use for spellchecker. It uses the same format as the
#        LANG environmental variable: It consists of  the two letter ISO 639
#        language code (e.g. 'en' for English) and an optional two letter
#        ISO 3166 country code after an underscore (e.g. en_GB for Britsh
#        English). Make sure the respective dictionary for aspell is installed.
#
ASPELL_LANG=en_US

## Key:         ASPELL_SKIP_TAGS
## ----------------------
## Description: list of DOcBook XML tags which content should _not_ be
##              spell-checked
## Type:        List
## Default:     ( author command email envar filename firstname guimenu
##                keycap literal option remark screen surname systemitem
##                ulink varname xref )
#
# NOTE: Spece separated list of tags, needs to be enclosed in brackets
#
ASPELL_SKIP_TAGS=(
    author
    command
    email
    envar
    filename
    firstname
    guimenu
    keycap
    literal
    option
    remark
    screen
    surname
    systemitem
    ulink
    varname
    xref
)

## Key:         BUILD_DIR
## ----------------------
## Description: Build directory where all daps generated files will go
## Type:        Path to directory (without a trailing slash)
## Default:     ""
#
# Allows to completely separate the output daps generates from the sources
# If not set it is automatically resolved to $DOC_DIR/build/$BOOK
BUILD_DIR=""

## Key:         CB_OPTIONS
## ------------------------
## Description: Command line options for /usr/bin/checkbot
## Type:        String
## Default:     "--dontwarn \"(301|302|902)\" --sleep 0 --timeout 60"
#
#
# Also see 'man 1 checkbot'. Do not change unless you really know what you do.
#
CB_OPTIONS="--dontwarn  \"(301|302|902)\" --sleep 0 --timeout 60"

## Key:         COMMENTS
## ---------------------
## Description: Create profiled sources with XML comments?
## Type:        yesno
## Default:     "no"
#
# By default XML comments (  ) will be stripped when profiling
# sources, so whenever you create source archives with daps
# (e.g. via dist-xml or locdrop), the XML files will contain no comments.
# Change this by setting COMMENTS="yes". Has no effect on book creation
# (html, pdf, etc). Can also be set to "yes" with the -c switch on teh command
# line
# Also see COMMENT_STR, DRAFT and REMARKS
#
COMMENTS="no"

## Key:         COLOR
## ------------------
## Description: Colored output?
## Type:        yesno
## Default:     "yes"
#
# By default errors, results, warnings and certain info messages are printed
# in color using bash olor codes. In cron jobs and scripts you probably want to
# turn off this behaviour by setting COLOR to "no"
#
COLOR="yes"

## Key:         COMMENT_STR
## ------------------------
## Description: String to be appended to file/directory names when comments
##              are turned on
## Type:        String
## Default:     "_comments"
#
COMMENT_STR="_comments"

## Key:         CONF_PREFIX
## ------------------------
## Description: Common prefix for all doc config files
## Type:        String
## Default:     "DC-"
#
# Also see PDFNAME
#
CONF_PREFIX="DC-"

## Key:         CONVERT_OPTS
## -------------------------
## Description: Command line options for "convert" to convert color PNGs
##              to grayscale
## Type:        String
## Default:     "-type grayscale -colors 256"
#
# Do not change unless you really know what you do.
#
CONVERT_OPTS="-type grayscale -colors 256"

## Key:         DOCCONF_DEFAULT
## -----------------------------
## Description: Specify a default DC-file that is used whenever
##              no DC-file is specified on the command line or via
##              DOCCONF_NAME in the DC-FILE
## Type:        String
## Default:     ""
#
# This value is usually set in a book specific DC-file
#
DOCCONF_DEFAULT=""

## Key:         DIA_OPTIONS
## -------------------------
## Description: Command line options for dia to convert DIA to SVG
## Type:        String
## Default:     "-t cairo-svg"
#
# Do not change unless you really know what you do.
#
DIA_OPTIONS="-t cairo-svg"

## Key: DOCBOOK4_STYLE_URI
## ------------------
## Description: URI to DocBook 4 stlysheets
## Type:        URI
## Default:     "http://docbook.sourceforge.net/release/xsl/current/"
#
# URI to the DocBook 4 stylesheets that can be resolved by xmlcatalog
# There should be no need to change this entry
# Note:
# URI _must_ end with a "/", otherwise it will not be resolved on Ubuntu
#
DOCBOOK4_STYLE_URI="http://docbook.sourceforge.net/release/xsl/current/"

## Key: DOCBOOK5_STYLE_URI
## ------------------
## Description: URI to DocBook 5 stlysheets
## Type:        URI
## Default:     "http://docbook.sourceforge.net/release/xsl-ns/current/"
#
# URI to the DocBook 5 stylesheets that can be resolved by xmlcatalog
# There should be no need to change this entry
# Note:
# URI _must_ end with a "/", otherwise it will not be resolved on Ubuntu
#
DOCBOOK5_STYLE_URI="http://docbook.sourceforge.net/release/xsl-ns/current/"

## Key: DOCBOOK5_RNG_URI
## ------------------
## Description: URI to DocBook 5 Relax NG schema
## Type:        URI
## Default:     "http://docbook.org/xml/5.0/rng/docbook.rng"
#
# URI to the DocBook 5 Relax NG schema that can be resolved by xmlcatalog
# There should be no need to change this entry
#
DOCBOOK5_RNG_URI="http://docbook.org/xml/5.0/rng/docbook.rng"

## Key:         DRAFT
## ------------------
## Description: Print "DRAFT" watermarks in HTML or PDF builds
## Type:        yesno
## Default:     "no"
#
# Turns on DRAFT watermarks in PDF or HTML builds when set to "yes"
# Is ignored for any other output format and has no effect on profiling.
# This value can be set to "yes" using the -d switch on the command line
# Also see COMMENTS and REMARKS
#
DRAFT="no"

## Key:         DRAFT_STR
## ----------------------
## Description: String to be appended to file/directory names when draft
##              is turned on
## Type:        String
## Default:     "_draft"
#
#
DRAFT_STR="_draft"

## Key:         EPUB_CHECK
## ------------------------
## Description: Check generated ePUB file with epubcheck
## Type:        yesno
## Default:     "no"
#
# Useful to find errors within an epub file when devolping stylesheets
#
EPUBCHECK="no"

## Key:         EPUB_CSS
## ------------------------
## Description: Absolute path to CSS file for EPUB builds
## Type:        Path to file
## Default:     ""
#
EPUB_CSS=""

## Key:         FALLBACK_STYLEROOT
## ----------------------
## Description: Fallback styleroot directory.
## Type:        Path to directory (without a trailing slash)
## Default:     ""
#
# When having specified custom stylesheets with STYLEROOT, the fallback
# for styles not specified in the custom STYLEROOT are the DocBook stylesheets
# Specify an alternative fallback with this option. Useful if you have a
# fork of e.g. your custom fo stylesheets. When setting STYLEROOT to this
# for directory that only has fo styles, html versions of that document would
# be build with the DocBook stylesheets. Setting FALLBACK_STYLEROOT to the
# directory containing your original custom stylesheets (which also have
# html stylesheets) will create html versions with your custom styles. The
# DocBook stylesheets remain as a last fallback resort.
#
# This option is ignored when not specifying STYLEROOT at the same time.
# Also see STYLEROOT
#
FALLBACK_STYLEROOT=""

## Key:         FOP_CONFIG_FILE
## -----------------------
## Description: Config file for the FOP pdf formatter
## Type:        Path
## Default:     "@sysconfdir@/daps/fop/fop-daps.xml"
#
# Specify a config file for FOP
# Also see FORMATTER, FOP-*
#
FOP_CONFIG_FILE="@sysconfdir@/daps/fop/fop-daps.xml"

## Key:         FOP_OPTIONS
## -----------------------
## Description: Command line options for the FOP pdf formatter
## Type:        String
## Default:     "-q" (turn on quiet mode)
#
# Specify command line options for the FOP formatter.
# Also see FORMATTER, FOP-*
#
FOP_OPTIONS="-q"

## Key:         FOP_WRAPPER
## -----------------------
## Description: Wrapper script for the FOP pdf formatter
## Type:        PATH to script
## Default:     "@pkgdatadir@/libexec/daps-fop""
#
# Optional wrapper script for calling FOP. The default "fop" will run
# the first fop executable found in your path (usually this will be
# /usr/bin/fop)
# Also see FORMATTER, FOP-*
#
FOP_WRAPPER="@pkgdatadir@/libexec/daps-fop"

## Key:         FORMATTER
## --------------------
## Description: Specify the PDF formatter to use
## Type:        String (fop,xep)
## Default:     "fop"
#
# Specify which PDF formatter to use. Currently only fop or xep are supported
# Also see FOP_*, XEP_*
#
FORMATTER="fop"

## Key:         GZIP_MAN
## ------------------
## Description: Compress man pages with gzip
## Type:        yesno
## Default:     "yes"
#
# By default man pages created with the "man" target will be compressed with
# gzip
#
GZIP_MAN="yes"

## Key:         HTML5
## ------------------------
## Description: Use XHTML5 instead of XHTML1 for HTML output
## Type:        yesno
## Default:     no
#
HTML5="no"

## Key:         HTML_CSS
## ------------------------
## Description: Absolute path to CSS file for HTML builds
## Type:        Path to file
## Default:     ""
#
HTML_CSS=""

## Key:         HTMLROOT
## ------------------------
## Description: Set HTMLROOT for novell.com/documentation
## Type:        String
## Default:     ""
#
# Only needed for novell.com/documentation
#
HTMLROOT=""

## Key:         IMG_VIEWER
## ------------------------
## Description: Image viewer to be used with target getimages
## Type:        String
## Default:     ""
#
# Command (gpicview) or full path (/usr/bin/gpicview) to an image viewer
#
IMG_VIEWER=""

## Key:         INCLUDE_MANIFEST
## -----------------------------
## Description: Include a manifest file to the archive created by dist-html
##              containing  list of included HTML files
## Type:        Bool
## Default:     ""
#
# Only affects the dist-html subcommand
#
INCLUDE_MANIFEST=""

## Key:         INK_OPTIONS
## ------------------------
## Description: Command line options for inkscape to convert SVG to PNG
## Type:        String
## Default:     "-z -w 800"
#
# Do not change unless you really know what you do.
#
INK_OPTIONS="-z -w 800"

## Key:         JING_FLAGS
## ------------------------
## Description: Flags for jing
## Type:        String, whitespace-separated
## Default:     "-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"
#
# The default flag enables jing to follow xi:includes
# Do not change unless you really know what you do.
#
JING_FLAGS="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"

## Key:         MAIN
## -----------------
## Description: File name of the set/book defining XML file
## Type:        file name (file name only, no absolute path)
## Default:     ""
#
# Name of the MAIN XML file. Mandatory.
# This value is usually set in a book specific DC-file.
#
MAIN=""

## Key:         PDFNAME
## --------------------
## TODO:        Rename variable
## Description: Custom name for generated files
## Type:        String
## Default:     ""
#
# By default the directory/filenames will be generated by stripping the
# CONF_PREFIX from the DC-file's name. Use this setting to choose a custom
# name.
# This value is usually set in a book specific DC-file.
# ATTENTION: Do not specify this value in a global config file if you generate
#            more than a single book, otherwise previous book builds will always
#            be overwritten by a new build
#
PDFNAME=""

## Key:         PROFARCH
## ---------------------
## Description: Profiling values for the attribute arch=""
## Type:        String (e.g. i386, x86_64)
## Default:     ""
#
# This value is usually set in a book specific DC-file.
#
PROFARCH=""

## Key:         PROFCONDITION
## ---------------------------
## Description: Profiling values for the attribute condition=""
## Type:        String
## Default:     ""
#
# This value is usually set in a book specific DC-file.
#
PROFCONDITION=""

## Key:         PROFILE_URN
## ---------------------------
## Description: URN for profiling stylesheet
## Type:        urn (String)
## Default:     ""
#
# In order to use profiling, the urn to a profiling stylesheet _either_ has
# to be specified in the header of the main file ($MAIN) via<?xml-stylesheet/>
# or via this variable. Valid urns can be found in the DAPS installation
# directory in etc/catalog.xml
PROFILE_URN=""

## Key:         PROFOS
## -------------------
## Description: Profiling values for the attribute os=""
## Type:        String
## Default:     ""
#
# This value is usually set in a book specific DC-file.
#
PROFOS=""

## Key:         PROFVENDOR
## -----------------------
## Description: Profiling values for the attribute vendor=""
## Type:        String
## Default:     ""
#
# This value is usually set in a book specific DC-file.
#
PROFVENDOR=""

## Key:         REMARK
## -------------------
## Description: Generate books with remarks?
## Type:        yesno
## Default:     "no"
#
# By default remarks are ignored when generating books. Set this parameter to
# "yes" to include remarks. Useful for proofreading.
# This value can be set to "yes" using the -r switch on the command line
# Also see COMMENTS and DRAFT
#
REMARKS="no"

## Key:         REMARKS_STR
## ------------------------
## Description: String to be appended to file/directory names when remarks
##              are turned on
## Type:        String
## Default:     "_remarks"
#
REMARK_STR="_remarks"

## Key:         ROOTID
## -------------------
## Description: ID of the book/chapter/etc. to generate
## Type:        String (must be a valid id from the set defined in MAIN)
## Default:     ""
#
# When not set, the complete book defined in MAIN is build. If MAIN defines a
# set of several books, you need to specify the id of a book (<book id="">) in
# order to build the single book. daps also supports building single
# articles, parts, and chapters.
# This value is usually set in a book specific DC-file and can also be set
# using the command line switch --rootid=""
#
ROOTID=""

## Key:      STYLEDEVEL
## -------------------
## Description: Custom Stylesheet directory for development purposes.
## Type:        Path to directory (without a trailing slash)
## Default:     ""
#
#
# By default daps uses the DocBook Stylesheets to create output. If you are
# developing your own set of stylesheets, you may want to set STYLEDEVEL in
# ~/.daps/config. If set STYLEDEVEL _always_ takes precedence over STYLEROOT!
# You may also want to set FALLBACK_STYLEROOT alomngside with STYLEDEVEL
#
# See also STYLEROOT, FALLBACK_STYLEROOT
#
# Do NOT use unless you really know what you are doing.
#
STYLEDEVEL=""

## Key:      STYLEROOT
## -------------------
## Description: Custom Stylesheet directory.
## Type:        Path to directory (without a trailing slash)
## Default:     ""
#
# By default daps uses the DocBook Stylesheets to create output. If you have
# your own set of stylesheets, specify the absolute path to the stylesheet
# directory here. The DocBook stylesheets will be used as a fallback in case
# styles are not defined for all output formats.
#
# See also FALLBACK_STYLEROOT
#
STYLEROOT=""


## Key:         USEMETA
## --------------------
## Description: Print SVN meta information in HTML and PDF builds
## Type:        yesno
## Default:     "no"
#
# If your XML sources are hosted on an SVN server, adds the following status
# information for each file to HTML and PDF builds if set to "yes":
#  * file name
#  * maintainer (content of SVN property doc:maintainer)
#  * status (content of SVN property doc:status)
# Useful for proofreading.
# Implies that remarks are turned on.
# This value can be set to "yes" using the -m switch on the command line
# Also see REMARKS
#
USEMETA="no"

## Key:         VERBOSITY
## --------------------
## Description: Verbosity level
## Type:        number
## Default:     0
#
# VERBOSITY=0: print only final results message (default)
# VERBOSITY=1: results of each target that is called
# VERBOSITY=2: detailed output of each target
#
VERBOSITY=0

## Key:         WH_SEARCH
## --------------------
## Description: Enable/Disbale webhelp search feature
## Type:        yesno
## Default:     yes
#
#
WH_SEARCH="yes"

## Key:         XEP_CONFIG_FILE
## -----------------------
## Description: Config file for the XEP pdf formatter
## Type:        Path
## Default:     "@sysconfdir@/daps/xep/xep-daps.xml"
#
# Specify a config file for XEP
# Also see FORMATTER, XEP-*
#
XEP_CONFIG_FILE="@sysconfdir@/daps/xep/xep-daps.xml"

## Key:         XEP_OPTIONS
## -----------------------
## Description: Command line options for the XEP pdf formatter
## Type:        String
## Default:     "-q" (turn on quiet mode)
#
# Specify command line options for the XEP formatter.
# Also see FORMATTER, XEP-*
#
XEP_OPTIONS="-q"

## Key:         XEP_WRAPPER
## -----------------------
## Description: Wrapper script for the XEP pdf formatter
## Type:        PATH to script
## Default:     "@pkgdatadir@/libexec/daps-xep"
#
# Optional wrapper script for calling XEP. The default "xep" will run
# the first xep binary found in your path (usually this will be
# /usr/bin/xep)
# Also see FORMATTER, XEP-*
#
XEP_WRAPPER="@pkgdatadir@/libexec/daps-xep"

## Key:         XML_MAIN_CATALOG
## -----------------------
## Description: Main XML catalog file
## Type:        PATH to file
## Default:     "/etc/xml/catalog"
#
# Path to the main XML catalog used to resolve URIs. /etc/xml/catalog is
# the standard location used by most (all?) Linux distributions. Only
# change if the main catalog is located elsewhere on you distribution.
#
XML_MAIN_CATALOG="/etc/xml/catalog"

## Key: XSLTPARAM
## --------------------
## Description: String passed to xsltproc for HTML and PDF builds
## Type:        number
## Default:     ""
#
# With XSLTPARAM you can overwrite stylesheet settings without having
# to touch the stylesheet files directly. You may overwrite parameters
# by specifying "--stringparam <PARAM_NAME> <NEW_VALUE>"
# Example:
# Set the pagesize for PDFs to 200x100 mm
# XSLTPARAM="--stringparam page.height 200mm --stringparam page.width 100mm"
#
# Can also be placed in an DC-file if being a per-book setting
#
XSLTPARAM=""

11 Troubleshooting

This chapter lists common problems and possible solutions, sorted into categories.

11.1 Installation and First Steps

11.2 Generating Output

Profiling Does Not Work as Expected?
  1. Check the values of your profiling attributes in the XML files: They must use consistent spelling throughout a documentation project. If you assigned multiple values to a profiling attribute, check if the values are separated with a semicolon, for example, os="linux;unix".

  2. Check the DC file for your documentation project: Does it contain one or multiple PROF* parameters? Otherwise DAPS does not know which profiling attributes to interpret. Do the PROF* parameters match the profiling attributes used in the XML files? Do the values of the PROF* parameters match the attribute values used in the XML files?

  3. Check the MAIN file of your documentation projects: Does its header contain the following line?

    href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" type="text/xml"

    If not, any profiling parameters in the DC file will be ignored during generation of the output.

For more details, refer to Section 3.5, “Profiling—Support for Document Variants” and http://www.sagehill.net/docbookxsl/Profiling.html.

11.3 Miscellaneous

Verbosity Level

DAPS is less verbose than its predecessor susedoc. To get the same level of output as with susedoc 4.x, run daps with the -v option. For more details, use the --debug option.

Log Files

If you should run into problems with DAPS that you cannot classify, check the DAPS log files in YOUR_DOC_DIR/build/BOOKNAME/log. A complete log file of the latest daps subcommand that was executed is available in YOUR_DOC_DIR/build/BOOKNAME/log/make_SUBCOMMAND.log

In case of an error the complete log will be shown on the screen (STDOUT).

Version Incompatibilities

If, after an update to a higher DAPS version, you experience strange effects that are difficult to debug, check your custom DAPS config file (~/.daps/config) against the system-wide configuration file (/etc/daps/config) for any parameters that may have changed. As the settings in the custom DAPS configuration file will override the settings in /etc/daps/config by default, any parameter incompatibilities between the files may lead to unexpected behavior of DAPS.

When switching from DAPS 1.x to DAPS 2.0, especially check the syntax of any XSLT parameters that you are using (on the command line, in scripts or in DC files). If you have not adjusted the parameters to the new syntax, this may result in strange error messages. For details, refer to XSLT Parameters: Syntax Change.

Glossary

Antenna House Formatter

See FO Formatter.

Conditional Text

See Profiling.

DTD (Document Type Definition)

The DTD (Document Type Definition) defines the exact elements, entities attributes and structure available in an XML or HTML document.

DOCTYPE

The DOCTYPE, or Document Type Declaration, not to be confused with a Document Type Definition, contains the information on the DTD to use with an XML document. Therefore, it also defines which particular XML format is for the document.

DAPS (DocBook Authoring and Publishing Suite)

DAPS provides authors of technical documentation with an easy-to-use toolchain to convert their DocBook documents into various output formats.

DocBook

DocBook is a semantic markup language for technical documentation published as a DTD.

Entity

An entity connects one or multiple characters with a unique identifier. One example where this is used, is for escaping characters that are necessary for XML markup. A character such as & must be written as the entity &amp; in XML.

You can also declare custom entities.

FO Formatter

Renders the XSL-FO files which are created by the DocBook XSL stylesheets into various output formats. The output format used most often is likely PDF. Formats that can usually be rendered into include:

  • Page description formats such as PDF, Postscript, and XPS.

  • Different raster and vector image formats such as PNG and SVG.

  • Text documents and Web page documents such as TXT, RTF, and HTML.

  • Internal formats of the formatter.

Well-known formatters include Apache FOP, XEP, and Antenna House Formatter. Whereas the former is an open source product, the latter two are proprietary solutions. Antenna House Formatter is incompatible with DAPS.

FO (Formatting Objects)

See XSL-FO.

FOP (Formatting Objects Processor)

See FO Formatter.

Main Element

Within this guide, main element refers to any XML element that is commonly used to create a coherent whole in an output format. In other words, either a book, an article, or a set.

PDF (Portable Document Format)

PDF is a page description format created by Adobe Systems in 1993. Today, it is widely adopted as the standard format for digitally distributed page-oriented documents. A major advantage of PDF is that the formats can be repproduced identically across different platforms.

PI (Processing Instruction)

PIs can be used to mark certain content as having to be treated differently by writing an instruction enclosed in <? and ?>. This is commonly used within (X)HTML web pages to mark parts of the file as being written in server-side scripting language PHP.

In DocBook, Processing Instructions can also be used for somewhat more mundane purposes, such as setting the background color of a preceding image.

Profiling

Through profiling, you can easily adapt your documentation to different variants of a product. For instance, a manufacturer of white-label products might appreciate being able to easily replace the brand name for the product they sell.

It is possible to further this concept and even replace entire sections of text depending on a product's target group, for instance, on whether documentation is generated for the entry-level or for the professional version of a product.

Project

A project consists of all the files that lie in a directory structure as required by DAPS, with the first directory level containing any DC files and subdirectories for xml files and images. When the first Main Element is built, an additional subdirectory called build will be created.

Such a project directory may contain the source files for multiple main elements.

SVG (Scalable Vector Graphics)

SVG is an XML-based vector graphics format, which is supported by most modern Web browsers.

Vector graphics formats are different from traditional raster graphics in that they describe the exact shape of an object instead of using the lossy process of subdividing an object into many individual raster points (such as pixels).

Stylesheet

In the context of DocBook, the term stylesheet usually refers to the XSLT stylesheets used to transform DocBook documents into their respective output formats.

Transformation

Data transformation converts data from a source data format into a destination data format. An example is the process of converting a DocBook XML document into HTML by using an XSLT processor.

Validation

Validation refers to the process of checking whether an XML document is formally correct, checking, for instance, if all XML tags are properly closed and nested. This is done using a DTD or XML Schema.

If a document is valid that does not mean that its contents are factually correct or that it is structured as you intended. However, validity does mean that a document can be further processed, for instance by a Web browser, or an XSL processor.

XEP

See FO Formatter.

XInclude

XIncludes are references to other DocBook files. XIncludes can be used to split one large file into multiple smaller, more manageable files. For instance, instead of having an entire book in a single file, you can create one central file from which you can reference individual chapter files.

In the context of using a version control system within your documentation process, having smaller files can also help avoid version conflicts if you and co-workers are working on different chapters of the same book.

XML Catalog

XML Catalogs can be used to make DTDs available locally, so they do not have to be downloaded over the network every time they are accessed.

XML Parser

Also known as an XML Processor, an XML Parser is used to provide the structural information contained in an XML file to another application.

XOP

XOP (XML-binary Optimized Packaging) is a W3C (World Wide Web Consortium) recommendation on how to represent binary data inside XML documents.

XML (Extensible Markup Language)

XML is a markup language with rules to encode documents into a form that is both human-readable and machine-readable.

XSL (Extensible Stylesheet Language)

XSL is a collective noun used to refer to XSLT, XSL-FO, and the XML Path Language (XPath).

See Also XSLT, XSL-FO.

XSL-FO

FO, XSL-FO or Extensible Stylesheet Language-Formatting Objects is a markup language used to mediate between other XML representations and a page formatting format such as PDF.

See Also XSLT.

XSLT (Extensible Stylesheet Language for Transformations)

XSLT or Extensible Stylesheet Language for Transformations is a language based on XML. It is used to transform XML documents.

A Migration of Existing DocBook Projects

This section provides instructions how to migrate existing DocBook projects so that you can use DAPS for managing and publishing them.

Procedure A.1: Making DocBook Projects Compatible with DAPS
  1. If your XML files are distributed across several subdirectories, flatten the hierarchy and put all XML files directly into the xml subdirectory that is required by DAPS. See Required Directory Structure. Hosting multiple documentation projects in the same xml directory is fine as long as the file names are unique. You can put multiple MAIN files there.

  2. If you have any XIncludes or entity declaration files, also put them into the xml subdirectory.

  3. Depending on the file type of your source images, add them to the respective subdirectories in YOUR_DOC_DIR/images/src. The image directory and its substructure is required by DAPS. For details, refer to Required Directory Structure.

  4. Make sure that the base names of your image files are unique. For details, refer to Section 5.3, “File name Requirements”.

  5. Adjust all references of image files, Xincludes, and entity declarations, in the existing XML files to match the structure required by DAPS. The references must not include any absolute or relative path, the plain file name is enough.

  6. For each deliverable (book, article, set) that you want to generate from your XML files, create a Doc Config file. For more information, refer to Section 2.4.1, “Key Files”. Find a template for DC files in your installed system in /usr/share/daps/init_templates/DC-file.template.

If you have already used DAPS' predecessor susedoc, use the /usr/bin/daps-envconvert script for migrating your ENV files to DC files. For a short overview of the main changes, refer to /usr/share/doc/packages/daps/README.upgrade_from_susedoc_4.x. In contrast to susedoc, DAPS uses the DocBook layout by default. The SUSE stylesheets have been moved to a separate package, suse-xsl-stylesheets. It is available from the Documentation:Tools repository. If you want to continue using the SUSE-layout for your documentation projects, install this package in addition to DAPS. To make DAPS use the SUSE layout, adjust the STYLEROOT parameter in the DC files of your documentation projects.

B Editor-specific Information

This chapter describes:

  • the use of DocBook macros for Emacs,

  • how to integrate daps-susespell into jEdit.

B.1 Emacs—Macros for Inserting DocBook Elements

Most editors allow you to define or record macros which you can use for automatically inserting empty skeletons for a complex XML construct as illustrated by Example B.1, “A varlistentry Element”.

Example B.1: A varlistentry Element
<varlistentry>
    <term></term>
    <listitem>
    <para></para>
    </listitem>
    </varlistentry>

For Emacs, DAPS already includes macros for adding DocBook elements such as listitem, figure, or indexterm. The macros are defined in docbook_macros.el and are added to your system during the installation of DAPS. They require that you use one of Emacs' main XML editing modes, either nxml or psgml.

Procedure B.1: Configuring Emacs to Use the DocBook Macros
  1. To load the DocBook macros, open your Emacs customization file (~/.emacs or ~/.gnu-emacs).

  2. Insert the following line:

    (load "/usr/share/emacs/site-lisp/docbook_macros.el" t t)
  3. Save the Emacs customization file and restart Emacs.

For an overview, which macros are available and how to use them, refer to http://en.opensuse.org/openSUSE:Documentation_Emacs_Docbook_Macros.

B.2 jEdit—Spell Check on the Fly

If you do not want to run daps spellcheck from the command line, you cam you can also integrate daps-susespell (plus a custom aspell dictionary, if needed) into your XML editor, so that spelling is checked on the fly during editing. Consult your editor's documentation on how to integrate a custom dictionary. If you use jEdit, proceed as outlined in Procedure B.2, “Integrating daps-susespell into jEdit”.

Procedure B.2: Integrating daps-susespell into jEdit

  1. Install and activate the plug-in for spell checking:

    1. Start jEdit and select Plugins › Plugin Manager.

    2. If the Spell Check plug-in is not already installed, install and activate it.

    3. Close and restart jEdit.

  2. Configure the plug-in as follows:

    1. Select Plugins › Plugin Options.

    2. In the left navigation pane, select Spell Check › General.

    3. Set Spell-checking engine to Aspell and select the Dictionary to use, for example en_US.

    4. If the desired dictionary does not appear in the drop-down list, install the respective aspell dictionary for the language and click Refresh list.

    5. In the left navigation pane, switch to Spell Check › Syntax handling.

    6. In the table, activate the markup entry and click Edit next to it.

    7. In the Token types picker, activate the following entries:

      • NULL

      • COMMENT1

      • LITERAL1

    8. In the left navigation pane, switch to Spell Check › Aspell Engine.

    9. Set the path to the Aspell executable file name. Select Enable markup mode.

    10. To use an additional custom aspell dictionary, specify the path to the custom dictionary in the input field below Additional parameters:

      --extra-dicts=PATH_TO_CUSTOM_DICT
          

      For example:

      --extra-dicts=/home/tux/custom_aspell.rws
    11. Confirm your settings in the plugin options dialog with OK or Apply.

  3. To execute a spell check during editing, select Plugins › Spell Check › Highlight misspelled words (or use the keyboard shortcut assigned to that menu item).

C Documentation Updates

This chapter lists the most important content changes for this document since the release of DAPS 1.0.

The manual was updated on the following dates:

C.1 Next (DAPS 2.0)

Work in progress

Make Files

The make files have now been split into several smaller make files, that are specific for the respective output like PDF, or HTML.

Verbosity

The number of verbosity levels has changed, as have the defaults used on the command line and in scripts:

  • Command Line: Default verbosity level is now v1, which shows all result messages and warnings.

  • Scripts: Default verbosity level is now v0, which shows the file names.

The verbosity levels v0, v1, v2, and debug are unchanged, but a new verbosity level has been added: v3. It shows the output of make -j1, where all commands are executed successively (no parallel processing). This makes the output easier to read than that of the debug verbosity level, where messages from parallel processes are shown in the order they arrive.

Bash Compatibility

Whereas DAPS 1.x required Bash 4, DAPS 2.0 is compatible with Bash 3.

Output Targets
  • For a list of command name changes and deprecated commands, refer to Deprecated Commands.

  • The EPUB output is now checked with EpubCheck, https://github.com/IDPF/epubcheck.

  • A new output format has been added: daps mobi generates *.mobi files for Amazon Kindle e-books.

  • HTML 4 is no longer supported. Per default, daps html now generates XHTML 1.1. HTML 5 output can be enforced by using the --html5 option.

  • Some commands for generating file lists (such as daps remaininggraphics) have been renamed, some are deprecated. For details, refer to Deprecated Commands.

  • For the daps list-srcfiles command, options are now available with which to exclude files from the list. For more details, run daps help list-srcfiles.

  • A new packaging command is available: daps package-src. It creates a TAR archive with profiled XML sources, resolved entities, and images. Use the --set-date to include the publication date.

  • A new target for distributable archives has been added: daps locdrop.

  • The daps bigfile command has changed: The daps bigfile-reduced is deprecated, use daps bigfile instead.

  • Generating page, desktop, or document files: The commands daps package-html and daps package-pdf now have options to define which files to generate: --documentfiles, --desktopfiles, and --pagefiles.

  • A new command has been added: daps clean-package. It removes all generated package data for a given DC or MAIN file.

Debugging

A new subcommand has been added: daps dapsenv. It prints a list of the most important make variables and their value.

Entities

In the profiled XML sources entities are now always resolved and replaced by their value.

Well-formed XML

If the XML is not well-formed, DAPS quits and shows a meaningful error message.

Overview of All Commands

With daps --commands, you can list all available commands.

Image Formats

DAPS now also supports JPEG as image format.

CSS

Work in progress

XSLT Processors

DAPS now also supports the Saxon XSLT processor. Use the option --xsltprocessor to define which processor to use. Per default, xsltproc is used.

XSLT Parameters: Syntax Change

When passing XSLT parameters (either on the command line, in scripts, or in DC files by using XSLTPARAM), you need to adjust the syntax when switching to DAPS 2.0. Instead of

--stringparam PARAM_NAME VALUE

now use:

--stringparam PARAM_NAME=VALUE
Deprecated Commands

The following commands are deprecated:

  • daps all. Use daps pdf instead.

  • daps bigfile-reduced. Use daps bigfile instead.

  • daps check. Use daps dapsenv instead.

  • daps chklink . Use daps checklink instead.

  • daps db2novdoc. This command is no longer supported.

  • daps desktop-files. Use daps package-html --desktopfiles or daps package-pdf --desktopfiles instead.

  • daps desktop-files-dir-name. This command is no longer supported.

  • daps dist. This command is no longer supported.

  • daps dist-all. This command is no longer supported.

  • daps dist-book. This command is no longer supported.

  • daps dist-desktop-files. This command is no longer supported.

  • daps dist-document-files. This command is no longer supported.

  • daps dist-document-files-pdf. This command is no longer supported.

  • daps dist-graphics. Use daps package-src instead.

  • daps dist-graphics-png. This command is no longer supported.

  • daps dist-html-single. Use daps package-html --single instead.

  • daps disthtml-single. Use daps package-html --single instead.

  • daps dist-xml. Use daps package-src instead.

  • daps document-files-dir-name. This command is no longer supported.

  • daps document-files-html. Use daps package-html --documentfiles instead.

  • daps document-files-pdf. Use daps package-pdf --documentfiles instead.

  • daps force. This command is no longer supported.

  • daps htmlsingle. Use daps html --single instead.

  • daps htmlsingle-name. Use daps html-dir-name --single instead.

  • daps html-single. Use daps html --single instead.

  • daps html-single-name. Use daps html-dir-name --single instead.

  • daps jana. Use daps checklink instead.

  • daps link-entity-dist. This command is no longer supported.

  • daps missinggraphics. Use daps list-images-missing instead.

  • daps online-localized. Use daps online-docs --noset instead.

  • daps offspring. This command is no longer supported.

  • daps pdf-color. Use daps pdf instead.

  • daps pdf-color-name. Use daps pdf-name instead.

  • daps penguin. This command is no longer supported.

  • daps prof. Use daps profile instead.

  • daps profiledir. Use daps showvariable VARIABLE=PROFILEDIR instead.

  • daps projectfiles. Use daps list-srcfiles --noimg instead.

  • daps projectgraphics. Use daps list-srcfiles --nodc --noent --noxml instead.

  • daps provide-images. Use daps images --grayscale instead.

  • daps provide-color-images. Use daps images --color instead.

  • daps provide-epub-images. This command is no longer supported.

  • daps remainingfiles. Use daps list-srcfiles-unused --noimg instead.

  • daps remaininggraphics. Use daps list-srcfiles-unused --noxml instead.

  • daps txt. Use daps text instead.

  • daps txt-name. Use daps text-name instead.

  • daps warn-images. Use daps list-images-multisrc instead.

  • daps wiki. This command is no longer supported.

  • daps wiki-name. This command is no longer supported.

  • daps xmlfiles. Use daps list-srcfiles --nodc --noent --noimg instead.

  • daps xml-graphics-bw. This command is no longer supported.

  • daps xmlgraphics. This command is no longer supported.

C.2 2013-10-10 (Maintenance Release)

Modularizing Documentation Projects

Chapter has been revised.

Review and Translation Processes

Major content has been added.

Packaging and Deploying Your Documentation

Major content has been added.

Customizing Layout of the Output Formats

Major content has been added.

Troubleshooting

Some additions and changes.

Configuring DAPS

An example of /etc/daps/config has been added.

Appendix C, Documentation Updates

An overview of the main documentation updates has been added.

Whole Document

Various small improvements throughout the document.

Print this page