<?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 article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>

<article class="whitepaper" lang="en">
 <title>Building Books</title>
 <subtitle>A Guide to Transforming Novdoc Documents or <quote>Don't
   panic!</quote></subtitle>
 <!-- FIXME: Find a better title? -->
 <articleinfo>
  <authorgroup>
   <author><firstname>Berthold</firstname>
    <surname>Gunreben</surname><email>berthold DOT gunreben AT suse DOT de</email>
   </author>
   <author><firstname>Thomas</firstname>
    <surname>Schraitle</surname><email>thomas DOT schraitle AT suse DOT de</email>
   </author>
  </authorgroup>
  <releaseinfo>$Id: daps.xml 1489 2012-05-16 14:53:26Z fsundermeyer $</releaseinfo>
  <revhistory>
   <revision><revnumber>1.0</revnumber><date>2005-05</date>
    <revdescription>
     <para>
      Initial version
     </para>
    </revdescription>
   </revision>
   <revision>
    <revnumber>1.41</revnumber>
    <date>2005-06-08</date>
    <revdescription>
     <para>Updated with suggestions from Dublin</para>
    </revdescription>
   </revision>
   <revision>
    <revnumber>1.46</revnumber>
    <date>2005-06-13</date>
    <revdescription>
     <para>Updating information about make targets</para>
    </revdescription>
   </revision>
   <revision>
    <revnumber>1.50</revnumber>
    <date>2005-06-21</date>
    <revdescription>
     <para>Added information about how to configure hyphenation</para>
    </revdescription>
   </revision>
   <revision>
    <revnumber>1.55</revnumber>
    <date>2005-07-11</date>
    <revdescription>
     <para>Reinserted accidently delete validation section from bg again</para>
    </revdescription>
   </revision>
   <revision>
    <revnumber>1.60</revnumber>
    <date>2005-07-13</date>
    <revdescription>
     <para>Added new section about Checking in and Quick Start</para>
    </revdescription>
   </revision>
   <revision>
    <revnumber></revnumber>
    <date>2005-10-11</date>
    <revdescription>
     <para>Added XEP installation, more task oriented descriptions. Reorganized
     the structure. Removed CVS section and moved it into a separate article.</para>
    </revdescription>
   </revision>
    <revision>
      <revnumber>546</revnumber>
      <date>2010-10-01</date>
      <revdescription>
        <para>Updated documentation</para>
      </revdescription>
    </revision>
    
  </revhistory>
  <mediaobject>
   <imageobject role="html">
    <imagedata width="100%" fileref="miracle.png"/>
   </imageobject>
   <imageobject role="fo">
    <imagedata width="60%" align="center" fileref="miracle.png"/>
   </imageobject>
  </mediaobject>
<!--
  <abstract>
   <para>
    This document describes what you need to set up an XML build environment
    for creating HTML and PDF from XML source code by using the daps build
    mechanic.
   </para>
  </abstract>
-->
 </articleinfo>


<!-- ******************************************************************* -->

 <sect1 id="sec.start">
  <title>Quick Start</title>
  <para>
   Configuring your system enables you to build books from DocBook XML sources.
   Proceed as follows:</para>

  <procedure>
   <step>
    <para>Check your requirements (see <xref xrefstyle="select:label"
      linkend="sec.requirements"/>)</para>
   </step>
   <step>
    <para>Install XEP (see <xref xrefstyle="select:label"
      linkend="sec.install.xep"/>)</para>
   </step>
   <step>
    <para>Setting up your XML environment (see <xref xrefstyle="select:label"
      linkend="sec.setupxmlenv"/>)</para>
   </step>
   <step>
    <para>Build your books (see <xref xrefstyle="select:label"
      linkend="sec.makemechanic"/>)</para>
   </step>
   <step>
    <para>Publish your PDF</para>
   </step>
  </procedure>


 </sect1>


<!-- ******************************************************************* -->
 <sect1 id="sec.requirements">
  <title>Requirements</title>
  <para>
   Before you start, you should be aware of some prerequisites. You need:
  </para>
  
  <orderedlist>
   <listitem>
    <para>A Linux system. :-)</para>
   </listitem>
   <listitem>
    <para>Some rudimentary Linux knowledge. This article cannot explain the
     basics of Linux.</para>
   </listitem>
   <listitem>
    <para>Some knowledge about XML and Subversion (where needed). This
          article cannot go in-depth into these two technologies, but we
          provide some links for further information. (See <xref
            linkend="biblio"/>.) </para>
   </listitem>
   <listitem>
    <para>The <package>daps</package> package. It requires several
      other packages, for example the DocBook stylesheets. </para>

    <!--<table id="tab.packagelist">
     <title>Needed packages</title>
     <tgroup cols="2">
      <colspec colname="col1"/>
      <colspec colname="col2"/>
      <thead>
       <row>
	<entry>Package</entry>
	<entry>Description</entry>
       </row>
      </thead>
      <tbody>
       <row>
	<entry namest="col1" nameend="col2" align="center"><emphasis>Tools</emphasis></entry>
       </row>
       <row>
	<entry><systemitem>autoconf</systemitem>,
	 <systemitem>automake</systemitem>, <systemitem>make</systemitem></entry>
	<entry>Tools to generate the <filename>configure</filename> script</entry>
       </row>
       <row>
	<entry><systemitem>subversion</systemitem></entry>
	<entry>A tool to work with Subversion repositories</entry>
       </row>
       <row>
	<entry><systemitem>inkscape</systemitem></entry>
	<entry>An SVG editor. Needed to convert our SVG graphics into PNG</entry>
       </row>
       <row>
	<entry><systemitem>libxml2</systemitem>, <systemitem>libxslt</systemitem></entry>
	<entry>Essential libraries for parsing, validating and transforming XML</entry>
       </row>
       <row>
	<entry><systemitem>docbook-xsl-stylesheets</systemitem></entry>
	<entry>This package is essential for building HTML and XSL-FO</entry>
       </row>
       <row>
	<entry><systemitem>ImageMagick</systemitem></entry>
	<entry>This package provides the <command>convert</command> command that
	is needed for image manipulation</entry>
       </row>
       <row>
	<entry><systemitem>svg-dtd</systemitem></entry>
	<entry>The SVG DTD that is needed by our SVG files</entry>
       </row>
       <row>
	<entry><systemitem>xfig</systemitem></entry>
	<entry>Needed to convert our old files in FIG format into SVG</entry>
       </row>
       <row>
	<entry><systemitem>xml-commons-resolver</systemitem></entry>
	<entry>Needed for XEP with XML catalog support</entry>
       </row>
       <row>
	<entry namest="col1" nameend="col2" align="center"><emphasis>Fonts</emphasis></entry>
       </row>
       <row>
	<entry><systemitem>agfa-fonts</systemitem></entry>
	<entry>Essential package that contains our fonts</entry>
       </row>
       <row>
	<entry><systemitem>freefont</systemitem></entry>
	<entry>Some other fonts that are needed</entry>
       </row>
       <row>
	<entry><systemitem>sazanami-fonts</systemitem></entry>
	<entry>Needed for Japanese books</entry>
       </row>
       <row>
	<entry><systemitem>ttf-arphic</systemitem></entry>
	<entry>Fonts for Chinese books</entry>
       </row>
       <row>
	<entry><systemitem>ttf-founder-simplified</systemitem></entry>
	<entry>Fonts for Chinese books</entry>
       </row>
       <row>
	<entry><systemitem>ttf-founder-traditional</systemitem></entry>
	<entry>Fonts for Chinese books</entry>
       </row>
      </tbody>
     </tgroup>
     </table>-->
    
   </listitem>
  </orderedlist>
 </sect1>


