Retagged some elements to make things more DocBooky. Use sgmltag to

advantage, cool!

1 files changed, 69 insertions, 56 deletions

diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml
index c791274..a51b0d0 100644
--- a/en_US/writing-guidelines.xml
+++ b/en_US/writing-guidelines.xml
@@ -17,7 +17,7 @@
 
   <indexterm>
     <primary>RTFM</primary>
-    <secondary>read the f*'ing manual</secondary>
+    <secondary>read the fine manual</secondary>
     <seealso>humor</seealso>
   </indexterm>
 
@@ -30,9 +30,8 @@
     guidelines that must be followed such as naming conventions.</para>
 
   <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>
+    not all available DocBook XML tags. For the complete list, refer to
+    <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
   </para>
 
   <section id="sn-id-naming-conventions">
@@ -57,7 +56,7 @@
 <figure id="fig-redhat-config-kickstart-basic">]]></screen>
 
     <para>IDs are unique identifiers, allowing DocBook XML to know where
-      to cross-reference a section or chapter or the like.  The
+      to cross-reference a section, chapter, or other element.  The
       following general rules apply to IDs:</para>
 
     <indexterm>
@@ -74,7 +73,7 @@
 
     <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>
+    self-identifying the XML container type.</para>
 
     <table id="tb-id-two-char-naming-conventions">
       <title>Two-Character Naming Conventions</title>
@@ -90,36 +89,36 @@
 	</thead>
 	<tbody>
 	  <row>
-	    <entry><command>preface</command></entry>
-	    <entry><computeroutput>pr-</computeroutput></entry>
+	    <entry><sgmltag class="element">preface</sgmltag></entry>
+	    <entry><literal>pr-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>chapter</command></entry>
-	    <entry><computeroutput>ch-</computeroutput></entry>
+	    <entry><sgmltag class="element">chapter</sgmltag></entry>
+	    <entry><literal>ch-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>section</command></entry>
-	    <entry><computeroutput>sn-</computeroutput></entry>
+	    <entry><sgmltag class="element">section</sgmltag></entry>
+	    <entry><literal>sn-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>figure</command></entry>
-	    <entry><computeroutput>fig-</computeroutput></entry>
+	    <entry><sgmltag class="element">figure</sgmltag></entry>
+	    <entry><literal>fig-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>table</command></entry>
-	    <entry><computeroutput>tb-</computeroutput></entry>
+	    <entry><sgmltag class="element">table</sgmltag></entry>
+	    <entry><literal>tb-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>appendix</command></entry>
-	    <entry><computeroutput>ap-</computeroutput></entry>
+	    <entry><sgmltag class="element">appendix</sgmltag></entry>
+	    <entry><literal>ap-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>part</command></entry>
-	    <entry><computeroutput>pt-</computeroutput></entry>
+	    <entry><sgmltag class="element">part</sgmltag></entry>
+	    <entry><literal>pt-</literal></entry>
 	  </row>
 	  <row>
-	    <entry><command>example</command></entry>
-	    <entry><computeroutput>ex-</computeroutput></entry>
+	    <entry><sgmltag class="element">example</sgmltag></entry>
+	    <entry><literal>ex-</literal></entry>
 	  </row>
 	</tbody>
       </tgroup>
@@ -152,79 +151,87 @@
 	<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>Do not use the trademark entities <sgmltag
+	      class="genentity">trade</sgmltag>, <sgmltag
+	      class="genentity">copy</sgmltag>, or <sgmltag
+	      class="genentity">reg</sgmltag> 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
+	  <para>Instead, use the <sgmltag>trademark</sgmltag> tag and its
 	    associates classes as follows:
 	    </para>
 	    <itemizedlist>
 	      <listitem>
-		<para>&lt;trademark&gt;trademark symbol after me&lt;/trademark&gt;
+	      <para><sgmltag
+	      class="starttag">trademark</sgmltag>trademark symbol after
+	      me<sgmltag class="endtag">trademark</sgmltag>
 		</para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;trademark class="registered"&gt;registered trademark symbol after me&lt;/trademark&gt;
