'\" t
.\"     Title: daps
.\"    Author: Frank Sundermeyer <fsundermeyer@opensuse.org>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/10/2020
.\"    Manual: DAPS
.\"    Source: daps @DAPS_VERSION@
.\"  Language: English
.\"
.TH "DAPS" "1" "01/10/2020" "daps @DAPS_VERSION@" "DAPS"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
daps \- A complete environment to build HTML, PDF, ePUB and other formats from DocBook XML\&.
.SH "SYNOPSIS"
.HP \w'\fBdaps\fR\ 'u
\fBdaps\fR \-d\ \fIDC\-file\fR [\fIGLOBAL\ OPTIONS\fR] subcommand [\fICOMMAND\ OPTIONS\fR]
.HP \w'\fBdaps\fR\ 'u
\fBdaps\fR \-\-main\ \fIMAIN\-file\fR [\fIGLOBAL\ OPTIONS\fR] subcommand [\fICOMMAND\ OPTIONS\fR]
.SH "DESCRIPTION"
.PP
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\&.
.PP
DAPS also includes tools that assist you when writing DocBook XML: linkchecker, validator, spellchecker, editor macros and stylesheets for converting DocBook XML\&.
.PP
Most of DAPS\*(Aq functionality can be accessed with the command
\fBdaps\fR\&. Run
\fBdaps \fR\fB\fBhelp\fR\fR
to access the built\-in tool documentation\&. If you want information about a specific command, you can run
\fBdaps \fR\fB\fIsubcommand\fR\fR\fB \fR\fB\fBhelp\fR\fR
.SH "GLOBAL OPTIONS"
.PP
\fB\-\-adocattr="NAME=VALUE"\fR
.RS 4
Overwrite, define or delete an AsciiDoc document attribute\&. >To overwrite an attribute already defined in the AsciiDoc document, use
\fINAME\fR=\fIVALUE\fR, or just
\fINAME\fR
for attributes without a value\&. To delete a value set in the document use
\fINAME\fR!\&. To set a value that is not already set in the document, use
\fINAME\fR=\fIVALUE\fR@\&.
.sp
Default: unset\&.
.sp
This option can be specified multiple times\&. Only works with AsciiDoc sources and is ignored otherwise\&.
.RE
.PP
\fB\-\-adocimgdir=\fR\fB\fIIMAGE_DIR\fR\fR
.RS 4
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)\&.
.sp
Default: unset\&.
.sp
Only works with AsciiDoc sources and is ignored otherwise\&.
.RE
.PP
\fB\-\-builddir=\fR\fB\fIBUILDDIR\fR\fR
.RS 4
Directory where every output DAPS generates will end up\&.
.sp
Default:
\fIDOC DIR\fR/build/
.RE
.PP
\fB\-\-color=(0|1)\fR
.RS 4
By default errors, results, warnings and certain info messages are printed in color using bash color codes\&. Set to \*(Aq0\*(Aq to turn off colors\&.
.sp
Default: 1 (when the output does not go to a terminal, colored output will be disabled automatically)\&.
.RE
.PP
\fB\-\-commands\fR
.RS 4
Show a list of available DAPS sub commands\&.
.RE
.PP
\fB\-\-debug\fR
.RS 4
Print debugging messages\&. Alternatively see the \-\-verbosity options for an output that is better readable\&.
.RE
.PP
\fB\-\-docconfig=\fR\fB\fIDC\-FILE\fR\fR\fB, \-d \fR\fB\fIDC\-FILE\fR\fR
.RS 4
Path to doc config file to use\&. Mandatory unless there is only a single
\fIDC\-FILE\fR
in the current directory or unless you have configured a default value (\fBDOCCONF_DEFAULT\fR) in
~/\&.config/daps/dapsrc\&.
.sp
Default: unset\&.
.sp
Note: Options
\fB\-\-docconfig\fR
and
\fB\-\-main\fR
exclude each other\&.
.RE
.PP
\fB\-\-fb_styleroot=\fR\fB\fIPATH_TO_STYLESHEET\fR\fR
.RS 4
Fallback styleroot directories\&. Can only be used in conjunction with
\fB\-\-styleroot\fR\&. 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\&.
.sp
Default: unset\&.
.RE
.PP
\fB\-\-force\fR
.RS 4
Force a rebuild of the document even when an up\-to\-date version exists\&.
.RE
.PP
\fB\-\-help, \-h\fR
.RS 4
Help
.RE
.PP
\fB\-\-jobs\fR
.RS 4
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\&.
.sp
Default: Use as man jobs as available CPU cores\&.
.RE
.PP
\fB\-\-main=\fR\fB\fIFILE\fR\fR\fB, \-m \fR\fB\fIFILE\fR\fR
.RS 4
Path to the main file defining your document\&.
.sp
Note: Options
\fB\-\-main\fR
and
\fB\-\-docconfig\fR
exclude each other\&.
.RE
.PP
\fB\-\-schema=\fR\fB\fIURN\fR\fR
.RS 4
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)
.RE
.PP
\fB\-\-styleroot=\fR\fB\fIPATH_TO_STYLESHEET\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-verbosity=0, \-v0\fR
.RS 4
Verbosity Level 0 (print 1 line of results)
.RE
.PP
\fB\-\-verbosity=1, \-v1, \-v\fR
.RS 4
Verbosity Level 1 (print intermediate results)
.RE
.PP
\fB\-\-verbosity=2, \-v2, \-vv\fR
.RS 4
Verbosity Level 2 (print all files created)
.RE
.PP
\fB\-\-verbosity=3, \-v3, \-vvv\fR
.RS 4
Verbosity Level 3 (print all commands, very verbose)\&. Parallelization of jobs will be turned off, to increase the readability\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print the version number
.RE
.PP
\fB\-\-xsltprocessor=\fR\fB\fIPROCESSOR\fR\fR
.RS 4
Specify an XSLT processor that is used to transform the XML files\&. Currently supported are "xsltproc" and "saxon" (version 6)\&.
.sp
Default: xsltproc
.RE
.SH "SUBCOMMANDS"
.PP
\fBhelp\fR
.RS 4
Print this help
.RE
.SS "Generate Documents"
.PP
\fBepub\fR
.RS 4
Generates an ePUB book
.RE
.PP
\fBhtml\fR
.RS 4
Generates an HTML book (chunked or single file HTML)
.RE
.PP
\fBman\fR
.RS 4
Generates a man page
.RE
.PP
\fBmobi\fR
.RS 4
Generates an Amazon Kindle eBook
.RE
.PP
\fBpdf\fR
.RS 4
Generates a PDF book (color, grayscale, printable)
.RE
.PP
\fBtext\fR
.RS 4
Generates an ASCII book
.RE
.PP
\fBwebhelp\fR
.RS 4
Generates an HTML book with collapsible TOC and search (experimental)
.RE
.SS "File Lists"
.PP
\fBlist\-file\fR
.RS 4
Lists the filename that contains the ID specified with the mandatory parameter
\fB\-\-rootid\fR\&.
.RE
.PP
\fBlist\-srcfiles\fR
.RS 4
List source files (XML sources, images, entity declarations, DC\-file) used by the document reference by the DC\-file
.RE
.PP
\fBlist\-srcfiles\-unused\fR
.RS 4
List files from the
xml/
and
images/src/
directories not used by the document reference by the DC\-file\&.
.RE
.PP
\fBlist\-images\-missing\fR
.RS 4
List images referenced in the XML sources but missing in the images\*(Aq source directory
.RE
.PP
\fBlist\-images\-multisrc\fR
.RS 4
List images for which have the same basename (e\&.g\&.
\fIfoo\&.svg\fR
and
\fIfoo\&.png\fR)\&. Refer to the DAPS manual for more information\&.
.RE
.SS "Cleaning up"
.PP
\fBclean\fR
.RS 4
Remove all profiled sources and temporary files
.RE
.PP
\fBclean\-images\fR
.RS 4
Remove all generated images
.RE
.PP
\fBclean\-package\fR
.RS 4
Remove all generated package data for the given DC\-file\&. Generated images and profiled sources will
\fInot\fR
be deleted\&.
.RE
.PP
\fBclean\-results\fR
.RS 4
Remove all generated books, archives, and log files for the given DC\-file\&. Generated images and profiled sources will
\fInot\fR
be deleted\&.
.RE
.PP
\fBclean\-all, real\-clean\fR
.RS 4
Remove everything generated by DAPS\&.
.RE
.SS "Packaging"
.PP
\fBpackage\-html\fR
.RS 4
Provide an HTML tarball (chunked HTML or single HTML), desktop, document, and/or page files (for KDE and GNOME)\&.
.RE
.PP
\fBpackage\-pdf\fR
.RS 4
Provide a PDF, desktop, document, and/or page files (for KDE and GNOME)
.RE
.PP
\fBpackage\-src\fR
.RS 4
Provide a TAR archive with profiled XML sources or AsciiDoc sources and graphics files\&.
.RE
.SS "Deploying"
.PP
\fBlocdrop\fR
.RS 4
Provide everything that is needed to translate the sources\&.
.RE
.PP
\fBonline\-docs\fR
.RS 4
Provide a profiled XML bigfile, a graphics tarball (PNG only), color\-pdf, ePUB, and a single\-html archive\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.PP
\fBunpack\-locdrop\fR
.RS 4
Unpack a localization drop packages source\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.SS "Other Commands"
.PP
\fBchecklink\fR
.RS 4
Linkchecker for links from <ulink> tags\&.
.RE
.PP
\fBgetimages\fR
.RS 4
List or display images from a profiled DocBook XML file\&.
.RE
.PP
\fBoptipng\fR
.RS 4
Optimize (size) source PNGs\&.
.RE
.PP
\fBprofile\fR
.RS 4
Profile XML sources\&.
.RE
.PP
\fBspellcheck\fR
.RS 4
Spellchecks the file specified with
\fB\-\-file\fR
or the document specified by
\fB\-\-rootid\fR\&.
.RE
.PP
\fBstylecheck\fR
.RS 4
Performs a style check on the given DC\-file or rootid\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.PP
\fBvalidate\fR
.RS 4
Validate profiled XML sources\&. Automatically profiles the XML sources if needed\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.PP
xmlformat
.RS 4
Prettify the XML source files using
\fBdaps\-xmlformat\fR\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.SS "File and Directory Names"
.PP
\fB\fItarget\fR\fR\fB\-name\fR
.RS 4
Print resulting file name for
\fItarget\fR\&.
\fItarget\fR
may be one of pdf, epub, pdf, txt
.RE
.PP
\fB\fItarget\fR\fR\fB\-dir\-name\fR
.RS 4
Print resulting directory name for
\fItarget\fR\&.
\fItarget\fR
may be html, man or webhelp
.RE
.SS "Debugging"
.PP
bigfile
.RS 4
Creates a single
\(lqbig\(rq
XML file by resolving xi:includes\&. Useful for detecting validation errors that cannot be found otherwise\&.
.sp
Not supported for AsciiDoc projects\&.
.RE
.PP
\fBdapsenv\fR
.RS 4
Print a list of the most important make variables and their value
.RE
.PP
\fBimages\fR
.RS 4
Generates all images for the given DC\-file or rootid
.RE
.PP
\fBshowvariable\fR
.RS 4
Print value of a given make variable: daps showvariable VARIABLE=\fIVARIABLE_NAME\fR
.RE
.SH "EXAMPLES"
.PP
Generate a single HTML page:
.RS 4
\fBdaps \fR\fB\fB\-d DC\-example html \-\-single\fR\fR
.RE
.PP
Generate ePUB using custom stylesheets:
.RS 4
\fBdaps \fR\fB\fB\-d DC\-example \-\-styleroot /usr/share/xml/docbook/stylesheets/daps2013 epub\fR\fR
.RE
.PP
Generate PDF for the print shop using the XEP formatter
.RS 4
\fBdaps \fR\fB\fB\-d DC\-example pdf \-\-formmatter=xep \-\-grayscale \-\-cropmarks\fR\fR
.RE
.PP
Check links and show the result in a browser
.RS 4
\fBdaps \fR\fB\fB\-d DC\-example checklink \-\-show\fR\fR
.RE
.SH "FILES"
.PP
/etc/daps/config
.RS 4
The system wide configuration file\&. See the file\*(Aqs inline documentation for detailed information\&.
.RE
.PP
~/\&.config/daps/dapsrc
.RS 4
The per user configuration file\&. See the inline documentation of
/etc/daps/config
for detailed information\&.
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fB\%https://opensuse.github.io/daps/\fR\m[]
.RS 4
DAPS project homepage
.RE
.PP
\m[blue]\fBDAPS Quick Start\fR\m[]\&\s-2\u[1]\d\s+2
.RS 4
Contains an overview of basic concepts and how to create your documents\&.
.RE
.PP
\m[blue]\fBDAPS User Guide\fR\m[]\&\s-2\u[2]\d\s+2
.RS 4
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)\&.
.RE
.SH "AUTHORS"
.PP
\fBFrank Sundermeyer\fR <\&fsundermeyer@opensuse\&.org\&>
.RS 4
Developer
.RE
.PP
\fBThomas Schraitle\fR <\&toms@opensuse\&.org\&>
.RS 4
Developer
.RE
.PP
\fBStefan Knorr\fR
.RS 4
Developer
.RE
.PP
\fBBerthold Gunreben\fR
.RS 4
Previous Developer of susedoc
.RE
.PP
\fBJana Jaeger\fR
.RS 4
Previous Developer of susedoc
.RE
.SH "NOTES"
.IP " 1." 4
DAPS Quick Start
.RS 4
\%https://opensuse.github.io/daps/doc/art.daps.quick.htm
.RE
.IP " 2." 4
DAPS User Guide
.RS 4
\%https://opensuse.github.io/daps/doc/book.daps.user.html
.RE