<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<chapter id="cha.daps.user.features">
 <title>Conceptual Overview</title>
 <abstract>
  <para>
   This chapter covers the following topics:
   <itemizedlist>
    <listitem>
     <para>
      Features unique to &dapsacr; such as support for multiple output formats and automatic document profiling
     </para>
    </listitem>
    <listitem>
     <para>
      Configuring &dapsacr;
     </para>
    </listitem>
    <listitem>
     <para>
      Basics of working with &dapsacr;.
     </para>
    </listitem>
    <listitem>
     <para>
      Basic syntax of <command>daps</command> commands
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </abstract>
 <sect1 id="sec.daps.user.dbversions">
  <title>Supported DocBook Versions</title>

  <para>
   &daps-db-versions;
  </para>
 </sect1>
 <sect1 id="sec.daps.user.features">
  <title>Key Features</title>

  <para>
   &dapsacr; supports technical writers in the editing, translation and
   publishing process of DocBook XML files (in the following, simply
   called as XML files):
  </para>

  <variablelist>
   <varlistentry>
    <term>Output Formats (Single-source Publishing)</term>
    <listitem>
     <para>
      &dapsacr; lets you publish your XML sources in several different
      output formats, for example: HTML, HTML-single, PDF, &epub;,
      text, and man pages. For details, refer to
      <xref linkend="cha.daps.user.output"/>.
      </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Custom Layouts</term>
    <listitem>
     <para>
      By default, &dapsacr; uses the DocBook stylesheets to generate the
      output formats. But &dapsacr; also supports custom layouts for your
      documentation projects (or for individual books within your set).
      Thus your XML documents can be published in different layouts without
      having to change the sources or the configuration.
<!--You do not need to define custom stylesheets for <emphasis>all</emphasis>
     output formats&mdash;in case a custom layout cannot be found, &dapsacr;
     will automatically fall back to the DocBook stylesheets.-->
     </para>
     <para>
      Apart from that, &dapsacr; allows you to change individual layout
      parameters by passing string parameters to <command>xsltproc</command>
      for HTML or PDF builds &mdash;without even touching the stylesheets.
      For details about custom layouts, refer to <xref linkend="cha.daps.user.layout"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Editor Macros</term>
    <listitem>
     <para>
      For Emacs, &dapsacr; includes a set of macros for easy insertion of
      complex DocBook elements like <sgmltag>variablelist</sgmltag>,
      <sgmltag>figure</sgmltag>, <sgmltag>table</sgmltag> or
      <sgmltag>indexterm</sgmltag>. Instead of inserting the child elements
      one-by-one, you will get a <quote>skeleton</quote> that includes all
      required child elements and is ready to be filled with contents. For
      details, refer to <xref linkend="sec.daps.user.editors.emacs.macros"/>.
     </para>
     <para><remark>taroth 2015-04-21: check with tbazant on his hack project
      about vi DB support</remark></para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Validating</term>
    <listitem>
     <para>
      Validating XML files within in a book or set exceeds validation of the
      current XML file, as links (<sgmltag>xref</sgmltag> elements) or
      XIncludes need to be resolved, too. With &dapsacr;, you can check
      validity of all files that belong to a documentation project with a
      single command. For details, refer to
      <xref linkend="sec.daps.user.output.validate"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Spell Check</term>
    <listitem>
     <para>
      &dapsacr; 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 <xref linkend="sec.daps.user.edit.spell"/> and
      <xref linkend="sec.daps.user.editors.jedit.spellcheck"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Link Checker</term>
    <listitem>
     <para>
      To make sure that all external links in your XML sources are still
      available (and do not give a <literal>404</literal> error or similar),
      &dapsacr; also includes a link checker (based on
      <literal>checkbot</literal>). Use it to create a report of all links
      that caused some kind of warning or error. For details, refer to
      <xref linkend="sec.daps.user.edit.chklink"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Image Handling</term>
    <listitem>
     <para>
      &dapsacr; provides sophisticated image handling support. For example,
      it automatically transforms images referenced in your XML files into different
      formats, list all source images referenced in your XML files, list any
      missing images or check if all image names are unique. You can also forward those lists to
      your preferred image viewer to conveniently browse through the images. 
      For details, refer to
      <xref linkend="cha.daps.user.img"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Profiling (Conditional Text)</term>
    <listitem>
     <para>
      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 <literal>profiling</literal>, 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. &dapsacr; supports profiling. Use the
      <literal>PROF*</literal> keys defined in &dapsconf-sys; to define
      which information should be included in the output. For details, refer
      to <xref linkend="cha.daps.user.modular"/>.
     </para>
    </listitem>
   </varlistentry>
