From aa790df9959a780792e2da0e2dae4115ddbf8196 Mon Sep 17 00:00:00 2001
From: Karsten Wade <kwade@redhat.com>
Date: Thu, 28 Apr 2005 10:35:41 +0000
Subject: Complete grammatical and technical edit of new Style chapter,
 sufficient to post these changes live.

---
 docs-style-en.xml | 237 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 142 insertions(+), 95 deletions(-)

diff --git a/docs-style-en.xml b/docs-style-en.xml
index 298a211..72be8de 100644
--- a/docs-style-en.xml
+++ b/docs-style-en.xml
@@ -1,7 +1,7 @@
 <chapter id="ch-style">
   
   <!--
-
+  
     To ensure code readability, please use a fill-width of 72 in
     Emacs. To set fill width in Emacs, use "C-u 72 C-x f".
 
@@ -22,27 +22,27 @@
   <itemizedlist>
     <listitem>
       <para>
-        excessive wordiness
+        Excessive wordiness
       </para>
     </listitem>
     <listitem>
       <para>
-        unnecessary or undefined jargon
+        Unnecessary or undefined jargon
       </para>
     </listitem>
     <listitem>
       <para>
-        grammatical or spelling errors
+        Grammatical or spelling errors
       </para>
     </listitem>
     <listitem>
       <para>
-        references to yourself or your experiences
+        References to yourself or your experiences
       </para>
     </listitem>
     <listitem>
       <para>
-        remarks which might offend or confuse any reader
+        Remarks which might offend or confuse any reader
       </para>
     </listitem>
   </itemizedlist>
@@ -60,20 +60,24 @@
     <title>Why Style Is Important</title>
       
     <para>
-      Writing well comes naturally to almost no one. It is a skill that
+	Writing well comes naturally to almost no one. It is a skill that
       professional writers, even famous ones, must practice constantly.
       <firstterm>Style</firstterm>
       <indexterm><primary>style</primary></indexterm> is the quality
-      that separates elegant writing from the merely functional.
-    </para> <para> Elegance comes in many forms. In prose and poetry,
+	that separates elegant writing from the merely functional.
+    </para>
+    <para>
+      Elegance comes in many forms. In prose and poetry,
       elegant writing may not follow some (or any) common rules of
-      grammar, syntax or spelling. A good example is Episode 18,
+      grammar, syntax, or spelling. A good example is Episode 18,
       "Penelope," in James Joyce's novel
-      <citetitle>Ulysses</citetitle><footnote id='fn-ulysses'> <para>
-          See, e.g. <ulink
+      <citetitle>Ulysses</citetitle><footnote id='fn-ulysses'>
+        <para>
+          For example, refer to. <ulink
             url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>. 
           Please note that this example contains some mature themes and
-          language, and is not suitable for all readers. </para>
+          language, and is not suitable for all readers.
+        </para>
       </footnote>. There, Joyce uses long streams of words without
       punctuation to simulate a character's internal consciousness. By
       violating basic rules of grammar and syntax, Joyce simulates the
@@ -86,9 +90,9 @@
       the more difficult the material becomes for the reader. For
       example, readers may not be native speakers of the language used,
       or they might be reading a translation. If the writer uses slang,
-      idiom, or jargon, a reader or translator may easily become
+      idioms, or jargon, a reader or translator may easily become
       confused. Take the following example, which compares two different
-      written executions of the same idea: 
+      written executions of the same idea:
     </para>
     <example>
       <title>Incorrect style</title> 
@@ -119,15 +123,11 @@
           found</computeroutput> indicates that your device was
         installed successfully.
       </para>
-    </example> 
-    <para>
-      The first example is more conversational English, which is not
-      appropriate for official written documentation. The second example
-      is more formal, but as a result it is easier to comprehend, both
-      for native readers and translators.
-    </para>
-    <para>
-      Following style rules and guidelines also makes readers more
+    </example> <para> The first example is more conversational English,
+      which is not appropriate for official written documentation. The
+      second example is more formal, but as a result it is easier to
+      comprehend, both for native readers and translators. </para>
+    <para> Following style rules and guidelines also makes readers more
       comfortable with a set of documents. Consistent style enhances the
       professional appearance of documentation, and its perceived value.
       On the other hand, lapses in punctuation or poor grammar
@@ -135,33 +135,37 @@
       reader can feel that an otherwise correct technical document is
       lacking in authority, simply because it is poorly written. Readers
       feel at ease when they do not have to struggle to understand an