<!-- ******************************************************************* -->
 <sect1 id="sec.install.xep">
  <title>Installing XEP</title>
  <para>The <package>daps</package> package installs everything what
    you need for building PDFs and HTML. In case you want to build your
    books with XEP (a commercial formatter from <ulink
      url="http://www.renderx.com">RenderX</ulink>) you should have 
    two files:</para>

  <orderedlist>
   <listitem>
    <para>The XEP ZIP archive with the name
     <filename>xep-X.Y-DATE-docbench.zip</filename>. The placeholders
     <replaceable>X</replaceable> and <replaceable>Y</replaceable> are major
     and minor number of the XEP release, <replaceable>DATE</replaceable>
     corresponds to the date in the format YearMonthDay.</para>
    <para>This file contains the XEP formatter and the XML editor oXygen. You
     can use both independently of each other.</para>
   </listitem>
   <listitem>
    <para>The license key with the name <filename>license.xml</filename> which
     is mailed to you after purchasing XEP.</para>
   </listitem>
  </orderedlist>

  <para>To install XEP on your system do the following:</para>

  <procedure>
   <title>Installing XEP on your system</title> 
   <step>
    <para>Log into your system as you normally do with your prefered user.</para>
    <warning>
     <title>XEP and user <systemitem
       class="username">root</systemitem></title>
     <para>Do not install XEP as <systemitem
      class="username">root</systemitem>. Installing XEP as <systemitem
       class="username">root</systemitem> makes it difficult to track errors
      and other weird combinations.</para>
    </warning>
   </step>
   <step>
    <para>Open a terminal window with <keycombo>
      <keycap function="alt">Alt</keycap>
      <keycap>F2</keycap>
     </keycombo> and enter <command>konsole</command>.</para>
   </step>
   <step>
    <para>Copy your XEP ZIP archive to <filename>/tmp</filename>:</para>
    <screen>cp xep-X.Y-DATE-docbench.zip /tmp</screen>
   </step>
   <step>
    <para>Change the directory:</para>
    <screen>cd /tmp</screen>
   </step>
   <step>
    <para>Unzip the archive:</para>
    <screen>unzip xep-X.Y-DATE-docbench.zip</screen>
    <para>It gives you two files: a <filename>README.txt</filename> and a file named
     <filename>setup-X.Y-DATE-docbench.zip</filename>.</para>
   </step>
   <step>
    <para>Start the installation dialog with:</para>
    <screen>java -jar setup-X.Y-DATE-docbench.jar</screen>
   </step>
   <step>
    <para>Choose the correct directory where you want to install XEP and the
     oXygen XML Editor and select the path to the license file. Proceed with
     <guimenu>Install</guimenu> twice to start the installation process.</para>
    <note>
     <title>Home directory accessed with NFS</title>
     <para>Install XEP <emphasis>always</emphasis> in a directory which resides
      on your local harddisc. Don't install XEP in a directory which is
      accessed by NFS (Network File System). This is the case if you work in a
      network environment where <filename>/home</filename> is mounted from a
      server. Otherwise choose a neutral one, like <filename>/local</filename>.
      Make sure you have write permissions to this directory.</para>
    </note>
   </step>
   <step>
    <para>Delete the copied archive and the extracted files under
     <filename>/tmp</filename> where neccessary.</para>
   </step>
   <step>
    <para>Extend to <envar>PATH</envar> environment variable with your
     installation directory from XEP. Open <filename>~/.bashrc</filename> or
     <filename>~/.bashrc.local</filename> and insert:</para>
    <screen>export PATH="<replaceable>XEP_INSTALLTION_PATH</replaceable>:$PATH"</screen>
    <para>Replace <replaceable>XEP_INSTALLTION_PATH</replaceable> with your XEP
    installation directory.</para>
   </step>
  </procedure>

 </sect1>

<!-- ******************************************************************* -->
 <sect1 id="sec.setupxmlenv">
  <title>Setting Up and Checking Your XML Build Environment</title>
  <para>
   Before you build a book, you should check whether all relevant packages are
   installed. Because it can be a bit difficult to know all packages, we have
   created a setup script that checks your system for the correct
   versions.</para>
  <para>We assume in this section, you use the directory
   <filename>/local</filename> for the storage of your files. Whenever you see
   there is this directory, replace it with your choice.</para>
  <para>Proceed as follows:</para>

  <procedure>
   <title>Setting up your XML Build Environment</title>
   <step>
    <para>Access the source code:</para>
    <stepalternatives>
     <step>
      <para>If you have access to the SUSE Subversion repository, see the
       separate documentation <citetitle>Using Subversion</citetitle> <xref
	linkend="bib.usingsvn"/>.</para>
     </step>
     <step>
      <para>If you don't have access to our Subversion repository, you get an archive
       from us. Unpack it and move it to your desired location.</para>
     </step>
    </stepalternatives>
   </step>
   <step>
    <para>Change the directory:</para>
    <screen>cd /local/suselx/novdoc/</screen>
   </step>
   <step>
    <para>Run the following commands:</para>
    <screen>./autogen.sh &amp;&amp; ./configure &amp;&amp; make</screen>
    <para>First it generates the <filename>configure</filename> and
     <filename>Makefile</filename> files. If this was successful the
     <filename>configure</filename> script checks for certain packages and
     programs, for example:</para>
    <screen>checking for inkscape... inkscape</screen>
   </step>
   <step>
    <para>Install further packages, if you get an error. The script tells you
     what you have to install.</para>
   </step>
   <step>
    <para>Run the following command if everything was successful:</para>
    <screen>make install-xep</screen>
    <para>This installs configuration and hyphenation files into the XEP
     installation directory.</para>
   </step>
  </procedure>
 </sect1>