<!-- <varlistentry>
    <term>Dynamic Product Names and Numbers</term>
    <listitem>
     <para>
      &daps-product-entities;
      <remark>taroth 2012-05-31: check with fs/toms: probably bound to change
      again</remark>
      For details, refer to <xref linkend="cha.daps.user.edit"/>.
     </para>
    </listitem>
   </varlistentry>-->
   <varlistentry>
    <term>Review and Translation Processes</term>
    <listitem>
     <para>
      &dapsacr; offers several features to simplify review and
      translation processes. By adding a single parameter, you can
      generate output that contains remarks for writers, reviewers,
      and translators. By default, remarks are suppressed in the final output
      version. You can also generate preview versions of your
      documentation with a <literal>DRAFT</literal> watermark appearing on
      the output. <!--taroth 2015-04-15: commenting for now, can hopefully be re-enabled after
       the dm relaunch: If you use &dm; in addition to &dapsacr;, you can
      annotate your XML files with meta information (like
      workflow status). &dapsacr; offers an option to also display this
      meta-information in the generated output.--> For handing over your files
      to review or translation, &dapsacr; can create TAR archives of the XML
      sources and graphics.
<!--Alternatively, transform all files
     included in your <sgmltag>book</sgmltag> or <sgmltag>set</sgmltag> into an
     XML bigfile. If you have a huge documentation project of which only individual
     books or files are to be translated, you can mark them for translation
     with &dm;. The command <command>daps locdrop</command> will automatically
     sort and pack those files into s separate tarball.-->
      For details, refer to <xref linkend="cha.daps.user.review"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Packaging and Deployment</term>
    <listitem>
     <para>
      For deploying the documentation as RPM packages and integrating it
      into KDE and GNOME desktop environments, &dapsacr; 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
      <command>daps package-*</command> commands. For details refer to
      <xref linkend="cha.daps.user.deploy"/>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>
 <sect1 id="sec.daps.user.config">
  <title>&dapsacr; Configuration</title>
 &daps-config;
 </sect1>
 <sect1 id="sec.daps.user.basics">
  <title>Defining Documentation Projects</title>

  <para>
   The easiest way to set up a new documentation project from scratch is to
   use the &dapsacr; initialization script <command>daps-init</command>. For
   instructions how to do so, refer to <xref linkend="pro.daps.init"/>. The
   script automatically creates the
   <xref linkend="sec.daps.user.basics.files" xrefstyle="select:title"/> and
   <xref linkend="sec.daps.user.basics.dirstruct" xrefstyle="select:title"/>
   that you need to get started with &dapsacr;.
  </para>

  <para>
   To migrate existing DocBook projects so that you can manage and publish
   them with &dapsacr;, follow the step-by-step instructions in
   <xref linkend="app.daps.user.migrate"/>.
  </para>
 </sect1>
 
 <sect1 id="sec.daps.user.basics.dirstruct">
  <title>Directory Structure</title>
  
  <!--taroth 2012-04-26: cave, same contents in DAPS Quick
   (art_daps_quick.xml, see id=sec.daps.quick.basics.dirstruct)-->
  
  <!--taroth 2012-04-26: impossible to outsource to phrases-decl.ent and
   include it multiple times (callout IDs!)-->
  
  <para>
   For &dapsacr; to work out of the box, your XML files and images must be
   organized in a specific structure within your documentation directory.
   <xref linkend="ex.daps.dir.doc" xrefstyle="select:label"/> shows the
   required structure including the key files for a &dapsacr; documentation
   project. You can also create multiple documentation directories for
   individual documentation projects, but they all need the substructure
   outlined below.
  </para>
  
  <sect2 id="sec.daps.user.oview.dir.src">
   <title>Source Files</title>
   <example id="ex.daps.dir.doc">
    <title>Required Directory Structure</title>
    <screen><replaceable>YOUR_DOC_DIR/</replaceable> <co id="co.docdir.base"/>
     |--&dc;-* <co id="co.docdir.dc"/>
     |--images/
     |   |--src/<co id="co.docdir.img.src"/>
     |   |  |--dia/
     |   |  |--eps/
     |   |  |--fig/
     |   |  |--jpg
     |   |  |--pdf/
     |   |  |--png/
     |   |  |--svg/
     |--xml/<co id="co.docdir.xml"/>
     |   |--MAIN*.xml<co id="co.docdir.main"/>
         |--*.xml</screen>
   </example>
   
   <calloutlist>
    <callout arearefs="co.docdir.base">
     <para>
      <quote>Working directory</quote> for the respective documentation
      project (in the following also called <literal>project directory</literal> 
      or <literal>documentation directory</literal>).
     </para>
    </callout>
    <callout arearefs="co.docdir.dc">
     <para>
      On the topmost level of your project directory, store the &dclong;
      (&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 <xref linkend="sec.daps.user.basics.files"/>.
     </para>
    </callout>
    <callout arearefs="co.docdir.img.src">
     <para>
      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 <xref linkend="sec.daps.user.imgs.refer"/>.
     </para>
    </callout>
    <callout arearefs="co.docdir.xml">
     <para>
      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 <filename>entity-decl.ent</filename>), put the
      entity declaration files here, too.
     </para>
    </callout>
    <callout arearefs="co.docdir.main">
     <para>
       The &main; file of the documentation project.  It contains the
       <quote>starting point</quote> (the highest-level object) of your
       documentation project and includes
       <quote>references</quote> to other books, chapters, appendixes, etc. 
       For more information, refer to
      <xref linkend="sec.daps.user.basics.files"/>.
     </para>
    </callout>
   </calloutlist>
   &daps-note-subdirs;
  </sect2>
  
  <sect2 id="sec.daps.user.oview.dir.build">
   <title>The <filename>build</filename> Subdirectory</title>
   <para>
    To strictly discriminate between all source content added by users and
    the content generated by &dapsacr;, &dapsacr; uses a
    <filename>build</filename> directory. When generating output from your
    documentation project for the first time, &dapsacr; adds a
    <filename>build</filename> directory to your documentation directory. It
    is located parallel to the <filename>xml</filename> and
    <filename>images</filename> subdirectories. (If desired, the name and
    path of the <filename>build</filename> directory can be changed with the
    parameter <parameter>BUILD_DIR</parameter> in &dapsconf-sys; or
    &dapsconf-user;.)
   </para>
   <para>
    The <filename>build</filename> directory is structured as follows:
   </para>
   <example id="ex.daps.user.build">
    <title>Build Directory</title>
    <screen><replaceable>YOUR_DOC_DIR</replaceable> <co id="co.docdir"/>
     <emphasis role="strong">|--build/</emphasis> <co id="co.builddir"/>
     |--<replaceable>NAME_OF_&dc;1</replaceable>/ <co id="co.builddir.dc"/>
     |--<replaceable>NAME_OF_&dc;2</replaceable>/ <xref linkend="co.builddir.dc"/>
     |--.images/ <co id="co.builddir.img"/>
     |--.profiled/ <co id="co.builddir.profiled"/>
     |--.tmp/ <co id="co.builddir.tmp"/></screen>
   </example>
   <calloutlist>
    <callout arearefs="co.docdir">
     <para>
      <quote>Working directory</quote> for the respective documentation
      project.
     </para>
    </callout>
    <callout arearefs="co.builddir">
     <para>
      Directory that holds all contents build by &dapsacr;.
     </para>
    </callout>
    <callout arearefs="co.builddir.dc">
     <para> For each of your documentation deliverables, &dapsacr; creates a
      subdirectory. It is named after the respective &dc; from which you
      build the book, article or set. For example, the output for
        <filename>&dc;-<replaceable>NAME</replaceable></filename> is written
      to
        <filename><replaceable>YOUR_DOC_DIR</replaceable>/build/<replaceable>NAME</replaceable></filename>.
      All formats that have been generated from the &dc; (PDF, HTML, TXT,
      &epub; etc.) can be found there. A <filename>log</filename>
      subdirectory stores log files for each output format that has been
      generated by &dapsacr;. </para>
    </callout>
    <callout arearefs="co.builddir.img">
     <para>
      Directory holding the images created by &dapsacr;.
     </para>
    </callout>
    <callout arearefs="co.builddir.profiled">
     <para>
      Directory holding the profiled XML sources created by &dapsacr;.
     </para>
    </callout>
    <callout arearefs="co.builddir.tmp">
     <para>
      Directory holding temporary files created by &dapsacr; (for example,
      the FO files).
     </para>
    </callout>
   </calloutlist>
  </sect2>
 </sect1>

  <sect1 id="sec.daps.user.basics.files">
   <title>Key Files</title> 
   &daps-key-files; <para>
    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:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      Small documentation projects, consisting of
      <xref linkend="sec.daps.user.basics.single" xrefstyle="select:title"/>
     </para>
    </listitem>
    <listitem>
     <para>
      Larger documentation projects, consisting of
      <xref linkend="sec.daps.user.basics.multiple" xrefstyle="select:title"/>
     </para>
    </listitem>
   </itemizedlist>