-      author's use of language.
-    </para>
-    <para>
-      This chapter cannot possibly cover enough material to make every
-      reader a good writer. Some manuals devoted entirely to writing
-      style are themselves hundreds of pages long. This chapter provides
-      enough guidelines for intermediate writers to understand style
-      usage in technical documentation.
-    </para>
-    <para>
-      If you are not a practiced writer, whether of technical
-      documentation or otherwise, you may benefit from other style
-      resources. The following list is far from comprehensive, but
-      provides a starting point: 
-    </para>
+      author's use of language. </para>
+    <para> This chapter cannot possibly cover enough material to make
+      every reader a good writer. Some manuals devoted entirely to
+      writing style are themselves hundreds of pages long. This chapter
+      provides enough guidelines for intermediate writers to understand
+      style usage in technical documentation. </para> <para> If you are
+      not a practiced writer, whether of technical documentation or
+      otherwise, you may benefit from other style resources. The
+      following list is far from comprehensive, but provides a starting
+      point: </para>
     <itemizedlist>
       <listitem>
         <para>
           <citetitle>The Elements of Style</citetitle>, by William
-          Strunk. Online version: <ulink
+          Strunk.  Online version: <ulink
             url="http://bartleby.com/141/">http://bartleby.com/141/</ulink>
         </para>
       </listitem>
+<!-- placeholder for when it's ready
+        <para>
+          <citetitle>The Elements of Style</citetitle>, by William
+          Strunk.  Fedora Docs Project version: <ulink
+            url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>
+        </para>
+-->      
+      <!-- KWade/TFox: Please check citation below, since I don't have
+      a copy. Thanks! And, um, I'm not sure if I should be using a
+      formal citation style below. /me is embarrassed. [PWF] -->
 
-	<!-- KWade/TFox: Please check citation below, since I don't have
-	a copy. Thanks! And, um, I'm not sure if I should be using a
-	formal citation style below. /me is embarrassed. [PWF] -->
+      <!-- this is the way to do it, you are correct. - kwade -->
+      <!-- comments may now be self-destructed -->
 
       <listitem>
         <para>
@@ -230,7 +234,10 @@
           </listitem>
         </varlistentry>
         <varlistentry> 
-          <term>Conformant</term> 
+          <term>Conformant</term> <!-- I'm having issues with the
+          sketchy definition of this non-dictionary word and the
+          associated text.  Not wrong, per se, just wishing for
+          something better.  This note shall remind us! - kwade -->
           <listitem>
             <para>
               Describe what you see. Do not describe what you want to
@@ -243,11 +250,18 @@
           <term>Clear</term> 
           <listitem> 
             <para>