<!-- ******************************************************************* -->
 <sect1 id="sec.makemechanic">
  <title>Using the SUSE Make Mechanic</title>
  <para>
   This section explains how to use our build system to create books in HTML
   and PDF. The entire process of building books from XML sources contains the
   steps in <xref linkend="fig.make.process"/>.
  </para>

  <figure id="fig.make.process">
   <title>Overview of the Entire Process</title>
   <mediaobject>
    <imageobject role="fo">
     <imagedata width="100%" scalefit="1" fileref="make-process.svg"/>
    </imageobject>
    <imageobject role="html">
     <imagedata fileref="make-process.png"/>
    </imageobject>
   </mediaobject>
  </figure>

  <para>The build process looks like:</para>
  <orderedlist>
   <listitem>
    <para>First, you need to access the files from our repository. This gives
     you a set of directories.</para>
   </listitem>
   <listitem>
    <para>You configure your settings in your current shell</para>
   </listitem>
   <listitem>
    <para>Make sure that your XML files are
     <emphasis>valid</emphasis>. You cannot build HTML or PDF with 
     invalid files.</para>
   </listitem>
   <listitem>
    <para>Your XML source code is <emphasis>profiled</emphasis> according to
     your settings. Find more in <xref linkend="sec.profiling"/>.</para>
   </listitem>
   <listitem>
    <para>The profiled XML sources are transformed into HTML or XSL-FO.</para>
   </listitem>
  </orderedlist>

  <sect2 id="sec.build.html">
   <title>Building HTML</title>
   <para>To build a HTML from the XML source code, you will see the following
    steps:</para>
   <orderedlist>
    <listitem>
     <para>According to your settings, the XML source codes will be profiled
      first</para>
    </listitem>
    <listitem>
     <para>The profiled XML sources are validated</para>
    </listitem>
    <listitem>
     <para>After the validation, the XML sources are transformed into HTML</para>
    </listitem>
   </orderedlist>

   <para>To build HTML do the following:</para>

   <procedure>
    <title>Building HTML</title>
    <step>
     <para>Open a shell with <keycombo>
       <keycap function="alt">Alt</keycap>
       <keycap>F2</keycap>
      </keycombo> and type <command>konsole</command></para>
    </step>
    <step>
     <para>Change the directory to your directory structure:</para>
     <screen>cd <replaceable>PATH_TO_YOUR_DIRECTORY</replaceable></screen>
    </step>
    <step>
     <para>Set up your shell to configure your environment. In general this is
      done with:</para>
     <screen>source ENV-SLPROF-html</screen>
    </step>
    <step>
     <para>Enter:</para>
     <screen>make html</screen>
     <para>This will profile the XML sources and transform this into HTML.</para>
    </step>
    <step>
     <para>Open a browser and access the HTML files under
      <filename>html</filename>.</para>
    </step>
   </procedure>
  </sect2>

  <sect2 id="sec.build.pdf">
   <title>Building PDF</title>
   <para>To build a PDF from the XML source code, you will see the following
    steps:</para>
  
   <orderedlist>
    <listitem>
     <para>According to your settings, the XML source codes will be profiled
      first</para>
    </listitem>
    <listitem>
     <para>The profiled XML sources are validated</para>
    </listitem>
    <listitem>
     <para>After a successful validation, the XML sources are transformed into
      a FO file. This is an intermediate format</para>
    </listitem>
   <listitem>
    <para>XEP reads the FO file, renders it in memory and save it as PDF</para>
   </listitem>
   </orderedlist>

   <para>To build a PDF do the following:</para>
   <procedure id="pro.building.pdf">
    <title>Building PDF</title>
    <step>
     <para>Open a shell with <keycombo>
       <keycap function="alt">Alt</keycap>
       <keycap>F2</keycap>
      </keycombo> and type <command>konsole</command></para>
    </step>
    <step id="st.building.pdf.cd">
     <para>Change the directory to your directory structure:</para>
     <screen>cd <replaceable>PATH_TO_YOUR_DIRECTORY</replaceable></screen>
    </step>
    <step>
     <para>Set up your shell to configure your environment. In general this is
      done with:</para>
     <screen>source ENV-SLPROF-print</screen>
    </step>
    <step>
     <para>Build your PDF with or without cropmarks:</para>
     <stepalternatives>
      <step>
       <para>With cropmarks:</para>
       <screen>make pdf</screen>
      </step>
      <step>
       <para>Without cropmarks:</para>
       <screen>make color-pdf</screen>
      </step>
     </stepalternatives>
    </step>
   </procedure>
  </sect2>

  <sect2 id="sec.build.rootid">
   <title>Transforming Only a Portion of the Book</title>
   <para>If you work on only one chapter, transforming the whole book is
        a waste of time. You can save time if you use the
          <varname>ROOTID</varname> parameter. For example, if you have
        a chapter with an <sgmltag class="attribute">id</sgmltag>
        attribute value of <sgmltag class="attvalue">chap.foo</sgmltag>,
        use the following procedure:</para>

   <procedure>
    <title>Transforming Only a Portion of the Book</title>
    <step>
     <para>Open a shell with <keycombo>
       <keycap function="alt">Alt</keycap>
       <keycap>F2</keycap>
      </keycombo> and type <command>konsole</command></para>
    </step>
    <step>
     <para>Set up your shell to configure your environment. In general this is
      done with:</para>
     <screen>source ENV-SLPROF-print</screen>
     <para>or</para>
     <screen>source ENV-SLPROF-online</screen>
     <para>depending on your desired output</para>
    </step>
    <step>
     <para>Open the chapter, appendix, glossary or preface that you are working
     on.</para>
    </step>
    <step>
     <para>Check your <sgmltag class="attribute">id</sgmltag> value by looking
      at the root element. Memorize this id.</para>
     <note>
      <title>Check Your <sgmltag>id</sgmltag> Attribute</title>
      <para>
       This mechanism only works if one of the top level elements
       (<sgmltag>chapter</sgmltag>, <sgmltag>appendix</sgmltag>,
       <sgmltag>preface</sgmltag>, or <sgmltag>glossary</sgmltag>) has an
       <sgmltag class="attribute">id</sgmltag> attribute. You cannot select a
       chapter without it. Insert an <sgmltag class="attribute">id</sgmltag>
       attribute into your top level element. Naming conventions are described
       in the style guide.
      </para>
     </note>
    </step>
    <step>
     <para>Build your output format:</para>
     <stepalternatives>
      <step>
       <para>For HTML:</para>
       <screen>ROOTID=<replaceable>THE_ROOT_ID_VALUE</replaceable> make html</screen>
      </step>
      <step>
       <para>For PDF:</para>
       <screen>ROOTID=<replaceable>THE_ROOT_ID_VALUE</replaceable> make pdf</screen>
      </step>
     </stepalternatives>
    </step>
    <step>
     <para>Open the result file as
      <filename><replaceable>THE_ROOT_ID_VALUE</replaceable>.html</filename> or
      <filename><replaceable>THE_ROOT_ID_VALUE</replaceable>.pdf</filename></para>
     <para>Be aware that for HTML a chapter is spread over different files.  The file
      <filename><replaceable>THE_ROOT_ID_VALUE</replaceable>.html</filename> is
      just the beginning. However this files contains links to everything
      inside the chapter.</para>
    </step>
   </procedure>
  </sect2>

  <sect2 id="sec.debugging">
   <title>Debugging PDFs</title>
   <para>In a PDF with lots of pages, it can be difficult to find the correct
    file if you find an error. For this purpose, we inserted the
    <emphasis>Debugging Mechanism</emphasis>.</para>
   <para>You only need to set an environment variable, and the process
    automatically generates a PDF with filenames in it. Of course, this PDF is
    only for debugging purposes and is not to be published!</para>
   <para>To create a PDF with filenames in it, do the following:</para>
   <procedure>
    <step>
     <para>Set the environment variable <envar>DRAFT</envar> to
      <option>yes</option>:</para>
     <screen>export DRAFT="yes"</screen>
    </step>
    <step>
     <para>Make sure that each root element in each file contains the attribute
      <sgmltag class="attribute">xml:base</sgmltag> with the filename in
      it:</para>
     <screen>&lt;sect1 id="sec.foo" xml:base="foo.xml"> ...</screen>
    </step>
    <step>
     <para>Re-create the PDF by running:</para>
     <screen>make force</screen>
    </step>
    <step>
     <para>The environment variable is now set. The PDF contains filenames in
      it.</para>
    </step>
   </procedure>
  </sect2>
 </sect1>


 <sect1 id="sec.troubleshooting">
  <title>Troubleshooting</title>
  <para></para>

   <sect2>
    <title>Fixing Errors</title>
    <para>
     Validation errors are fatal when they appear in the profiled
     source code. If some error occurs, you must modify the
     original source code in a way that the profiled code becomes
     valid. Therefore, you have to fix the error in a completely
     different file than where it is found in the first place. There are two
     mechanisms that may be used to validate the profiled source code:
    </para>

    <orderedlist>
     <listitem>
      <para><command>make <option>validate</option></command></para>
     </listitem>
     <listitem>
      <para><command>make <option>bigfile</option></command></para>
     </listitem>
    </orderedlist>

    <para>
     The target <command>make <option>bigfile</option></command> is a
     workaround for a bug in <command>xmllint</command> that occurs in versions
     before 2.6.15. When you use this target, you find the complete
     book in <filename>tmp/$(BOOK).xml</filename>. The only way to
     handle errors then is to look up the error in this huge file, and then
     find the same error somewhere in the xml sources to fix it.
    </para>
    <para>
     If you call <command>make <option>validate</option></command>,
     all validation errors will be listed with the filename and
     line number of the profiled sources. This means that, depending on
     the profiling options, the error might be exactly at the same
     place in the source files, or in a later line. If you have
     problems finding the error, you can look up the
     profiled sources at the specified line number and then find the same
     lines in the original files.
    </para>
    <para>
     If you get an error that says that, some element does not follow
     the DTD, you have another way to search for the problem:
    </para>
    <screen>Element table content does not follow the DTD, expecting
(title , tgroup), got (tgroup )
Document profiled/x86-amd64-em64t_slprof-slpers_0_0/MAIN.box.xml does not validate</screen>
    <para>
     In this example, the error first says, that the problem occurs
     in a table. The error also tells you which XML structure has been
     found, and what was expected. In this case, the DTD
     expected a title element inside the table before starting with
     the actual table content.
    </para>
    <para>
     Another common problem is having data outside of XML tags. Such
     an error may looks like the following:
    </para>
    <screen>Element table content does not follow the DTD, expecting
(title , tgroup), got (title <emphasis role="bold">CDATA</emphasis> tgroup )
Document profiled/x86-amd64-em64t_slprof-slpers_0_0/MAIN.box.xml does not validate</screen>
    <para>
     In this example, there is a character, that is not 
     whitespace between the title of a table and the table content.
     Please note that sometimes such characters are not displayed
     because they might not be a printable characters. In such cases,
     the easiest fix is to remove all whitespace, and then
     format the xml again.
    </para>
    <para>
     Most of the problems are found by <command>make
      <option>validate</option></command>, but a view things are not detected
     by this method. The FO-processor XEP detects at least one more type of
     problem: whether index ranges have matching start and end elements. This
     kind of error is quite clearly described in the output of XEP. If you have
     any doubt, please compare the specified elements with the original English
     version.
    </para>
   </sect2>

  <sect2>
   <title>Missing Font during build PDF</title>
   <para>If you build a PDF and XEP complains about some missing fonts you
    didn't install the configuration file for XEP. Look at <xref
     linkend="pro.building.pdf"/> and begin with <xref
     linkend="st.building.pdf.cd"/>. </para>

  </sect2>
 </sect1>

<!-- ******************************************************************* -->
 <sect1 id="sec.background">
  <title>Background Information</title>
  <para>You need this section only, if you need more in-depth information of
   some background information.</para>

  <sect2 id="sec.usingmake">
   <title>Using make</title>
   <para>
    The command line utility <command>make</command> reads a file
    <filename>Makefile</filename> that includes a rule set for creating and
    converting files. The <filename>Makefile</filename> in a project
    directory just includes the file <filename>common.mk</filename> in
    <filename
    class="directory">suselx/novdoc/make</filename>.
   </para>
   <para>
    First, select which project to work on. This is done
    by sourcing an ENV- file that contains the needed information to build a
    certain book.
   </para>
   <screen>source ENV-styleguide</screen>
   <para>
    After this, you can use the build environment in your current shell.
   </para>
  </sect2>

  <sect2 id="sec.profiling">
   <title>Profiling Books</title>
   <sect3>
    <title>Some Basics</title>
   <para>
     Before you create your HTML or PDF, you have to make a decision about
     <emphasis>profiling</emphasis>. Profiling describes a method that manages
     different <quote>versions</quote> in one file.
   </para>
   <para>
    For example, think of a chapter about installing a program on
    different processor architectures. Each must use different setup
    utilities and paths. One solution would be to write one
    chapter for each architecture. The problem is that there are more
    things that are similar than things that are different. Maintaining
    files that only differ in some minor paragraphs or sections is
    a nightmare.
   </para>
   <para>
    A solution is to use profiling. In general, you insert each architecture
    into <emphasis>one</emphasis> file and distinguish the different
    platforms with an XML attribute. The only drawback is that you have to
    extract the correct version that is <quote>buried</quote> in the
    file.
   </para>
   <para>
    To tell the build mechanics about the needed architectures, you need to
    make sure that the variables <systemitem>PROFARCH</systemitem> and
    <systemitem>PROFOS</systemitem> are set properly in your ENV- file. <xref
     linkend="ex.makedoc"/> shows you the content of the
    <filename>ENV-</filename> file that sets variables for this document. (See
    also <xref linkend="app.newproject"/>.)
   </para>
   <example id="ex.makedoc">
    <title>A <filename>ENV-*</filename> file</title>
    <screen># ENV file