<note>
   <title>Differences Between DocBook 4 and  DocBook 5</title>
   <para>The examples below differ slightly with regards to the respective
    DocBook version. One of the main differences is the header of the XML files.
    Apart from that, the <sgmltag>articleinfo</sgmltag> and
     <sgmltag>bookinfo</sgmltag> elements no longer exist in DocBook 5. They
    have been replaced by the generic <sgmltag>info</sgmltag> element.
   </para>
</note>

  <sect2 id="sec.daps.user.basics.single">
   <title>Single Deliverables (Article or Book)</title>
   <para>
   The simplest case of a documentation project is probably a white paper or
   article. Typically, its content can be stored in a single XML file with
   <sgmltag>article</sgmltag> 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 (<sgmltag>article</sgmltag>). 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 <sgmltag>section</sgmltag> elements or
   <sgmltag>sect1</sgmltag>, <sgmltag>sect2</sgmltag> etc.).
   </para>
   <tip>
    <title>Creating an Example Document</title>
    <para> The command <command>daps-init</command> allows you to automatically
     set up an example article or book, together with a &dc; file, as
     described in <xref linkend="pro.daps.init"/>. Use the 
     <option>--docbook4</option> or the <option>--docbook5</option>
     option to define the Docbook version to use. The examples below are based
     on the output of <command>daps-init</command>, but vary deliberately in
     some details to show key parameters that you might want to add or change.
    </para>
   </tip>
   <para>
    Find simple examples for DocBook 4 and DocBook 5 in
    <xref linkend="ex.daps.main.art.db4" xrefstyle="select:label"/> and <xref
     linkend="ex.daps.main.art.db5" xrefstyle="select:label"/>, respectively.
   </para>
   <example id="ex.daps.main.art.db4">
    <title>&main; file of an Article (DocBook 4.x)</title>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
