DAPS Documentation › User Guide › Conceptual Overview

Applies to DAPS 3.1

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 Key Files
2.7 Basic DAPS Syntax

This chapter covers the following topics:

Features unique to DAPS such as support for multiple output formats and automatic document profiling
Configuring DAPS
Basics of working with DAPS.
Basic syntax of daps commands

2.1 Supported DocBook Versions #

DAPS supports DocBook 4.x and DocBook 5.x.

2.2 Key Features #

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

Output Formats (Single-source Publishing)

DAPS lets you publish your XML sources in several different output formats, for example: HTML, HTML-single, PDF, EPUB, 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). Thus your XML documents can be published in different layouts without having to change the sources or the configuration.

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 one-by-one, 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.3, “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 automatically transforms images referenced in your XML files into different formats, list all source images referenced in your XML files, list any missing images or check if all image names are unique. You can also forward those lists to your preferred image viewer to conveniently browse through the images. 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 several features to simplify review and translation processes. By adding a single parameter, you can generate output that contains remarks for writers, reviewers, and translators. By default, remarks are suppressed in the final output version. You can also generate preview versions of your documentation with a DRAFT watermark appearing on the 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 and 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 regard 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)
~/.config/daps/dapsrc (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 2, “Using daps-init ”. 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, Migrating Existing DocBook Projects.

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

2.5.1 Source Files #

Example 2.1: Required Directory Structure #

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

1	“Working directory” for the respective documentation project (in the following also called `project directory` or `documentation directory`).
2	On the topmost level of your project directory, store the Doc Config (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.6, “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 5.4, “Referencing Images”.
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 and includes “references” to other books, chapters, appendixes, etc. For more information, refer to Section 2.6, “Key Files”.

Important: Structure of the `xml` and `image/src/*` Directories

Avoid subdirectories within the xml and image/src/* directories. Referencing or including files from subdirectories within those directories can lead to unpredictable results with DAPS.

2.5.2 The `build` Subdirectory #

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 ~/.config/daps/dapsrc.)

The build directory is structured as follows:

Example 2.2: 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. It is named after the respective DC from which you build the book, article or set. For example, the output for `DC-NAME` is written to `YOUR_DOC_DIR/build/NAME`. 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 Key Files #

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

MAIN File: A DocBook XML file in the xml directory. It contains 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. Other XML files may be included into the MAIN file via <xi:include/> statements.
Doc Config (DC) File: A configuration file in the project directory. It defines several 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:

Small documentation projects, consisting of Single Deliverables (Article or Book)
Larger documentation projects, consisting of Multiple Deliverables: Articles or Books in a Set

Note: Differences Between DocBook 4 and DocBook 5

The examples below differ slightly with regards to the respective DocBook version. One of the main differences is the header of the XML files. Apart from that, the articleinfo and bookinfo elements no longer exist in DocBook 5. They have been replaced by the generic info element.

2.6.1 Single Deliverables (Article or Book) #

The simplest case of a documentation project is probably a white paper or article. Typically, its content can be stored 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: Creating an Example Document

The command daps-init allows you to automatically set up an example article or book, together with a DC file, as described in Procedure 2, “Using daps-init ”. Use the --docbook4 or the --docbook5 option to define the Docbook version to use. 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 simple examples for DocBook 4 and DocBook 5 in Example 2.3 and Example 2.4, respectively.

Example 2.3: 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>

Example 2.4: MAIN file of an Article (DocBook 5.x) #

<?xml version="1.0" encoding="UTF-8"?>
[...]

 <article xml:id="art.template" xml:lang="en"
  xmlns="http://docbook.org/ns/docbook" 
  xmlns:xlink="http://www.w3.org/1999/xlink">

<info>
 <title>Article Template</title>
 <subtitle>generated by DAPS</subtitle>
 <info>
  <releaseinfo>Version 0.1</releaseinfo>
  <releaseinfo>Revision: 0</releaseinfo>
  <releaseinfo>
   Build Date: <?dbtimestamp format="B d, Y"?>
  </releaseinfo>
  <legalnotice>
   <para>
    <link xlink:href="http://www.gnu.org/licenses/fdl-1.3-standalone.html">
    GNU Free Documentation License</ulink>
   </para>
  </legalnotice>
 </info>
 <abstract>
  <para>
   You may use this file as a template. For a complete DocBook reference
   see <citetitle>DocBook: The Definitive Guide</citetitle>, available at
   <link xlink:href="http://www.docbook.org/tdg/en/html/docbook.html"/>.
  </para>
 </abstract>
 <sect1 xml: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 xml: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.3 or Example 2.4 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.3 or Example 2.4 could look as follows:

Example 2.5: Basic DC File for an Article #

## Doc config file for the DAPS example document
## 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.6: 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>

Example 2.7: MAIN file of a Book (DocBook 5.x) #

<?xml version="1.0" encoding="UTF-8"?>
[...]

<book xml:id="book.template" xml:lang="en"
      xmlns="http://docbook.org/ns/docbook" 
      xmlns:xlink="http://www.w3.org/1999/xlink">
 <info>
  <title>Book Template</title>
  <subtitle>generated by daps</subtitle>
  <productname>Book Template</productname>
   <legalnotice>
   <para>
    <link xlink:href="http://www.gnu.org/licenses/fdl-1.3-standalone.html">
    GNU Free Documentation License</ulink>
   </para>
  </legalnotice>
 </info>
 <chapter xml: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 xml: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.6 or Example 2.7 . 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.6 or Example 2.7 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.8: 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.6.2 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). Those 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.9: 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 and the DAPS User Guide— both guides belong to the same documentation set, but use different layouts.

Example 2.10: DC File For a Book in a Set #

## Doc config file for DAPS Quick Start
## 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

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

Example 2.11: 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

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

FORMATTER="xep" 5

##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" 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, `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	Specifies the PDF formatter to use. For supported formatters, refer to Section 3.2, “Software Requirements”. In this example, XEP is specified as PDF formatter.
6	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.12, “DC File for a Set”.

Example 2.12: 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

## enable sourcing
export DOCCONF=$BASH_SOURCE 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, 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	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.7 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.13, “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.13: 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: Specifying the DC File

For execution of most commands, DAPS needs to know which DC file to use. Usually, you do so by specifying a DC file with the global option -d. For example:

tux:~> daps -d PATH_TO_DC_FILE pdf

Only in the following cases you may omit the -d option:

If your documentation directory contains only one DC file. In that case, DAPS automatically uses the corresponding file.
If you have specified a default DC file to use in ~/.config/daps/dapsrc (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.
If you want to call the help function.

To view the global options and the available subcommands for DAPS, 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

Print this page