<?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.edit">
 <title>Editing DocBook XML</title>
 <abstract>
  <para>
   This chapter covers the following topics:
   <itemizedlist>
    <listitem>
     <para>
      Choosing an editor for editing DocBook XML files
     </para>
    </listitem>
    <listitem>
     <para>
      Checking the contents of your DocBook files for mistakes
     </para>
    </listitem>
    <listitem>
     <para>
      Adapting your documentation to fit multiple similar product versions
      at once <remark>dpopov 2016-10-11: How to use the same source to
      document similar product versions</remark>
     </para>
    </listitem>
    <listitem>
     <para>
      How to keep track of the files included a documentation project
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </abstract>
<!--taroth 2012-03-08: building an appliance with a pre-configured jedit would
  be a great idea-->
 <sect1 id="sec.daps.user.edit.basics">
  <title>Basic Structural Elements</title>
  &db-structure-elements;
 </sect1>
 <sect1 id="sec.daps.user.edit.editor">
  <title>Choice of Editor</title>
 &daps-editor;
 <para>
   XML elements can be nested deeply <remark>dpopov 2016-10-11: XML supports
   deep nesting</remark>. Constructs like <sgmltag>variablelist</sgmltag>,
   <sgmltag>table</sgmltag> or <sgmltag>image</sgmltag> often have a lot of
   child elements&mdash;some of them required, some optional. If you have an
   editor with schema support, it will tell you which elements are allowed at
   the current cursor position, but nevertheless it is cumbersome if you need
   to insert the child elements of complex XML constructs
   consecutively. <remark>dpopov 2016-10-11: Although an editor with schema
   support can prompt you which elements are allowed at the current cursor
   position, it can still be tedious to insert elements of complex XML
   constructs one by one.</remark>
 </para>

  <para>
   Most editors allow you to write or record macros that can be used to
   automatically insert <quote>skeletons</quote> for complex XML
   constructs. For Emacs, &dapsacr; already includes macros for adding DocBook
   elements. For details, refer to <xref
   linkend="sec.daps.user.editors.emacs.macros"/>.
  </para>
 </sect1>
 <sect1 id="sec.daps.user.edit.spell">
  <title>Spell Checking</title>

  <para>
   &dapsacr; comes with a spell checker optimized for DocBook documents. The
   spell checker skips tags and attributes, thus allowing you to focus on the
   content of the document. The spell checker is based on &aspell; and can be
   evoked with the &dapsacr; <command>spellcheck</command>. By default, it starts
   in interactive mode, but you can also run it in the <quote>batch</quote> mode,
   where it directs a sorted list of misspelled words to standard output.
   &dapsacr; also allows you to specify a custom dictionary and the language
   to use for spell check.
  </para>

  <para>
   The following examples demonstrate how to use spell check with
   &dapsacr;. All options in these examples can be used together, except for
   <option>--file</option> and <option>--rootid</option> that are mutually
   exclusive.
  </para>

  <note>
   <title><command>spellcheck</command> Options and XIncludes</title>
   <para>
    All options in the following examples can be used together, except for
    <option>--file</option> and <option>--rootid</option> that are mutually exclusive.
   </para>
   <para>
    The <command>spellcheck</command> command always follows
    <sgmltag>xi:includes</sgmltag>, even when using the
    <option>--file</option> option.
   </para>
  </note>

  <variablelist>
   <varlistentry>
    <term>Spell Checking Files in a Documentation Project</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck</screen>
     <para>
      Runs a spell check operation on all files in the documentation project
      with the default dictionary (<literal>en_US</literal>). The files are
      opened one by one in interactive mode and checked with &aspell;. To
      abort spell checking of the current file, press <keycap>X</keycap>. The
      spell check continues with the next file in the project.
     </para>
     <para>
      Uses the ROOTID defined in the specified &dc; file as starting point.
      You can restrict the spell check to parts of the set, such as a
      <sgmltag>book</sgmltag>, <sgmltag>article</sgmltag>,
      <sgmltag>glossary</sgmltag>, <sgmltag>appendix</sgmltag>,
      <sgmltag>part</sgmltag>, or <sgmltag>chapter</sgmltag> element. To do
      this, specify the ID of the respective element with the
      <option>--rootid</option> option:
     </para>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck --rootid=<replaceable>ID</replaceable>&nbsp;</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Spell Checking a Single XML File</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck --file <replaceable>PATH_TO_XML_FILE</replaceable>&nbsp;</screen>
     <para>
      Checks the specified file (plus all files included with
      XIncludes on this level) using the default dictionary. Suggests
      alternative spellings for each misspelled word and waits for user
      interaction.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Spell Checking XML Files in Languages Other than English</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck --lang=<replaceable>LANG</replaceable> \
  [--file <replaceable>PATH_TO_XML_FILE</replaceable>]</screen>
     <para>
      Checks the specified documentation project or file with the dictionary
      for <replaceable>LANG</replaceable> (make sure the specified &aspell;
      dictionary is installed). Suggests alternative spellings for each
      misspelled word and waits for user interaction. The language code used
      for the <option>--lang</option> option is the same that is used for
      the <envar>LANG</envar> environment variable and matches the directory
      names in <filename>/usr/share/locale</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Spell Checking XML Files in Batch Mode</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck --list \
  [--file <replaceable>PATH_TO_XML_FILE</replaceable>]</screen>
     <para>
      Checks the specified documentation project or file. Returns a list of
      misspelled words to standard output. You can use the
      <option>--list</option> option to easily collect a list of words that
      are unknown to &aspell; and use this output as basis for a custom
      &aspell; word list or dictionary.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Spell Checking XML Files with an Additional Custom Dictionary</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> spellcheck --extra-dict=<replaceable>PATH_TO_CUSTOM_DICT</replaceable> \