-              Read <ulink
-                url="http://www.bartleby.com/141/"><citetitle>The
-                  Elements of Style</citetitle></ulink> to help make
-              your writing clear.
-            </para> 
+              Read <citetitle>The Elements of Style</citetitle> (<ulink
+                url="http://www.bartleby.com/141/">http://www.bartleby.com/141/</ulink>) 
+              to help make your writing clear.
+            </para>
+<!-- placeholder for when this is published:
+            <para>
+              Read <citetitle>The Elements of Style</citetitle>
+                &FED;-version (<ulink
+                url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>) 
+              to help make your writing clear.
+            </para>
+-->
           </listitem> 
         </varlistentry> 
         <varlistentry> 
@@ -264,9 +278,9 @@
           <term>Concise</term> 
           <listitem> 
             <para>
-		Review your work frequently as you write your document. Ask
-              yourself which words you can take out. See <xref
-		  linkend="sn-fundamentals-2"/> for a specific guideline.
+              Review your work frequently as you write your document.
+              Ask yourself which words you can take out. Refer to <xref
+                linkend="sn-fundamentals-2"/> for specific guidelines.
             </para> 
           </listitem> 
         </varlistentry> 
@@ -281,12 +295,12 @@
       </para>
       <variablelist>
         <varlistentry>
-          <term>Golden Rule 1: Be brief.</term>
+          <term>Golden Rule 1: Be brief</term>
           <listitem>
             <itemizedlist>
               <listitem>
                 <para>
-                  Limit each sentence to less than 25 words.
+                  Limit each sentence to fewer than 25 words.
                 </para>
               </listitem>
               <listitem>
@@ -313,7 +327,7 @@
           </listitem>
         </varlistentry>
         <varlistentry>
-          <term>Golden Rule 2: Be organized.</term>
+          <term>Golden Rule 2: Be organized</term>
           <listitem>
             <itemizedlist>
               <listitem>
@@ -373,7 +387,7 @@
           </listitem>
         </varlistentry>
         <varlistentry>
-          <term>Golden Rule 3: Be demonstrative.</term>
+          <term>Golden Rule 3: Be demonstrative</term>
           <listitem>
             <para>
               Use explicit examples to demonstrate how an application
@@ -404,7 +418,7 @@
           </listitem>
         </varlistentry>
         <varlistentry id="vle-golden-rule-4">
-          <term>Golden Rule 4: Be objective.</term>
+          <term>Golden Rule 4: Be objective</term>
           <listitem>
             <para>
               Write in a neutral tone. 
@@ -560,15 +574,17 @@
             <itemizedlist> 
               <listitem> 
                 <para>
-                  A term does not appear in the &FED; Jargon Guide.
+                  A term does not appear in the <citetitle>&FED; Jargon
+                    Buster</citetitle> (<ulink
+                    url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>).
                 </para> 
               </listitem> 
               <listitem> 
                 <para>
-                  A term does not appear in the <ulink
-                    url="http://www.bartleby.com/61/">
-                    <citetitle>American Heritage
-                      Dictionary</citetitle></ulink>.
+                  A term does not appear in the <citetitle>American
+                    Heritage Dictionary</citetitle> (<ulink
+                    url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ 
+                  </ulink>).
                 </para> 
               </listitem> 
               <listitem> 
@@ -647,11 +663,11 @@
     <para>
       This section contains an alphabetical list of grammar and usage
       guidelines for use in &FED; documentation. Many of these
-      guidelines are only applicable to English-language usage, see the
-      <ulink url="http://www.bartleby.com/61/"> <citetitle>American
-          Heritage Dictionary </citetitle></ulink> and the <ulink
-        url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> 
-        <citetitle>Chicago Manual of Style</citetitle></ulink>. 
+      guidelines are only applicable to English-language usage, refer to
+      the <citetitle>American Heritage Dictionary</citetitle> (<ulink
+        url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
+      and the <citetitle>Chicago Manual of Style</citetitle> (<ulink
+        url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
     </para> 
     <variablelist> 
       <varlistentry> 
@@ -681,6 +697,11 @@
               </para> 
             </listitem> 
           </itemizedlist>
+          <para>
+            For abbreviations of phrases, such as i.e. for "in other
+            words" and e.g. for "for example", do not use the
+            abbreviation.  Spell out the entire phrase.
+          </para>
         </listitem> 
       </varlistentry> 
       <varlistentry> 
@@ -911,7 +932,10 @@
             <listitem> 
               <para>
                 Do not use angle brackets to indicate variables in text,
-                instead use the <emphasis>replaceable</emphasis> tag.
+                instead use the
+                <replaceable>&lt;replaceable&gt;</replaceable> tag.
+                Refer to <xref linkend="s1-xml-tags-replaceable"/> for
+                information about using this tag.
               </para>
             </listitem> 
           </itemizedlist>
@@ -1182,7 +1206,8 @@
       <varlistentry> 
         <term>Gender</term> 
         <listitem> 
-          <para> See <xref linkend="sn-fundamentals-9"/>.
+          <para>
+            Refer to <xref linkend="sn-fundamentals-9"/>.
           </para>
         </listitem> 
       </varlistentry> 
@@ -1190,9 +1215,10 @@
         <term>Grammar</term> 
         <listitem> 
           <para>
-            Use standard American English grammar rules, see the <ulink
+            Use standard American English grammar rules, refer to the
+            <citetitle>Chicago Manual of Style</citetitle> (<ulink
               url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> 
-              <citetitle>Chicago Manual of Style</citetitle></ulink>.
+              http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
           </para>
         </listitem> 
       </varlistentry> 
@@ -1217,7 +1243,7 @@
             <listitem> 
               <para>
                 All lowercase letters for conjunctions, articles, and
-                prepositions of less than four letters
+                prepositions of fewer than four letters
               </para> 
             </listitem> 
             <listitem> 
@@ -1255,9 +1281,11 @@
             </listitem> 
             <listitem> 
               <para>
-                With some standard prefixes and suffixes. Use the <ulink
-                  url="http://www.bartleby.com/61/"> <citetitle>American
-                    Heritage Dictionary</citetitle></ulink> for guidance
+                With some standard prefixes and suffixes. Use the
+                <citetitle>American Heritage Dictionary</citetitle>
+                (<ulink
+                  url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
+                for guidance
               </para> 
             </listitem> 
             <listitem> 
@@ -1268,7 +1296,7 @@
             <listitem> 
               <para>
                 In variable names of two or more words, such as
-                <replaceable> directory-name</replaceable>. Note:
+                <replaceable>directory-name</replaceable>. Note:
                 <replaceable>filename</replaceable> is an exception.
               </para> 
             </listitem> 
@@ -1299,10 +1327,11 @@
             </listitem> 
             <listitem> 
               <para>
-                With a word that is listed as unhyphenated in the <ulink
-                  url="http://www.bartleby.com/61/"> <citetitle>American
-                    Heritage Dictionary</citetitle></ulink>, and that
-                uses a common prefix
+                With a word that is listed as unhyphenated in the
+                <citetitle>American Heritage Dictionary</citetitle>
+                (<ulink
+                  url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>), 
+                and that uses a common prefix
               </para> 
             </listitem> 
             <listitem> 
@@ -1478,10 +1507,10 @@
         <listitem> 
           <para>
             Use standard American English punctuation rules. In addition
-            to the specific points of punctuation in this section, see
-            also the <ulink
-              url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> 
-              <citetitle>Chicago Manual of Style</citetitle></ulink>.
+            to the specific points of punctuation in this section, refer
+            also to the <citetitle>Chicago Manual of Style</citetitle>
+            (<ulink
+              url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
           </para>
         </listitem> 
       </varlistentry> 
@@ -1506,6 +1535,23 @@
           </para> 
         </listitem> 
       </varlistentry> 
+      <varlistentry>
+        <term>See v. Refer to</term>
+        <listitem>
+          <para>
+            When referring a user to another resource, use "refer to"
+            instead of "see", and "refer also to" instead of "see also".
+            This differentiates from the
+            <computeroutput>&lt;see&gt;</computeroutput> and
+            <computeroutput>&lt;seealso&gt;</computeroutput> tags that
+            are used in indexing.  These tags create special links in
+            the index.  To be consistent throughout the document, we
+            reserve the special words "see" and "see also" for
+            hyperlinked index references, and use "refer to" and "refer
+            also to" for non-hyperlinked and non-indexed references.
+          </para>
+        </listitem>
+      </varlistentry>
       <varlistentry> 
         <term>Semicolon</term> 
         <listitem> 
@@ -1529,9 +1575,10 @@
         <term>Spelling</term> 
         <listitem> 
           <para>
-            Use standard American English spelling rules, see the <ulink
-              url="http://www.bartleby.com/61/"> <citetitle>American
-                Heritage Dictionary</citetitle></ulink> for guidelines.
+            Use standard American English spelling rules, refer to the
+            <citetitle>American Heritage Dictionary</citetitle> (<ulink
+              url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
+            for guidelines.
           </para>
         </listitem> 
       </varlistentry> 
@@ -1559,7 +1606,7 @@
             <listitem> 
               <para> <!-- See <xref linkend="units"/> for a list of
                 units relevant to the GNOME Desktop. --> For further
-                guidelines, see the <citetitle>IEEE Standard Dictionary
+                guidelines, refer to the <citetitle>IEEE Standard Dictionary
                   of Electrical and Electronics Terms</citetitle>. 
               </para> 
             </listitem> 
@@ -1647,7 +1694,7 @@
         words "will" and "shall" are almost never needed in describing
         what the user should do or see. They add unnecessary length to
         sentences and can confuse translators. They are also often
-        indicators of passive voice; see also
+        indicators of passive voice; refer also to
 	    <xref
 	    linkend="sn-misc-active-voice"/>.
       </para>
@@ -1710,7 +1757,7 @@
         an overly dogmatic tone. The word "avoid" is useful for this
         purpose.  Note that contractions are often used for negative
         words such as <emphasis>don't</emphasis> or
-        <emphasis>can't</emphasis>. See <xref
+        <emphasis>can't</emphasis>. Refer to <xref
 	    linkend="vle-contractions" />.
       </para>
     </section>
@@ -1753,8 +1800,7 @@
         state, "Do <replaceable>XYZ</replaceable>." Then elaborate as
         required. If the whole section concerns how to do
         <replaceable>XYZ</replaceable>, leave this sentence out
-        entirely. See also <xref linkend="vle-golden-rule-4"
-          />.
+        entirely. Refer also to <xref linkend="vle-golden-rule-4" />.
       </para>
     </section>
 
@@ -1882,7 +1928,7 @@
         <para>
 	    Use the entities provided by the &FDP;. These entities are found
           in the <filename>common/</filename> folder in the
-          <filename>fedora-docs</filename> distribution. (See also
+          <filename>fedora-docs</filename> distribution. (Refer also to
 	    <xref
 	    linkend="ch-getting-files"/>.) For instance, do not use
           abbreviations such as "FC2." Instead, use the predefined
@@ -1892,9 +1938,9 @@
       </section>
 
     </section>
-	      
+    
   </section>
-
+  
 </chapter>
 <!-- Keep this comment at the end of the file
 Local variables:
@@ -1902,3 +1948,4 @@ mode: xml
 sgml-parent-document:("documentation-guide-en.xml" "book" "chapter")
 End:
 -->
+
-- 
cgit