<!ENTITY wip "<emphasis>Work in progress</emphasis>" >

<!ENTITY audience
"This document is intended for users who want to make efficient use of
 DocBook XML for editing and publishing their documentation&mdash;be it
 documentation sets, individual books, or articles. Key knowledge of XML
 and DocBook and of using the Bash Shell (or command line interfaces 
 in general) is required.">

<!ENTITY daps-description-short
"&dapsacr; (&dapslong;) helps technical writers to author and publish documentation written in
 DocBook XML. &dapsacr; is a command line based software for Linux* and released
 as open source.">

<!ENTITY daps-description-long
"The &dapslong; (&dapsacr;) is developed as open source software for Linux*
 operating systems and is licensed under the GPL.  A number of integrated
 tools, stylesheets, scripts, and makefiles help technical writers in the
 editing, translation and publishing process. &dapsacr; supports single
 source publishing into several different output formats, and is suited
 both for small documentation projects and for comprehensive projects,
 created by multiple authors in a collaborative effort.">

<!ENTITY daps-userguide-abstract
"The &dapsuser; is a comprehensive guide for technical writers using &dapsacr;.
 It guides you through creating, editing, managing and publishing your
 documents&mdash;be it a short article by a single author or a large
 documentation project written by multiple authors.">

<!ENTITY daps-quickstart-abstract
"The &dapsquick; is a short introduction to &dapsacr; for technical writers. It
 includes step-by-step instructions for key editing and publishing tasks.">

<!ENTITY daps-feedback
  '<para>We want to hear your comments and suggestions about &dapslong; (including
   this guide and the other documentation included with &dapsacr;). You can
   contact us on the <literal>#opensuse-doc</literal> IRC channel on
   <literal>irc.freenode.net</literal> or in the discussion forum at <ulink
   url="http://sourceforge.net/p/daps/discussion/"></ulink>.
   For bugs or enhancement requests, open an issue at
   <ulink url="https://github.com/openSUSE/daps/issues/new"></ulink>. A user account
   at <ulink url="https://github.com"></ulink> is needed.</para>
   <para>
   Patches and user contributions are welcome!
  </para>
  '>

<!ENTITY daps-db-versions
"&dapsacr; supports DocBook 4.x and DocBook 5.x.">

<!ENTITY daps-sys-req-general
'  <para>
  &dapsacr; 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 example, for creating PDF output files. Although not
  required, &dapsacr; benefits from multi-core processors.
 </para>
'>

<!ENTITY daps-sys-req-sw
'  <para>&dapsacr; runs on any modern Linux system. It has not been
    attempted to port &dapsacr; to Windows* or Mac OS X* yet.</para>
   <para>When installing &dapsacr; as an RPM package (on any SUSE-based system),
   dependencies on other software packages are automatically resolved during
   installation. No additional action is required.</para>
'>

<!ENTITY daps-addon
'  <para>In addition to &dapsacr;, you need the following software:</para>
   <itemizedlist>
    <listitem>
     <para>An XML (or text) editor of your choice.</para>
    </listitem>
    <listitem>
     <para>For generating PDF output: an FO formatter, like
      <ulink url="http://projects.apache.org/projects/fop.html">FOP</ulink> or
      <ulink url="http://www.renderx.com">XEP</ulink>. The FO formatter
      <ulink url="http://www.antennahouse.com">Antenna House Formatter</ulink>
      is currently not supported. Whereas FOP is an open source product,
      both XEP and Antenna House are commercial products.</para>
    </listitem>
   </itemizedlist>
   <para>To add further components like version management or a workflow
   mechanism for your projects, use &dapsacr; in combination with the following
   software:</para>
  <itemizedlist>
   <listitem>
    <para>Any version management system, like CVS, Subversion, Mercurial or Git.
      </para>
   </listitem>
   <!--taroth 2015-04-15: commenting for now, can hopefully be re-enabled after
   the dm relaunch<listitem>
    <para>&dm;, a command line tool for adding and retrieving the meta information
     of all files belonging to a documentation project. &dm; is especially useful
     for larger, collaborative projects where it helps you keep track of
     owners (authors) and editing statuses of all files. However, &dm; requires
     hosting your documentation files on a Subversion server.
     </para>
   </listitem>-->
  </itemizedlist>
  <para>
   Together with the software components mentioned above, &dapsacr; can be
   used as a fully-fledged authoring and content management system for documentation
   projects based on DocBook.
  </para>
' >

<!ENTITY daps-sys-req-hw
'   <variablelist>
     <varlistentry>
      <term>RAM</term>
      <listitem>
       <para>The required amount of RAM mostly depends on the volume of your
       documentation projects. For creation of PDF output, at least 2 GB of RAM are
       recommended.</para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>CPU</term>
      <listitem>
       <para>If you have multiple or very large documentation projects, a machine
       with multiple cores is recommended.</para>
      </listitem>
     </varlistentry>
    <varlistentry>
     <term>Hard Disk Space</term>
     <listitem>
      <para>The disk space consumed mostly depends on the amount of your
       documentation sources and the number of output formats you want to generate.</para>
     </listitem>
    </varlistentry>
    </variablelist>
'>

<!ENTITY daps-install
'  <para>
    The &dapslong; can be installed and used on any Linux distribution.
    Currently, &dapsacr; is available as an RPM package for the &osuse;
    distribution and for &sle; products.
    Eventually, packages for other distributions may become available.
    For the latest status update and installation instructions, refer to    
    <ulink url="https://github.com/openSUSE/daps/blob/master/INSTALL.adoc"/>.
  </para>
'>

<!ENTITY daps-install-osuse
'   <para>
    There are a few ways to install &dapsacr; on &osuse;. To always stay up-to-date
    with the latest version of &dapsacr; install the <systemitem class="resource">daps</systemitem>
    package from the <systemitem class="service">&suse-dapsrepo;</systemitem> repository as outlined below.
   </para>
 
   <para>
    You may also use the <systemitem class="resource">daps</systemitem> package
    that shipped with your version of &osuse;. However, you then might miss the latest
    features and bug fixes in &dapsacr;.
   </para> '>

<!ENTITY daps-install-osuse-zypper
'   <para>The quickest way to install &dapsacr; is using the
<command>zypper</command> command.</para>
    <procedure>
     <title>Installing &dapsacr; via Zypper From &suse-dapsrepo;</title>
     <step>
      <para>Open a browser and enter the following URL: <ulink url="http://download.opensuse.org/repositories/Documentation:/Tools"></ulink></para>
     </step>
     <step>
      <para>Select your distribution and product number to make the browser show the URL for the respective repository.</para>
     </step>
     <step>
      <para>Copy the URL from the address bar.</para>
     </step>
     <step>
      <para>Open a terminal.</para>
     </step>
     <step>
      <para>Add the repository with the following zypper command:</para>
      <screen>&prompt.root;<command>zypper ar -f <replaceable>URL</replaceable> &suse-dapsrepo;</command></screen>
      <para>Replace <replaceable>URL</replaceable> with the URL you pasted from
      your browser.</para>
     </step>
     <step>
      <para>Install &dapsacr; with the following zypper command:</para>
      <screen>&prompt.root;<command>zypper in --from &suse-dapsrepo; daps</command></screen>
      <para>In order to install &dapsacr; you have to trust the <systemitem>&suse-dapsrepo;</systemitem> repository.</para>
     </step>
    </procedure>
   '>


<!ENTITY daps-install-sle 
'<para>Starting with &sle; 12, &dapsacr; is also available for
    &sle;. The &dapsacr; package is provided by the &sdk; (SDK), a
    free extension for &sle;. You need to install it as add-on (or
    extension). You can install the SDK (without any physical media) as an
    extension after the registration of your system at &scc;. If you prefer
    to install from a physical medium, proceed as follows:</para>
   
   <procedure>
    <step>
     <para> Download the installation media for the SDK from <ulink
       url="http://download.suse.com/"/>.</para>
    </step>
    <step>
     <para>Install the SDK as an add-on product to &sle;. </para>
     <para>For details on how to install add-on products (with or without
      physical media), see the <citetitle>&sle; 12 &deploy;</citetitle>,
      available at &suse-onlinedoc;. Refer to chapter <citetitle>Installing
       Add-On Products</citetitle>, <ulink
       url="https://www.suse.com/documentation/sles-12/book_sle_deployment/data/cha_add-ons.html"
      />.</para>
    </step>
    <step>
     <para>Install the <systemitem class="resource">daps</systemitem> package,
      using either the &yast; <guimenu>Software Management</guimenu> module
      or the following command:</para>
     <screen>&prompt.root;zypper in daps</screen>
     <para>Dependencies on other software packages are automatically resolved
      during installation.</para>
    </step>
   </procedure>'>

<!ENTITY daps-images-intro
' <para>
   Depending on the output format you generate (PDF or HTML,
   for example), &dapsacr; automatically transforms the source images you
   provide (which are also referenced in your XML sources) 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. For more details, see the &dapsuser;.
  </para>'>

<!ENTITY daps-images-dir
'    &dapsacr; 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
     <filename>images/src/file_extension</filename>. For example, <acronym>PNG</acronym>
     files must be stored under <filename>images/src/png</filename>. If you used
     <command>daps-init</command> to set up your project, the appropriate
     directories should already exist.
'>

<!ENTITY daps-img-formats
" <para>&dapsacr; supports the following types of images:</para>
  <itemizedlist>
   <listitem>
    <para>
     DIA (input format only)
    </para>
   </listitem>
   <listitem>
    <para>
     EPS (experimental)
    </para>
   </listitem>
   <listitem>
    <para>
     FIG (input format only)
    </para>
   </listitem>
   <listitem>
    <para>
     JPEG
    </para>
   </listitem>
   <listitem>
    <para>
     PDF (experimental - only works for PDF output and with XEP formatter)
    </para>
   </listitem>
   <listitem>
    <para>
     PNG
    </para>
   </listitem>
   <listitem>
    <para>
     SVG
    </para>
   </listitem>
  </itemizedlist>">

<!ENTITY daps-file-names-req
' <variablelist>
   <varlistentry>
     <term>XML extension required</term>
     <listitem>
     <para>
       Always use the .xml extension, so DAPS can recognize the files, which are
       needed to build the document.
     </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term>No Spaces and Colons In File and Directory Names</term>
     <listitem>
      <para>Avoid spaces and colons in file and directory names. 
      The <command>make</command> command
       in &dapsacr; has trouble understanding them. Use underscores
       (<filename>_</filename>) or hyphens (<filename>-</filename>) instead.
       </para>
       <para>It is good practice to only use the following characters for
       file or directory names: alphabetic characters [a-z] or [A-Z], numerical
       characters [0-9], hyphens (<literal>-</literal>), or underscores
       (<literal>_</literal>).</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Unique Image Names</term>
     <listitem>
      <para>Always store just one file with a particular name within the
      <filename>images/src</filename> directory of a project. As &dapsacr; 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.</para>
      <para>Additionally, having a file called <filename>example.png</filename>
      and another called <filename>example.svg</filename> 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?</para>
      <para>
      When invoking &dapsacr; with the parameter <command><parameter>-v</parameter></command>,
      a warning will be printed whenever a file name appears twice within a project.
      To specifically check for image name clashes upfront, use the
      <command>daps list-images-multisrc</command> subcommand.
     </para>
     <para>
      It is a good idea to find a consistent file naming scheme. For example, when
      documenting software, it might prove helpful to include the name of the
      application at the beginning of the file name. You can also use prefixes like
     <filename>screenshot_</filename> and <filename>diagram_</filename>
      to separate between different types of images.
    </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <note><title>Hint on Using UTF-8 characters in File Names</title>
   <para>
     Depending on your environment, the build process could fail if you are using
     file names with UTF-8 characters. Run the <command>locale</command>
     command and check if the LANG environment variable contains UTF-8. Otherwise
     adjust the LANG environment variable accordingly.
   </para>
   </note>
  '>

<!ENTITY daps-img-ref
' <para>
    As your images need to be located in a defined directory structure,
    &dapsacr; automatically finds the path to your images. Therefore,
    referencing images in your XML sources is very straightforward: 
    you must not include any path in the
    <sgmltag class="attribute">fileref</sgmltag> attribute&mdash;the
    file name is enough.
   </para>
  <para>
    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
    <sgmltag class="attribute">role</sgmltag> attribute to specify the
    output format, for example <sgmltag class="attvalue">fo</sgmltag> or
    <sgmltag class="attvalue">html</sgmltag>.
    </para>'>

<!ENTITY ex-daps-img-ref
 '<para>Let us assume you have a source image file named <filename>graphic.dia</filename>. To make
    &dapsacr; use an SVG version of your image for PDF output (<literal>role="fo"</literal>) and
    a PNG version for HTML output (<literal>role="html"</literal>), reference the images as follows:
   </para>
<screen>&lt;figure&gt;
  &lt;title&gt;Main Window&lt;/title&gt;
  &lt;mediaobject&gt;
    &lt;imageobject role="fo"&gt;
      &lt;imagedata fileref="graphic.svg" width="70&#37;"/&gt;
    &lt;/imageobject&gt;
    &lt;imageobject role="html"&gt;
      &lt;imagedata fileref="graphic.png" width="75&#37;"/&gt;
    &lt;/imageobject&gt;
  &lt;/mediaobject&gt;
&lt;/figure&gt;</screen>'>

<!ENTITY daps-config
  '<para>
   &dapsacr; can be customized to a large degree: per system, per user, and per
   document. The configuration file &dapsconf-sys; lists all parameters that can
   be configured, including a short description for each parameter. Parameters
   are always defined as <option>KEY="VALUE"</option> pairs. Any parameter can be
   set in various locations, which are listed below in ascending order with
   regard 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.
  </para>

  <itemizedlist>
   <listitem>
    <para>
     &dapsconf-sys; (system-wide configuration file)
    </para>
   </listitem>
   <listitem>
    <para>
     &dapsconf-user; (user-specific configuration file)
    </para>
   </listitem>
   <listitem>
    <para>
     &dc; (doc config) file of the documentation project (for settings specific
     to a document or documentation set)
    </para>
   </listitem>
   <listitem>
    <para>
     on the fly at the command line by specifying options to a
     <command>daps</command> command.
    </para>
   </listitem>
  </itemizedlist>'>


<!ENTITY daps-key-files
 ' <para>
    The following key files define a documentation project so that
    it can be processed by &dapsacr;:
   </para>
   <variablelist>
    <varlistentry>
     <term>&main; File</term>
     <listitem>
      <para>
     A DocBook XML file in the <filename>xml</filename> directory. It contains the <quote>starting point</quote> (the
     highest-level object) of your documentation project (for example,
       <sgmltag>book</sgmltag> or <sgmltag>article</sgmltag>). For larger
       documentation projects, it is good practice to name the file
    <filename>MAIN-<replaceable>PROJECTNAME</replaceable>.xml</filename>,
       but you can use any other file name as well. Other XML files may be
       included into the &main; file via <sgmltag>&lt;xi:include/&gt;</sgmltag>
       statements.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>&dclong; (&dc;) File</term>
     <listitem>
      <para>
      A configuration file in the project directory. It defines several 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
      <parameter>MAIN</parameter>, pointing to the XML file that you want to
      process. Usually, you create one &dc; file per book or article. For a
      documentation <sgmltag>set</sgmltag> (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.
     </para>
     </listitem>
    </varlistentry>
   </variablelist> '>

<!ENTITY daps-co-main
 ' <para>
   Specifies the XML &main; file. It contains the highest-level object
   (root element) of your documentation project. The &main; file must be located
   in <filename><replaceable>YOUR_DOC_DIR</replaceable>/xml/</filename>.
   Therefore, you only need to specify the &main;&#39;s file name in the &dc; file
   (no path).</para>'>

<!ENTITY daps-co-rootid
 '<para>
  Defines the root ID of the element to be used for creating an output format.
  Usually, you specify the root ID of a <sgmltag>book</sgmltag> or
  <sgmltag>article</sgmltag> element here.</para>'>

<!ENTITY daps-co-styleroot
  '<para>
   For a custom layout, use the <parameter>STYLEROOT</parameter> parameter to
   specify the (absolute or relative) path to the directory containing the
   custom stylesheets. Using absolute paths is recommended for &dc; files.
   </para>'>

<!ENTITY daps-co-fbstyleroot
  '<para>Allows you to define a fallback which is used in case the custom
     stylesheets defined with <parameter>STYLEROOT</parameter> cannot be accessed.
     In case neither the stylesheets specified with <parameter>STYLEROOT</parameter>
     nor with <parameter>FALLBACK_STYLEROOT</parameter> can be accessed, &dapsacr;
     uses the default DocBook layout.</para>'>

<!ENTITY daps-co-css
  '<para>If not specified, &dapsacr; 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.</para>'>

<!ENTITY daps-co-source
  "<para>
   Enabling this parameter allows you to source the &dc; file on the Bash with
   &dapsacr;. Sourcing a &dc; file (formerly called <literal>ENV</literal> file)
   was necessary to work with the documentation environment provided by &susedoc;,
   &dapsacr;'s predecessor.
  </para>">

<!ENTITY daps-co-formatter
 '<para>Specifies the PDF formatter to use.</para>'>

<!ENTITY daps-co-draft
 '<para>When set to <literal>yes</literal>, a DRAFT watermark appears in PDF or
   HTML outputs of the document.</para>'>

<!ENTITY daps-editor
 ' <para>
   As &dapsacr; 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. Several open source editors can be
   extended with plug-ins for automatic tag insertion and completion,
   insertion of <sgmltag>xref</sgmltag> 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,
   <ulink url="http://www.jedit.org/">jEdit</ulink> is a good choice.
  </para>'>


<!ENTITY db-structure-elements
 ' <para>
   If you have worked with DocBook before, you know about the typical top-level
   elements for documents, <sgmltag>book</sgmltag> and
   <sgmltag>article</sgmltag>. For larger documentation projects, another
   typical top-level element is <sgmltag>set</sgmltag> (a collection of books).
  </para>

  <para>
   To define the individual components of a book, use structural elements
   such as <sgmltag>part</sgmltag>, <sgmltag>chapter</sgmltag>,
   <sgmltag>preface</sgmltag> or <sgmltag>appendix</sgmltag>. Chapters are
   usually subdivided into sections (<sgmltag>section</sgmltag> elements or
   <sgmltag>sect1</sgmltag>, <sgmltag>sect2</sgmltag> etc.). Smaller structural
   units are <sgmltag>para</sgmltag> (for paragraphs), or list elements
   such as <sgmltag>orderlist</sgmltag>, <sgmltag>itemizedlist</sgmltag>, or
   <sgmltag>variablelist</sgmltag>.
  </para>

  <para>
   If you have set up your documentation project from scratch with
   <command>daps-init</command>, you can explore the example documents that
   are installed within the directory structure. They show the most commonly
   used DocBook XML constructs.
  </para>'>

<!ENTITY db-profiling-intro
'<para>
   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 <emphasis>profiling</emphasis>. </para>'>


<!ENTITY db-profiling
 ' <para>
      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.</para>
      <para>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. </para>'>

<!ENTITY daps-product-entities
   '&dapsacr; allows setting product name and product number dynamically.
    This enables you to use the same XML sources for different products.
    Use the entities <literal>&amp;productname;</literal> and
    <literal>&amp;productnumber;</literal> in your XML
    sources, and define the respective values in an entity (using
    profiling for multiple products).'>

<!ENTITY daps-profiling-attributes
  '<para>DocBook offers profiling attributes for various purposes.
   &dapsacr; currently supports the following attributes:</para>
  <itemizedlist>
    <listitem>
     <para>
      <sgmltag class="attribute">arch</sgmltag>
     </para>
    </listitem>
    <listitem>
     <para>
      <sgmltag class="attribute">condition</sgmltag>
     </para>
    </listitem>
    <listitem>
     <para>
      <sgmltag class="attribute">os</sgmltag>
     </para>
    </listitem>
    <listitem>
     <para>
      <sgmltag class="attribute">vendor</sgmltag>
     </para>
    </listitem>
   </itemizedlist>
   <para>Each profiling attribute has a corresponding profiling parameter
   in &dapsacr;: </para>
   <itemizedlist>
    <listitem>
     <para><parameter>PROFARCH</parameter></para>
    </listitem>
    <listitem>
     <para><parameter>PROFCONDITION</parameter></para>
    </listitem>
    <listitem>
     <para><parameter>PROFOS</parameter></para>
    </listitem>
    <listitem>
     <para><parameter>PROFVENDOR</parameter></para>
    </listitem>
   </itemizedlist>
   <para>The profiling parameters are used in the &dc; file to define
   which profiling attributes in the XML files should be interpreted
   during generation of output.</para>'>

<!ENTITY daps-output-remarks
'<para>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 &dapsacr; by
     default, but if you want XEP to treat remark elements like FOP does, you
     can change the respective &dapsacr; parameter.<remark>taroth 2012-10-16:
     todo - add link as soon as this is covered in &dapsuser;</remark> In HTML,
     HTML-single and &epub; output, the contents of the remark elements is shown
     in red within the text.
    </para>'>

<!ENTITY daps-note-output-adv
'<note>
   <title>Availability of Advanced Output Options</title>
   <para>Advanced output options are only supported for selected formats. For example, 
   <option>--draft</option> and <option>--remarks</option> are only available in HTML, 
   HTML-single, PDF, and &epub; output.     
  </para>
  <!--
  <itemizedlist>
   <listitem>
     <para>
      <option>-/-meta</option>: <remark>taroth 2013-01-08:fs, toms: is the
      following correct?</remark>Only available in HTML, HTML-single, and PDF.</para>
    </listitem>
    <listitem>
     <para>
      <option>-/-draft</option> and <option>-/-remarks</option>:
     Only available in HTML, HTML-single, PDF, and &epub; output. </para>
    </listitem>
   </itemizedlist>-->
   <para>Using the <option>--remarks</option> option<!--and <option>-/-meta</option> options-->
      automatically turns draft mode on.</para>
   <para>By default, &dapsacr; adds a string to the base name of the output file
     to flag output formats generated with special options.
     Example file names are <filename>*_draft_en.pdf</filename> or
     <filename>*_remarks_*_draft_en.pdf</filename>.</para>
  </note>'>

<!ENTITY daps-validation-basics
' <para>
    Generating any output requires that your XML files are valid. As soon as any
    output command is executed, &dapsacr;
    automatically runs a validation check first. If it fails, &dapsacr;
    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, &dapsacr; shows the path to the profiled XML sources
    and the total number of errors.</para>'>


<!ENTITY daps-example-validation-error
 ' <example>
     <title>Parser Output For Validation Errors (<sgmltag>xref</sgmltag> to unknown ID)</title>
     <screen>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</screen>
</example>
<note><title>Validating is Done in Build Directory</title>
<para>Validation is always done in the <filename>build</filename>
directory and in the profiled sources, as indicated by
 the path above (<filename>/local/[...]/build/.profiled/[...]/MAIN.DAPS.xml
 </filename>). However,  you need to fix the validation error in the sources located in your
 <filename>xml</filename> directory, otherwise the fixes will not take effect. 
 Profiling is similar to conditional text. For details, refer to the chapter
 about modularizing document projects in the &dapsuser;.
 </para>
</note>'>

<!ENTITY daps-cmd-basic-syntax
'<screen>&prompt.user;&dapscmd; [--global-options] subcommand [--command-options] [arguments]</screen>'>

<!ENTITY daps-help-basics
'<para>
   To view the global options and the available subcommands for &dapsacr;, use the command:
  </para>

  <screen>&prompt.user;&dapscmd; help</screen>

  <para>
   For a short help text on a specific <emphasis>subcommand</emphasis>, use:
  </para>

  <screen>&prompt.user;&dapscmd; help  <replaceable>subcommand</replaceable>&nbsp;</screen>

  <para>
   For example, if you want more information about generating HTML output,
   run:
  </para>

  <screen>&prompt.user;&dapscmd; help html</screen>'>

<!ENTITY daps-dc-file-tip
'<tip>
   <title>Specifying the &dc; File</title>
   <para>For execution of most commands, &dapsacr; needs to know which &dc; file
      to use. Usually, you do so by specifying a &dc; file with the global option
     <option>-d</option>. For example:</para>
     <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_DC_FILE</replaceable> pdf</screen>
     <para>Only in the following cases you may omit the <option>-d</option>
     option:</para>
   <itemizedlist>
     <listitem>
     <para>If your documentation directory contains only one &dc; file. In that case,
     &dapsacr; automatically uses the corresponding file.</para>
    </listitem>
    <listitem>
     <para>If you have specified a default &dc; file to use in &dapsconf-user;
    (as a value for <parameter>DOCCONF_DEFAULT</parameter>). In that case,
     &dapsacr; automatically uses the corresponding file, unless you specify a
     different one on the command line.</para>
    </listitem>
     <listitem>
     <para>If you want to call the help function.</para>
    </listitem>
   </itemizedlist>
  </tip>'>

<!ENTITY daps-output-all
'<para>
   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 <command>daps&nbsp;help</command>.
   The available output formats are listed below <menuchoice><guimenu>Subcommands</guimenu>
   <guimenu>Generate Books</guimenu> </menuchoice>.
  </para>'>

<!ENTITY daps-output-cmd-basics
'<para>
    Independent of the individual output format you want to create, you need
    to specify the &dc; file to use:
   </para>
  <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> <replaceable>OUTPUT_FORMAT</replaceable>&nbsp;</screen>
  <para>
    For example:
   </para>
  <screen>&prompt.user;&dapscmd; -d &dc;-daps-example pdf</screen>
  <para>
    At the end of the transformation process, &dapsacr; shows a message
    where to find the generated output.
   </para>'>
   
 <!ENTITY daps-note-subdirs
 ' <important>
    <title>Structure of the <filename>xml</filename> and
     <filename>image/src/*</filename> Directories</title>
    <para>Avoid subdirectories within the <filename>xml</filename> and
      <filename>image/src/*</filename> directories. Referencing or including
     files from subdirectories within those directories can lead
     to unpredictable results with &dapsacr;.</para>
   </important>'>
  
<!ENTITY daps-note-filelists
' <note>
   <title>Output of File Listings</title>
   <para>By default, the output of the listing commands is a list of file names
    (including the absolute path), all printed in one line with the file names
    separated by blanks. This default output format is useful for piping (or
    copying and pasting) the output for use with another command. </para>
   <para>If you need a pretty printed output where each file name is listed on a
    separate line, use the <option>--pretty</option> option. </para>
  </note>'>
  
<!ENTITY daps-note-superfluous-files
  ' <important>
      <title>Use a <sgmltag>set</sgmltag> to Check for Superfluous
       Files</title>
      <para> If you are storing multiple &dc; files in the same project
       directory, use the &dc; file of a <sgmltag>set</sgmltag> for this check.
       As it contains all articles and books in the project directory, this makes
       sure that any files found during the check are indeed unnecessary.
      </para>
    </important>'>
    
<!ENTITY daps-partial-builds
'<para>Instead of always building your complete documentation project
     (<sgmltag>set</sgmltag>, <sgmltag>book</sgmltag>, or
     <sgmltag>article</sgmltag>), &dapsacr; also allows you to build only
    individual parts. The <quote>starting point</quote> of your documentation
    project is usually defined by the root element of the &main; file that
    is referenced in the respective &dclong;. To build only a part of your
    documentation project, use the <option>--rootid</option> option to specify
    the ID of an individual <sgmltag>book</sgmltag>, <sgmltag>article</sgmltag>,
     <sgmltag>glossary</sgmltag>, <sgmltag>appendix</sgmltag>,
     <sgmltag>part</sgmltag>, or <sgmltag>chapter</sgmltag>.
     </para>'>

<!ENTITY daps-img-format-support
'<important>
    <title>Limited Support with &dapsacr;</title>
    <para>
     This image format is only supported in combination with the XEP formatter. Using this format
     might also lead to longer document creation times.
    </para>
   </important>'>