[--file <replaceable>PATH_TO_XML_FILE</replaceable>]</screen>
     <para>
      Checks the specified documentation project or file with
      the default dictionary and the additional custom dictionary specified
      with <option>--extra-dict</option>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   For your convenience, you can integrate a spellchecker such a &aspell; (and
   a custom &aspell; dictionary, if needed) into your XML editor. This way,
   spelling is checked <quote>on the fly</quote> <remark>dpopov 2016-10-11:
   why quotes? On-the-fly is an established term.</remark> during
   editing. Consult your editor's documentation on how to integrate a custom
   dictionary. If you use &jedit;, proceed as outlined in <xref
   linkend="sec.daps.user.editors.jedit.spellcheck"/>.
  </para>
 </sect1>
 <sect1 id="sec.daps.user.edit.chklink">
  <title>Checking Links to Web Pages</title>

  <para>
   To prevent the <literal>404</literal> or similar errors, &dapsacr; includes
   a link checker for validating all external links (such as HTTP, HTTPS and
   FTP links) in the XML sources. This tool is based on
   <literal>checkbot</literal>, see <command>man 1 checkbot</command> for more
   information. The link checker searches for the <sgmltag
   class="attribute">url</sgmltag> attribute in <sgmltag>ulink</sgmltag>
   elements and checks links included there. Use it to create a report of all
   links that caused some kind of warning or error.
  </para>

  <note>
   <title><command>linkcheck</command> follows XIncludes</title>
   <para>
    The <command>linkcheck</command> command always follows
    <sgmltag>xi:include</sgmltag> statements, even when using the
    <option>--file</option> option.
   </para>
  </note>

  <variablelist>
   <varlistentry>
    <term>Checking Links in a Documentation Project</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> linkcheck</screen>
     <para>
      Uses the ROOTID defined in the specified &dc; file as a starting point.
      Checks the <sgmltag>ulink</sgmltag> elements in all files belonging to
      the documentation project. The resulting HTML report
      <filename>*checkbot-localhost.html</filename> can be opened in a
      browser, see <xref linkend="fig.daps.user.edit.chklink"/>. To open the
      results directly in the browser, add the <option>--show</option> option.
     </para>
     <para>
      If your &dc; file references a documentation <sgmltag>set</sgmltag>, you
      probably do not want to check all files belonging to the set. You can
      restrict the check to parts of the set, such as a
      <sgmltag>book</sgmltag>, <sgmltag>article</sgmltag>,
      <sgmltag>glossary</sgmltag>, <sgmltag>appendix</sgmltag>,
      <sgmltag>part</sgmltag>, or <sgmltag>chapter</sgmltag> element. To do
      so, specify the ID of the respective element with the
      <option>--rootid</option> option:
     </para>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> linkcheck --rootid=<replaceable>ID</replaceable>&nbsp;</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Checking Links in a Single XML File</term>
    <listitem>
<screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> linkcheck --file=<replaceable>PATH_TO_XML_FILE</replaceable>&nbsp;</screen>
     <para>
      Checks the <sgmltag>ulink</sgmltag> elements in the specified file. Upon
      completion, &dapsacr; returns an HTML file with a list of all
      problematic links. Open the resulting
      <filename>checkbot-localhost.html</filename> file in a browser.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <figure id="fig.daps.user.edit.chklink">
   <title>Example Output of <command>daps linkcheck</command></title>
   <mediaobject>
    <imageobject role="fo">
     <imagedata fileref="daps_chklink_report.png" width="90%"/>
    </imageobject>
    <imageobject role="html">
     <imagedata fileref="daps_chklink_report.png" width="80%"/>
    </imageobject>
   </mediaobject>
  </figure>

  <tip>
   <title>Opening the Link Check Report</title>
   <para>
    To directly open the link check report, use the &dapsacr; command output
    as an argument for a browser (for example, the command line Web browser
    <command>w3m</command>):
   </para>
   <screen>&prompt.user;<command>w3m</command> -dump $(&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> linkcheck)</screen>
  </tip>
 </sect1>
 <sect1 id="sec.daps.user.edit.profile">
  <title>Profiling&mdash;Support for Document Variants</title>
  &db-profiling-intro;
  &db-profiling;
  <para>
   For details, refer to <xref linkend="sec.daps.user.modular.profile"/>.
  </para>
 </sect1>
 <sect1 id="sec.daps.user.edit.manage">
  <title>Keeping Track of Your Documentation Project</title>
  <para>&dapsacr; provides useful commands that can help you to keep track of the files and images in your documentation project.</para>
  <variablelist>
   <varlistentry>
    <term>Listing All Files in a Documentation Project</term>
    <listitem>
     <screen>&prompt.user;&dapscmd; -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles</screen>
     <para>Lists all source files (XML sources, images, entity declarations, and
      the &dc; file) used by the document specified with the &dc; file.
       </para>
       <screen>&prompt.user;&dapscmd; -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles --xmlonly</screen>
       <para>List only source XML files used by the document specified with the &dc; file. </para>
       <screen>&prompt.user;&dapscmd; -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles --imgonly</screen>
       <para>List only source images used by the document specified with the &dc; file. </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Checking for Superfluous <remark>dpopov 2016-10-11: Perhaps Unused instead of Superfluous? </remark>
    Files</term>
    <listitem>
     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles-unused</screen>
     <para>
       Lists all files that are <emphasis>not</emphasis> referenced in the
       document specified by the &dc; file, but are available in the
       <filename>xml</filename> and <filename>images/src</filename>
       subdirectories.  This command is useful if you want to clean up your
       source files and want to know which files are no longer needed for the
       documentation project.
     </para>
    &daps-note-superfluous-files;
    </listitem>
   </varlistentry>
  <varlistentry>
   <term>Checking Where an ID or File is Included</term>
   <listitem>
    <screen>&prompt.user;&dapscmd;-d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable> list-file --rootid
     <replaceable>ID</replaceable></screen>
     <para> Lists the file that contains the ID specified with the mandatory
      parameter <option>--rootid</option>. For example:</para>
    <screen>&prompt.user;&dapscmd;&nbsp;-d DC-daps-example list-file&nbsp;--rootid sec.template.examples.images
The ID "sec.template.examples.images" appears in:
/DOC_DIR_PATH/xml/MAIN-daps-example.xml</screen>
   </listitem>
  </varlistentry>
 </variablelist>

  <para>For the image-related commands, see <xref
  linkend="sec.daps.user.imgs.manage"/>.</para>

  <!--taroth 2015-04-24: keep in sync with similar content in daps_user_images.xml-->
 &daps-note-filelists;

 <para> See
   <xref linkend="ex.daps.output.default"/> and
   <xref linkend="ex.daps.output.pretty"/> for a comparison of both outputs.</para>

  <example id="ex.daps.output.default">
   <title>Default Output of a File Listing &dapsacr; Command</title>
   <screen><?dbsuse-fo font-size="0.70em"?>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles</command>
<replaceable>YOUR_DOC_DIR</replaceable>/DC-daps-example&nbsp;<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example1.png&nbsp;<replaceable
>YOUR_DOC_DIR</replaceable>/images/src/png/example_png2.png&nbsp;<replaceable>YOUR_DOC_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
  </example>

  <example id="ex.daps.output.pretty">
   <title>Pretty-printed Output of a File Listing &dapsacr; Command</title>
   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--pretty</command>
<replaceable>YOUR_DOC_DIR</replaceable>/DC-daps-example
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png1.png
<replaceable>YOUR_DOC_DIR</replaceable>/images/src/png/example_png2.png
<replaceable>YOUR_DOC_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
  </example>

  <tip>
   <title>Using Pretty-Printed Output for Counting</title>
   <para> To count the number of files listed in a given output, you can
    also combine the <parameter>--pretty</parameter> parameter with the
    <command>wc</command> command: </para>
   <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles --pretty | wc -l</screen>
   <para> For <xref linkend="ex.daps.output.pretty"
   xrefstyle="select:label"/>, the command above would return
    <computeroutput>4</computeroutput> as a value.
   </para>
  </tip>

 </sect1>

 <sect1 id="sec.daps.user.edit.more">
  <title>Further Information</title>

  <para>
   For a complete DocBook reference see
   <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"><citetitle>&tdg;</citetitle>
   </ulink>.
  </para>

  <para>
   Useful tips and tricks on using DocBook and the DocBook stylesheets can be
   found in <citetitle>The DoCookBook&mdash;Recipes for DocBook Developers and
   Writers</citetitle>, available at <ulink
   url="http://doccookbook.sourceforge.net/"></ulink>
  </para>
 </sect1>
</chapter>