Some content updates, push new bugfix rev 0.3.0.1, no publishing needed yet

4 files changed, 174 insertions, 72 deletions

diff --git a/en_US/getting-files.xml b/en_US/getting-files.xml
index 81a777c..21c6481 100644
--- a/en_US/getting-files.xml
+++ b/en_US/getting-files.xml
@@ -16,7 +16,7 @@
     tools.  Follow the directions below to configure your system.
   </para>
 
-  <section id="ch-getting-files-system-packages">
+  <section id="sn-system-packages">
     <title>System Packages</title>
 
     <para>
@@ -59,42 +59,114 @@
 
   </section>
 
-  <section id="ch-getting-files-filenames">
-    <title>Filename Conventions</title>
+  <section id="sn-getting-files-names">
+    <title>Naming Conventions</title>
     <para>
-      The &FDP; provides the tools, scripts, and stylesheets to transform your
-      <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.
+      The &FDP; provides the tools, scripts, and stylesheets to
+      transform your <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, follow the conventions in this
+      section to name your files.
     </para>
-    <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.  On the CVS server, these directories are called
-        <firstterm>modules</firstterm>.  Use
-        the <command>cvs co -c</command> command to view existing module names.
-      </para>
-      <example>
-	<title>Partial List of CVS Modules</title>
-	<screen><userinput>cd ~/localrepo/fedora-docs/</userinput>
-<computeroutput>developer-guide developer-guide
+    <para>On the CVS server, directories that contain document files are
+      called <firstterm>modules</firstterm>.  Each module represents a
+      single document.  Each document may consist of several
+      <firstterm>branches</firstterm> if that document changes with each
+      release of &DISTRO;.  Contributors can check out single branches
+      of these modules or the entire module.  Each document or branch
+      may contain multiple XML source files.</para>
+    <para>Use the <command>cvs co -c</command> command to view existing
+      module names.</para>
+    <example>
+      <title>Partial List of CVS Modules</title>
+      <screen><userinput>cd ~/localrepo/fedora-docs/</userinput>
+<computeroutput><![CDATA[about-fedora about-fedora &docs-common
+about-fedora-F-7 &about-fedora-F-7-dir &docs-common
+about-fedora-F-7-dir -d about-fedora about-fedora/F-7
+about-fedora-devel &about-fedora-devel-dir &docs-common
+about-fedora-devel-dir -d about-fedora about-fedora/devel
+build-docs   infrastructure/build-docs &docs-common
+cvsroot      CVSROOT
+desktop-up2date desktop-up2date &docs-common
+desktop-user-guide desktop-user-guide &docs-common
+desktop-user-guide-FC-6 &desktop-user-guide-FC-6-dir &docs-common
+desktop-user-guide-FC-6-dir -d desktop-user-guide desktop-user-guide/FC-6
+desktop-user-guide-devel &desktop-user-guide-devel-dir &docs-common
+desktop-user-guide-devel-dir -d desktop-user-guide desktop-user-guide/devel
+developer-guide developer-guide &docs-common
 docs         .
 docs-common  docs-common
-documentation-guide documentation-guide
-example-tutorial example-tutorial</computeroutput></screen>
-      </example>
+documentation-guide documentation-guide &docs-common]]></computeroutput></screen>
+    </example>
+    <para>The leftmost entry in each line is the name of a module you
+      can check out from CVS.  The rest of the line ensures that
+      checkouts include the proper branch of a document and the common
+      build tools.  For more information on CVS, refer to <xref
+	linkend="ch-cvs"/>.</para>
+    <para>Note in the listing above that the
+      <systemitem>about-fedora</systemitem> module has two branches
+      avalable.  One branch is for &DISTRO; 7 and one is for forward
+      development to match the current work of developers.  On the other
+      hand, the <systemitem>documentation-guide</systemitem> module is
+      not branched.</para>
+    <section id="ch-getting-files-naming-modules">
+      <title>Module Names</title>
       <para>Choose a module name that accurately reflects your
-	document's subject, but avoid any name already taken.</para>
+	document's subject, but avoid any name already taken.  The
+	document title without any use of the word
+	<wordasword>&FEDLC;</wordasword> is a reasonable choice in most
+	cases.  Use the length descriptors
+	<wordasword>tutorial</wordasword> or
+	<wordasword>guide</wordasword> in the module name where
+	appropriate.</para>
       <important>
 	<title>Avoid Redundancy</title>
 	<para>
