Chapter 1. Conceptual Overview

Chapter 1. Conceptual Overview¶

Contents

1.1. Basic Concepts

DAPS (DocBook Authoring and Publishing Suite) is developed as open source software for Linux operating systems. It consists of integrated tools, stylesheets, scripts, and makefiles that support technical writers in the editing, translation and publishing process of DocBook XML files. DAPS supports single source publishing into a number of different output formats, like PDF, HTML, single HTML, or EPUB.

It can be used in combination with the following components:

an XML editor of your choice
an FO formatter (like FOP or XEP)
a version management system, like CVS or Subversion

1.1. Basic Concepts¶

1.1.1. Defining Documentation Projects¶

To define which XML files belong to your documentation project, and which variants can be generated from the project with the help of conditional text (or profiling, as it is called in DocBook), you need a special file called ENV file. It is a text file and sets a number of variables for your documentation project:

Example 1.1. An ENV-* file¶

# ENV file for DAPS User Guide
MAIN=MAIN.DAPS.xml         
ROOTID=book_daps_user.xml  
PROFARCH="x86;ppc"         
PROFOS="lin;win"           

LAYOUT=                    
DISTVER=1.0                
HTMLROOT="daps"            
PRODUCTNAME="DocBook Authoring and Publishing Suite"   

export DAPS_ENV_NAME=$(basename $BASH_SOURCE)

	Mandatory variable. Sets the main file that contains “references” to other books, chapters, appendices, etc. If your documentation project consists of multiple books and articles (a `set`), the MAIN variable usually references the file that contains the <set> element.
	Optional variable. Defines the root ID of the element to be used for creating an output format. Usually, you define the root ID of a <book> or article element here.
	Optional variable. If you want to profile your text for different platforms or (processor) achitectures (for example, x86 or ppc), this variable selects the architecture profiling information.
	If you want to profile your text for different operating systems (for example, for Linux and Windows), this variable selects the operating system profiling information.
	Determines the layout of the book. Per default, DAPS ships the following layouts: `flyer` Creates a flyer layout that can be used for Quick Starts. `pocket` Creates a pocket layout which a smaller page format. Empty, no value Selects the default layout.
	Sets the version of the current project.


	Optional line. You only need to add this line if you want to be able to source ENV files with DAPS. Sourcing an ENV file was necessary to work with the documentation environment provided by susedoc— DAPS' predecessor.

For a documentation set (a collection of books), you can define multiple ENV files. By referring different root IDs, you define which book is to be built with the specific ENV file. Of course, you can also specify different layouts for certain books (or use different values for one of the other variables defined in the ENV file):

Example 1.2. An ENV-* file¶

# ENV file for DAPS Quick Start
MAIN="MAIN.DAPS.xml"
ROOTID="art.daps.quickstart"
PROFOS="osuse"
PROFARCH="x86;amd64;em64t"
DISTVER="1.0"
LAYOUT="flyer"

export DAPS_ENV_NAME=$(basename $BASH_SOURCE)

Because ENV files define which XML files belong to a documentation project, they are necessary for validating your XML files and for generating any kind of output. Without ENV files, you cannot produce any output from your DocBook sources with DAPS.

If your documentation set contains cross-references between the individual books, it is useful to define an additional ENV file (without the root ID variable) that can be used to generate an HTML output that contains all hyperlinks between the individual books.

DAPS also contains a script for creating a new documentation project from scratch. . When using that script, an example ENV file is automatically created.

1.1.2. Directory Structure¶

For DAPS to work out of the box, XML files and images should be organized in the following directory structure: