<?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.output">
 <title>Generating Output Formats</title>
 <abstract>
  <para>
   This chapter covers the following topics:
   <itemizedlist>
    <listitem>
     <para>
      Validating your XML files
     </para>
    </listitem>
    <listitem>
     <para>
      Basic command syntax for generating output formats
     </para>
    </listitem>
    <listitem>
     <para>
      Output formats you can generate with &dapsacr;
     </para>
    </listitem>
    <listitem>
     <para>
      Generating partial builds of your documentation
     </para>
    </listitem>
    <listitem>
     <para>Specifying the &main; file at the command line (instead of using a &dc;
     file)</para>
    </listitem>
   </itemizedlist>
  </para>
 </abstract>
 <sect1 id="sec.daps.user.output.validate">
  <title>Validating Your XML Sources</title>
  &daps-validation-basics;
  &daps-example-validation-error;
  <para>
    Using profiling in your DocBook sources makes validation
    unreliable. Furthermore, validating XML files within a
    <sgmltag>book</sgmltag> or <sgmltag>set</sgmltag> often exceeds validation
    of the current XML file, as links (<sgmltag>xref</sgmltag> elements) or
    XIncludes need to be resolved, too.
  </para>

  <para>
   &dapsacr; can handle all those cases because of the built-in
   <literal>xmllint</literal> validator. By default,
   <sgmltag>remark</sgmltag> elements and XML comments are ignored during
   validation. However, if you intend to create a (draft) output including
   remarks or comments, you need to include them for validation&mdash;see
   the example commands below.
  </para>

  <para>
   To validate all files that belong to your documentation project,
   &dapsacr; only needs to know which &dc; file to use. Use the
   <option>-d</option> option to specify it.
  </para>

  <variablelist>
   <varlistentry>
    <term>Validating All XML Files in a Book, Article or Set</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_DC_FILE</replaceable> validate </screen>
     <para>
      If the XML files are not valid, &dapsacr; will return the parser
      errors. If validation was successful, &dapsacr; returns: <literal>All
      files are valid.</literal>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Validating Files Including <sgmltag>remark</sgmltag> Elements</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_DC_FILE</replaceable> validate --remarks</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Validating Files Without Checking Cross References (<sgmltag>xref</sgmltag>)</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_DC_FILE</replaceable> validate --norefcheck</screen>
     <para>
      This option only affects DocBook 5 sources and is ignored when
      processing DocBook 4.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>
 <sect1 id="sec.daps.user.output.syntax">
  <title>Basic Syntax for Generating Output</title>

  <para>
   &dapsacr; supports a number of different output formats, including also
   <quote>exotic</quote> formats like man pages or simple text.
   <xref linkend="tab.daps.user.output.overview" xrefstyle="select:label"/>
   gives an overview.
  </para>

  <para>
   You can build several output formats (without them interfering with each
   other in the <filename>build</filename> directory), build your complete
   documentation project (set, book, or article), or only a part of it (for
   example, a specific chapter).
  </para>

  <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>
 </sect1>
 <sect1 id="sec.daps.user.output.formats">
  <title>Supported Output Formats</title>

  <para>
   The following table lists the main output formats and their
   characteristics, and the &dapsacr; subcommands to generate them. Refer to
   <xref linkend="sec.daps.user.output.syntax" xrefstyle="select:label"/>
   for the commands' basic syntax.
  </para>

  <!--<remark>toms 2013-01-18: According to DocBook: Web Help -> WebHelp -
  taroth 2013-01-21: hm, I already did some research on that topic some months ago
  and I found lots of different spellings even within the project itself, that's
  why in the end I decided to use the spelling that seemed most reasonable to
  me...</remark>-->

  <table id="tab.daps.user.output.overview">
   <title>&dapsacr; Output Commands and Formats</title>
   <xi:include href="daps_table_output_formats_i.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
  </table>
  &daps-output-all;
  <para>
   By default, &dapsacr; uses the regular DocBook stylesheets, but &dapsacr;
   also allows you to customize your output formats in a very flexible way.
   For details, refer to <xref linkend="cha.daps.user.layout"/>.
  </para>
 </sect1>
 <sect1 id="sec.daps.user.output.adv">
  <title>Advanced Output Options</title>

  <para>
   In the following, find some example commands for special use cases, like
   doing partial builds of your documentation project or specifying no
   further parameters than the &main; file for an output. In the last case,
   you can do completely without a &dc; file.
  </para>

  <para>
   For more advanced output options like including remarks or
   draft watermarks in the output, creating one big XML file or creating
   distributable archives, refer to <xref linkend="cha.daps.user.review"/>.
  </para>

  <variablelist>
   <varlistentry>
    <term>Building Only Parts of a Documentation Project</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d &dc;-daps-example pdf --rootid=cha.template.examples</screen>
     &daps-partial-builds;
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Specifying the &main; File on the Command Line</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -m <replaceable>PATH_TO_MAIN_FILE</replaceable></screen>
     <para>
      If you do not need to specify any further parameters than the &main;
      file, you can do completely without a &dc; file. With the
      <option>-m</option> option you can specify the &main; file defining
      your document. The options <option>-m</option> and <option>-d</option>
      exclude each other.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Opening the Output Directly in a PDF Viewer</term>
    <listitem>
     <screen>&prompt.user;<command>evince</command> $(daps -d &dc;-daps-example pdf) &amp;</screen>
     <para>Use the syntax above to open the PDF output directly in a PDF viewer (for example,
      Evince).</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Getting More Information about the Build Process</term>
    <listitem>
     <para>
      By default &dapsacr;, only provides the path to the resulting file as
      output. To set higher verbosity levels, use the global options
      <option>-v</option>, <option>-vv</option>, <option>-vvv</option>, and
      <option>--debug</option>.
     </para>
     <para>
      Output verbosity ranges from <option>-v</option> (print one line of
      results) to <option>-vvv</option> (print all commands, very verbose).
      For example, the following command will print all files created during
      the build process:
     </para>
     <screen>&prompt.user;&dapscmd; -vv -d &dc;-daps-example pdf</screen>
     <para>For debug output, use the following command:</para>
     <screen>&prompt.user;&dapscmd; --debug -d &dc;-daps-example pdf</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Specifying the Number of Parallel Jobs During the Build Process</term>
    <listitem>
     <para>
      By default &dapsacr; uses as many jobs as there are CPU cores
      available. Use the option <option>--jobs</option> to define the number
      of parallel jobs used for the build process. Higher numbers will lower
      the build time, but will also increase CPU load. For example, the
      following command will use 16 jobs for the build process:
    </para>
     <screen>&prompt.user;&dapscmd; --jobs=16 -d &dc;-daps-example pdf</screen>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>
 <sect1 id="sec.daps.user.output.xmlformat">
  <title>Pretty XML Formatting</title>
  <para>
   It can be useful to have properly formatted XML sources.
   A homogeneous formatting facilitates collaboration and makes diffs more readable.
   If done consistently, <command>xmlformat</command> reduces the amount of changes
   that need to be stored in version control systems which leads to smaller repositories.
  </para>
  <variablelist>
   <varlistentry>
    <term>Prettify all project XML files</term>
    <listitem>
     <screen>&prompt.user;&dapscmd; -d &dc;-daps-example xmlformat</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Prettify a specific XML file</term>
    <listitem>
     <screen>&prompt.user;&dapscmd; -d &dc;-daps-example xmlformat --file=xml/example.xml</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Prettify only parts of a book</term>
    <listitem>
     <screen>&prompt.user;&dapscmd; -d &dc;-daps-example xmlformat --rootid=cha.template.examples</screen>
    </listitem>
   </varlistentry>
  </variablelist>
  <important>
   <title>
    <command>xmlformat</command> Alters Source XML Files
   </title>
   <para>
    This command reformats your XML files in place, replacing their contents with the reformatted XML.
    To keep the files with the previous formatting, make a backup before running <command>daps xmlformat</command>.
   </para>
  </important>
 </sect1>
 <sect1 id="sec.daps.user.output.timestamp">
 <title>Putting the current Date and Time into the Target Document</title>
 <para>
 To get information about the build date and time, you can use the <sgmltag class="pi">dbtimestamp</sgmltag> tag.
 The processing instruction <sgmltag class="pi">dbtimestamp</sgmltag> is processed by &daps;, when the document
 is built. The date and time will then show up in the final document, based on how you've set the date/time format.
 </para>
 <example>
	 <title>Example for implementing the dbtimestamp tag in an XML File:</title>
   <screen>&lt;para>Current date: &lt;?dbtimestamp?>.&lt;/para></screen>
 </example>
 <para>
 The format of the date/time can be customized via the format parameter.
 </para>
 <example>
   <title>Example for implementing the dbtimestamp tag with a customized format:</title>
	 <screen>&lt;para>Current date: &lt;?dbtimestamp format="A, d B Y"?>.&lt;/para></screen>
 </example>
 <para>
 For further information about the format elements look at this site:
 <ulink  url="http://www.sagehill.net/docbookxsl/Datetime.html"/>  
 </para>
 </sect1>
 </chapter>