-	  Do not use the word <wordasword>&FED;</wordasword> to name
+	  Do not use the word <wordasword>&FEDLC;</wordasword> to name
 	  modules in the &FDP; CVS repository.
 	</para>
       </important>
+      <segmentedlist id="sl-correct-module-naming">
+	<title>Correct Module Naming</title>
+	<segtitle>Document Name</segtitle>
+	<segtitle>CVS Module Name</segtitle>
+	<seglistitem>
+	  <seg>Desktop User Guide</seg>
+	  <seg>desktop-user-guide</seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg>Software Management with
+	    <application>Yum</application></seg>
+	  <seg>yum-guide</seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg>Using <application>Pup</application></seg>
+	  <seg>pup-tutorial</seg>
+	</seglistitem>
+      </segmentedlist>
+    </section>
+    <section>
+      <title>File Names</title>
+      <para>Follow these guidelines for naming files to make
+	collaboration and document reuse easy:</para>
+      <itemizedlist>
+	<listitem>
+	  <para>As with module names, avoid using the word
+	    <wordasword>&FEDLC;</wordasword> in file names since it is
+	    redundant.</para>
+	</listitem>
+	<listitem>
+	  <para>If the document is comprised of many XML files, avoid
+	    repeating the name of the document when naming the
+	    constituent files.</para>
+	</listitem>
+	<listitem>
+	  <para>Avoid numbering files to show order, since editors and
+	    authors often rearrange documents or reuse their files in
+	    other documents.</para>
+	</listitem>
+      </itemizedlist>
     </section>
   </section>
 </chapter>
diff --git a/en_US/module-struct.xml b/en_US/module-struct.xml
index 25851ec..46eea9b 100644
--- a/en_US/module-struct.xml
+++ b/en_US/module-struct.xml
@@ -19,7 +19,8 @@
     <title>Structure of a Module</title>
     <para><xref linkend="ex-module-structure"/> shows a directory tree
       of an example module, excluding any <filename
-	class="directory">CVS</filename> folders:</para>
+	class="directory">CVS</filename> folders.  Note that this
+      example document does not have branches.</para>
     <example id="ex-module-structure">
       <title>Example Module Structure</title>
       <screen><computeroutput><![CDATA[example-doc/
@@ -77,11 +78,11 @@
 	<seg>Translation (PO) directory</seg>
 	<seg>optional</seg> 
 	<seg>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.</seg>
+	  contains specially formatted Portable Object, or
+	  <acronym>PO</acronym>, 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.</seg>
       </seglistitem>
       <seglistitem>
 	<seg>Makefile</seg>
@@ -97,13 +98,29 @@
 	  document specific metadata</seg>
       </seglistitem>
     </segmentedlist>
+    <important>
+      <title>Common Build Tools</title>
+      <para>Never add the <systemitem>docs-common</systemitem> build
+	tools directory to an individual module.  Special formatting in
+	the module list downloads these tools when a user checks out a
+	document module.  For more information, refer to <xref
+      linkend="ch-getting-files-naming-modules"/>.</para>
+    </important>
   </section>
   <section id="sn-build-system">
     <title>The Document Build System</title>
     <para>
       The build system can render the document into another format such
       as <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev>, using
-      <command>make(1)</command> and shell scripts.  Authors need
+      <command>make(1)</command><footnote>
+	<para>In Linux and &DISTRO; documentation, references to
+	  commands often include a number inside parentheses.  This
+	  number represents the section of
+	  <firstterm>manpages</firstterm> that includes documentation
+	  for that command.  To read the manpage for
+	  <command>make(1)</command>, use the command <command>man 1
+	    make</command>.</para>
+      </footnote> and shell scripts.  Authors need
       <emphasis>no</emphasis> prior experience with either shell scripts
       or a <command>make(1)</command>.
     </para>
diff --git a/en_US/rpm-info.xml b/en_US/rpm-info.xml
index cd047be..d8bc50e 100644
--- a/en_US/rpm-info.xml
+++ b/en_US/rpm-info.xml
@@ -33,6 +33,10 @@
   <title>Fedora Documentation Guide</title>
   <desc>Guidelines and procedures for producing documentation for Fedora</desc>
   <changelog order="newest-first">
+    <revision date="2007-06-28" number="0.3.0.1">
+      <author worker="PaulWFrields"/>
+      <details>Assorted fixes to reflect newer version of reality</details>
+    </revision>
     <revision date="2007-06-23" number="0.3.0">
       <author worker="PaulWFrields"/>
       <author worker="TammyFox"/>
diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml
index f6bf7ed..0691825 100644
--- a/en_US/writing-guidelines.xml
+++ b/en_US/writing-guidelines.xml
@@ -34,6 +34,26 @@
     <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
   </para>
 
+  <section id="sn-xml-guidelines-header">
+    <title>File Header</title>
+    <section id="sn-xml-header-xml">
+      <title>XML Header</title>
+      <para>In accordance with good XML practices, the first line in any
+	DocBook XML source files should identify the file as XML.  Use
+	the following line as the first line of any new XML file:</para>
+      <screen><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></screen>
+    </section>
+    <section id="sn-xml-header-cvs">
+      <title>CVS Id Header</title>
+      <para>All the files must contain the CVS Id header. Use the
+      following line as the second line of any new XML file:</para>
+      <screen><![CDATA[<!-- $Id: -->]]></screen>
+      <para>Any time the file is committed to CVS, the line is updated
+	automatically to include information about the file. For
+	example:</para>
+      <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.8 2007/06/29 00:10:59 pfrields Exp $ -->]]></screen>
+    </section>
+  </section>
   <section id="sn-id-naming-conventions">
     <title>ID Naming Conventions</title>
 
@@ -132,7 +152,9 @@
   <title>How To Fold Laundry</title>
   <section id="sn-folding-shirts">
     <title>Folding Shirts</title>]]></screen>
-    
+  </section>
+  <section id="sn-xml-tags">
+    <title>XML Tags</title>
       <indexterm>
 	<primary>xml tags</primary>
 	<secondary>caveats</secondary>
@@ -157,28 +179,31 @@
 	    cannot be changed via the stylesheet.</para>
 	  
 	  <para>Instead, use the <sgmltag>trademark</sgmltag> tag and its
-	    associates classes as follows:
-	    </para>
-	    <itemizedlist>
-	      <listitem>
-	      <para><sgmltag
-	      class="starttag">trademark</sgmltag>trademark symbol after
-	      me<sgmltag class="endtag">trademark</sgmltag>
-		</para>
-	      </listitem>
-	      <listitem>
-	      <para><sgmltag class="starttag">trademark
-	      class="registered"</sgmltag>registered trademark symbol
-	      after me<sgmltag class="endtag">trademark</sgmltag>
-		</para>
-	      </listitem>
-	      <listitem>
-	      <para><sgmltag class="starttag">trademark
-	      class="copyright"</sgmltag>copyright symbol after
-	      me<sgmltag class="endtag">trademark</sgmltag></para>
-	      </listitem>
-	    </itemizedlist>
-	  </listitem>
+	    associates classes as follows:</para>
+	  <segmentedlist>
+	    <segtitle>DocBook XML source</segtitle>
+	    <segtitle>Rendered content</segtitle>
+	    <seglistitem>
+	      <seg><code><![CDATA[<trademark>trademark symbol after
+		  me</trademark>]]></code></seg>
+	      <seg><trademark>trademark symbol after
+		  me</trademark></seg>
+	    </seglistitem>
+	    <seglistitem>
+	      <seg><code><![CDATA[<trademark
+		  class="registered">registered trademark symbol after
+		  me</trademark>]]></code></seg>
+	      <seg><trademark class="registered">registered trademark
+		  symbol after me</trademark></seg>
+	    </seglistitem>
+	    <seglistitem>
+	      <seg><code><![CDATA[<trademark class="copyright">copyright
+		  symbol after me</trademark>]]></code></seg>
+	      <seg><trademark class="copyright">copyright symbol after
+		  me</trademark></seg>
+	    </seglistitem>
+	  </segmentedlist>
+	</listitem>
 	</varlistentry>
 	<varlistentry>
 	  <term>Content inside <sgmltag>para</sgmltag> tags</term>
@@ -239,22 +264,6 @@
 
   </section>
   
-  <section id="sn-xml-guidelines-header">
-    <title>File Header</title>
-
-    <para>All the files must contain the CVS Id header. If you create a
-      new file, the first line must be:</para>
-
-    <screen><![CDATA[<!-- $Id: -->]]></screen>
-
-    <para>The first time it is committed to CVS (and every time it is
-      committed to CVS) the line is updated automatically to include
-      information about the file. For example:</para>
-
-    <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.7 2007/03/08 03:00:44 pfrields Exp $ -->]]></screen>
-
-  </section>
-
   <section id="sn-xml-admon">
     <title>Admonitions</title>