NAME¶
daps - A complete environment to build HTML, PDF, ePUB and other
formats from DocBook XML.
SYNOPSIS¶
daps -d DC-file
[GLOBAL OPTIONS] subcommand
[COMMAND OPTIONS]
daps --main MAIN-file
[GLOBAL OPTIONS] subcommand
[COMMAND OPTIONS]
DESCRIPTION¶
DAPS contains a set of stylesheets, scripts and Makefiles that
enable you to create HTML, PDF, ePUB and other formats from DocBook XML with
a single command. It also contains tools to generate profiled source
tarballs for distributing your XML sources for translation or review.
DAPS also includes tools that assist you when writing DocBook XML:
linkchecker, validator, spellchecker, editor macros and stylesheets for
converting DocBook XML.
Most of DAPS' functionality can be accessed with the command
daps. Run daps help to access the built-in tool
documentation. If you want information about a specific command, you can run
daps subcommand help
GLOBAL OPTIONS¶
--adocattr="NAME=VALUE"
Overwrite, define or delete an AsciiDoc document
attribute. >To overwrite an attribute already defined in the AsciiDoc
document, use
NAME=
VALUE, or just
NAME for attributes
without a value. To delete a value set in the document use
NAME!. To
set a value that is not already set in the document, use
NAME=
VALUE@.
Default: unset.
This option can be specified multiple times. Only works with
AsciiDoc sources and is ignored otherwise.
--adocimgdir=IMAGE_DIR
Specify a directory for the images used in the AsciiDoc
sources. Must contain all images, subdirectories are ignored. Not required if
the images reside in the directory structure required for DocBook projects
(see DAPS manual).
Default: unset.
Only works with AsciiDoc sources and is ignored otherwise.
--builddir=BUILDDIR
Directory where every output DAPS generates will end up.
Default: DOC DIR/build/
--color=(0|1)
By default errors, results, warnings and certain info
messages are printed in color using bash color codes. Set to '0' to turn off
colors.
Default: 1 (when the output does not go to a terminal, colored
output will be disabled automatically).
--commands
Show a list of available DAPS sub commands.
--debug
Print debugging messages. Alternatively see the
--verbosity options for an output that is better readable.
--docconfig=DC-FILE, -d
DC-FILE
Path to doc config file to use. Mandatory unless there is
only a single
DC-FILE in the current directory or unless you have
configured a default value (
DOCCONF_DEFAULT) in ~/.config/daps/dapsrc.
Default: unset.
Note: Options --docconfig and --main exclude each
other.
--fb_styleroot=PATH_TO_STYLESHEET
Fallback styleroot directories. Can only be used in
conjunction with
--styleroot. By default, the DocBook stylesheets are
used as a fallback if custom styles for an output format are not present. With
this option you can specify a list of alternative fallbacks (space separated
absolute paths). The directories will be tested in the order specified, the
first one that applies to the requested format, will be used. The original
DocBook stylesheets will be used as a last resort. Useful if you have forks of
your custom stylesheets.
Default: unset.
--force
Force a rebuild of the document even when an up-to-date
version exists.
--help, -h
Help
--jobs
Specify how many parallel jobs to use. Higher numbers
will significantly increase the processing speed, but will also set your
machine under heavy load, up to a point where it may become (temporarily)
unresponsive.
Default: Use as many jobs as CPU cores are available.
--main=FILE, -m FILE
Path to the main file defining your document.
Note: Options --main and --docconfig exclude each
other.
--schema=URN
URN to a DocBook 5 schema that is to be used for
validation. Will be ignored when validating DocBook 4 documents. Note: To
validate with a local schema, specify an absolute path with the
file:// prefix
(e.g.
file:///foo/schema.rnc)--styleroot=PATH_TO_STYLESHEET
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.
--verbosity=0, -v0
Verbosity Level 0 (print 1 line of results)
--verbosity=1, -v1, -v
Verbosity Level 1 (print intermediate results)
--verbosity=2, -v2, -vv
Verbosity Level 2 (print all files created)
--verbosity=3, -v3, -vvv
Verbosity Level 3 (print all commands, very verbose).
Parallelization of jobs will be turned off, to increase the readability.
--version
Print the version number
--xsltprocessor=PROCESSOR
Specify an XSLT processor that is used to transform the
XML files. Currently supported are "xsltproc" and "saxon"
(version 6).
Default: xsltproc
SUBCOMMANDS¶
help
Print this help
Generate Documents¶
epub
Generates an ePUB book
html
Generates an HTML book (chunked or single file
HTML)
man
Generates a man page
mobi
Generates an Amazon Kindle eBook
pdf
Generates a PDF book (color, grayscale, printable)
text
Generates an ASCII book
webhelp
Generates an HTML book with collapsible TOC and search
(experimental)
File Lists¶
list-file
Lists the filename that contains the ID specified with
the mandatory parameter --rootid.
list-srcfiles
List source files (XML sources, images, entity
declarations, DC-file) used by the document reference by the DC-file
list-srcfiles-unused
List files from the xml/ and images/src/ directories not
used by the document reference by the DC-file.
list-images-missing
List images referenced in the XML sources but missing in
the images' source directory
list-images-multisrc
List images for which have the same basename (e.g.
foo.svg and foo.png). Refer to the DAPS manual for more
information.
Cleaning up¶
clean
Remove all profiled sources and temporary files
clean-images
Remove all generated images
clean-package
Remove all generated package data for the given DC-file.
Generated images and profiled sources will not be deleted.
clean-results
Remove all generated books, archives, and log files for
the given DC-file. Generated images and profiled sources will not be
deleted.
clean-all, real-clean
Remove everything generated by DAPS.
Packaging¶
package-html
Provide an HTML tarball (chunked HTML or single HTML),
desktop, document, and/or page files (for KDE and GNOME).
package-pdf
Provide a PDF, desktop, document, and/or page files (for
KDE and GNOME)
package-src
Provide a TAR archive with profiled XML sources or
AsciiDoc sources and graphics files.
Deploying¶
locdrop
Provide everything that is needed to translate the
sources.
unpack-locdrop
Unpack a localization drop packages source.
Not supported for AsciiDoc projects.
Other Commands¶
getimages
List or display images from a profiled DocBook XML
file.
linkcheck
Checks URLs within <ulink> and <link>
tags.
optipng
Optimize (size) source PNGs.
profile
Profile XML sources.
spellcheck
Spellchecks the file specified with --file or the
document specified by --rootid.
stylecheck
Performs a style check on the given DC-file or rootid.
Not supported for AsciiDoc projects.
validate
Validate profiled XML sources. Automatically profiles the
XML sources if needed.
Not supported for AsciiDoc projects.
xmlformat
Prettify the XML source files using
daps-xmlformat.
Not supported for AsciiDoc projects.
File and Directory Names¶
target-name
Print resulting file name for target.
target may be one of pdf, epub, pdf, txt
target-dir-name
Print resulting directory name for target.
target may be html, man or webhelp
Debugging¶
bigfile
Creates a single “big” XML file by
resolving xi:includes. Useful for detecting validation errors that cannot be
found otherwise.
Not supported for AsciiDoc projects.
dapsenv
Print a list of the most important make variables and
their value
images
Generates all images for the given DC-file or
rootid
showvariable
Print value of a given make variable: daps showvariable
VARIABLE=VARIABLE_NAME
EXAMPLES¶
Generate a single HTML page:
daps -d DC-example html
--single
Generate ePUB using custom stylesheets:
daps -d DC-example --styleroot
/usr/share/xml/docbook/stylesheets/daps2013 epub
Generate PDF for the print shop using the XEP formatter
daps -d DC-example pdf --formmatter=xep
--grayscale --cropmarks
Check links and show the result in a browser
daps -d DC-example linkcheck
--show
FILES¶
/etc/daps/config
The system wide configuration file. See the file's inline
documentation for detailed information.
~/.config/daps/dapsrc
The per user configuration file. See the inline
documentation of /etc/daps/config for detailed information.
SEE ALSO¶
https://opensuse.github.io/daps/
DAPS project homepage
DAPS Quick Start[1]
Contains an overview of basic concepts and how to create
your documents.
DAPS User Guide[2]
Is intended for users who want to make efficient use of
DocBook XML for editing and publishing their documentation. Key knowledge of
XML and DocBook is expected, as well as key knowledge of using the Bash Shell
(or command line interfaces in general).
AUTHORS¶
Frank Sundermeyer <fsundermeyer@opensuse.org>
Developer
Thomas Schraitle <toms@opensuse.org>
Developer
Stefan Knorr
Developer
Berthold Gunreben
Previous Developer of susedoc
Jana Jaeger
Previous Developer of susedoc
NOTES¶
- 1.
- DAPS Quick Start
- 2.
- DAPS User Guide