+	      <para><sgmltag class="starttag">trademark
+	      class="registered"</sgmltag>registered trademark symbol
+	      after me<sgmltag class="endtag">trademark</sgmltag>
 		</para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;trademark class="copyright"&gt;copyright symbol after me&lt;/trademark&gt;</para>
+	      <para><sgmltag class="starttag">trademark
+	      class="copyright"</sgmltag>copyright symbol after
+	      me<sgmltag class="endtag">trademark</sgmltag></para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term>Content inside <command>para</command> tags</term>
+	  <term>Content inside <sgmltag>para</sgmltag> tags</term>
 	  <listitem>
-	    <para>In general, use <command>para</command> tags
+	    <para>In general, use <sgmltag>para</sgmltag> 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>Specifically, do not use <sgmltag>para</sgmltag> tags
+	    around the following (or, to put this another way, do not
+	    embed the following within <sgmltag
+	      class="element">para</sgmltag> elements):
 	    </para>
 	    <itemizedlist>
 	      <listitem>
-		<para>&lt;screen&gt;</para>
+	      <para><sgmltag class="element">screen</sgmltag></para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;itemizedlist&gt;</para>
+	      <para><sgmltag class="element">itemizedlist</sgmltag></para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;orderedlist&gt;</para>
+	      <para><sgmltag class="element">orderedlist</sgmltag></para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;variablelist&gt;</para>
+	      <para><sgmltag class="element">variablelist</sgmltag></para>
 	      </listitem>
 	      <listitem>
-		<para>&lt;table&gt;</para>
+	      <para><sgmltag class="element">table</sgmltag></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>
+	  <term>Content inside <sgmltag class="element">para</sgmltag> elements within
+	  <sgmltag>listitem</sgmltag> tags</term>
+	  <listitem>
+	    <para>Content inside <sgmltag class="element">para</sgmltag>
+	    elements within <sgmltag class="element">listitem</sgmltag>
+	    elements <emphasis>must</emphasis> start immediately after
+	    the beginning <sgmltag class="starttag">para</sgmltag> tag
+	    to avoid extra white space in the PDF version.</para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
-	  <term>Content inside <command>screen</command> tags</term>
+	  <term>Content inside <sgmltag>screen</sgmltag> tags</term>
 	  <listitem>
-	    <para>The content inside <command>screen</command> tags
-	    (&lt;screen&gt; and &lt;/screen&gt;)
+	    <para>The content inside <sgmltag>screen</sgmltag> tags
+	    (<sgmltag class="starttag">screen</sgmltag> and <sgmltag
+	    class="endtag">screen</sgmltag>)
 	    <emphasis>must</emphasis> be flush left in the XML file;
 	    otherwise, the extraneous whitespace will appear in the HTML
 	    version.
@@ -247,7 +254,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.3 2007/02/04 13:57:23 kwade Exp $ -->]]></screen>
+    <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.4 2007/02/05 00:33:47 pfrields Exp $ -->]]></screen>
 
   </section>
 
@@ -301,7 +308,7 @@
       <tertiary>note</tertiary>
     </indexterm>
     
-    <Indexterm>
+    <indexterm>
       <primary>XML tags</primary>
       <secondary>admonitions</secondary>
       <tertiary>caution</tertiary>
@@ -529,8 +536,11 @@
 		<guibutton>OK</guibutton>.</para>
 	    </step>
 	  </procedure>
+	  <!-- This section is dropped, right?  [PWF] -->
+<!--
 	  <para>For more information about calling the images from the
 	    XML, refer to <xref linkend="sn-xml-tags-figure"/>.</para>
+-->
 	</listitem>
       </varlistentry>
       <varlistentry>
@@ -576,8 +586,11 @@
  8032 pts/0    S      0:00 ssh user@host.example.com
  8032 pts/1    S      0:00 ssh root@backup.example.com</computeroutput></screen>
 	  </example>
+	  <!-- This section is dropped, right?  [PWF] -->
+<!--
 	  <para>For more information about using screen, refer to <xref
 	      linkend="sn-xml-tags-screen"/>.</para>
+-->
 	</listitem>
       </varlistentry>
     </variablelist>