Added documentation about the document building system. Dropped the

one-line "converting" chapter by creating a "Prerequisites" section
in the "getting-files" section.

6 files changed, 364 insertions, 81 deletions

diff --git a/Makefile b/Makefile
index 49c1461..f6edc50 100644
--- a/Makefile
+++ b/Makefile
@@ -1,15 +1,19 @@
-###############################################################################
+#######################################################################
 # Makefile for RHLP docs project
 # Created by: Tammy Fox <tfox@redhat.com>
 # Last edited by: Tammy Fox <tfox@redhat.com>
 # WARNING: need passivetex 1.24 for pdf generation to work
 # License: GPL
 # Copyright 2003 Tammy Fox, Red Hat, Inc.
-###############################################################################
+#######################################################################
 
 LANGUAGES	       	= en zh_CN
 DOCBASE 	       	= documentation-guide
-XMLEXTRAFILES-en	=
+XMLEXTRAFILES-en=acknowledgments-en.xml docs-emacs-en.xml               \
+        docs-emacs-nxml-en.xml docs-getting-files-en.xml                \
+        docs-intro-en.xml docs-rh-guidelines-en.xml docs-style-en.xml   \
+        docs-tutorial-en.xml docs-vim-en.xml docs-xml-tags-en.xml       \
+        documentation-guide-en.xml
 
 ######################################################
 include ../docs-common/Makefile.common
diff --git a/acknowledgments-en.xml b/acknowledgments-en.xml
index 7e53ae5..c7dc535 100644
--- a/acknowledgments-en.xml
+++ b/acknowledgments-en.xml
@@ -37,4 +37,9 @@
       linkend="s1-xml-tags-screen"></xref>.
     </para>
 
+    <para>
+     A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been 
+     applied to more fully explaing the document building system.
+    </para>
+
   </chapter>
diff --git a/docs-converting-en.xml b/docs-converting-en.xml
deleted file mode 100644
index ac0684b..0000000
--- a/docs-converting-en.xml
+++ /dev/null
@@ -1,20 +0,0 @@
-<!-- $Id: docs-converting-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ -->
-
-<chapter id="ch-converting">
-  <title>Converting to HTML and PDF</title>
-
-  <para>
-    Each directory containing a document also has a Makefile. In the directory,
-    run the command <command>make html</command> to build the HTML version and
-    <command>make pdf</command> to build the PDF version.
-  </para>
-  
-  <warning>
-    <title>Warning</title>
-    <para>
-      The PDF production is somewhat fragile right now. It may or may not
-      work.
-    </para>
-  </warning>
-
-</chapter>
diff --git a/docs-converting-zh_CN.xml b/docs-converting-zh_CN.xml
deleted file mode 100644
index dc06576..0000000
--- a/docs-converting-zh_CN.xml
+++ /dev/null
@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- $Id: docs-converting-zh_CN.xml,v 1.1 2005/12/09 15:28:54 bbbush Exp $ --><chapter id="ch-converting">
-  <title>生成 HTML 及 PDF</title>
-  <para>每个包含文档的目录都有一个 Makefile。在这个目录下，运行命令 <command>make html</command> 来生成 HTML 版本，运行 <command>make pdf</command> 来生成 PDF 版本。</para>
-  <warning>
-    <title>警告</title>
-    <para>PDF 的生成仍然不完善，可能无法工作。</para>
-  </warning>
-</chapter>
diff --git a/docs-getting-files-en.xml b/docs-getting-files-en.xml
index 21481d1..abed9c4 100644
--- a/docs-getting-files-en.xml
+++ b/docs-getting-files-en.xml
@@ -1,83 +1,389 @@
 <!-- $Id: -->
 <!--
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 
- <!ENTITY BOILERPLATE "This header makes editing XML easier" >
+<!ENTITY BOILERPLATE "This header makes editing XML easier" >
+<!ENTITY FDPX         "Fedora Docs Project"                 >
+<!ENTITY FED          "Fedora"                              >
 
 ]>
 -->
 <chapter id="ch-getting-files">
-   <title>Getting the Files</title>
+  <title>Prerequisites</title>
 
+  <para>
+    Before you being working with the &FED; documents, you must have certain tools and packages installed on your system.
+    The directions below will help you configure your setup.
+  </para>
+
+  <section id="ch-getting-files-system-packages">
+    <title>System Packages</title>
     <para>
-      To start working on the Docs Project, you will need the appropriate
-      DocBook XML files, stylesheets, and scripts. The following packages are
-      required:
-    </para>
+    To start working on the Docs Project, you will need the appropriate DocBook XML files, stylesheets, and scripts.
+    The following packages are required:
+  </para>
 
     <itemizedlist>
       <listitem>
-  <para><filename>xmlto</filename> &mdash; for producing HTML and PDF outputs</para>
+        <para>
+          <filename>xmlto</filename> &mdash; for producing HTML and PDF outputs.
+      </para>
       </listitem>
       <listitem>
-  <para><filename>docbook-style-xsl</filename> &mdash; for the default XSLT stylesheets we
-  build on</para>
+        <para>
+          <filename>docbook-style-xsl</filename> &mdash; for the default XSLT stylesheets we build on.
+      </para>
       </listitem>
       <listitem>
-  <para><filename>docbook-dtds</filename> &mdash; XML versions of the DocBook DTD</para>
+        <para>
+          <filename>docbook-dtds</filename> &mdash; XML versions of the DocBook DTD
+      </para>
       </listitem>
     </itemizedlist>
 
     <para>
-      The custom scripts and stylesheets used are all stored in CVS on the
-      <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS server.
-      You need to check them out along with the DocBook XML files for the
-      existing docs.
-    </para>
+    You can verify these packages are on your system by:
+  </para>
+
+    <screen>
+      <userinput>
+rpm -q xmlto
+rpm -q docbook-style-xsl
+rpm -q docbook-dtds
+</userinput>
+    </screen>
 
     <para>
-      You should perform these steps only once, when you first make a checkout
-      from docs CVS.  When you see the password prompt, press the
-      <keycap>Enter</keycap> key.
-    </para>
+    Any missing package can be installed using <application>yum(8)</application> this way:
+  </para>
+
+    <screen>
+      <userinput>
+su -c 'yum install xmlto'
+su -c 'yum install docbook-style-xsl'
+su -c 'yum install docbook-dtds'
+</userinput>
+    </screen>
+  </section>
+  <section id="ch-getting-files-fdp">
+    <title>Fedora Documentation Tools</title>
+
+    <para>
+    You need perform these steps only once.
+    These files are common to all the &FDPX; documents.
+  </para>
+
+    <para>
+    The custom scripts and stylesheets used are all stored in CVS on the <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS server.
+    You need to check them out along with the DocBook XML files for the existing docs.
+  </para>
+
+    <para>
+    When you see the password prompt, press the <keycap>Enter</keycap> key.
+    In the example below, we also show how to obtain a copy of an existing &FDPX; document.
+  </para>
 
-<screen>
-<userinput>mkdir my-fedora-docs
-cd my-fedora-docs
+    <screen>
+<userinput>mkdir my-fedora-docs-sandbox
+cd my-fedora-docs-sandbox
 export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs
 cvs login
 cvs co docs-common
 cvs co example-tutorial</userinput>
 </screen>
-
+  </section>
+  <section id="ch-getting-files-filenames">
+    <title>Filename Conventions</title>
     <para>
-      When you perform an anonymous CVS checkout, you can view the files and
-      retreive the latest versions.  You cannot add (commit) any updates or new
-      files back to the repository.  To commit changes to CVS, you must have
-      <abbrev>CVS</abbrev> write access.  Refer to <ulink
-      url="http://fedoraproject.org/wiki/DocsProject/NewWriters"/> to learn
-    about getting write access to <abbrev>CVS</abbrev>.
+      &FDPX; provides the tools, scripts, and stylesheets to transform your <abbrev>XML</abbrev> documents into either <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> output formats.
+      In addition, your document can automatically be built into an <abbrev>RPM</abbrev> package.
     </para>
-
     <para>
-      To see a list of the available documents:
+      To take advantage of these services, you should follow our conventions for naming your files.
+      While you may choose whatever filenames you like, adopting our practices will make your life simpler.
+      Of course, if you are bringing your own document into our building system, changing hundreds of filenames may seem quite a burden; relax, we can use your filenames with just a little work on your part.
+      Read on to find out how.
     </para>
-
-<screen><userinput>cvs co -c</userinput></screen>
-
+    <section id="ch-getting-files-filenames-doc">
+      <title>Document Filenames</title>
+      <para>
+        Each document lives in a peer directory to the <filename>docs-common</filename> directory you extracted from the &FED; archive earlier.
+        Name your document directory something related to its subject, just avoid any name already taken.
+        The <userinput>cvs co -c</userinput> command mentioned earlier will show you the names already taken.
+      </para>
+    </section>
+    <section id="ch-getting-files-i18n">
+      <title>Anticipating I18N Translation</title>
+      <para>
+        The &FDPX; includes an active translation team.
+        Project documents are often translated into several languages.
+        By convention, the translated files share the directory with the original files; filenames must be unique.
+      </para>
+      <para>
+        &FDPX; filenames are constructed appending a dash followed by the <abbrev>ISO</abbrev> language symbol before any file extention.
+        For example, a file whose language content is <abbrev>US</abbrev> English could be named <filename>mydoc-en.xml</filename>; the file containing its Chinese translation would then be named <filename>mydoc-zh_CN.xml</filename>, and so on.
+      </para>
+      <para>
+        To assist this effort, the document build system assumes that each file is tagged with its <abbrev>I18N</abbrev> locale.
+        Our filename convention is shown in <xref linkend="ch-getting-files-i18n-table"/>
+      </para>
+      <table id="ch-getting-files-i18n-table">
+        <title>&FDPX; Filename Conventions</title>
+        <tgroup cols="2">
+          <colspec align="right" colnum="1" colwidth="*1"/>
+          <colspec colnum="2" colwidth="*5"/>
+          <thead>
+            <row>
+              <entry>
+                <phrase>Compoment</phrase>
+              </entry>
+              <entry>
+                <phrase>Description</phrase>
+              </entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>
+                <phrase><replaceable>anything_but_dash</replaceable></phrase>
+              </entry>
+              <entry>
+                <para>
+                  The initial portion of a filename can be anything, as long as <emphasis>no dash</emphasis> is used.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <phrase><filename>-</filename></phrase>
+              </entry>
+              <entry>
+                <para>
+                  A dash (<filename>-</filename>) is to be used only to introduce the <systemitem class="macro">${LANG}</systemitem> filename component.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <phrase><systemitem class="macro">${LANG}</systemitem></phrase>
+              </entry>
+              <entry>
+                <para>
+                  The <systemitem class="macro">${LANG}</systemitem> component identifies the <wordasword>locale</wordasword> for the file content.
+                </para>
+                <para>
+                  In addition to helping classify files according to their language content, we also use the <systemitem class="macro">${LANG}</systemitem> value as an <abbrev>UTF-8</abbrev> locale when rendering the document.
+                  For example, the document <filename>mydoc-it.xml</filename>will be rendered using <systemitem class="resource">it.UTF-8</systemitem> as the language environment.
+                </para>
+                <para>
+                  For more information on <abbrev>I18N</abbrev> localization, visit the <ulink url="http://www.openi18n.org"/> web site.
+                </para>
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <warning>
+        <title>Document Filenames Are Special</title>
+        <para>
+          The main file in your document <emphasis>must</emphasis> follow the file naming convention or the document building system cannot find it.
+        </para>
+      </warning>
+    </section>
+  </section>
+  <section id="ch-getting-files-build-system">
+    <title>The Document Build System</title>
     <para>
-      Pick your document of interest and then download it to your working directory:
+      Common tasks such as rendering the document into either <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> can be performed easily using the document building system.
     </para>
-
-<screen><userinput>cvs co example-tutorial</userinput></screen>
-
     <para>
-      Except for the <citetitle>&IG;</citetitle>, all documentation in CVS must
-      be tutorials written in DocBook XML article format using the template in
-      the <filename>example-tutorial</filename> directory. Each tutorial
-      <emphasis>must</emphasis> be in its own directory. No XML files should be
-      in the root directory.
+      The building system heavily leverages the <application>make(1)</application> tool and shell scripts to automate these activities, but authors need <emphasis>no</emphasis> prior experience with either shell scripts or a <filename>Makefile</filename>.
+      While individual documents do have their own <filename>Makefile</filename>, it is only a few lines long and very simple.
+      The document <filename>Makefile</filename> content is designed for cut&apos;s paste.
     </para>
+    <para>
+      As an example, <xref linkend="ch-getting-files-build-system-makefile"/> shows the whole <filename>Makefile</filename> for a simple document having only one file and one language.
+    </para>
+    <example id="ch-getting-files-build-system-makefile">
+  <title>Sample Document Makefile</title>
+<programlisting width="60">
+DOCBASE        	= mydoc
+LANGUAGES      	= en
+XMLEXTRAFILES-en=
+include ../docs-common/Makefile.common
+</programlisting>
+</example>
+    <para>
+      Our main <abbrev>XML</abbrev> file is <filename>mydoc-en.xml</filename>; no translation has been done yet.
+    </para>
+    <para>
+      The <systemitem class="macro">LANGUAGES</systemitem> definition lists the English locale <literal>en</literal>; when other translations become available, their locale will just be appended to this definition.
+    </para>
+    <para>
+      Our document has only the main file <filename>mydoc-en.xml</filename>, but other documents may be split over several files.
+      The <systemitem class="macro">XMLEXTRAFILES-en</systemitem> definition catalogs these additional files so that the document building system can watch them for changes and rebuild the document when necesssary.
+      This definition is just a simple list of files.
+    </para>
+    <para>
+      The final line, beginning with <literal>include</literal>, references the main <filename>Makefile</filename> for the build system.
+      The <filename>Makefile.common</filename> file contains all the <application>make(1)</application> targets and rules to actually build the document and the various archives.
+    </para>
+    <para>
+      Add new document translations by:
+    </para>
+    <orderedlist>
+      <listitem>
+        <para>
+          Add the translated document files to the document directory.
+          Be sure to use the proper <systemitem class="macro">${LANG}</systemitem> filename component to keep the filenames similar, but unique.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Edit the <filename>Makefile</filename> to append the new <systemitem class="macro">${LANG}</systemitem> to the <systemitem class="macro">LANGUAGES</systemitem> definition.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Create a new <systemitem class="macro">XMLEXTRAFILES-${LANG}</systemitem> definition that references any document files other than the base file.
+        </para>
+      </listitem>
+    </orderedlist>
+    <section id="ch-getting-files-build-system-targets">
+      <title>Build System Actions</title>
+      <para>
+        To render the <abbrev>XML</abbrev> document into <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> the command: <userinput>make html</userinput>,
+        <userinput>make html-nochunk</userinput>, or <userinput>make pdf</userinput> may be used.
+      </para>
+      <para>
+        <xref linkend="ch-getting-files-build-system-targets-table"/> lists the defined build system targets.
+      </para>
+      <table id="ch-getting-files-build-system-targets-table">
+        <title>Document Building Targets</title>
+        <tgroup cols="2">
+          <colspec align="right" colnum="1" colwidth="*1"/>
+          <colspec colnum="2" colwidth="*5"/>
+          <thead>
+            <row>
+              <entry><phrase>Target</phrase></entry>
+              <entry><phrase>Description</phrase></entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><phrase><filename>all</filename></phrase></entry>
+              <entry>
+                <para>
+                  Builds the <abbrev>HTML</abbrev>, and the <abbrev>PDF</abbrev> forms of the document in all its defined translations.
+                </para>
+                <para>
+                  Also builds the archives, such as <application>tar(1)</application> and <application>rpm(8)</application>.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>tarball</filename></phrase></entry>
+              <entry>
+                <para>
+                  Builds only the <application>tar(1)</application> archive for all document languages.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>pdf</filename></phrase></entry>
+              <entry>
+                <para>
+                  Builds only the <abbrev>PDF</abbrev> document for all document languages.
+                </para>
+                <para>
+                  Currently, <abbrev>PDF</abbrev> production is problematic and probably will not work for your document.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>html</filename></phrase></entry>
+              <entry>
+                <para>
+                  Builds only the <abbrev>HTML</abbrev> document for each defined translation.
+                  Output is placed in a separate directory:
+                  <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>/</filename>; each document section is given its own file within that directory.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>html-nochunks</filename></phrase></entry>
+              <entry>
+                <para>
+                  Builds only the <abbrev>HTML</abbrev> document for each defined translation.
+                  Output is placed in a single file:
+                  <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>.html</filename>; no other files are created.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>clean</filename></phrase></entry>
+              <entry>
+                <para>
+                  Deletes any temporary, or generated files.
+                  Does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, or archive files.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry><phrase><filename>distclean</filename></phrase></entry>
+              <entry>
+                <para>
+                  Erases all <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, and archive files.
+                  Automatically invokes the <filename>clean</filename> target as well.
+                </para>
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <para>
+        You can add your own special targets and rules by placing them at the bottom of the document <filename>Makefile</filename>, below the <literal>include</literal> line.
+      </para>
+      <para>
+        Be sure to follow your target definitions with a double colon, not just one.
+        This will allow you to supply extra steps for the defined targets.
+      </para>
+    </section>
+    <section id="ch-getting-files-build-system-images">
+      <title>Finding Document Image Files</title>
+      <para>
+        Image files, such as <filename>.PNG</filename>, are often used in documents.
+        While your image files may be placed anywhere you like, we recommend that you store your image files in a <filename>figs/</filename> subdirectory within your document directory.
+        In other words, place your image <filename>picture.png</filename> in the <filename>mydoc/figs/picture.png</filename> file.
+      </para>
+      <para>
+        You may organize your image files into as many subdirectories under <filename>figs/</filename> as you choose.
+        The document building system will recreate your image subdirectory structure in the output documents.
+      </para>
+      <para>
+        In addition, we recommend that you follow our convention on naming the image.
+        For example, an image often contains a caption or other text.
+        This text should be translated along with the document content, so keeping <filename>words-en.png</filename> separate from <filename>words-ru.png</filename> is a good practice.
+      </para>
+      <para>
+        Sometimes, a document may require images that do not follow the naming convention.
+        You may still use these images with the document building system, but it requires that you create an ordinary text file containing the image filenames you want to use.
+        This file must be named <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> so that the build system can find it as the search for image filenames begins.
+      </para>
+      <para>
+        An easy way to create the <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> file is shown in <xref linkend="ch-getting-files-build-system-manifest"/>.
+      </para>
+      <example id="ch-getting-files-build-system-manifest">
+  <title>Building A Manifest</title>
+<programlisting>
+rm -f figs/Manifest-en
+find figs -print >/tmp/manifest
+mv /tmp/manifest figs/Manifest-en
+vi figs/Manifest-en
+</programlisting>
+</example>
 
-  </chapter>
+    </section>
+  </section>
+</chapter>
diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml
index 8c1240d..7d7ad19 100644
--- a/documentation-guide-en.xml
+++ b/documentation-guide-en.xml
@@ -1,4 +1,4 @@
-<!-- $Id: documentation-guide-en.xml,v 1.21 2005/09/19 00:00:31 pfrields Exp $ -->
+<!-- $Id: documentation-guide-en.xml,v 1.22 2005/12/13 21:56:24 jtr Exp $ -->
 <!-- breaks the build ... <?xml version="1.0" encoding="utf-8"?> -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
@@ -22,7 +22,6 @@
 <!ENTITY VIM SYSTEM "docs-vim-en.xml">
 <!ENTITY TAGS SYSTEM "docs-xml-tags-en.xml">
 <!ENTITY TUTORIAL SYSTEM "docs-tutorial-en.xml">
-<!ENTITY CONVERTING SYSTEM "docs-converting-en.xml">
 <!ENTITY CVS SYSTEM "../docs-common/common/cvs-en.xml">
 <!ENTITY ACKNOWLEDGMENTS SYSTEM "acknowledgments-en.xml">
 <!ENTITY STYLE SYSTEM "docs-style-en.xml">
@@ -76,8 +75,6 @@
 
   &STYLE;
 
-  &CONVERTING;
-
   &CVS;
 
   &ACKNOWLEDGMENTS;