<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.docbook.org/xml/4.5/docbookx.dtd"
[
  <!ENTITY daps_command "daps">
  <!ENTITY % entities SYSTEM "entity-decl.ent">
  %entities;
]>

<refentry lang="en" id="daps">
  <refentryinfo>
  <productname>&daps_command;</productname>
  <authorgroup>
   <author>
    <contrib>Developer</contrib>
    <firstname>Frank</firstname>
    <surname>Sundermeyer</surname>
    <email>fsundermeyer@opensuse.org</email>
   </author>
   <author>
    <contrib>Developer</contrib>
    <firstname>Thomas</firstname>
    <surname>Schraitle</surname>
    <email>toms@opensuse.org</email>
   </author>
   <author>
    <contrib>Developer</contrib>
    <firstname>Stefan</firstname>
    <surname>Knorr</surname>
   </author>
   <author>
    <contrib>Previous Developer of susedoc</contrib>
    <firstname>Berthold</firstname>
    <surname>Gunreben</surname>
   </author>
   <author>
    <contrib>Previous Developer of susedoc</contrib>
    <firstname>Jana</firstname>
    <surname>Jaeger</surname>
   </author>
  </authorgroup>
 </refentryinfo>
 <refmeta>
  <refentrytitle>&daps_command;</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="date"><?dbtimestamp format="Y B d"?></refmiscinfo>
  <refmiscinfo class="version">&dapsversion;</refmiscinfo>
  <refmiscinfo class="manual">&dapsacr;</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>&daps_command;</refname>
  <refpurpose>
   A complete environment to build HTML, PDF, ePUB and other formats from
   DocBook XML.
  </refpurpose>
 </refnamediv>

 <refsynopsisdiv id="daps.synopsis">
  <title>Synopsis</title>
  <cmdsynopsis>
   &dapscmd;
   <arg choice="plain">-d <replaceable>DC-file</replaceable></arg>
   <arg choice="opt"><replaceable>GLOBAL OPTIONS</replaceable></arg>
   <arg choice="plain">subcommand</arg>
   <arg choice="opt"><replaceable>COMMAND OPTIONS</replaceable></arg>
  </cmdsynopsis>

  <cmdsynopsis>
   &dapscmd;
   <arg choice="plain">--main <replaceable>MAIN-file</replaceable></arg>
   <arg choice="opt"><replaceable>GLOBAL OPTIONS</replaceable></arg>
   <arg choice="plain">subcommand</arg>
   <arg choice="opt"><replaceable>COMMAND OPTIONS</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="daps.description">
  <title>Description</title>
  <para>
    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.
   </para>
   <para>
    DAPS also includes tools that assist you when writing DocBook XML:
    linkchecker, validator, spellchecker, editor macros and stylesheets for
    converting DocBook XML.
   </para>
   <para>
    Most of DAPS' functionality can be accessed with the command
    &dapscmd;. Run <command>&daps; <option>help</option></command> to access
    the built-in tool documentation.  If you want information about a specific
    command, you can run <command>&daps; <replaceable>subcommand</replaceable>
    <option>help</option></command>
   </para>
  </refsect1>

 <refsect1 id="daps.globaloptions">
  <title>Global Options</title>
  <variablelist>
   <varlistentry>
    <term><option>--adocattr="NAME=VALUE"</option></term>
    <listitem>
     <para>
      Overwrite, define or delete an AsciiDoc document attribute. >To overwrite
      an attribute already defined in the AsciiDoc document, use
      <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable>, or just
      <replaceable>NAME</replaceable> for attributes without a value. To delete
      a value set in the document use <replaceable>NAME</replaceable>!. To set
      a value that is not already set in the document, use
      <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable>@.
     </para>
     <para>Default: unset.</para>
     <para>
      This option can be specified multiple times. Only works with
      AsciiDoc sources and is ignored otherwise.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--adocimgdir=<replaceable>IMAGE_DIR</replaceable></option>
    </term>
    <listitem>
     <para>
      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).
     </para>
     <para>Default: unset.</para>
     <para>
      Only works with AsciiDoc sources and is ignored otherwise.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--builddir=<replaceable>BUILDDIR</replaceable></option></term>
    <listitem>
     <para>Directory where every output &dapsacr; generates will end up.</para>
     <para>Default: <replaceable>DOC DIR</replaceable>/build/</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--color=(0|1)</option></term>
    <listitem>
     <para>
      By default errors, results, warnings and certain info messages are
      printed in color using bash color codes. Set to '0' to turn off
      colors.
     </para>
     <para>
      Default: 1 (when the output does not go to a terminal, colored
      output will be disabled automatically).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--commands</option></term>
    <listitem>
     <para>Show a list of available &dapsacr; sub commands.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--debug</option></term>
    <listitem>
     <para>
      Print debugging messages. Alternatively see the --verbosity options for an
      output that is better readable.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--docconfig=<replaceable>DC-FILE</replaceable>, -d
     <replaceable>DC-FILE</replaceable></option>
    </term>
    <listitem>
     <para>
      Path to doc config file to use. Mandatory unless there is only a single
      <replaceable>DC-FILE</replaceable> in the current directory or unless you
      have configured a default value (<envar>DOCCONF_DEFAULT</envar>) in
      &dapsconf-user;.
     </para>
     <para>Default: unset.</para>
     <para>
      Note: Options <option>--docconfig</option> and <option>--main</option>
      exclude each other.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--fb_styleroot=<replaceable>PATH_TO_STYLESHEET</replaceable></option>
    </term>
    <listitem>
     <para>
      Fallback styleroot directories. Can only be used in conjunction with
      <option>--styleroot</option>. 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.
     </para>
     <para>Default: unset.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--force</option></term>
    <listitem>
     <para>
      Force a rebuild of the document even when an up-to-date version exists.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--help, -h</option></term>
    <listitem>
     <para>Help</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--jobs</option></term>
    <listitem>
     <para>
      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.
     </para>
     <para>Default: Use as many jobs as CPU cores are available.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--main=<replaceable>FILE</replaceable>, -m
     <replaceable>FILE</replaceable></option>
    </term>
    <listitem>
     <para>
      Path to the main file defining your document.
     </para>
     <para>
      Note: Options <option>--main</option> and <option>--docconfig</option>
      exclude each other.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--schema=<replaceable>URN</replaceable></option></term>
    <listitem>
     <para>
      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
      <literal>file://</literal> prefix
      (e.g. <literal>file:///foo/schema.rnc</literal>)
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--styleroot=<replaceable>PATH_TO_STYLESHEET</replaceable></option>
    </term>
    <listitem>
     <para>
      By default, &dapsacr; 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.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--verbosity=0, -v0</option></term>
    <listitem>
     <para>Verbosity Level 0 (print 1 line of results)</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--verbosity=1, -v1, -v</option></term>
    <listitem>
     <para>Verbosity Level 1 (print intermediate results)</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--verbosity=2, -v2, -vv</option></term>
    <listitem>
     <para>Verbosity Level 2 (print all files created)</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--verbosity=3, -v3, -vvv</option></term>
    <listitem>
     <para>
      Verbosity Level 3 (print all commands, very verbose). Parallelization of
      jobs will be turned off, to increase the readability.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--version</option></term>
    <listitem>
     <para>Print the version number</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--xsltprocessor=<replaceable>PROCESSOR</replaceable></option>
    </term>
    <listitem>
     <para>
      Specify an XSLT processor that is used to transform the XML
      files. Currently supported are "xsltproc" and "saxon" (version
      6).
     </para>
     <para>
      Default: xsltproc
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 id="daps.commands">
  <title>Subcommands</title>
  <variablelist>
   <varlistentry>
    <term><option>help</option></term>
    <listitem>
     <para>Print this help</para>
    </listitem>
   </varlistentry>
  </variablelist>
  <refsect2>
   <title>Generate Documents</title>
   <variablelist>
    <varlistentry>
     <term><option>epub</option></term>
     <listitem>
      <para>Generates an ePUB book</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>html</option></term>
     <listitem>
      <para>Generates an HTML book (chunked or single file HTML)</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>man</option></term>
     <listitem>
      <para>Generates a man page</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>mobi</option></term>
     <listitem>
      <para>Generates an Amazon Kindle eBook</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>pdf</option></term>
     <listitem>
      <para>Generates a PDF book (color, grayscale, printable)</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>text</option></term>
     <listitem>
      <para>Generates an ASCII book</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>webhelp</option></term>
     <listitem>
      <para>
       Generates an HTML book with collapsible TOC and search (experimental)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>File Lists</title>
   <variablelist>
    <varlistentry>
     <term><option>list-file</option></term>
     <listitem>
      <para>
       Lists the filename that contains the ID specified with the mandatory
       parameter <option>--rootid</option>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>list-srcfiles</option></term>
     <listitem>
      <para>
       List source files (XML sources, images, entity declarations, DC-file)
       used by the document reference by the DC-file
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>list-srcfiles-unused</option></term>
     <listitem>
      <para>
       List files from the <filename>xml/</filename> and
       <filename>images/src/</filename> directories not used by the document
       reference by the DC-file.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>list-images-missing</option></term>
     <listitem>
      <para>
       List images referenced in the XML sources but missing in the images'
       source directory
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>list-images-multisrc</option></term>
     <listitem>
      <para>
       List images for which have the same basename
       (e.g. <replaceable>foo.svg</replaceable> and
       <replaceable>foo.png</replaceable>). Refer to the DAPS manual for more
       information.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Cleaning up</title>
   <variablelist>
    <varlistentry>
     <term><option>clean</option></term>
     <listitem>
      <para>Remove all profiled sources and temporary files</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>clean-images</option></term>
     <listitem>
      <para>Remove all generated images</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>clean-package</option></term>
     <listitem>
      <para>
       Remove all generated package data for the given DC-file. Generated
       images and profiled sources will <emphasis>not</emphasis> be deleted.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>clean-results</option></term>
     <listitem>
      <para>
       Remove all generated books, archives, and log files for the given
       DC-file. Generated images and profiled sources will
       <emphasis>not</emphasis> be deleted.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>clean-all</option>, <option>real-clean</option></term>
     <listitem>
      <para>Remove everything generated by DAPS.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Packaging</title>
   <variablelist>
    <varlistentry>
     <term><option>package-html</option></term>
     <listitem>
      <para>
       Provide an HTML tarball (chunked HTML or single HTML), desktop,
       document, and/or page files (for KDE and GNOME).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>package-pdf</option></term>
     <listitem>
      <para>
       Provide a PDF, desktop, document, and/or page files (for KDE and GNOME)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>package-src</option></term>
     <listitem>
      <para>Provide a TAR archive with profiled XML sources or AsciiDoc sources
      and graphics files.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Deploying</title>
   <variablelist>
    <varlistentry>
     <term><option>locdrop</option></term>
     <listitem>
      <para>Provide everything that is needed to translate the sources.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>unpack-locdrop</option></term>
     <listitem>
      <para>
       Unpack a localization drop packages source.
      </para>
      <para>
       Not supported for AsciiDoc projects.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Other Commands</title>
   <variablelist>
    <varlistentry>
     <term><option>getimages</option></term>
     <listitem>
      <para>List or display images from a profiled DocBook XML file.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>linkcheck</option></term>
     <listitem>
      <para>Checks URLs within <sgmltag class="starttag">ulink</sgmltag> and <sgmltag class="starttag">link</sgmltag> tags.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>optipng</option></term>
     <listitem>
      <para>Optimize (size) source PNGs.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>profile</option></term>
     <listitem>
      <para>Profile XML sources.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>spellcheck</option></term>
     <listitem>
      <para>
       Spellchecks the file specified with <option>--file</option> or the
       document specified by <option>--rootid</option>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>stylecheck</option></term>
     <listitem>
      <para>Performs a style check on the given DC-file or rootid.</para>
      <para>
       Not supported for AsciiDoc projects.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>validate</option></term>
     <listitem>
      <para>
       Validate profiled XML sources. Automatically profiles the XML sources if
       needed.
      </para>
      <para>
       Not supported for AsciiDoc projects.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>xmlformat</option></term>
     <listitem>
      <para>
       Prettify the XML source files using <option>daps-xmlformat</option>.
      </para>
      <para>
       Not supported for AsciiDoc projects.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>File and Directory Names</title>
   <variablelist>
    <varlistentry>
     <term><option><replaceable>target</replaceable>-name</option></term>
     <listitem>
      <para>Print resulting file name for
      <replaceable>target</replaceable>. <replaceable>target</replaceable> may
      be one of pdf, epub, pdf, txt
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option><replaceable>target</replaceable>-dir-name</option></term>
     <listitem>
      <para>
       Print resulting directory name for
       <replaceable>target</replaceable>. <replaceable>target</replaceable> may
       be html, man or webhelp
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Debugging</title>
   <variablelist>
    <varlistentry>
     <term><option>bigfile</option></term>
     <listitem>
      <para>
       Creates a single <quote>big</quote> XML file by resolving
       xi:includes. Useful for detecting validation errors that cannot be
       found otherwise.
      </para>
      <para>
       Not supported for AsciiDoc projects.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>dapsenv</option></term>
     <listitem>
      <para>
       Print a list of the most important make variables and their value
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>images</option></term>
     <listitem>
      <para>Generates all images for the given DC-file or rootid</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>showvariable</option></term>
     <listitem>
      <para>
       Print value of a given make variable: daps showvariable
       VARIABLE=<replaceable>VARIABLE_NAME</replaceable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
 </refsect1>

 <refsect1 id="daps.examples">
  <title>Examples</title>
  <variablelist>
   <varlistentry>
    <term>Generate a single HTML page:</term>
    <listitem>
     <para>
      <command>&daps; <option>-d DC-example html --single</option></command>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Generate ePUB using custom stylesheets:</term>
    <listitem>
     <para>
      <command>&daps; <option>-d DC-example --styleroot
      /usr/share/xml/docbook/stylesheets/daps2013 epub</option></command>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Generate PDF for the print shop using the XEP formatter</term>
    <listitem>
     <para>
      <command>&daps; <option>-d DC-example pdf --formmatter=xep --grayscale --cropmarks</option></command>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Check links and show the result in a browser</term>
    <listitem>
     <para><command>&daps; <option>-d DC-example linkcheck --show</option></command></para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 id="daps.files">
  <title>Files</title>
  <variablelist>
   <varlistentry>
    <term>&dapsconf-sys;</term>
    <listitem>
     <para>
      The system wide configuration file. See the file's inline documentation
      for detailed information.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>&dapsconf-user;</filename></term>
    <listitem>
     <para>
      The per user configuration file. See the inline documentation of
      &dapsconf-sys; for detailed information.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 id="daps.moreinfo">
   <title>See Also</title>
   <variablelist>
     <varlistentry>
       <term>&dapsurl;</term>
       <listitem>
         <para>DAPS project homepage</para>
       </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <ulink url="https://opensuse.github.io/daps/doc/art.daps.quick.html">DAPS
       Quick Start</ulink>
      </term>
      <listitem>
       <para>
        Contains an overview of basic concepts and how to create your
        documents.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <ulink url="https://opensuse.github.io/daps/doc/book.daps.user.html">DAPS
       User Guide</ulink>
      </term>
      <listitem>
       <para>
        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).
       </para>
       </listitem>
     </varlistentry>
     <!--<varlistentry>
       <term><ulink url="http://daps.sf.net/docs/daps-adminguide.html"
       >DAPS Administration Guide</ulink></term>
       <listitem>
         <para>Intended for developers who wants to add their own
           stylesheets.</para>
       </listitem>
     </varlistentry>-->
   </variablelist>
 </refsect1>

</refentry>