the latest stuff I did :)

1 files changed, 127 insertions, 50 deletions

diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml
index 32ed5aa..c791274 100644
--- a/en_US/writing-guidelines.xml
+++ b/en_US/writing-guidelines.xml
@@ -8,7 +8,7 @@
 ]>
 
 <chapter id="ch-rh-guidelines">
-  <title>&RH; Documentation Guidelines</title>
+  <title>&FED; Documentation Guidelines</title>
 
   <indexterm>
     <primary>recursion</primary>
@@ -29,7 +29,13 @@
   <para>Please read this chapter carefully. This chapter describes the
     guidelines that must be followed such as naming conventions.</para>
 
-  <section id="sn-xml-guidelines-naming">
+  <para>This chapter only discusses tags used for documentation for the &PROJECT;,
+    not all available DocBook XML tags. For the complete list, refer to:</para>
+  <para>
+    <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</ulink>
+  </para>
+
+  <section id="sn-id-naming-conventions">
     <title>ID Naming Conventions</title>
 
     <indexterm>
@@ -41,11 +47,10 @@
       <primary>naming conventions</primary>
     </indexterm>
 
-    <para>You will see certain ID names referred to below and this will
-      help to explain how we come up with those names. For
+    <para>This section explains the ID naming convention. For
       example:</para>
 
-    <screen><![CDATA[<chapter id="ch-uniquename">
+    <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">
 
 <section id="sn-install-make-disks">
 
@@ -64,35 +69,15 @@
       <primary>naming conventions</primary>
       <secondary>rules for defining an ID</secondary>
     </indexterm>
-      
-    <itemizedlist>
-      <listitem>
-	<para>Restrict the ID name, which is everything between the
-	  quotation marks, to 32 characters or fewer</para>
-      </listitem>
-      <listitem>
-	<para>Keep it as short and simple as possible</para>
-      </listitem>
-      <listitem>
-	<para>Make sure the name is recognizable and relevant to the
-	  information</para>
-      </listitem>
-    </itemizedlist>
-      
-    <para>Some examples are <command>"ch-uniquename"</command> (13
-      characters) and <command>"sn-install-make-disks"</command> (21
-      characters).</para>
+    
+    <para>Keep it as short and simple as possible.</para>
 
-    <para>A section within a particular chapter always uses the chapter
-      name (minus the <command>"ch-"</command>) in its ID. For example,
-      you are working with the <command>"ch-intro"</command> chapter and
-      need to create your first section on disk partitions. That section
-      ID would look similar to <command>"sn-intro-partition"</command>
-      which contains the section number, the main chapter ID, and a
-      unique ID for that section.</para>
+    <para>Start the ID with the special short two-character label.  This
+    makes URLs and other references to this ID human readable, by
+    self-identifying what the XML container type is.</para>
 
-    <table id="tb-xml-namingconventions">
-      <title>Naming Conventions</title>
+    <table id="tb-id-two-char-naming-conventions">
+      <title>Two-Character Naming Conventions</title>
 
       <tgroup cols="2">
 	<colspec colnum="1" colname="tag" colwidth="100"/>
@@ -117,22 +102,6 @@
 	    <entry><computeroutput>sn-</computeroutput></entry>
 	  </row>
 	  <row>
-	    <entry><command>section</command></entry>
-	    <entry><computeroutput>sn-</computeroutput></entry>
-	  </row>
-	  <row>
-	    <entry><command>section</command></entry>
-	    <entry><computeroutput>sn-</computeroutput></entry>
-	  </row>
-	  <row>
-	    <entry><command>sect3</command></entry>
-	    <entry><computeroutput>s3-</computeroutput></entry>
-	  </row>
-	  <row>
-	    <entry><command>sect4</command></entry>
-	    <entry><computeroutput>s4-</computeroutput></entry>
-	  </row>
-	  <row>
 	    <entry><command>figure</command></entry>
 	    <entry><computeroutput>fig-</computeroutput></entry>
 	  </row>
@@ -156,6 +125,114 @@
       </tgroup>
     </table>
 
+    <para>Use the title of the item as the ID.  If your title is not
+      unique, there is either a problem you need to fix (titles should
+      be unique within a document), or it is part of a template and
+      should reflect the containing chapter/section of the template. For
+      example:</para>    
+    
+    <screen><![CDATA[<chapter id="ch-how-to-fold-laundry">
+<title>How To Fold Laundry</title>]]></screen>
+      
+    <screen><![CDATA[<section id="sn-folding-shirts">
+<title>Folding Shirts</title>]]></screen>
+    
+      <indexterm>
+	<primary>xml tags</primary>
+	<secondary>caveats</secondary>
+      </indexterm>
+    
+      <para>
+	It is very important that you remember the caveats in this
+	section. These are learned suggestions or rules that make your
+	XML experience better.
+      </para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Do Not Use Trademark Entities</term>
+	  <listitem>
+	    <para>Do not use the trademark entities &amp;trade;, &amp;copy;, or
+	    &amp;reg; because the do not produce HTML output that works for all
+	    charsets. The HTML output produces by these entities are declared in
+	    the DTD and cannot be changed via the stylesheet.</para>
+	  
+	  <para>Instead, use the <command>trademark</command> tag and its
+	    associates classes as follows:
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>&lt;trademark&gt;trademark symbol after me&lt;/trademark&gt;
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;trademark class="registered"&gt;registered trademark symbol after me&lt;/trademark&gt;
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;trademark class="copyright"&gt;copyright symbol after me&lt;/trademark&gt;</para>
+	      </listitem>
+	    </itemizedlist>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Content inside <command>para</command> tags</term>
+	  <listitem>
+	    <para>In general, use <command>para</command> tags
+	    around anything other than a simple paragraph. Doing so will
+	    create additional white space within the text itself in the
+	    PDF version.
+	    </para>
+	    <para>Specifically, do not use <command>para</command> tags around
+	      the following (or, to put this another way, do not embed the
+	      following within <command>para</command> tags):
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>&lt;screen&gt;</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;itemizedlist&gt;</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;orderedlist&gt;</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;variablelist&gt;</para>
+	      </listitem>
+	      <listitem>
+		<para>&lt;table&gt;</para>
+	      </listitem>
+	    </itemizedlist>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Content inside <command>para</command> tags within
+	  <command>listitem</command> tags</term>
+	  <listitem>    <sect id="sn-xml-tags-caveats">
+      <title>Tags and Entities Caveats</title>
+
+
+	    <para>Content inside <command>para</command> tags within
+	    <command>listitem</command> tags <emphasis>must</emphasis> start
+	    immediately after the beginning &lt;para&gt; tag to avoid extra
+	    white space in the PDF version.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Content inside <command>screen</command> tags</term>
+	  <listitem>
+	    <para>The content inside <command>screen</command> tags
+	    (&lt;screen&gt; and &lt;/screen&gt;)
+	    <emphasis>must</emphasis> be flush left in the XML file;
+	    otherwise, the extraneous whitespace will appear in the HTML
+	    version.
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
   </section>
   
   <section id="sn-xml-guidelines-header">
@@ -170,7 +247,7 @@
       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.2 2007/02/03 22:29:37 kwade Exp $ -->]]></screen>
+    <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.3 2007/02/04 13:57:23 kwade Exp $ -->]]></screen>
 
   </section>
 
@@ -224,7 +301,7 @@
       <tertiary>note</tertiary>
     </indexterm>
     
-    <indexterm>
+    <Indexterm>
       <primary>XML tags</primary>
       <secondary>admonitions</secondary>
       <tertiary>caution</tertiary>