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.
xref
to unknown ID)entity-decl.ent
&productname;
and &productnumber;
Entities/etc/daps/config
(DAPS 1.0)varlistentry
ElementCopyright © 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.
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.
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 .
This guide contains links to additional documentation resources. The following manuals are available for DAPS:
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.
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.
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!
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, Alt–F1: a key to press or a key combination; keys are shown in uppercase as on a keyboard
, › : menu items, buttons
Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.
This documentation is written in DocBook (see http://www.docbook.org) and generated by DAPS.
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.
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.
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.
If you have multiple or very large documentation projects, a machine with multiple cores is recommended.
The disk space consumed mostly depends on the amount of your documentation sources and the number of output formats you want to generate.
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.
In addition to DAPS, you need the following software:
An XML (or text) editor of your choice.
For generating PDF output: an FO formatter, like FOP (http://projects.apache.org/projects/fop.html) or XEP (http://www.renderx.com). The FO formatter Antenna House Formatter (http://www.antennahouse.com) is currently not supported. Whereas FOP is an open source product, both XEP and Antenna House are commercial products.
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.
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”.
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.
Open your browser and go to http://software.opensuse.org/.
Enter daps
.
On the resulting page, click
› › .Look for the version from the repository
Documentation:Tools
and click the
link next to it. A window called
should appear.
Follow the instructions and click
, , and finally .
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 .
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.
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
.
Before starting the installation, check the DAPS System Requirements and make sure all required packages and tools are installed.
Go to http://sourceforge.net/projects/daps/files/ and
download the DAPS source TAR archive,
daps-version_number.tar.bz2
.
Unpack the TAR archive:
tux >
tar -xvf daps-version_number.tar.bz2
Change to the newly created daps
subdirectory and
start the configure script:
tux >
./configure
If you want to adjust the DAPS installation paths:
View the available options with
tux >
./configure
--help
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.
Check the summary carefully.
Install missing packages, if necessary. After installing new packages, repeat Step 3 and check the summary again.
If everything is prepared according to your wishes, enter:
tux >
make
Start the installation process with:
tux >
sudo make install
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.
Currently, DAPS supports only DocBook 4.x. Support for DocBook 5.x is planned for version 2.0.
DAPS supports technical writers in the editing, translation and publishing process of DocBook XML files (in the following, simply referred to as XML files):
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.
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.
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 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”.
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”.
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”.
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.
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.
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.
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.
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.
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.
The following key files define a documentation project so that it can be processed by DAPS:
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.
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:
Small documentation projects, consisting of Single Deliverables (Article or Book)
Larger documentation projects, consisting of Multiple Deliverables: Articles or Books in a Set
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.).
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.
<?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:
## 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:
<?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.
## 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
Specifies the XML MAIN file. It contains the highest-level object
(root element) of your documentation project. The MAIN file must be located
in | |
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. |
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).
<?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.
## 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
Specifies the XML MAIN file. It contains the highest-level object
(root element) of your documentation project. The MAIN file must be located
in | |
Defines the root ID of the element to be used for creating an output format.
Usually, you specify the root ID of a
In this example, | |
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. | |
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. | |
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. |
## 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
Specifies the XML MAIN file. It contains the highest-level object
(root element) of your documentation project. The MAIN file must be located
in | |
Defines the root ID of the element to be used for creating an output format.
Usually, you specify the root ID of a
In this example, | |
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. | |
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. | |
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. | |
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. | |
When set to |
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”.
## 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
Specifies the XML MAIN file. It contains the highest-level object
(root element) of your documentation project. The MAIN file must be located
in | |
Defines the root ID of the element to be used for creating an output format.
Usually, you specify the root ID of a 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. | |
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. | |
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. | |
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. | |
When set to | |
Enabling this parameter allows you to source the DC file on the Bash with
DAPS. Sourcing a DC file (formerly called |
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.
YOUR_DOC_DIR/ 1 |--DC-* 2 |--images/ | |--src/3 | | |--dia/ | | |--eps/ | | |--fig/ | | |--pdf/ | | |--png/ | | |--svg/ |--xml/4 | |--MAIN*.xml5
“Working directory” for the respective documentation project. | |
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”. | |
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. | |
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 | |
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”. |
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:
YOUR_DOC_DIR 1 |--build/ 2 |--NAME_OF_DC1/ 3 |--NAME_OF_DC2/ 3 |--.images/ 4 |--.profiled/ 5 |--.tmp/ 6
“Working directory” for the respective documentation project. | |
Directory that holds all contents build by DAPS. | |
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
| |
Directory holding the images created by DAPS. | |
Directory holding the profiled XML sources created by DAPS. | |
Directory holding temporary files created by DAPS (for example, the FO files). |
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.
tux >
daps
1 --debug2 -d3 DC-daps-example html4 --static5
Main command: | |
Global Option | |
Global Option | |
Subcommand | |
Command option |
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
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
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.
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”.
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.
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.
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
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.
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
.
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.
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.
checklink
follows XIncludes
The checklink
command always follows
xi:includes
, even when using the
--file
option.
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
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.
daps checklink
#
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)
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”.
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/.
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).
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.
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.
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.
Remark
Elementstux >
daps
-d PATH_TO_DC_FILE validate --remarks
<!--Comment-->
)tux >
daps
-d PATH_TO_DC_FILE validate --comments
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.
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.
Subcommand |
Output/Note |
---|---|
|
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
|
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
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 |
html --single |
Creates a single HTML file, named after the DC file used to
create the output. Open the generated
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 |
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 |
webhelp |
Creates a DocBook Web Help output. Open the generated
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
|
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 › .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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”.
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.
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.
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
.
<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>
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.
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.
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 ...
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
.
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.
tux >
daps -d PATH_TO_DC_FILE projectgraphics
Lists all graphics used by the DocBook files that are referenced in the current DC file.
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.
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.
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.
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”.
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.
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.
tux >
daps -d PATH_TO_DC_FILE xmlgraphics
Lists all color images of the specified documentation project that have been 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.
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.
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.
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.
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.
entity-decl.ent
#<?xml version="1.0" encoding="iso-8859-1" ?> <!ENTITY exampleuser "tux"> <!ENTITY exampleuserII "wilber"> <!ENTITY examplegroup "users"> [...]
<?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> [...]
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.
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.
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.
<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:
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:
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:
<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:
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 |
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”.
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.
Attribute Name |
Use |
Profiling Parameter |
---|---|---|
|
Computer or chip architecture, such as | PROFARCH |
|
No preassigned semantics, general purpose attribute. | PROFCONDITION |
|
Operating system. | PROFOS |
|
Product vendor. | PROFVENDOR |
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.
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.
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.
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).
<?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>
Unprofiled listitems. The common features 1-3 are available in all software editions or versions. | |
Listitem profiled with attribute
| |
Listitem profiled with attribute
| |
Listitem profiled with two attributes: Attribute
|
<?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.
## Doc Config File for Frog Sound Recordings ## (Home Edition) ## Mandatory Parameters MAIN="art_frog.xml" 1 ## Profiling PROFCONDITION="basic" 2 [...]
MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”. | |
DAPS profiling parameter for the
|
## Doc Config File for Frog Sound Recordings ## (Professional Edition) ## Mandatory Parameters MAIN="art_frog.xml" 1 ## Profiling PROFCONDITION="prof" 2 [...]
MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”. | |
DAPS profiling parameter for the
|
## 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 [...]
MAIN parameter referencing the MAIN file. See Example 6.7, “MAIN file With PI for Profiling”. | |
DAPS profiling parameter for the
| |
DAPS profiling parameter for the
|
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.
<!--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”.
Insert one of the respective elements setinfo
,
bookinfo
, or articleinfo
in your
set, book, or article.
Within setinfo
, bookinfo
, or
articleinfo
, add both a
productname
and productnumber
element.
Use the &productname;
and
&productnumber;
entity within the respective
elements.
Then use them in the text wherever you need them.
&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>
Processing instruction (PI) in the header of the MAIN file. If it is missing, any profiling parameters in the DC file will be ignored. | |
Reference to the separate entity declaration file (with a parameter entity). | |
Element | |
Element | |
Element | |
Paragraph containing the entities |
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.
DC File |
Output |
---|---|
Frog Sound Recordings (Basic) 1.0 is a software for recording, editing, and mixing audio data. | |
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. |
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)
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.
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:
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.
DRAFT
Watermarktux >
daps -d PATH_TO_DC_FILE color-pdf --draft
Generates a PDF that has a DRAFT
watermark printed
on each page.
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.
--meta
OptionAs the --meta
relies on certain mechanisms and SVN
properties, including metadata in the output only works under the
following conditions:
Profiling is activated in your XML sources. For details, refer to Section 6.3.2.2, “MAIN file: Processing Instruction”.
You manage your documentation project with Docmanager. and have set the respective SVN properties.
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.
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.
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.
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”.
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.
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.
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.
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.
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
.
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.
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
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
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
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
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
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.
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:
HTML Parameter Reference: http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
FO Parameter Reference: http://docbook.sourceforge.net/release/xsl/current/doc/fo/index.html
Manpages Parameter Reference: http://docbook.sourceforge.net/release/xsl/current/doc/manpages/index.html
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
As value of | |
You must quote the string with double and single quotes. | |
Name of the parameter to adjust. | |
Value for 3.
It will be passed on unmodified to the XSLT processor call that
creates the |
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/.
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:
Open both ~/.daps/config
and /etc/daps/config
in a text editor.
Select which parameters you want to modify.
Copy only those to ~/.daps/config
.
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.
Save ~/.daps/config
and test if your changes lead to the expected
results.
/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=""
This chapter lists common problems and possible solutions, sorted into categories.
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"
.
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?
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.
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.
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).
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.
See FO Formatter.
See Profiling.
The DTD (Document Type Definition) defines the exact elements, entities attributes and structure available in an XML or HTML document.
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 provides authors of technical documentation with an easy-to-use toolchain to convert their DocBook documents into various output formats.
DocBook is a semantic markup language for technical documentation published as a DTD.
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 &
in XML.
You can also declare custom entities.
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.
See XSL-FO.
See FO Formatter.
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 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.
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.
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.
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 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).
In the context of DocBook, the term stylesheet usually refers to the XSLT stylesheets used to transform DocBook documents into their respective output formats.
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 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.
See FO Formatter.
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 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.
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 (XML-binary Optimized Packaging) is a W3C (World Wide Web Consortium) recommendation on how to represent binary data inside XML documents.
XML is a markup language with rules to encode documents into a form that is both human-readable and machine-readable.
XSL is a collective noun used to refer to XSLT, XSL-FO, and the XML Path Language (XPath).
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 or Extensible Stylesheet Language for Transformations is a language based on XML. It is used to transform XML documents.
This section provides instructions how to migrate existing DocBook projects so that you can use DAPS for managing and publishing them.
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.
If you have any XIncludes or entity declaration files, also put them
into the xml
subdirectory.
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.
Make sure that the base names of your image files are unique. For details, refer to Section 5.3, “File name Requirements”.
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.
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.
This chapter describes:
the use of DocBook macros for Emacs,
how to integrate daps-susespell into jEdit.
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”.
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
.
To load the DocBook macros, open your Emacs customization file
(~/.emacs
or ~/.gnu-emacs
).
Insert the following line:
(load "/usr/share/emacs/site-lisp/docbook_macros.el" t t)
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.
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”.
Install and activate the plug-in for spell checking:
Start jEdit and select
› .If the
plug-in is not already installed, install and activate it.Close and restart jEdit.
Configure the plug-in as follows:
Select
› .In the left navigation pane, select
› .
Set en_US
.
If the desired dictionary does not appear in the drop-down list, install the respective aspell dictionary for the language and click
.In the left navigation pane, switch to
› .In the table, activate the
entry and click next to it.In the
, activate the following entries:NULL
COMMENT1
LITERAL1
In the left navigation pane, switch to
› .Set the path to the
. Select .To use an additional custom aspell dictionary, specify the path to the custom dictionary in the input field below
:--extra-dicts=PATH_TO_CUSTOM_DICT
For example:
--extra-dicts=/home/tux/custom_aspell.rws
Confirm your settings in the plugin options dialog with
or .To execute a spell check during editing, select
› › (or use the keyboard shortcut assigned to that menu item).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:
Work in progress
The make files have now been split into several smaller make files, that are specific for the respective output like PDF, or HTML.
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.
Whereas DAPS 1.x required Bash 4, DAPS 2.0 is compatible with Bash 3.
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.
A new subcommand has been added: daps dapsenv
. It
prints a list of the most important make variables and their value.
In the profiled XML sources entities are now always resolved and replaced by their value.
If the XML is not well-formed, DAPS quits and shows a meaningful error message.
With daps --commands
, you can list all available
commands.
DAPS now also supports JPEG as image format.
Work in progress
DAPS now also supports the Saxon XSLT processor. Use the
option --xsltprocessor
to define which processor to use.
Per default, xsltproc
is used.
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
The following commands are deprecated:
. Use
daps
all
instead.daps
pdf
. Use
daps
bigfile-reduced
instead.daps
bigfile
. Use
daps
check
instead. daps
dapsenv
. Use
daps
chklink
instead. daps
checklink
. This command is no longer
supported. daps
db2novdoc
. Use
daps
desktop-files
or
daps
package-html --desktopfiles
instead. daps
package-pdf --desktopfiles
. This command is
no longer supported. 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
. Use
daps
dist-graphics
instead.daps
package-src
. This command is
no longer supported. daps
dist-graphics-png
. Use
daps
dist-html-single
instead.
daps
package-html --single
. Use
daps
disthtml-single
instead.
daps
package-html --single
. Use
daps
dist-xml
instead. daps
package-src
. This command is no longer
supported. daps
document-files-dir-name
. Use
daps
document-files-html
instead. daps
package-html --documentfiles
. Use
daps
document-files-pdf
instead. daps
package-pdf --documentfiles
. This command is no longer
supported. daps
force
. Use
daps
htmlsingle
instead. daps
html --single
. Use
daps
htmlsingle-name
instead.
daps
html-dir-name --single
. Use
daps
html-single
instead. daps
html --single
. Use
daps
html-single-name
instead. daps
html-dir-name --single
. Use
daps
jana
instead. daps
checklink
. This command is no
longer supported. daps
link-entity-dist
. Use
daps
missinggraphics
instead. daps
list-images-missing
. Use
daps
online-localized
instead. daps
online-docs --noset
. This command is no
longer supported. daps
offspring
. Use
daps
pdf-color
instead. daps
pdf
. Use
daps
pdf-color-name
instead. daps
pdf-name
. This command is no
longer supported. daps
penguin
. Use
daps
prof
instead. daps
profile
. Use
daps
profiledir
instead. daps
showvariable VARIABLE=PROFILEDIR
. Use
daps
projectfiles
instead. daps
list-srcfiles --noimg
. Use
daps
projectgraphics
instead. daps
list-srcfiles --nodc --noent --noxml
. Use
daps
provide-images
instead.daps
images --grayscale
. Use
daps
provide-color-images
instead.daps
images --color
. This command is no
longer supported. daps
provide-epub-images
. Use
daps
remainingfiles
instead. daps
list-srcfiles-unused --noimg
. Use
daps
remaininggraphics
instead. daps
list-srcfiles-unused --noxml
. Use
daps
txt
instead. daps
text
. Use
daps
txt-name
instead. daps
text-name
. Use
daps
warn-images
instead. daps
list-images-multisrc
. This command is no longer supported.
daps
wiki
. This command is no longer supported.
daps
wiki-name
. Use
daps
xmlfiles
instead. daps
list-srcfiles --nodc --noent --noimg
. This command is no
longer supported. daps
xml-graphics-bw
. This command is no longer
supported.daps
xmlgraphics
Chapter has been revised.
Major content has been added.
Major content has been added.
Major content has been added.
Some additions and changes.
An example of /etc/daps/config
has been added.
An overview of the main documentation updates has been added.
Various small improvements throughout the document.
This appendix contains the GNU General Public License version 2 and the GNU Free Documentation License version 1.2.
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation’s software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author’s protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors’ reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone’s free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
a). You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
b). You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
c). If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
a). Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
b). Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
c). Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
one line to give the program’s name and an idea of what it does. Copyright (C) yyyy name of author This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w’. This is free software, and you are welcome to redistribute it under certain conditions; type `show c’ for details.
The hypothetical commands `show w’ and `show c’ should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w’ and `show c’; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision’ (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License (http://www.fsf.org/licenses/lgpl.html) instead of this License.
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.