Some retagging and deconfusification

1 files changed, 117 insertions, 81 deletions

diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml
index 324aed0..6249a11 100644
--- a/en_US/writing-guidelines.xml
+++ b/en_US/writing-guidelines.xml
@@ -46,18 +46,9 @@
       <primary>naming conventions</primary>
     </indexterm>
 
-    <para>This section explains the ID naming convention. For
-      example:</para>
-
-    <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">
-
-<section id="sn-install-make-disks">
-
-<figure id="fig-redhat-config-kickstart-basic">]]></screen>
-
-    <para>IDs are unique identifiers, allowing DocBook XML to know where
-      to cross-reference a section, chapter, or other element.  The
-      following general rules apply to IDs:</para>
+    <para>This section explains the ID naming convention.  IDs are
+      unique identifiers that allow DocBook XML to cross-reference a
+      section, chapter, or other element.</para>
 
     <indexterm>
       <primary>XML tags</primary>
@@ -68,19 +59,40 @@
       <primary>naming conventions</primary>
       <secondary>rules for defining an ID</secondary>
     </indexterm>
-    
-    <para>Keep it as short and simple as possible.</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 the XML container type.</para>
+    <para>The following general rules apply to IDs:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Keep an ID as short and simple as possible.</para>
+      </listitem>
+      <listitem>
+	<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 the XML container type.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>
+      <xref linkend="ex-id-usage"/> demonstrates some example ID
+      attributes used properly.
+    </para>
+
+    <example id="ex-id-usage">
+      <title>Proper ID Usage</title>
+    <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">
+
+<section id="sn-install-make-disks">
+
+<figure id="fig-redhat-config-kickstart-basic">]]></screen>
+    </example>
 
     <table id="tb-id-two-char-naming-conventions">
       <title>Two-Character Naming Conventions</title>
 
       <tgroup cols="2">
-	<colspec colnum="1" colname="tag" colwidth="100"/>
-	<colspec colnum="2" colname="prefix" colwidth="100"/>
+	<colspec colnum="1" colname="tag"/>
+	<colspec colnum="2" colname="prefix"/>
 	<thead>
 	  <row>
 	    <entry>Tag</entry>
@@ -124,17 +136,13 @@
       </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>    
+    <para>Use the title of the item as the ID.  Make your titles unique
+      within a document to prevent conflicts.  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>
+  <title>How To Fold Laundry</title>
+  <section id="sn-folding-shirts">
+    <title>Folding Shirts</title>]]></screen>
     
       <indexterm>
 	<primary>xml tags</primary>
@@ -254,7 +262,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.5 2007/02/18 14:24:33 pfrields Exp $ -->]]></screen>
+    <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.6 2007/02/18 22:59:19 pfrields Exp $ -->]]></screen>
 
   </section>
 
@@ -320,17 +328,25 @@
       <tertiary>important</tertiary>
     </indexterm>
 
-    <para>There are five types of admonitions in DocBook: Caution,
-      Important, Note, Tip, and Warning.  All of the admonitions have
-      the same structure: an optional Title followed by paragraph-level
+    <para>There are five types of admonitions in DocBook: <sgmltag
+	class="element">caution</sgmltag>, <sgmltag
+	class="element">important</sgmltag>, <sgmltag
+	class="element">note</sgmltag>, <sgmltag
+	class="element">tip</sgmltag>, and <sgmltag
+	class="element">warning</sgmltag>.  All of the admonitions have
+      the same structure: an optional <sgmltag
+	class="element">title</sgmltag> followed by paragraph-level
       elements. The DocBook DTD does not impose any specific semantics
       on the individual admonitions. For example, DocBook does not
-      mandate that Warnings be reserved for cases where bodily harm can
-      result.</para>
+      mandate that a <sgmltag class="element">warning</sgmltag> is
+      reserved for cases where bodily harm can result.</para>
       
     <section id="sn-xml-notesetc">
-      <title>Creating Notes, Tips, Cautions, Importants, and
-	Warnings</title>
+      <title>Creating a <sgmltag class="element">note</sgmltag>,
+	<sgmltag class="element">tip</sgmltag>, <sgmltag
+	  class="element">caution</sgmltag>, <sgmltag
+	  class="element">important</sgmltag>, or <sgmltag
+	  class="element">warning</sgmltag></title>
 
       <indexterm>
 	<primary>XML tags</primary>
@@ -358,24 +374,27 @@
       </indexterm>
 
       <para>There are several ways to bring attention to text within a
-	document. A <emphasis>Note</emphasis> is used to bring
+	document. A <emphasis><sgmltag
+	    class="element">note</sgmltag></emphasis> is used to bring
 	additional information to the users' attention. A
-	<emphasis>Tip</emphasis> is used to show the user helpful
-	information or another way to do something. A
-	<emphasis>Caution</emphasis> is used to show the user they must
-	be careful when attempting a certain step. An
-	<emphasis>Important</emphasis> tag set can be used to show the
-	user a piece of information that should not be overlooked. While
-	this information may not change anything the user is doing, it
-	should show the user that this piece of information could be
-	vital. A <emphasis>Warning</emphasis> is used to show the reader
-	that their current setup will change or be altered, such as
-	files being removed, and they should not choose this operation
-	unless they are alright with the consequences.</para>
-
-      <para>The following lines of code will show the basic setup for
-	each case as mentioned above, along with an example of how it
-	would be displayed in the HTML.</para>
+	<emphasis><sgmltag class="element">tip</sgmltag></emphasis> is
+	used to show the user helpful information or another way to do
+	something. A <emphasis><sgmltag
+	    class="element">caution</sgmltag></emphasis> is used to show
+	the user they must be careful when attempting a certain step. An
+	<emphasis><sgmltag
+	    class="element">important</sgmltag></emphasis> tag set can
+	be used to show the user a piece of information that should not
+	be overlooked. While this information may not change anything
+	the user is doing, it should show the user that this piece of
+	information could be vital. A <emphasis><sgmltag
+	    class="element">warning</sgmltag></emphasis> is used to show
+	the reader that their current setup will change or be altered,
+	such as files being removed, and they should not choose this
+	operation unless they are alright with the consequences.</para>
+
+      <para>The following lines of code show the basic setup for each
+	case mentioned above, along with its appearance in HTML.</para>
 
       <screen><![CDATA[<note>
   <title>Note</title>
@@ -547,39 +566,56 @@
 	<term>Text Screenshot</term>
 	<listitem>
 	  <para>Textual screen information is also useful for readers.
-	    If you use a graphical screenshot to illustrate a function,
-	    and the textual mode has identical functions, you should not
-	    include both, unless omitting either would make your
-	    description unclear. You should make your information
-	    generic over specific. Omit the username and machine
-	    information, and separate what the user types from sample
-	    command output. Also, in <command>screen</command> tags,
-	    what the user types should be in
-	    <command>userinput</command> tags, and what the user is
-	    shown as output should be in
-	    <command>computeroutput</command> tags. For example, the
-	    usage in
-	      <xref linkend="ex-text-screenshot-bad"/> should look like
-	    <xref
-	      linkend="ex-text-screenshot-good"/>.
+	    Follow these guidelines for textual screenshots:</para>
+	  <itemizedlist>
+	    <listitem>
+	      <para>If you use a graphical screenshot to illustrate a
+		function, and the textual mode has identical functions,
+		do not include both, unless omitting either would make
+		your description unclear.</para>
+	    </listitem>
+	    <listitem>
+	      <para>Make your information generic over specific, and
+		omit any username and machine information if possible.
+		Do not include the shell prompt unless it is vital to
+		the demonstration.</para>
+	    </listitem>
+	    <listitem>
+	      <para>Separate what the user types from sample command
+		output.</para>
+	    </listitem>
+	    <listitem>
+	      <para>When using <sgmltag class="element">screen</sgmltag>
+		to demonstrate a procedure, use <sgmltag
+		  class="element">userinput</sgmltag> tags to show what
+		the user types, and use <sgmltag
+		  class="element">computeroutput</sgmltag> tags to show
+		the resulting output.</para>
+	    </listitem>
+	  </itemizedlist>
+	  <para>
+	    <xref linkend="ex-text-screenshot-good"/> is an example of
+	    textual screenshot usage.
 	  </para>
-	  <example id="ex-text-screenshot-bad">
-	    <title>Incorrect Textual Screenshot</title>
-	    <screen><userinput>ps ax | grep ssh</userinput>
-<computeroutput> 2564 ?        S      0:23 /usr/sbin/sshd
- 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
- 8235 ?        S      0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost
-17223 pts/0    S      0:00 ssh rbalboa@core-router7
-17227 pts/2    S      0:10 ssh rbalboa@smbshare2
-21113 pts/7    S      1:19 ssh rocky@xxx.private</computeroutput></screen>
-	  </example>
 	  <example id="ex-text-screenshot-good">
-	    <title>Correct Textual Screenshot</title>
+	    <title>Correct Textual Screenshot (XML Source and
+	      HTML)</title>
+	    <screen><![CDATA[<example id="ex-text-screenshot-good">
+  <title>Correct Textual Screenshot</title>
+  <para>To find all the currently active ssh sessions, 
+    execute the following command:</para>
+  <screen><userinput>ps ax | grep ssh</userinput></screen>
+  <para>Output appears similar to the following:</para>
+  <screen><computeroutput> 2564 ?        S      0:23 /usr/sbin/sshd
+ 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
+ 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>]]></screen>
 	    <para>To find all the currently active ssh sessions, execute the
 		following command:</para>
-	    <screen><command>ps ax | grep ssh</command></screen>
+	    <screen><userinput>ps ax | grep ssh</userinput></screen>
 
-	    <para>The output will appear similar to:</para>
+	    <para>Output appears similar to the following:</para>
 
 	      <screen><computeroutput> 2564 ?        S      0:23 /usr/sbin/sshd
  3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients