Exclude nxml chapter for now, and reorganize first chapter

4 files changed, 372 insertions, 324 deletions

diff --git a/en_US/acknowledgments.xml b/en_US/acknowledgments.xml
index 9a71775..47a3f11 100644
--- a/en_US/acknowledgments.xml
+++ b/en_US/acknowledgments.xml
@@ -25,8 +25,8 @@
     <para>
       Patches from Gavin Henry (ghenry at suretecsystems.com) have been applied
       to add the trailing slashes to the <command>figure</command> tag example
-      in <filename>docs-xml-tags.xml</filename> and to add <xref
-      linkend="ch-emacs-nxml"></xref>.
+      in <filename>docs-xml-tags.xml</filename><!-- and to add <xref
+      linkend="ch-emacs-nxml"></xref>-->.
     </para>
 
     <para>
diff --git a/en_US/docs-getting-files.xml b/en_US/docs-getting-files.xml
index 6e762ea..c86a6d4 100644
--- a/en_US/docs-getting-files.xml
+++ b/en_US/docs-getting-files.xml
@@ -1,5 +1,5 @@
 <!-- $Id: -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!-- *************** Bring in Fedora entities *************** -->
@@ -13,7 +13,7 @@
 
   <para>
     To work on official &FED; documentation you need to install the required
-    tools.  The directions below will help you configure your setup.
+    tools.  Follow the directions below to configure your system.
   </para>
 
   <section id="ch-getting-files-system-packages">
@@ -44,7 +44,7 @@
 
     <para>
       The &FDP;'s custom scripts and stylesheets are stored in CVS on the
-      <systemitem class="fqdomainname">cvs.fedora.redhat.com</systemitem> CVS
+      <systemitem class="fqdomainname">cvs.fedoraproject.org</systemitem> CVS
       server.  Check them out along with the DocBook XML files for the existing
       docs.
     </para>
@@ -52,7 +52,7 @@
 <screen>
 <userinput>mkdir <replaceable>my-fedora-docs-sandbox</replaceable>
 cd <replaceable>my-fedora-docs-sandbox</replaceable>
-export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs
+export CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fedora.redhat.com:/cvs/docs
 cvs login
 cvs co docs-common</userinput>
 </screen>
@@ -64,8 +64,9 @@ cvs co docs-common</userinput>
     <note>
       <title>Common Files</title>
       <para>
-	You need to perform these steps only once.  These files are common to
-	all the official documentation.
+	You need to perform this "checkout" step only once, although you may
+	need to update the files later.  These files are common to all the
+	official documentation.
       </para>
     </note>
 
@@ -75,18 +76,14 @@ cvs co docs-common</userinput>
 
   </section>
 
-  <!-- Starting here, the information is EXTREMELY useful but goes way outside
-  the scope of the chapter.  This stuff needs to be relocated in the redesigned
-  DocGuide. [PWF, 2006-01-03] -->
-
   <section id="ch-getting-files-filenames">
     <title>Filename Conventions</title>
     <para>
       &FDP; 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, these tools can build
-      your document into an <abbrev>RPM</abbrev> package.  To take advantage of
-      these services, you must follow conventions for naming your files.
+      <abbrev>XML</abbrev> documents into other output formats such as
+      <abbrev>HTML</abbrev>.  In addition, these tools can build your document
+      into a <abbrev>RPM</abbrev> package.  To take advantage of these
+      services, you must follow conventions for naming your files.
     </para>
     <section id="ch-getting-files-filenames-doc">
       <title>Document Filenames</title>
@@ -103,320 +100,16 @@ cvs co docs-common</userinput>
 	<para>
 	  Do not use the word <wordasword>&FED;</wordasword> in your module
 	  name.  Since all documents in the repository are &FED; documentation,
-	  using it creates unnecessary confusion.
+	  using this term creates unnecessary confusion.
 	</para>
       </important>
     </section>
-    <section id="ch-getting-files-i18n">
-      <title>Anticipating I18N Translation</title>
-      <para>
-        The &FDP; 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.  Therefore, filenames
-        must be unique.
-      </para>
-      <para>
-        To construct a filename, append a dash followed by the
-        <abbrev>ISO</abbrev> language symbol before any file extension.  For
-        example, a file whose language content is <abbrev>U.S.</abbrev> English
-        might be named <filename>mydoc-en.xml</filename>, its Chinese
-        translation 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>&FDP; 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>
-      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>
-    <para>
-      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;n 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>Using 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>
-      <note>
-      <title>Use PNG Images, Not JPG</title>
-        <para>
-            Depending on the output media, sometimes images may be scaled,
-            streteched, or squashed.
-            To minimize any distortions, we recommend that you use only
-            <wordasword>PDF</wordasword> images and avoid <wordasword>JPG</wordasword> files.
-        </para>
-        <para>
-          You may find the <systemitem class="filesystem">convert(1)</systemitem> program, from the <application>ImageMagick</application> <abbrev>RPM</abbrev> package, provides a convenient way to reformat any <wordasword>JPG</wordasword> images you already have.
-        </para>
-      </note>
-      <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.
-        An image file with no text can be named just <filename>picture.png</filename>, for example.
-      </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>
-
-    </section>
   </section>
 </chapter>
 
 <!--
 Local variables:
 mode: xml