[...]

<emphasis role="strong">&lt;article lang="en" id="art.template"&gt;</emphasis>
 &lt;title&gt;Article Template&lt;/title&gt;
 &lt;subtitle&gt;generated by DAPS&lt;/subtitle&gt;
 &lt;articleinfo&gt;
  &lt;releaseinfo&gt;Version 0.1&lt;/releaseinfo&gt;
  &lt;releaseinfo&gt;Revision: 0&lt;/releaseinfo&gt;
  &lt;releaseinfo&gt;
   Build Date: &lt;?dbtimestamp format="B d, Y"?&gt;
  &lt;/releaseinfo&gt;
  &lt;legalnotice&gt;
   &lt;para&gt;
    &lt;ulink url="http://www.gnu.org/licenses/fdl-1.3-standalone.html"&gt;
    GNU Free Documentation License&lt;/ulink&gt;
   &lt;/para&gt;
  &lt;/legalnotice&gt;
 &lt;/articleinfo&gt;
 &lt;abstract&gt;
  &lt;para&gt;
   You may use this file as a template. For a complete DocBook reference
   see &lt;citetitle&gt;&tdg;&lt;/citetitle&gt;, available at
   &lt;ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/&gt;.
  &lt;/para&gt;
 &lt;/abstract&gt;
 &lt;sect1 id="sec.template.examples"&gt;
  &lt;title&gt;Examples: The most commonly used DocBook XML constructs&lt;/title&gt;
  &lt;para&gt;
   I am a paragraph in a section 1.
  &lt;/para&gt;
  &lt;sect2 id="sec.template.examples.lists"&gt;
   &lt;title&gt;Lists&lt;/title&gt;
   &lt;para&gt;
    This section 2 showcases 3 types of lists.
   &lt;/para&gt;
   [...]
  &lt;/sect2&gt;
 &lt;/sect1&gt;
<emphasis role="strong">&lt;/article&gt;</emphasis></screen>
   </example>

  <example id="ex.daps.main.art.db5">
    <title>&main; file of an Article (DocBook 5.x)</title>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
[...]

 <emphasis>&lt;article xml:id="art.template" xml:lang="en"
  xmlns="http://docbook.org/ns/docbook" 
  xmlns:xlink="http://www.w3.org/1999/xlink"&gt;</emphasis>