. .env-profile                    <co id="co.makedoc.env-profile"/>

export MAIN=MAIN.makedoc.xml      <co id="co.makedoc.main"/>

export PROFARCH="x86;amd64;em64t" <co id="co.makedoc.profarch"/>
export PROFOS="slprof;slpers"     <co id="co.makedoc.profos"/>
export PROFCONDITION="print"      <co id="co.makedoc.condition"/>
export LAYOUT="flyer"             <co id="co.makedoc.layout"/>
export DISTVER=9.3                <co id="co.makedoc.distver"/>
</screen></example>
   <calloutlist>
    <callout arearefs="co.makedoc.env-profile">
            <para> Includes system relevant information. This is
              mandatory, and must be called at the beginning of this
              file.</para>
          </callout>
    <callout arearefs="co.makedoc.main">
     <para>
      Sets the main file that contains <quote>references</quote> to other
      chapters, appendixes, etc. This variable is mandatory.
     </para>
    </callout>
    <callout arearefs="co.makedoc.profarch">
     <para>
      Selects the architecture profiling information. This is an
      optional variable, but is most likely used in our books.
     </para>
    </callout>
    <callout arearefs="co.makedoc.profos">
     <para>
      Selects the operating system profiling information. This is
      an optional variable, but is most likely used in our books.
     </para>
    </callout>
    <callout arearefs="co.makedoc.condition">
     <para>
      Selects those parts of the book that are to be printed or made
      available online. Currently used parameters are print and
      online.
     </para>
    </callout>
    <callout arearefs="co.makedoc.layout">
      <para>Determines the layout of the book. The following values are
        possible:</para>
      <variablelist>
        <varlistentry>
          <term><option>flyer</option></term>
          <listitem>
            <para>Creates a flyer layout which is used for Quick Starts.
            It has usually two columns with small margins.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><option>pocket</option></term>
          <listitem>
            <para>Creates a pocket layout which is used mostly for the
              Start-Up guide. It has a smaller page format than the
              usual guides.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Empty, no value</term>
          <listitem>
            <para>Selects the default layout.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      
    </callout>
    <callout arearefs="co.makedoc.distver">
     <para>
       Sets the version of the current distribution. This is used to
       distinguish versions built with make dist.
     </para>
    </callout>
   </calloutlist>
   <para>
     As an author or user, you do not need to do anything special. The make
     process knows which files have been modified and must be profiled again.
     When changing profiling variables, the <filename>ENV-</filename> file has
     to be sourced again, and a make force command will redo the profiling.
   </para>
   </sect3>   
   <sect3>
    <title>Changes in <filename>MAIN*</filename> files</title>
    <para>The make mechanics can be used not only for Novdoc but for DocBook as
     well. For this reason, mechanic has to know which stylesheet to use
     for profiling. We have to use different stylesheets, because we have
     different DTDs. Each DTD needs a separate profiling stylesheet. In general,
     tey are all the same, but they differ in one part: which DOCTYPE they
     generate.</para>
    <para>To use it, insert the following line into the MAIN,  right after
     the XML declaration:</para>
    <screen>&lt;?xml-stylesheet
     href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" 
     type="text/xml" 
     title="Profiling step"?></screen>
    <para>The second line can be only one of the following:</para>
    <screen>urn:x-daps:xslt:profiling:novdoc-profile.xsl
urn:x-daps:xslt:profiling:docbook43-profile.xsl</screen>
    <para>The first line is the default and should be used. Insert the
     second line only if you use DocBook V4.3.</para>
   </sect3>
  </sect2>

  <sect2 id="sec.validatingbooks">
   <title>Validating Books</title>
   <para>
    Before you transform your XML document, you must take care that the
    <emphasis>complete</emphasis> document is valid. If only one file is
    invalid, the process stops and you do not get your desired
    output format. This has nothing to do with the make process itself. It is
    the design of XML. You can only get predicted results if the input
    files adhere to a certain structure. 
   </para>
   <para>
    If you want to validate your document without building, use the
    command
   </para>
<screen>make validate</screen>
   <para>The make process takes care of profiling the files then
    validates the entire document. To validate only single files, use:</para>
   <screen>make validatesingle</screen>

   <warning>
    <title>Validating Single Files</title>
    <para>Validating single files can give unexpected results. In general,
     some sections or files depend on others. This can make validation
     difficult.</para>
   </warning>
  </sect2>

  <sect2>
   <title>Adding Images</title>
   <para>
    Add new images under
    <filename
     class="directory">images/src</filename> in the
    subdirectory of the correct format. Currently, two
    formats are supported.
   </para>
   <variablelist>
    <varlistentry>
     <term>PNG (Portable Network Graphic)</term>
     <listitem>
      <para>
       This is a bitmap format that is used in our online versions (HTML) for
       all kinds of graphics. In the printed books, it is used for
       screenshots too.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>SVG (Scalable Vector Graphic)</term>
     <listitem>
      <para>
       This is a vector format that is used in our books (PDF) when
       available. It can be scaled to different resolutions and you always
       get very high quality.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    If you have a format that is not listed above, convert it into the
    supported format. For historical reasons, there is a FIG format, too. New
    files should be created and saved as SVG or PNG.
   </para>
   <note>
    <title>Support for Other Formats</title>
    <para>
     There is no need to use formats other than PNG. Other bitmap formats, like
     JPEG or GIF, can easily be converted into PNG. Make sure that you
     always use PNG.
    </para>
    <para>
     For other vector formats, check if your graphic program allows exporting
     SVG. If this is not possible, export to PNG. When in doubt, ask the
     authors of this guide.
    </para>
   </note>
  </sect2>

  <sect2 id="sec.trans.book">
   <title>Transforming Books</title>
   <para>
    Our books can be transformed into two target formats: HTML and PDF. Use
    HTML for online versions and PDF for a nice printout. To create HTML, type:
   </para>
   <screen>make html</screen>
   <para>To create PDF, type:</para>
   <screen>make pdf</screen>
   <para>
    This creates lots of messages. The HTML files are saved into
    <filename class="directory">html</filename>. To view it, point a browser
    to <filename>index.html</filename> in this directory.
   </para>
   <para> For creating a PDF, just enter <command>make</command>. The
        resulting PDF appears in the current directory and has the name
            <filename>$(<replaceable>BOOK</replaceable>).pdf</filename>.</para>
  </sect2>
 </sect1>