-sgml-parent-document: ("documentation-guide-en.xml" "book" "chapter")
-fill-column: 80
+fill-column: 72
 End:
 -->
diff --git a/en_US/docs-module-struct.xml b/en_US/docs-module-struct.xml
new file mode 100644
index 0000000..a751f2b
--- /dev/null
+++ b/en_US/docs-module-struct.xml
@@ -0,0 +1,348 @@
+<!-- $Id: -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- *************** Bring in Fedora entities *************** -->
+<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
+%FEDORA-ENTITIES-EN;
+
+]>
+
+<chapter id="ch-how-modules-work">
+  <title>How Modules Work</title>
+  <para>Documentation modules have a specific structure that enables the
+    preconfigured tools to work correctly.  Follow this structure exactly or you
+    may have problems building your module.  The &FDP; build tools locate
+    resources in the module and use them to build new output such as HTML or RPM
+    packages.</para>
+  <section id="sn-module-struct">
+    <title>Structure of a Module</title>
+    <para>The following listing shows a directory tree of an example module,
+      excluding any <filename class="directory">CVS</filename> folders:</para>
+
+    <screen><computeroutput><![CDATA[example-doc/
+    |-- en_US/
+            |-- example-doc.xml
+            |-- para.xml
+            |-- doc-entities.xml
+            |-- rpm-info.xml
+    |-- figs/
+            |-- fedora-logo-sprite.eps
+            |-- fedora-logo-sprite.png
+    |-- po/
+            |-- de.po
+            |-- example-doc.pot
+            |-- pt.po
+    |-- Makefile]]></computeroutput></screen>
+    
+    <formalpara>
+      <title>Primary language directory (required)</title>
+      <para>This is the only directory absolutely required. It is named for the
+	original language of the document, such as <filename
+	  class="directory">en_US</filename> (US English).  The primary language
+	does not have to be US English; all languages are supported.  This
+	directory contains all the XML source for the actual document, as well
+	as XML source for document-specific
+	<firstterm>entities</firstterm><footnote>
+	  <para>Think of an XML entity as a predefined snippet of information.
+	    It can represent a chunk of XML source, or simply a word or
+	    character. If the information changes, it need be replaced only
+	    once, in the definition, to fix all usage.</para>
+	</footnote>.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Graphics directory (optional)</title>
+      <para>The <filename class="directory">figs/</filename> directory is an
+	optional directory where graphics for the document should be stored. If
+	graphics are screenshots that are particular to a language, the
+	<filename class="directory">figs/</filename> directory can and should be
+	stored in a language directory.</para>
+    </formalpara>
+    <formalpara>
+      <title>Translation (PO) directory (optional)</title> 
+      <para>The <filename class="directory">po/</filename> directory contains
+	specially formatted files created and used by translators. The &FDP;
+	build tools use these files to create translated versions of documents.
+	The translated documents are not stored in CVS; they are created as
+	needed from these PO files.</para>
+    </formalpara>
+    <formalpara>
+      <title>Makefile (required)</title>
+      <para>The <filename>Makefile</filename> controls the build process. Its
+	content is discussed below. <!-- include xref here --></para>
+    </formalpara>
+  </section>
+  <section id="ch-getting-files-build-system">
+    <title>The Document Build System</title>
+    <para>
+      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. 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 and
+      paste operations.
+    </para>
+    <para>
+      <xref
+	linkend="ch-getting-files-build-system-makefile"/> below shows the
+      whole <filename>Makefile</filename> for a simple document having
+      only two files and one language.
+    </para>
+    <example id="ch-getting-files-build-system-makefile">
+      <title>Sample Document Makefile</title>
+      <programlisting>
+<![CDATA[
+DOCBASE         = example-doc
+PRI_LANG      	= en_US
+OTHERS          = de pt
+DOC_ENTITIES    = doc-entities
+
+define XMLFILES_template
+XMLFILES-${1}   = ${1}/example-doc.xml \
+                  ${1}/para.xml
+endef
+
+include ../docs-common/Makefile.common
+]]>
+      </programlisting>
+    </example>
+    <para>
+      Do not be concerned with some of the more complicated syntax (in
+      particular, the <command>XMLFILES_template</command> stanza).  An
+      explanation for this template appears a few paragraphs
+      below.</para>
+    <formalpara>
+      <title><varname>DOCBASE</varname></title>
+      <para>This variable contains the name for the main (parent) XML document.
+	Follow convention by naming your document after the module name.</para>
+    </formalpara>
+    <formalpara>
+      <title><varname>PRI_LANG</varname></title>
+      <para>This variable contains the ISO code for the original version of the
+	document, such as <systemitem>en_US</systemitem>.</para>
+    </formalpara>
+    <formalpara>
+      <title><varname>OTHERS</varname></title>
+      <para>This variable contains a listing of ISO codes for any other versions
+	into which the document has been translated.  The module must contain a
+	<filename class="directory">po/</filename> directory and a PO file for
+	any indicated additional languages.</para>
+    </formalpara>
+    <formalpara>
+      <title><varname>DOC_ENTITIES</varname></title>
+      <para>This variable contains a listing of any files containing entity
+	definitions.  The &FDP; uses a special XML format to record
+	document-specific entities, so they can be translated and built on the
+	fly like any other XML document.  An example is shown later in this
+	guide. <!-- need xref here --></para>
+    </formalpara>
+    <formalpara>
+      <title><varname>XMLFILES_template</varname></title>
+      <para>This template allows the build tools to work with the
+	document in multiple languages once it is translated.  The
+	<varname>${1}</varname> marking is a variable used to substitute
+	the appropriate language.  This template is not terribly
+	complicated.  For a new module, duplicate this section exactly
+	except for the actual filenames.  Prepend the text
+	<varname>${1}/</varname>, in place of the language code
+	directory name, to each filename in your document.
+      </para>
+    </formalpara>
+    <important>
+      <title>Files Exempt From Listing</title>
+      <para>Do not include the document-specific entities XML file or the
+	<filename>rpm-info.xml</filename> file, which will be discussed later in
+	this guide.<!-- include xref --></para>
+    </important>
+    <!-- TEMP MARKER - PWF finished here Nov 28 2006 -->
+    <para>
+      The final line, beginning with <literal>include</literal>, references the
+      main <filename>Makefile</filename> for the build system. This
+      <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>Using 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>
+      <note>
+      <title>Use PNG Images, Not JPG</title>
+        <para>
+            Depending on the output media, sometimes images may be scaled,
+            streteched, or squashed.
+            To minimize any distortions, we recommend that you use only
+            <wordasword>PDF</wordasword> images and avoid <wordasword>JPG</wordasword> files.
+        </para>
+        <para>
+          You may find the <systemitem class="filesystem">convert(1)</systemitem> program, from the <application>ImageMagick</application> <abbrev>RPM</abbrev> package, provides a convenient way to reformat any <wordasword>JPG</wordasword> images you already have.
+        </para>
+      </note>
+      <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.
+        An image file with no text can be named just <filename>picture.png</filename>, for example.
+      </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>
+
+    </section>
+  </section>
+</chapter>
+
+<!--
+Local variables:
+mode: xml
+fill-column: 72
+End:
+-->
diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml
index 1d9ae2f..63c719b 100644
--- a/en_US/documentation-guide.xml
+++ b/en_US/documentation-guide.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- $Id: documentation-guide.xml,v 1.2 2006/11/29 00:29:48 pfrields Exp $ -->
+<!-- $Id: documentation-guide.xml,v 1.3 2006/11/29 22:18:53 pfrields Exp $ -->
 <!-- breaks the build ... <?xml version="1.0" encoding="utf-8"?> -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
@@ -25,6 +25,11 @@
   <xi:include href="docs-getting-files.xml" xpointer="element(ch-getting-files)"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
+  <!-- HOWMODULESWORK -->
+  <xi:include href="docs-module-struct.xml"
+    xpointer="element(ch-how-modules-work)"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <!-- GUIDELINES --> 
   <xi:include href="docs-rh-guidelines.xml" xpointer="element(ch-rh-guidelines)"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -34,9 +39,11 @@
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <!-- EMACS-NXML --> 
-  <!-- This chapter needs editing, but we can't exclude it now. -->
+  <!-- This chapter needs editing, so we're excluding it now. -->
+  <!--
   <xi:include href="docs-emacs-nxml.xml" xpointer="element(ch-emacs-nxml)"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
+  -->
 
   <!-- VIM --> 
   <xi:include href="docs-vim.xml" xpointer="element(ch-vim)"