&lt;info&gt;
 &lt;title&gt;Article Template&lt;/title&gt;
 &lt;subtitle&gt;generated by DAPS&lt;/subtitle&gt;
 &lt;info&gt;
  &lt;releaseinfo&gt;Version 0.1&lt;/releaseinfo&gt;
  &lt;releaseinfo&gt;Revision: 0&lt;/releaseinfo&gt;
  &lt;releaseinfo&gt;
   Build Date: &lt;?dbtimestamp format="B d, Y"?&gt;
  &lt;/releaseinfo&gt;
  &lt;legalnotice&gt;
   &lt;para&gt;
    &lt;link xlink:href="http://www.gnu.org/licenses/fdl-1.3-standalone.html"&gt;
    GNU Free Documentation License&lt;/ulink&gt;
   &lt;/para&gt;
  &lt;/legalnotice&gt;
 &lt;/info&gt;
 &lt;abstract&gt;
  &lt;para&gt;
   You may use this file as a template. For a complete DocBook reference
   see &lt;citetitle&gt;&tdg;&lt;/citetitle&gt;, available at
   &lt;link xlink:href="http://www.docbook.org/tdg/en/html/docbook.html"/&gt;.
  &lt;/para&gt;
 &lt;/abstract&gt;
 &lt;sect1 xml:id="sec.template.examples"&gt;
  &lt;title&gt;Examples: The most commonly used DocBook XML constructs&lt;/title&gt;
  &lt;para&gt;
   I am a paragraph in a section 1.
  &lt;/para&gt;
  &lt;sect2 xml:id="sec.template.examples.lists"&gt;
   &lt;title&gt;Lists&lt;/title&gt;
   &lt;para&gt;
    This section 2 showcases 3 types of lists.
   &lt;/para&gt;
   [...]
  &lt;/sect2&gt;
 &lt;/sect1&gt;
<emphasis role="strong">&lt;/article&gt;</emphasis></screen>
   </example>
   
   
   <para>
    Let us assume, the XML file shown in
    <xref linkend="ex.daps.main.art.db4"
     xrefstyle="select:label"/> or <xref linkend="ex.daps.main.art.db5"
      xrefstyle="select:label"/> is 
    named <filename>MAIN-DAPS-example-article.xml</filename> 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 <parameter>MAIN</parameter>, pointing to the XML file that
    you want to process. Therefore, a very basic &dc; file for the article
    in <xref linkend="ex.daps.main.art.db4" xrefstyle="select:label"/> or <xref
     linkend="ex.daps.main.art.db5" xrefstyle="select:label"/> could look as follows:
   </para>
   <example id="ex.daps.user.dc.art.simple">
    <title>Basic &dc; File for an Article</title>
<screen>## Doc config file for the DAPS example document
## See /etc/daps/config for documentation of the settings below
##

## Mandatory Parameter
<emphasis role="strong">MAIN="MAIN-DAPS-example-article.xml" </emphasis></screen>
    &daps-co-main;
   </example>
   <para>
    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 <option>--main</option> 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
    <xref linkend="cha.daps.user.output"/>.
   </para>
<!-- <screen>daps -m xml/MAIN-daps-example.xml html</screen>-->
   <para>
    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:
   </para>
   <example id="ex.daps.main.book.db4">
    <title>&main; file of a Book (DocBook 4.x)</title>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
[...]

<emphasis role="strong">&lt;book id="book.template" lang="en"&gt;</emphasis>
 &lt;bookinfo&gt;
  &lt;title&gt;Book Template&lt;/title&gt;
  &lt;subtitle&gt;generated by daps&lt;/subtitle&gt;
  &lt;productname&gt;Book Template&lt;/productname&gt;
   &lt;legalnotice&gt;
   &lt;para&gt;
    &lt;ulink url="http://www.gnu.org/licenses/fdl-1.3-standalone.html"&gt;
    GNU Free Documentation License&lt;/ulink&gt;
   &lt;/para&gt;
  &lt;/legalnotice&gt;
 &lt;/bookinfo&gt;
 &lt;chapter id="cha.template.examples"&gt;
  &lt;title&gt;Examples: the most commonly used DocBook XML constructs&lt;/title&gt;
  &lt;abstract&gt;
   &lt;para&gt;
    You may use this file as a template. For a complete reference on DocBook
    see &lt;citetitle&gt;&amp;tdg;&lt;/citetitle&gt;, available at
    &lt;ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/&gt;.
   &lt;/para&gt;
  &lt;/abstract&gt;
  &lt;para&gt;
   I am a paragraph in a chapter.
  &lt;/para&gt;
  &lt;sect1 id="sec.template.examples.lists"&gt;
   &lt;title&gt;Lists&lt;/title&gt;
   &lt;para&gt;
    This is a section 1.
   &lt;/para&gt;
  &lt;/sect1&gt;
 &lt;/chapter&gt;
<emphasis role="strong">&lt;/book&gt;</emphasis>
</screen>
   </example>

 <example id="ex.daps.main.book.db5">
    <title>&main; file of a Book (DocBook 5.x)</title>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
[...]

<emphasis>&lt;book xml:id="book.template" xml:lang="en"
      xmlns="http://docbook.org/ns/docbook" 
      xmlns:xlink="http://www.w3.org/1999/xlink"&gt;</emphasis>
 &lt;info&gt;
  &lt;title&gt;Book Template&lt;/title&gt;
  &lt;subtitle&gt;generated by daps&lt;/subtitle&gt;
  &lt;productname&gt;Book Template&lt;/productname&gt;
   &lt;legalnotice&gt;
   &lt;para&gt;
    &lt;link xlink:href="http://www.gnu.org/licenses/fdl-1.3-standalone.html"&gt;
    GNU Free Documentation License&lt;/ulink&gt;
   &lt;/para&gt;
  &lt;/legalnotice&gt;
 &lt;/info&gt;
 &lt;chapter xml:id="cha.template.examples"&gt;
  &lt;title&gt;Examples: the most commonly used DocBook XML constructs&lt;/title&gt;
  &lt;abstract&gt;
   &lt;para&gt;
    You may use this file as a template. For a complete reference on DocBook
    see &lt;citetitle&gt;&amp;tdg;&lt;/citetitle&gt;, available at
    &lt;ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/&gt;.
   &lt;/para&gt;
  &lt;/abstract&gt;
  &lt;para&gt;
   I am a paragraph in a chapter.
  &lt;/para&gt;
  &lt;sect1 xml:id="sec.template.examples.lists"&gt;
   &lt;title&gt;Lists&lt;/title&gt;
   &lt;para&gt;
    This is a section 1.
   &lt;/para&gt;
  &lt;/sect1&gt;
 &lt;/chapter&gt;
<emphasis role="strong">&lt;/book&gt;</emphasis>
</screen>
   </example>

   <para>
    In the above example, the book's contents are also contained in a single
    XML file, however, this time with <sgmltag>book</sgmltag> as the root
    element. In contrast to an article, books can contain more structural
    levels: they are usually divided into <sgmltag>chapter</sgmltag>
    elements (that may contain sections and subsections) as outlined in
    <xref linkend="ex.daps.main.book.db4" xrefstyle="select:label"/> or
    <xref linkend="ex.daps.main.book.db5" xrefstyle="select:label"/> . In
    addition to chapters, books may also contain other structural elements
    such as <sgmltag>preface</sgmltag>, <sgmltag>glossary</sgmltag>, and
    <sgmltag>appendix</sgmltag>. A further additional structural level is
    called <sgmltag>part</sgmltag>. For a complete reference, see
    <citetitle>&tdg;</citetitle>, available at
    <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
   </para>
   <para>
    Let us assume the XML file shown in 
    <xref linkend="ex.daps.main.book.db4" xrefstyle="select:label"/> or
    <xref linkend="ex.daps.main.book.db5" xrefstyle="select:label"/>
    is named <filename>MAIN-DAPS-example-book.xml</filename> 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.
   </para>
   <example id="ex.daps.dc.book">
    <title>&dc; File For a Book with Custom Layout</title>
<screen>## 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" <co id="co.daps.dc.book.main"/>

## Optional Parameters

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/custom/xslt" <co id="co.daps.dc.book.styleroot"/>
</screen>
   </example>
   <calloutlist>
    <callout arearefs="co.daps.dc.book.main"> &daps-co-main; </callout>
    <callout arearefs="co.daps.dc.book.styleroot"> &daps-co-styleroot;
     <!--The custom stylesheet directory must have the same structure as the
     original DocBook stylesheet root directory, but it but does not need to
     contain stylesheets for all output formats. If &dapsacr; cannot find a
     custom stylesheet for a specific output format, it uses the
     default DocBook layout instead.-->
    </callout>
   </calloutlist>
  </sect2>

  <sect2 id="sec.daps.user.basics.multiple">
   <title>Multiple Deliverables: Articles or Books in a Set</title>
   <para>
    If your documentation project consists of multiple books in a
    <sgmltag>set</sgmltag>, the &main; file is the one that contains the
    <sgmltag>set</sgmltag> 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 (<code>book*.xml</code>). Those 
    are then assembled in the &main; file using
    <literal>XIncludes</literal>. Note that this is not specific to
    sets&mdash;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
    <xref linkend="sec.daps.user.modular.xi"/> and
    <ulink
    url="http://www.docbook.org/tdg51/en/html/ch02.html"><citetitle>Physical
    Divisions: Breaking a Document into Separate Files</citetitle></ulink>.
   </para>
  
   <example id="ex.daps.main.set">
    <title>&main; file of a Set (DocBook 4.x)</title>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