<!-- ******************************************************************* -->
 <sect1 id="sec.administration">
  <title>Notes on Administration</title>
  <para>You need this section only, if you need more in-depth information of
   configuration and administration of the whole build mechanic.</para>

  <sect2 id="sec.hyphenation">
   <title>Hyphenation</title>
   <para>You need to read this section only if you want to support a new
    language that is not available in our Subversion repository. Other users
    can skip this section.</para>
   <para>XEP supports hyphenation in different languages. It uses the same
    algorithm as LaTeX. Therefore you can use the same files from LaTeX in
    XEP.</para>
   <para>We distinguish between these two possible options:</para>
  <itemizedlist>
   <listitem>
    <para>Support a new language</para>
   </listitem>
   <listitem>
    <para>Provide exceptions to hyphenated words in a supported language</para>
   </listitem>
  </itemizedlist>

  <sect3>
   <title>Support a new Language</title>
   <para>The hyphenation algorithm uses hyphenation patterns to determine
    possible positions in a word. XEP stores this information in the files
    <filename>hyphen/*.tex</filename>.</para>
   <para>If you want to support a new language, proceed with following
    steps:</para>

   <procedure>
    <step id="st.hyphen.copy">
     <para>Copy the respective hyphenation pattern from LaTeX into <filename
       class="directory">hyphen</filename> in your XEP installation
      directory.</para>
    </step>
    <step>
     <para>Open the XEP configuration file, usually
      <filename>xep-daps.xml</filename>.</para>
    </step>
    <step>
     <para>Search for the following line:</para>
     <screen>&lt;languages default-language="en-US" xml:base="hyphen/"></screen>
    </step>
    <step id="st.hyphen.insertxml">
     <para>Insert after this line the following XML code:</para>
     <screen>&lt;language name="Czech" codes="cz">
       &lt;hyphenation pattern="czhyphen_rx.tex"/></screen>
     <para>In this example, you insert hyphenation patterns for Czech. The
      information can be found in file
      <filename>czhyphen_rx.tex</filename>.</para>
    </step>
    <step>
     <para>Repeat <xref linkend="st.hyphen.copy"/> to <xref
       linkend="st.hyphen.insertxml"/>, if you have other
      languages.</para>
    </step>
    <step>
     <para>Save the configuration file.</para>
    </step>
   </procedure>
  </sect3>

  <sect3>
   <title>Exceptions of Hyphenation</title>
   <para>Sometimes, the algorithm creates unwanted results. For this reason,
    you can insert exceptions of hyphenation. Do the following:</para>
   <procedure>
    <step>
     <para>Open the respective file for your language, for example
      <filename>hyphen.tex</filename> for English.</para>
    </step>
    <step>
     <para>If there is no line beginning with <literal>\hyphenation</literal>,
      insert the following code:</para>
     <screen>\hyphenation{%</screen>
    </step>
    <step>
     <para>Insert in the next line as many exceptions as you like. Each
      exception contains dashes to indicate the possible locations of
      hyphens. For example:</para>
     <screen>ap-pen-dix%
man-u-script%
man-u-scripts%</screen>
    </step>
    <step>
     <para>Terminate the line with:</para>
     <screen>}</screen>
    </step>
    <step>
     <para>Save the file.</para>
    </step>
   </procedure>
  </sect3>
 </sect2>
 </sect1>

<!-- ******************************************************************* -->
 <sect1 id="sec.notestranslations">
  <title>Notes on Translations</title>
  <para>If you are a translator, you probably need more specific information.
   This section gives a brief overview of what you need to know. If in doubt,
   contact the authors of this document.</para>

  <sect2>
   <title>Comments and Remarks</title>
   <para>Our XML source code contains comments in two forms: as XML
    comments and as
    remark elements. Both are used frequently and look like this:</para>
   <screen>&lt;!-- This is an XML comment --&gt;
... 
&lt;remark>Here comes a remark comment&lt;/remark></screen>
   <para>You do not need to translate comments. They are only informative text for
    writers or even for you. Sometimes there is language-specific information,
    so we inform you about these issues in a comment or remark.</para>
  </sect2>

  <sect2>
   <title>Screens</title>
   <para>Computer output and input often contains whitespace (space and
    linebreaks). Make sure that you do not insert or delete spaces inside a
    <sgmltag>screen</sgmltag> element. Every space here is considered
    essential.</para>
   <para>In general, <sgmltag>screen</sgmltag> contents should be translated
    only in rare cases.</para>
  </sect2>

  <sect2>
   <title>Entities</title>
   <para>Entities are placeholders for text or other XML structures. An entity
    name must never be translated! An entity looks like: <sgmltag
     class="genentity">entityname</sgmltag>.</para>
  </sect2>

  <sect2>
   <title>IDs in Elements</title>
   <para>Copy <sgmltag class="attribute">id</sgmltag> attributes from the
    original English source code to the target language. This is important. If
    you omit this step, correct references cannot be created. An id attribute
    looks like this (bold text):</para>
   <screen>&lt;sect1 <emphasis role="bold">id="sec.foo"</emphasis>>
...
&lt;/sect1</screen>
  </sect2>

  <sect2>
   <title>Be aware of Text between Tags</title>
   <para>The <quote>normal</quote> text occurs inside the <sgmltag>para</sgmltag>
element. However, there are some locations where text is not allowed. For example, a
description of a menu item is marked up with <sgmltag>menuchoice</sgmltag> and
<sgmltag>guimenu</sgmltag>. See <xref linkend="ex.menuchoice.correct"/>.</para>
   <example id="ex.menuchoice.correct">
    <title>Correct use of <sgmltag>menuchoice</sgmltag></title>
    <screen>&lt;menuchoice>
  &lt;guimenu>Alt&lt;/guimenu>
  &lt;guimenu>F2&lt;/guimenu>
&lt;/menuchoice></screen>
   </example>
   <para>Don't insert text between <sgmltag class="endtag">guimenu</sgmltag>
and <sgmltag class="starttag">guimenu</sgmltag> like in <xref
     linkend="ex.menuchoice.wrong"/>.</para>
   <example id="ex.menuchoice.wrong">
    <title>Incorrect use of <sgmltag>menuchoice</sgmltag></title>
    <screen>&lt;menuchoice>
  &lt;guimenu>Alt&lt;/guimenu> <emphasis role="bold">with</emphasis>
  &lt;guimenu>F2&lt;/guimenu>
&lt;/menuchoice></screen>
   </example>
  </sect2>

 </sect1>

<!-- ******************************************************************* -->
 <appendix id="app.newproject">
  <title>Adding a New Project</title>
  <para>
   When adding a new project, you can distinguish two cases. First, you want to
   reuse some of the existing chapters and, therefore, only need to create a new
   <filename>MAIN*.xml</filename> and a new <filename>ENV-*</filename> file.
   If you want to create a completely new project, you need to
   set up the directory structure and also put the Makefile in place.
  </para>
  <para>
   The main task of the Makefile is to include the ruleset provided in a system
   makefile named <filename>common.mk</filename>. You can copy the
   Makefile from another project and make sure that the path to
   <filename>novdoc</filename> is correct.
  </para>
  <para>
   In the <filename>ENV-*</filename> file you need to set several
   parameters, the following are mandatory:
  </para>
  <variablelist>
   <varlistentry>
    <term><systemitem>DTDROOT</systemitem>
    </term>
    <listitem>
     <para>
      This variable contains the absolute path to the novdoc directory
      on your system. This is usually done with a line like:
     </para>
     <screen>export DTDROOT=$(cd ../../novdoc; pwd)</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><systemitem>MAIN</systemitem></term>
    <listitem>
     <para>
      This is the MAIN file. The top level file of your document. All required files are
      included directly in this file, or in one of the included files.
      This file must exist in the <filename
      class="directory">xml</filename> subdirectory.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><systemitem>BOOK</systemitem></term>
    <listitem>
     <para>
      Use this variable to give your project a name. The resulting PDF
      will be named like that variable, extended by
      <filename class="extension">.pdf</filename>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  <para>
   Some necessary variables that are needed by the system must be loaded from
   the system profile. The current <filename>ENV-*</filename> contains the
   line:
  </para>
  <screen>. $DTDROOT/etc/system-profile</screen>
  <para>
   There are also several optional parameters you can set in this
   file. It is very important that you set the optional parameters after
   loading the system profile. The system profile removes all
   previously set optional values in order to have a clean environment. The
   following list gives an overview over currently available optional
   parameters.
  </para>
  <variablelist>
   <varlistentry>
    <term><systemitem>PROFOS</systemitem> and
    <systemitem>PROFARCH</systemitem></term>
    <listitem>
     <para>
      When using profiling attributes in your document, you need to
      select the needed parts by setting these variables.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><systemitem>FOPOPTIONS</systemitem></term>
    <listitem>
     <para>
      The default value of <systemitem>FOPOPTIONS</systemitem> is
      <option>-q</option>. This changes the behaviour of the
      FO-Processor (XEP and FOP) to be less verbose about what it does.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><systemitem>COMMENTS</systemitem></term>
    <listitem>
     <para>
      You might want to print the comments you include in a document. To print
      your remakrs in the PDF, set <systemitem>COMMENTS</systemitem> variable
      to 1.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  <para>
   For the various transforming processes, make needs several directories are
   needed by make. These have to be provided in each project
   directory.
  </para>
 </appendix>

<!-- ******************************************************************* -->

 <appendix id="app.reference">
  <title>Make Targets Reference</title>  
  
  <refentry id="blub">
   <refentryinfo>
    <title>buildbooks</title>
   </refentryinfo>
   <refmeta>
    <refentrytitle>buildbooks</refentrytitle>
    <manvolnum>1</manvolnum>
   </refmeta>
   <refnamediv id="buildbooks">
    <refname>buildbooks</refname>
    <refpurpose>Building Books with make</refpurpose>
   </refnamediv>

   <refsect1 id="maketargets">
    <title>Make Targets</title>
    <para>Use the following syntax:</para>
    <cmdsynopsis><command>make</command> <arg choice="opt">TARGET</arg></cmdsynopsis>
    <cmdsynopsis><command>make</command> <arg choice="plain">ROOTID=<arg
       choice="req">ID_VALUE</arg></arg> <arg choice="opt">BUILDTARGET</arg>
    </cmdsynopsis>
    <para>
     The optional <replaceable>TARGET</replaceable> argument can
     be a BUILDTARGET, or some other target. The BUILDTARGETS can have
     one or more of the following names:
    </para>
    <variablelist>
     <varlistentry>
      <term><option>pdf</option></term>
      <listitem>
       <para>Creates PDF with cropmarks and with grey images. This is the
	default target.</para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>color-pdf</option></term>
      <listitem>
       <para>Creates PDF without cropmarks and with color images.</para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>force</option></term>
      <listitem>
       <para>
	This is just like the pdf target, but every source file is 
        profiled again. This is useful when you make
        changes to the build environment that make cannot detect. 
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>html</option></term>
      <listitem>
       <para>
        Creates HTML. The resulting document can be found in the
        html subdirectory with index.html being the starting point. If
	you use a ROOTID, the starting point will be
	html/$(ID_VALUE).html.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
    <para>
     The following are common targets where
     <replaceable>ROOTID</replaceable> does not have any effect:
    </para>
    <variablelist>
     <varlistentry>
      <term><option>check</option></term>
      <listitem>
       <para>
        Print the values of several variables that are used in the
        Makefile.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>clean</option></term>
      <listitem>
       <para>
        Remove all profiled files as well as temporary files. Does not
	remove books that have been made.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>configure</option></term>
      <listitem>
       <para>
        Starts a reconfiguration of the currently used
	<command>xep-suse</command> script. This is necessary after an update,
	when a change in the <filename>xep-daps.xml</filename> file has
	changed. If unsure, just run the command. See also the target
	<option>update</option>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>directories</option></term>
      <listitem>
       <para>
        Create a template directory structure.
        When creating a completely new project, you may just create
	the main directory, and copy the file
	<filename>Makefile</filename> from an existing project. Make
	sure that the path to <filename>common.mk</filename> in
	Makefile is correct and run make directories.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>dist-html</option></term>
      <listitem>
       <para>
        Create html and desktop packages. These are needed to submit
	the packages of the distribution. Resulting files are
	$(BOOK)_$(LANG)-desktop.tar.bz2 and
	$(BOOK)_$(LANG)-html.tar.bz2 where $(LANG) is selected by the
	lang attribute of $(MAIN).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>filelist</option></term>
      <listitem>
       <para>
        Creates a list of all xml files used in the current book. You
	might want to add the entity file to complete this list.
       </para>      
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>dist-xml</option></term>
      <listitem>
       <para>
	Create packages of the unprofiled xml files and of the
	profiled xml files in .zip archives. The
        resulting name is $(BOOK)_$(LANG)-src.zip for the unprofiled xml and
	$(BOOK)_$(LANG).zip for the profiled version. If one of these files
	already exists, it is renamed with the old script.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>dist-graphics</option></term>
      <listitem>
       <para>
        Create package of the PNG and SVG files that are used in the
	current project. The name of the archive is
	$(BOOK)_$(LANG)-graphics.tar.bz2 where $(LANG) is selected by
	the lang attribute of $(MAIN).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>showgfx</option></term>
      <listitem>
       <para>
        Print a list of the images that are missing from the currently selected
	book.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>show-remarks</option></term>
      <listitem>
       <para>
        Show all the remarks in a selected book. In oXygen, the
	displayed xpath may also be used to jump to the remark 
	in the source xml file.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>update</option></term>
      <listitem>
       <para>
        Get all updates of the stylesheets and make mechanics. After this, the
	profiling step of all source files is performed during the next
	rebuild. See also the target <option>configure</option>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>validate</option></term>
      <listitem>
       <para>
        Update the profiling step and validate the profiled book.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><option>validatesingle</option></term>
      <listitem>
       <para>
	Validate each individual file of the XML source, rather than the entire
	book.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
    <para>
     The variable <replaceable>ID_VALUE</replaceable> can contain any
     chapter or section id. In this case, the basename of the
     resulting pdf or html will be this id.
    </para>
   </refsect1>
  </refentry>
 </appendix>


<!-- ******************************************************************* -->
 <glossary id="glossary">
  <title>Glossary</title>
  <glossentry id="gl.dtd">
   <glossterm>DTD (Document Type Definition)</glossterm>
   <glossdef>
    <para>A document type definition (DTD) is a set of declarations
     that conform to a particular markup syntax. It describes a class, or
     type, of SGML or XML documents. With a DTD, XML documents
     can be validated. This is useful if you want to check the allowed
     structure for a certain XML instance. </para>
   </glossdef>
  </glossentry>
  <glossentry id="gl.profiling">
   <glossterm>profiling</glossterm>
   <glossdef>
    <para>Profiling describes a filtering mechanism. An XML document can hold
     different versions in <emphasis>one</emphasis> file, like different
     architectures, platforms, operating systems, or user levels. The author
     inserts profiling information into XML documents at specific places and
     the profiling mechanism selects only those parts that are relevant. This
     solves the problem of having lots of files with only minor
     differences. The author has to maintain only one file, but has to take
     care of the correct profiling information.</para>
    <para>Profiling information is inserted with the attributes <sgmltag
      class="attribute">os</sgmltag> and <sgmltag>arch</sgmltag>.</para>
   </glossdef>
  </glossentry>
  <glossentry>
   <glossterm>&prof;</glossterm>
   <glossdef>
    <remark>ENV files, ENV profiles, project specific env files, project profile</remark>
    <para>Project profiles contain information needed to select the
     correct profiling information. The first step to build a book is to
     <emphasis>source</emphasis> the project profile in your current shell.
     This sets all the relevant variables needed by our
     Makefiles.</para>
    <glossseealso otherterm="gl.profiling"/>
   </glossdef>
  </glossentry>
  <glossentry id="gl.valid">
   <glossterm>valid</glossterm>
   <glossdef>
    <para>Valid means that an XML document is well-formed and adheres to a
     certain DTD.</para>
    <glossseealso otherterm="gl.dtd"/>
    <glossseealso otherterm="gl.wellformed"/>
   </glossdef>
  </glossentry>
  <glossentry id="gl.wellformed">
   <glossterm>well-formed</glossterm>
   <glossdef>
    <para>An XML document is well-formed if a start tag and an end tag have the
     same name, each tag contains only valid characters according to the XML
     specification, the nesting is correct (every start tag must have a
     corresponding end tag), and attribute values are enclosed by single
     (<literal>&apos;</literal>) or double quotes (<literal>&quot;</literal>).
    </para>
   </glossdef>
  </glossentry>
  <glossentry id="gl.xslfo">
   <glossterm>XSL-FO (XSL Formatting Objects)</glossterm>
   <glossdef>
    <para>XSL-FO (or just FO) is a specification for describing page
     layouts. The book production process needs it as an intermediary file for
     building PDFs.</para>
   </glossdef>
  </glossentry>

 </glossary>

<!-- ******************************************************************* -->
 <bibliography id="biblio">
  <title>Links</title>
  <biblioentry id="bib.dbtdg">
   <abbrev>docbook-tdg</abbrev>
   <title>DocBook&mdash;The Definitive Guide</title>
   <bibliosource><ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/></bibliosource>
   <authorgroup>
    <author>
     <firstname>Norman</firstname>
     <surname>Walsh</surname>
    </author>
    <author>
     <firstname>Leonard</firstname>
     <surname>Muellner</surname>
    </author>
   </authorgroup>
  </biblioentry>
  <biblioentry id="bib.svn">
   <abbrev>cvs</abbrev>
   <title>Version Control with Subversion</title>
   <bibliosource><ulink url="http://svnbook.red-bean.com/"/></bibliosource>
   <authorgroup>
    <author>
     <firstname>Ben</firstname>
     <surname>Collins-Sussman</surname>
    </author>
    <author>
     <firstname>Brian</firstname>
     <othername>W.</othername>
     <surname>Fitzpatrick</surname>
    </author>
    <author>
     <firstname>Michael</firstname>
     <surname>Pilato</surname>
    </author>
   </authorgroup>
  </biblioentry>
  <biblioentry id="bib.usingsvn">
   <abbrev>using.svn</abbrev>
   <title>Using Subversion</title>
   <authorgroup>
    <author>
     <firstname>Berthold</firstname>
     <surname>Gunreben</surname>
    </author>
    <author>
     <firstname>Thomas</firstname>
     <surname>Schraitle</surname>
    </author>
   </authorgroup>
   <bibliosource></bibliosource>
  </biblioentry>
 </bibliography>

</article>