[...]

<emphasis role="strong">&lt;set lang="en"&gt;</emphasis>
 &lt;title&gt;&dapsacr; Documentation&lt;/title&gt;
 &lt;xi:include href="book_daps_user.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/&gt;
 &lt;xi:include href="book_daps_quickstarts.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/&gt;
 &lt;!&#45;&#45;&lt;xi:include href="book_daps_developer.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"/&gt;&#45;&#45;&gt;
<emphasis role="strong">&lt;/set&gt;</emphasis></screen>
   </example>
   
    <para>
    For a documentation <sgmltag>set</sgmltag> (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 <parameter>ROOTID</parameter> 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.
   </para>
   <para>
    The following two &dc; files are those of the &dapsquick; and the
    &dapsuser;&mdash; both guides belong to the same documentation set, but
    use different layouts.
   </para>
   
   <example id="ex.daps.dc.quick">
    <title>&dc; File For a Book in a Set</title>
<screen>## Doc config file for &dapsquick;
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" <co id="co.daps.dc.quick.main"/>

## 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 &lt;book&gt;/&lt;article&gt; 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" <co id="co.daps.dc.quick.rootid"/>

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/flyer" <co id="co.daps.dc.quick.styleroot"/>
#FALLBACK_STYLEROOT="" <co id="co.daps.dc.quick.fbstyleroot"/></screen>
    <calloutlist>
     <callout arearefs="co.daps.dc.quick.main"> &daps-co-main; </callout>
     <callout arearefs="co.daps.dc.quick.rootid"> &daps-co-rootid; <para>
       In this example, <literal>art.daps.quick</literal> is the root ID of
       the &dapsquick;, contained in <filename>MAIN.DAPS.xml</filename>.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.quick.styleroot"> &daps-co-styleroot;
       <para>
       In this example, the parameter specifies the path to a directory with
       &suse;-specific stylesheets for the flyer layout that is used by the
       &dapsquick;.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.quick.fbstyleroot"> &daps-co-fbstyleroot;
       <para>
       In this example, no fallback is specified and the parameter is
       disabled.
      </para>
     </callout>
    </calloutlist>
   </example>
   <example id="ex.daps.dc.user">
    <title>&dc; File For Another Book in the Same Set</title>
<screen>## Doc config file for &dapsuser;
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" <co id="co.daps.dc.user.main"/>

## 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 &lt;book&gt;/&lt;article&gt; 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" <co id="co.daps.dc.user.rootid"/>

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/" <co id="co.daps.dc.user.styleroot"/>
#FALLBACK_STYLEROOT="" <co id="co.daps.dc.user.fbstyleroot"/>

## Formatter
# Specify which PDF formatter to use. Currently only fop or xep are supported

FORMATTER="xep" <co id="co.daps.dc.user.formatter"/>

##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" <co id="co.daps.dc.user.draft"/>
</screen>
    <calloutlist>
     <callout arearefs="co.daps.dc.user.main"> &daps-co-main; </callout>
     <callout arearefs="co.daps.dc.user.rootid"> &daps-co-rootid; <para>
       In this example, <literal>book.daps.user</literal> is the root ID of
       the &dapsuser;, contained in <filename>MAIN.DAPS.xml</filename>.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.user.styleroot"> &daps-co-styleroot;
       <para>
       In this example, the parameter specifies the path to a directory with
       &suse;-specific stylesheets that is used by the &dapsuser;.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.user.fbstyleroot"> &daps-co-fbstyleroot;
       <para>
       In this example, no fallback is specified and the parameter is
       disabled.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.user.formatter"> &daps-co-formatter;
       <para>
       For supported formatters, refer to
       <xref linkend="sec.daps.quick.req.sw"/>. In this example, XEP is
       specified as PDF formatter.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.user.draft"> &daps-co-draft; </callout>
    </calloutlist>
   </example>
   <para>
    If your documentation project contains cross-references between the
    individual books in a set, it is useful to define an additional &dc;
    file &mdash;<emphasis>without</emphasis> the
    <parameter>ROOTID</parameter> 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 <xref linkend="ex.daps.dc.set"/>.
   </para>
   <example id="ex.daps.dc.set">
    <title>&dc; File for a Set</title>
<screen>## Doc config file for the &dapsacr; Documentation Set
## See /etc/daps/config for documentation of the settings below

## Mandatory Parameter
MAIN="MAIN.DAPS.xml" <co id="co.daps.dc.set.main"/>

## 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 &lt;book&gt;/&lt;article&gt; 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="" <co id="co.daps.dc.set.rootid"/>

## Custom Stylesheets
## (if not defined the DocBook stylesheets will be used)

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse/xslt/" <co id="co.daps.dc.set.styleroot"/>
#FALLBACK_STYLEROOT="" <co id="co.daps.dc.set.fbstyleroot"/>

## enable sourcing
export DOCCONF=$BASH_SOURCE <co id="co.daps.dc.set.source"/></screen>
    <calloutlist>
     <callout arearefs="co.daps.dc.set.main"> &daps-co-main; </callout>
     <callout arearefs="co.daps.dc.set.rootid"> &daps-co-rootid; <para>
       In this example, no <parameter>ROOTID</parameter> is set. This allows
       to build the complete documentation set, with the output containing
       all hyperlinks between the individual books.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.set.styleroot"> &daps-co-styleroot;
       <para>
       In this example, the parameter specifies the path to a directory with
       &suse;-specific stylesheets.
      </para>
     </callout>
     <callout arearefs="co.daps.dc.set.fbstyleroot"> &daps-co-fbstyleroot;
       <para>
       In this example, no fallback is specified and the parameter is
       disabled.
      </para>
     </callout>
      <callout arearefs="co.daps.dc.set.source"> &daps-co-source; </callout>
    </calloutlist>
   </example>
  </sect2>
 </sect1>
<!--taroth 2012-05-08: updated until here, todo: add directory stuff created by
     DAPS-->
 
 <sect1 id="sec.daps.user.syntax">
  <title>Basic &dapsacr; Syntax</title>

  <para>
   Before moving forward, let's get familiar with the basic syntax of the
   <command>daps</command> command:
  </para>

  &daps-cmd-basic-syntax;

  <para>
   <xref linkend="ex.daps.user.syntax"/> shows an example command that
   generates HTML output. Global options are used to specify the level of
   verbosity, and the &dclong; file for creating the output.
  </para>

<!--taroth 2013-01-15: cave, same contents in DAPS Quick
  (art_daps_quick.xml, see id=sec.daps.quick.syntax)-->

<!--taroth 2013-01-15: impossible to source out to phrases-decl.ent and
  include it multiple times (callout IDs!)-->

  <example id="ex.daps.user.syntax">
   <title>&dapsacr; Syntax</title>
<screen>&prompt.user;&dapscmd;<co id="co.daps.user.syntax.main"/> --debug<co id="co.daps.user.syntax.debug"/> -d<co id="co.daps.user.syntax.dc"/> &dc;-daps-example html<co id="co.daps.user.syntax.output"/> --static<co id="co.daps.user.syntax.static"/></screen>
   <calloutlist>
    <callout arearefs="co.daps.user.syntax.main">
     <para>
      Main command: <command>daps</command>
     </para>
    </callout>
    <callout arearefs="co.daps.user.syntax.debug">
     <para>
      Global Option <option>--debug</option>: Sets the highest verbosity
      level (number of messages shown during the transformation process from
      XML to HTML).
     </para>
    </callout>
    <callout arearefs="co.daps.user.syntax.dc">
     <para>
      Global Option <option>-d</option>: Defines the relative or absolute
      path to the &dclong; file. In this example, <command>daps</command> is
      called in the same directory that holds the &dclong; file.
     </para>
    </callout>
    <callout arearefs="co.daps.user.syntax.output">
     <para>
      Subcommand <command>html</command>: Defines the output format to
      create.
     </para>
    </callout>
    <callout arearefs="co.daps.user.syntax.static">
     <para>
      Command option <option>--static</option>: Tells &dapsacr; to copy CSS
      and image files to the same location like the HTML files. For more
      information, see <xref linkend="tab.daps.user.output.overview"/>.
     </para>
    </callout>
   </calloutlist>
  </example>

  &daps-dc-file-tip;

  &daps-help-basics;

 </sect1>
<!--taroth 2012-04-25: it is recommended to use absolute paths in DC files, but the
 following parameters also allow for relative paths:
 BUILD_DIR
 DAPSROOT
 DOCCONF_DEFAULT
 EPUB_CSS
 FALLBACK_STYLEROOT
 FOP_CONFIG_FILE
 FOP_WRAPPER
 HTML_CSS
 STYLEDEVEL
 STYLEROOT
 XEP_CONFIG_FILE
 XEP_WRAPPER-->
</chapter>