This represents that state of the Doc Guide with Paul's Style chapter included, prior to _any_ editing from me.

2 files changed, 1936 insertions, 3 deletions

diff --git a/docs-style-en.xml b/docs-style-en.xml
new file mode 100644
index 0000000..6480e54
--- /dev/null
+++ b/docs-style-en.xml
@@ -0,0 +1,1930 @@
+  <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".
+
+    [PWF]
+
+  -->
+
+    <title>Style</title>
+
+    <para>
+      Writing good technical documentation is not simply reproducing
+      command lines and instruction sets. Good documentation is easy to
+      read, understand, and translate, and presents a concise logical
+      progression of concepts. Good documentation can also be defined by
+      what it does <emphasis>not</emphasis> contain. Your tutorial
+      should avoid:
+    </para>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  excessive wordiness
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  unnecessary or undefined jargon
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  grammatical or spelling errors
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  references to yourself or your experiences
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  remarks which might offend or confuse any reader
+	</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      In this chapter, you will find style rules and guidelines for
+      writing &FED; documentation. Guidelines are not the same as
+      rules. It is acceptable to violate a guideline when it makes your
+      material easier to understand. Follow guidelines whenever
+      possible, but follow rules at all times. Assume any advice is a
+      guideline unless identified otherwise.
+    </para>
+
+    <section id="sn-intro-to-style">
+      
+      <title>Why Style Is Important</title>
+      
+      <para>
+	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, elegant
+	writing may not follow some (or any) common rules of 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
+	    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>
+	</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
+	disorganized but loosely connected thought patterns of his
+	narrator.
+      </para>
+      <para>
+	Technical documentation, however, should always respect these
+	rules. The more a document departs from standard language usage,
+	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 confused. Take the following example, which compares two
+	different written executions of the same idea:
+      </para>
+      <example>
+	<title>Incorrect style</title> 
+
+	<!-- I prefer "incorrect," because I think terms such as
+	"problematic" are mealy-mouthed. They remind me of the late
+	1980's English textbook trend toward the politically correct yet
+	wholly unhelpful "standard/nonstandard."  But then, I tend to be
+	dogmatic; it's probably my Catholic upbringing. [PWF] -->
+
+	<para>
+	  So you made the changes I showed you in the last section.
+	  What's the next thing you should do? Just pop your thumb drive
+	  onto your system and read the <filename>messages</filename>
+	  log. When you see "USB device found," then Bob's your uncle.
+	</para>
+      </example>
+      <example>
+	<title>Correct style</title> 
+	
+	<!-- I prefer "correct." See above. [PWF] -->
+	
+	<para>
+	  After you complete the configuration changes above, attach the
+	  USB removable media to your system. Use the
+	  <command>dmesg</command> command to examine the kernel message
+	  log. The message <computeroutput>USB device
+	  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
+	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
+	negatively affect a reader's reaction to written material. A
+	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>
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    <citetitle>The Elements of Style</citetitle>, by William
+	    Strunk.  Online version: <ulink
+	    url="http://bartleby.com/141/">http://bartleby.com/141/</ulink>
+	  </para>
+	</listitem>
+
+	<!-- 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] -->
+
+	<listitem>
+	  <para>
+	    <citetitle>The Chicago Manual of Style</citetitle>, by the
+	    University of Chicago Press. Online version: <ulink
+	    url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    <citetitle>Paradigm Online Writing Assistant</citetitle>,
+	    maintained by Chuck Guilford, Ph.D. Online only: <ulink
+	      url="http://www.powa.org/">http://www.powa.org/</ulink>
+	  </para>
+	</listitem>
+      </itemizedlist>
+      <para>
+	There are many free software documentation projects which have
+	developed their own style guidelines. This chapter, in fact,
+	draws heavily on the <citetitle>GNOME Documentation Style
+	Guidelines</citetitle> (<firstterm>GDSG</firstterm>). You may
+	read the original <citetitle>GDSG</citetitle> at <ulink
+	url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>.
+      </para>
+      
+    </section>
+    
+    <section id="sn-tech-docs-fundamentals">
+    
+      <title>Fundamental Concepts of Technical Documentation</title>
+      
+      <note>
+	<title>Bibliographic Information</title>
+	<para>
+	  This section is drawn primarily from the
+	  <citetitle>GDSG</citetitle>.
+	</para>
+      </note>
+      
+      <!-- This section will reproduce mostly what is in Chapter 1 of
+      the GDSG. There may be minor changes. FIXME: Make sure the
+      appropriate front matter of the Documentation Guide includes
+      attribution as required by the GNU FDL. -->
+
+      <para>
+	This chapter provides a brief introduction to writing technical
+	documentation.
+      </para>
+
+      <section id="sn-fundamentals-1">
+	<title>General Style Requirements</title>
+	<para>
+	  Technical writing for the &FP; imposes special constraints
+	  beyond the basic requirements of good prose. Good &FED;
+	  technical documentation has the following characteristics:
+	</para>
+	<variablelist>
+	  <varlistentry>
+	    <term>Comprehensive</term>
+	    <listitem>
+	      <para>
+		Describe all of the functionality of a product. Do not
+		omit functionality that you regard as irrelevant for the
+		user.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry> 
+	    <term>Conformant</term> 
+	    <listitem>
+	      <para>
+		Describe what you see. Do not describe what you want to
+		see. Present your information in the order that users
+		experience the subject matter.  
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <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> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Consistent</term> 
+	    <listitem> 
+	      <para>
+		Use agreed vocabulary throughout your documentation. Use
+		the same vocabulary as other writers who are working on
+		related documentation.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <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.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	</variablelist> 
+      </section> 
+      <section id="sn-fundamentals-2"> 
+	<title>Golden Rules</title> 
+	<para>
+	  This section contains some basic style guidelines. Subsequent
+	  sections in this chapter expand on these guidelines to give
+	  more detailed guidance.
+	</para>
+	<variablelist>
+	  <varlistentry>
+	    <term>Golden Rule 1: Be brief.</term>
+	    <listitem>
+	      <itemizedlist>
+		<listitem>
+		  <para>
+		    Limit each sentence to less than 25 words.
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>
+		    Limit each procedure step to 23 words.
+		  </para>
+		</listitem>
+	      </itemizedlist>
+	      <example id="ex-golden-rule-1-wrong">
+		<title>Incorrect: Too long</title>
+		<para> 
+		  Under normal operating conditions, the kernel does not
+		  always immediately write file data to the disks,
+		  storing it in a memory buffer and then periodically
+		  writing to the disks to speed up operations. 
+		</para>
+	      </example>
+	      <example id="ex-golden-rule-1-right">
+		<title>Correct: Less wordy</title>
+		<para>
+		  Normally, the kernel stores the data in memory prior
+		  to periodically writing the data to the disk. 
+		</para>
+	      </example>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Golden Rule 2: Be organized.</term>
+	    <listitem>
+	      <itemizedlist>
+		<listitem>
+		  <para>
+		    Limit each paragraph to one topic.
+		  </para> 
+		</listitem> 
+		<listitem> 
+		  <para>
+		    Limit each sentence to one idea.
+		  </para> 
+		</listitem> 
+		<listitem> 
+		  <para>
+		    Limit each procedure step to one action.
+		  </para> 
+		</listitem> 
+	      </itemizedlist>
+	      <example id="ex-golden-rule-2-wrong">
+		<title>Incorrect: Disorganized topics</title>
+		<para>
+		  The <application>Workspace Switcher</application>
+		  applet helps you navigate all of the virtual desktops
+		  available on your system. The X Window system, working
+		  in hand with a piece of software called a
+		  <emphasis>window manager</emphasis>, allows you to
+		  create more than one virtual desktop, known as
+		  <emphasis>workspaces</emphasis>, to organize your
+		  work, with different applications running in each
+		  workspace. The <application>Workspace
+		    Switcher</application> applet is a navigational tool
+		  to get around the various workspaces, providing a
+		  miniature road map in the GNOME panel showing all your
+		  workspaces and allowing you to switch easily between
+		  them. 
+		</para>
+	      </example>
+	      <example id="ex-golden-rule-2-right">
+		<title>Correct: Organized topics</title>
+		<para>
+		  You can use the <application>Workspace
+		    Switcher</application> to add new
+		  <emphasis>workspaces</emphasis> to the GNOME Desktop.
+		  You can run different applications in each workspace.
+		  The <application>Workspace Switcher</application>
+		  applet provides a miniature map that shows all of your
+		  workspaces. You can use the <application>Workspace
+		    Switcher</application> applet to switch between
+		  workspaces.
+		</para>
+	      </example>
+	      <tip>
+		<para>
+		  Plan the order of paragraphs before you start writing.
+		  Decide which topic you want to cover in each
+		  paragraph.
+		</para>
+	      </tip>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Golden Rule 3: Be demonstrative.</term>
+	    <listitem>
+	      <para>
+		Use explicit examples to demonstrate how an application
+		works. Provide instructions rather than descriptions.
+	      </para>
+	      <example id="ex-golden-rule-3-wrong">
+		<title>Incorrect: Describes but does not
+		  demonstrate</title>
+		<para>
+		  There is a text box that you can use to find out the
+		  definition of a word.
+		</para>
+	      </example>
+	      <example id="ex-golden-rule-3-right">
+		<title>Correct: Demonstrates usage</title>
+		<para>
+		  To request a definition of a word, type the word in
+		  the text box, then click on the Lookup button. 
+		</para>
+	      </example>
+	      <tip>
+		<para>
+		  Do not apply this guideline too rigidly. Sometimes you
+		  must explain how software works to support your how-to
+		  examples.
+		</para>
+	      </tip>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry id="vle-golden-rule-4">
+	    <term>Golden Rule 4: Be objective.</term>
+	    <listitem>
+	      <para>
+		Write in a neutral tone. 
+	      </para>
+	      <example id="ex-golden-rule-4-wrong">
+		<title>Incorrect: Sentence takes sides</title>
+		<para>
+		  The applet is a handy little screen grabber. 
+		</para>
+	      </example>
+	      <example id="ex-golden-rule-4-right">
+		<title>Correct: Sentence is objective</title>
+		<para>
+		  Use the applet to take screenshots.
+		</para>
+	      </example>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+      </section> 
+
+      <section id="sn-fundamentals-3"> 
+
+	<title>Tone</title> 
+	<para>
+	  Inappropriate tone can hinder reader access to information. A
+	  neutral tone free of opinion or personal flavor reduces the
+	  processing load for the reader to understand the information.
+	  Another benefit of a neutral tone is that several writers can
+	  work in parallel on a large technical documentation project.
+	  Furthermore, different writers can join the project at
+	  different times. The use of a neutral tone helps to achieve
+	  consistency across a documentation set, and thereby
+	  facilitates user access to information. The best way to
+	  achieve a common, neutral tone is to apply the following
+	  principles:
+	</para>
+	<variablelist> 
+	  <varlistentry> 
+	    <term>Avoid humor</term> 
+	    <listitem> 
+	      <para>
+		Humor distracts from the information you are trying to
+		provide. Humor also makes documentation difficult to
+		translate. Stay factual.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid personal opinions</term> 
+	    <listitem> 
+	      <para>
+		Whether you think a function is useful or woeful is
+		irrelevant. Report the function to the user, with
+		instructions about how to use the function. Stay
+		accurate.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid colloquial language</term> 
+	    <listitem> 
+	      <para>
+		Colloquial language is difficult to translate and
+		usually culture-specific. Stay neutral.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid topical expressions</term> 
+	    <listitem> 
+	      <para>
+		An expression that is in common use today might convey
+		something completely different tomorrow. Stay technical.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid aspirational statements</term> 
+	    <listitem> 
+	      <para>
+		Statements about the future developments of a product do
+		not belong in technical documentation. Write about what
+		you see right now. Stay real.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	</variablelist>
+      </section> 
+      <section id="sn-fundamentals-4"> 
+	<title>Reaching the Right Audience</title> 
+	<para>
+	  All of the decisions that you make about the structure and
+	  content of a manual follow from an understanding of the
+	  audience. You need to think about how the audience accesses
+	  the documentation, what sort of information the audience
+	  needs, and the experience level of the audience. Usually, you
+	  need to create documentation that is suitable for different
+	  audiences. The following sections introduce some of the
+	  audience-related topics you need to consider.
+	</para> 
+      </section>
+      <section id="sn-fundamentals-6"> 
+	<title>User Motivation</title> 
+	<para>
+	  Do not waste the time of the user who looks for information in
+	  your documentation. Users do not read technical documentation
+	  for entertainment. Users usually have specific questions. You
+	  need to give clear answers to those questions.
+	</para> 
+      </section> 
+      <section id="sn-fundamentals-7"> 
+	<title>New Users</title> 
+	<para>
+	  New users to &FC; are likely to consult online tutorials for
+	  guidance about unfamiliar applications or functionality. Each
+	  tutorial should contain enough introductory information to
+	  tell new users how to start using the relevant functions. Each
+	  tutorial should also contain enough usage instructions to tell
+	  users the different actions that they can perform with the
+	  command or function. Keep these instructions task-oriented.
+	  You do not need to describe GUI screens, dialogs, and dialog
+	  elements in a tutorial, unless there is an unusual feature
+	  that affects your instructions.
+	</para> 
+      </section> 
+      <section id="sn-fundamentals-8"> 
+	<title>Experienced Users</title> 
+	<para>
+	  Experienced users are more likely to use documentation as a
+	  reference. The documentation therefore needs to be complete,
+	  well-organized, and in the case of printed manuals,
+	  well-indexed.
+	</para> 
+      </section> 
+      <section id="sn-fundamentals-9"> 
+	<title>Do Not Offend Your Audience</title> 
+	<para>
+	  To avoid offending your readers, apply the following
+	  guidelines to your documentation: 
+	</para>
+	<variablelist> 
+	  <varlistentry> 
+	    <term>Avoid insider language</term> 
+	    <listitem> 
+	      <para>
+		Insider language includes both undefined jargon and the
+		tendency of the computer community to shorten words. For
+		example, use the term <emphasis>documentation</emphasis>
+		instead of the term <emphasis>docs</emphasis>. You can
+		identify jargon if terminology fails the following
+		conditions:
+	      </para>
+	      <itemizedlist> 
+		<listitem> 
+		  <para>
+		    A term does not appear in the &FED; Jargon Guide.
+		  </para> 
+		</listitem> 
+		<listitem> 
+		  <para>
+		    A term does not appear in the <ulink
+		      url="http://www.bartleby.com/61/">
+		      <citetitle>American Heritage
+			Dictionary</citetitle></ulink>.
+		  </para> 
+		</listitem> 
+		<listitem> 
+		  <para>
+		    A term does not appear in the glossary of the manual
+		    that you are writing.
+		  </para> 
+		</listitem> 
+		<listitem> 
+		  <para>
+		    A term is not defined in the body text of the manual
+		    that you are writing.
+		  </para> 
+		</listitem> 
+	      </itemizedlist>
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid gender-specific language</term> 
+	    <listitem> 
+	      <para>
+		Pronoun constructions such as
+		<emphasis>his/her</emphasis> or
+		<emphasis>s/he</emphasis> do not exist. There is no need
+		to identify gender in your instructions.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid culture-specific language</term> 
+	    <listitem> 
+	      <para>
+		There is little point in giving an example that everyone
+		in your town knows about, but is a complete mystery to
+		everyone else in the world.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	  <varlistentry> 
+	    <term>Avoid talking down to your reader</term> 
+	    <listitem> 
+	      <para>
+		There are few experiences more irritating for a user
+		than documentation that says an action is easy or quick,
+		when in fact the user cannot complete the action. Do not
+		qualify or prejudge actions.
+	      </para> 
+	    </listitem> 
+	  </varlistentry> 
+	</variablelist>
+	<para>
+	  Other parts of this guide discuss in more detail tone and
+	  language usage that can cause offense.
+	</para> 
+
+      </section> 
+
+    </section> 
+
+    <section id="sn-grammar-and-usage">
+
+      <title>Grammar and Usage Guidelines</title>
+
+      <note>
+	<title>Bibliographical Information</title>
+	<para>
+	  This section is drawn partly from the <citetitle>GDSG</citetitle>, and
+	  partly from <citetitle>The Elements of Style</citetitle>, updated as
+	  necessary for the needs of 21st-century technical documentation
+	  writers.
+	</para>
+      </note>
+
+      <!-- FIXME: Again, check attribution viz. GNU FDL. This will be more work
+      than the previous section. -->
+
+      <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>. 
+      </para> 
+      <variablelist> 
+	<varlistentry> 
+	  <term>Abbreviations</term> 
+	  <listitem> 
+	    <para>
+	      A shortened form of a word or phrase that takes the place
+	      of the full word or phrase, for example Dr., a.m., p.m.,
+	      and so on.  Apply the following rules when you use
+	      abbreviations:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Avoid creating new abbreviations. Unfamiliar
+		  abbreviations can confuse rather than clarify a
+		  concept.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not explain or expand familiar abbreviations.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not include familiar abbreviations in the glossary
+		  of your manual.
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Adjectives</term> 
+	  <listitem> 
+	    <para>
+	      Use adjectives with caution. If an adjective is necessary
+	      to differentiate between items, then use adjectives. In
+	      all cases, test whether the phrase can stand alone without
+	      the adjective. 
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Acronyms</term> 
+	  <listitem> 
+	    <para>
+	      A term that represents a multi-word term. Typically,
+	      acronyms are formed in the following ways:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  From the first letters of each word in a compound
+		  term, for example Table of Contents (TOC).
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  From recognizable parts of a compound term, such as
+		  GNU Object Model Environment (GNOME).
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	    <para>
+	      Apply the following rules when you use acronyms:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  On the first occurrence of an acronym, spell out the
+		  full term, with the acronym in parentheses.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not spell out the full compound for well-known
+		  acronyms, unless you think the information is useful
+		  for readers.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Avoid creating new acronyms. Unfamiliar acronyms can
+		  confuse rather than clarify a concept.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Write the acronym in uppercase letters, unless there
+		  is a compelling case for lowercase.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Include the acronym and the full term in the glossary
+		  of your manual. 
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Adverbs</term> 
+	  <listitem> 
+	    <para>
+	      Use adverbs with caution. If an adverb is necessary to
+	      qualify the function of a component, then use an adverb.
+	      In all cases, test whether the phrase can stand alone
+	      without the adverb. Classic superfluous adverbs are:
+	      <emphasis>simply, easily, quickly</emphasis>.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Anthropomorphism</term> 
+	  <listitem> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Do not apply emotions, desires, or opinions to
+		  software applications.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not apply a sense of location or dimension to a
+		  software application. You can not be
+		  <emphasis>in</emphasis> a text editor.
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Articles</term> 
+	  <listitem> 
+	    <para>
+	      Do not use the definite article <emphasis>the</emphasis>
+	      to begin any of the following items:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Manual titles
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Chapter titles
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Headings
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Figure captions
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Table captions
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Callouts
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Apostrophe</term> 
+	  <listitem> 
+	    <para>
+	      Do not use apostrophes except where absolutely
+	      required
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>
+		  Do not use apostrophes to denote possession.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not use apostrophes to denote contractions.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not use apostrophes to denote plurals.
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	    <example id="ex-apostrophe-wrong">
+	      <title>Incorrect: Apostrophes</title>
+	      <itemizedlist>
+		<listitem>
+		  <para>
+		    the <guimenu>Main Menu's</guimenu>
+		    <guimenuitem>Help</guimenuitem> option
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>
+		    don't use the default option
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>
+		    several SCSI disk's
+		  </para>
+		</listitem>
+	      </itemizedlist>
+	    </example>
+	    <example id="ex-apostrophe-right">
+	      <title>Correct: No apostrophes</title>
+	      <itemizedlist>
+		<listitem>
+		  <para>
+		    the <guimenuitem>Help</guimenuitem> option on the
+		    <guimenu>Main Menu</guimenu>
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>
+		    do not use the default option
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>
+		    several SCSI disks
+		  </para>
+		</listitem>
+	      </itemizedlist>
+	    </example>
+	  </listitem>
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Brackets</term> 
+	  <listitem> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Do not use brackets [such as these] as a substitute
+		  for parentheses (such as these).
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Use brackets for optional command line entries.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Do not use angle brackets to indicate variables in
+		  text, instead use the <emphasis>replaceable</emphasis>
+		  tag.
+		</para>
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Capitalization</term> 
+	  <listitem> 
+	    <para>
+	      Capitalize in the following situations:
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  All letters in acronyms, unless the acronym is a
+		  well-known exception
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial letter of the first word in a list
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial letter of the first word in a callout
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial letter of a key name, such as the
+		  <keycap>Shift</keycap> key
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial letter of a sentence. Avoid starting a
+		  sentence with a command name or application name that
+		  has a lowercase initial letter
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial letter of a complete sentence after a colon
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	    <para>
+	      Do not capitalize in the following situations: 
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  A compound term that is followed by an abbreviation or
+		  an acronym
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  When you want to emphasize something
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Variable names
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  The initial letter of the first word following a
+		  colon, if the word is part of an incomplete sentence
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Captions</term> 
+	  <listitem> 
+	    <para>
+	      Use the same rules as for headings, for all captions
+	      accompanying figures and tables. Do not put a period at
+	      the end of a caption.
+	    </para> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Colon</term> 
+	  <listitem> 
+	    <para>
+	      Use a colon in the following situations: 
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>
+		  To introduce a list
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>
+		  Before an explanation
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>
+		  After an introduction
+		</para>
+	      </listitem>
+	    </itemizedlist>
+	    <para>
+	      Do not use a colon in the following situations:
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>
+		  To introduce a figure or a table
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>
+		  To introduce headings
+		</para>
+	      </listitem>
+	      <listitem>
+		<para>
+		  At the end of an introduction to a procedure
+		</para>
+	      </listitem>
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Column headings</term> 
+	  <listitem> 
+	    <para>
+	      Use the same rules as for headings.
+	    </para> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Comma</term> 
+	  <listitem> 
+	    <para>
+	      Use commas in the following situations: 
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  To separate items in a series
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  To separate the parts of a sentence
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  To separate nonrestrictive phrases
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Instead of dashes to set off appositives
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  With <emphasis>for example</emphasis> and similar
+		  expressions
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	    <para>
+	      Do not use commas in the following situations: 
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  In a series of adjectives used as one modifier
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Between two short independent clauses
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Commands</term> 
+	  <listitem> 
+	    <para>
+	      Do not use commands as verbs. 
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry id="vle-contractions"> 
+	  <term>Contractions</term> 
+	  <listitem> 
+	    <para>
+	      Do not use contractions such as
+	      <emphasis>can't</emphasis>, <emphasis>don't</emphasis>, or
+	      <emphasis>isn't</emphasis>. 
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Dash</term> 
+	  <listitem> 
+	    <para>
+	      Do not use the em dash or the en dash. Use a paragraph
+	      break or a colon instead, where you want to create an
+	      introductory piece of text. If you have several items that
+	      you want to introduce, then you can use a variable list.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Ellipsis</term> 
+	  <listitem> 
+	    <para>
+	      Use an ellipsis in the following situations:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  To show that you have omitted something from a
+		  sentence 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  To indicate a pause when you quote displayed text
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Fractions</term> 
+	  <listitem> 
+	    <para>
+	      Follow these rules when using fractions:
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Use numerals for fractions in tables and in units of
+		  measurement, but spell out fractions in prose.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Use a space between a numeral and a related fraction,
+		  if there is a possible ambiguity. For example: 1
+		  1&#47;2 instead of 11&#47;2.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  If a fraction is used in a compound modifier, insert a
+		  hyphen between the fraction and the unit of
+		  measurement.
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Gender</term> 
+	  <listitem> 
+	    <para> 
+	      See <xref linkend="sn-fundamentals-9"/>.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Grammar</term> 
+	  <listitem> 
+	    <para>
+	      Use standard American English grammar rules, see the
+	      <ulink
+		url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> 
+		<citetitle>Chicago Manual of Style</citetitle></ulink>.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Headings</term> 
+	  <listitem> 
+	    <para>
+	      Use the following capitalization rules in headings:
+	    </para> 
+	    <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Initial uppercase letter of the first word
+		</para>
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial uppercase letter for all nouns, adjectives,
+		  and verbs.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  All lowercase letters for conjunctions, articles, and
+		  prepositions of less than four letters
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial uppercase letter for prepositions of four
+		  letters or longer
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Initial uppercase letter for conjunctions of four
+		  letters or longer
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	    <!-- <para> See <xref linkend="infodesign-2"/> for more 
+	    information about headings. </para> -->
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Hyphen</term> 
+	  <listitem> 
+           <para>
+	      Use hyphens in the following situations: 
+	    </para>
+            <itemizedlist> 
+	      <listitem> 
+		<para> 
+		  With a numeral in a compound modifier 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  To prevent ambiguity
+		</para> 
+	      </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
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  In spelled-out fractions 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  In variable names of two or more words, such as
+		  <replaceable> directory-name</replaceable>. Note:
+		  <replaceable>filename</replaceable> is an exception.
+		</para> 
+	      </listitem> 
+            </itemizedlist>
+	    <para>
+	      Do not use hyphens in the following situations: 
+	    </para> 
+            <itemizedlist> 
+	      <listitem> 
+		<para>
+		  For industry-accepted terms
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  To construct verbs
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  With an adverb ending in <emphasis>ly</emphasis>
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  With numerals as single modifiers 
+		</para> 
+	      </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
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  With trademarked terms
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Latin terms</term> 
+	  <listitem> 
+	    <para>
+	      Do not use Latin terms. Use an equivalent English term
+	      instead. 
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Like</term> 
+	  <listitem> 
+            <para>
+	      Do not use the term <emphasis>like</emphasis> to
+	      denote equivalence or similarity.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Lists</term> 
+	  <listitem> 
+            <para>
+	      Introduce a list with a complete sentence that ends with a
+	      colon.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Numbers</term> 
+	  <listitem> 
+	    <para>
+	      Spell out numbers in the following situations:
+	    </para>
+	    <itemizedlist> 
+	      <listitem> 
+		<para> 
+		  Numbers from zero through nine unless the number
+		  is part of a measurement
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Approximations
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Extreme values such as <emphasis>million</emphasis>,
+		  but precede the value with a numeral
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Any number that begins a sentence 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  A number that is immediately followed by a numeral,
+		  for example: two 10 MB files 
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Numerals</term> 
+	  <listitem> 
+            <para>
+	      Use numerals in the following situations:
+	    </para> 
+            <itemizedlist> 
+	      <listitem> 
+		<para>
+		  The number 10 or greater
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para> 
+		  Negative numbers 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Most fractions
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Percentages
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Decimals
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Measurements 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Units of time smaller than one second
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  References to bits and bytes
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Parentheses</term> 
+	  <listitem> 
+	    <para>
+	      Use parentheses in the following situations:
+	    </para> 
+            <itemizedlist> 
+	      <listitem> 
+		<para>
+		  To contain the abbreviation of a term on the first
+		  occurrence of the full term 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para> 
+		  In man page references, specifically the section
+		  number 
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Period</term> 
+	  <listitem> 
+	    <para>
+	      Use a period in the following situations:
+	    </para> 
+            <itemizedlist> 
+	      <listitem> 
+		<para>
+		  To end a sentence
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  In file and directory names
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  In abbreviations that can be mistaken for words, such
+		  as a.m. and U.S.
+		</para> 
+	      </listitem> 
+	    </itemizedlist> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Punctuation</term> 
+	  <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>.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Punctuation in numbers</term> 
+	  <listitem> 
+	    <para>
+	      Do not use a comma in numerals of four digits. Use a comma
+	      in numerals of more than four digits.
+	    </para> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Quotation marks</term> 
+	  <listitem> 
+	    <para>
+	      Use quotation marks to indicate material that is taken
+	      verbatim from another source. Do not use quotation marks
+	      to excuse terms from legitimacy. If the term is not
+	      legitimate, then use another term. If you must use that
+	      term, declare the term in the glossary and make the term
+	      legitimate.
+	    </para> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Semicolon</term> 
+	  <listitem> 
+	    <para>
+	      Do not use semicolons. 
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry>
+	  <term>Slash</term>
+	  <listitem>
+	    <para>
+	      Except where required as part of a filename, do not use
+	      slashes "&#47;" in your writing. The construction
+	      "and&#47;or," for example, does not exist. Use one or the
+	      other term instead.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry> 
+	  <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.
+	    </para>
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Titles</term> 
+	  <listitem> 
+	    <para>
+	      For manual titles use the same rules as for headings.
+	    </para> 
+	  </listitem> 
+	</varlistentry> 
+	<varlistentry> 
+	  <term>Units</term> 
+	  <listitem> 
+	    <para>
+	      Follow these rules when using units:
+	    </para>
+            <itemizedlist> 
+	      <listitem> 
+		<para>
+		  Use standard abbreviations for units of measurements,
+		  do not invent your own abbreviations.
+		</para> 
+	      </listitem> 
+	      <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 of Electrical and Electronics
+		    Terms</citetitle>. 
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Use periods for abbreviated units that might be
+		  mistaken for a word.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Most standard abbreviations of units account for both
+		  singular and plural usage.
+		</para> 
+	      </listitem> 
+	      <listitem> 
+		<para>
+		  Insert a space between the numeral and the unit of
+		  measurement. 
+		</para> 
+	      </listitem> 
+	    </itemizedlist>
+	  </listitem> 
+	</varlistentry> 
+      </variablelist> 
+
+    </section>
+
+    <section id="sn-composition-tips">
+
+      <title>Composition Tips</title>
+
+<!--
+
+	This section will collect miscellanea and advice for specific situations
+	that the &FDP; editors encounter. I hope they will feel free to e-mail
+	me sticky situations or particularly interesting examples of work
+	they've beautified. Hopefully not too much will be drawn from my own
+	work!
+
+-->
+
+      <para>
+	This section contains usage tips based on situations the &FDP;
+	editors have encountered in the past. You should read and
+	understand these examples to improve your own documentation. The
+	&FDP; editors welcome additional examples.
+      </para>
+
+      <section id="sn-misc-active-voice">
+	<title>Active Voice</title>
+	<para>
+	  Always use active voice, except when it is awkward to do so.
+	  The tutorial tells the user how to accomplish a task, and
+	  should give instructions clearly and concisely. Avoid using
+	  "must," "need to," and the like. These words are redundant in
+	  a tutorial, since the reader assumes you are outlining
+	  necessary steps to accomplish a task. Also avoid using
+	  "should," "might," and other words that indicate you are
+	  unsure about the subject matter. Your tutorial should cover a
+	  subject authoritatively. The reader should never be concerned
+	  about unknown effects of following the tutorial.
+	</para>
+	<example id="ex-misc-passive-voice">
+	  <title>Incorrect: Passive voice</title>
+	  <para>
+	    The <command>yum update</command> command must be run.
+	  </para>
+	  <para>
+	    You should run the <command>yum update</command> command.
+	  </para>
+	</example>
+	<example id="ex-misc-active-voice">
+	  <title>Correct: Active voice</title>
+	  <para>
+	    Run the <command>yum update</command> command.
+	  </para>
+	</example>
+      </section>
+
+      <section id="sn-present-tense">
+	<title>Present Tense</title>
+	<para>
+	    Write in the present tense. A good rule of thumb is that the
+	  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
+	    <xref
+	    linkend="sn-misc-active-voice"/>.
+	</para>
+	<example id="ex-misc-future-tense">
+	  <title>Incorrect: Future tense</title>
+	  <para>
+	    The application will display a list of target files.
+	  </para>
+	  <para>
+	    A list of target files will be displayed by the application.
+	  </para>
+	</example>
+	<example id="ex-misc-present-tense">
+	  <title>Correct: Present tense</title>
+	  <para>
+	    The application displays a list of target files.
+	  </para>
+	</example>
+      </section>
+	  
+      <section id="sn-narrative-voice">
+	<title>Narrative Voice</title>
+	<para>
+	  Do not use the first person "I," "we," or "us" to refer to
+	  yourself the writer (whether including the reader or not), the
+	  &FDP;, the &FED; community, or any other group. Do not refer
+	  to users with a third person pronoun ("he," "she," or "he or
+	  she") or the word "one." It is acceptable to refer to the
+	  reader with the second person pronoun "you."
+	</para>
+	<example id="ex-misc-wrong-person">
+	  <title>Incorrect: First or third person</title>
+	  <para>
+	    As described in the last section, I always run
+	    <command>up2date</command> before configuring the Samba
+	    server.
+	  </para>
+	  <para>
+	    If the user needs to back up his or her files, s/he should
+	    use the <command>tar</command> or <command>cpio</command>
+	    command.
+	  </para>
+	</example>
+	<example id="ex-misc-correct-person">
+	  <title>Correct: Second (or no) person</title>
+	  <para>
+	    Refer to the section on <command>up2date</command> before
+	    configuring the Samba server.
+	  </para>
+	  <para>
+	    Users can back up files with the <command>tar</command> or
+	    <command>cpio</command> command.
+	  </para>
+	</example>
+      </section>
+
+      <section id="sn-misc-negative">
+	<title>Negative Words</title>
+	<para>
+	  Avoid negative words when possible, since they give
+	  documentation 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
+	    linkend="vle-contractions" />.
+	</para>
+      </section>
+
+      <section id="sn-misc-uncertainty">
+	<title>Uncertainty</title>
+	<para>
+	  Avoid overuse of "typically," "usually," "most of," "many,"
+	  and the like. While occasional use of these constructions is
+	  acceptable, overuse reduces the authority of your
+	  documentation. The documentation should adequately cover a
+	  stock installation of &FC;. It is impossible for a
+	  tutorial-length document to cover every possible configuration
+	  scenario. Address the most common scenarios and note
+	  discrepancies only as required.
+	</para>
+      </section>
+	
+      <section id="sn-misc-offtopic">
+	<title>Redundant Coverage</title>
+	<para>
+	  Avoid covering redundant material, such as how to update a
+	  &FC; system. These overarching topics may be covered in other
+	  tutorials. Writers frequently violate this guideline because
+	  they feel their tutorial is not long enough. Keep your
+	  tutorial from wandering off-topic. Instead, refer the reader
+	  to a separate tutorial whenever possible for complete coverage
+	  of that topic.
+	</para>
+      </section>
+
+      <section id="sn-misc-importance">
+	<title>Self-referential Value Judgments</title>
+	<para>
+	  Avoid statements like "One of the most important things to do
+	  is <replaceable>XYZ</replaceable>." If the procedure is
+	  important, the reader already expects it to be in your
+	  tutorial. The converse is also true: if a procedure appears in
+	  your tutorial, the reader expects it is important. This is
+	  especially true if you use a whole section for the procedure
+	  in question. Merely 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" />.
+	</para>
+      </section>
+
+      <section id="sn-misc-precision">
+	<title>Precision of Language</title>
+	<para>
+	  Use precise words for actions users should take. Do not
+	  instruct users to "go" to a selection, or "find" a menu.
+	</para>
+	<example id="ex-precision-wrong">
+	  <title>Incorrect: Imprecise wording</title>
+	  <itemizedlist>
+	    <listitem>
+	      <para>
+		Go to the <guimenu>Main Menu</guimenu> ->
+		<guimenuitem>Foobar</guimenuitem>
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+		Find the option labeled <guilabel>Search</guilabel>
+	      </para>
+	    </listitem>
+	  </itemizedlist>
+	</example>
+	<example id="ex-precision-right">
+	  <title>Correct: Precise wording</title>
+	  <itemizedlist>
+	    <listitem>
+	      <para>
+		From the <guimenu>Main Menu</guimenu>, select
+		<guimenuitem>Foobar</guimenuitem>
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+		Select the <guilabel>Search</guilabel> option
+	      </para>
+	    </listitem>
+	  </itemizedlist>
+	</example>
+	<important>
+	  <title>Do Not Discriminate Against Non-GUI Users</title>
+	  <para>
+	    If you are writing about a GUI-only application, you may use
+	    "click" freely. If you are writing about an application that
+	    has a text-mode interface, use "select" instead as shown
+	    above.
+	  </para>
+	</important>
+
+      </section>
+	    
+      <section id="sn-misc-docbook-tips">
+	<title>DocBook Tips</title>
+	<para>
+	  This section contains tips on how to use DocBook tags more
+	  effectively in your documentation.
+	</para>
+
+	<section id="sn-misc-admonitions">
+	  <title>Admonitions</title>
+	  <para>
+	    Avoid overuse of admonitions.  Use only the most important
+	    material inside the admonition.  Doing so will keep
+	    admonitions short and effective. Any background material
+	    required to explain the most important admonition statements
+	    should be moved outside the admonition.
+	  </para>
+	  <example id="ex-misc-ineffective-admonition">
+	    <title>Incorrect: Lengthy admonition</title>
+	    <para>
+	      <warning>
+		<title>Using <command>sfdisk</command></title>
+		<para>
+		  The <command>sfdisk</command> command accepts a script
+		  file as standard input to set up partitions on a hard
+		  disk. Sometimes <command>sfdisk</command> will simply
+		  reject an erroneous input file. In other cases, it
+		  will use the input verbatim, writing an incorrect
+		  partition table to your disk. Always use the
+		  <command>sfdisk -n</command> command to check your
+		  input file before writing to the disk.
+		</para>
+	      </warning>
+	    </para>
+	  </example>
+	  <example id="ex-misc-good-admonition">
+	    <title>Correct: Brief admonition</title>
+	    <para>
+	       The <command>sfdisk</command> command accepts a script
+	      file as standard input to set up partitions on a hard
+	      disk. Sometimes <command>sfdisk</command> will simply
+	      reject an erroneous input file. In other cases, it will
+	      use the input verbatim, writing an incorrect partition
+	      table to your disk.
+	      <warning>
+		<title>Using <command>sfdisk</command></title>
+		<para>
+		  Always use the <command>sfdisk -n</command> command to
+		  check your input file before writing to the disk.
+		</para>
+	      </warning>
+	    </para>
+	  </example>
+	  <para>
+	    Avoid punctuation in titles for sections or admonitions,
+	    except for commas only where demanded. Use a title that says
+	    something about the admonition comment, such as "Reboot
+	    required," instead of simply using the admonition type for a
+	    title ("Note").
+	  </para>
+	</section>
+
+	<section id="sn-misc-replaceable">
+	  <title>The &lt;replaceable&gt; Tag</title>
+	  <para>
+	    If your documentation formally states a specific value will
+	    be used as a convention, do not use the &lt;replaceable&gt;
+	    tag in your text or examples.
+	  </para>
+	</section>
+
+	<section id="sn-misc-entities">
+	  <title>XML Entities</title>
+	  <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
+	    <xref
+	    linkend="ch-getting-files"/>.) For instance, do not use
+	    abbreviations such as "FC2." Instead, use the predefined
+	    entities "&amp;FC; &amp;FCVER;," which produces the text
+	    "&FC; &FCVER;."
+	  </para>
+	</section>
+
+      </section>
+	      
+    </section>
+
+  </chapter>
diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml
index f2f37ea..eae73bb 100644
--- a/documentation-guide-en.xml
+++ b/documentation-guide-en.xml
@@ -1,8 +1,9 @@
-<!-- $Id: documentation-guide-en.xml,v 1.16 2004/09/13 02:03:22 tfox Exp $ -->
-
+<!-- $Id: documentation-guide-en.xml,v 1.17 2005/04/28 08:55:41 kwade Exp $ -->
+<!-- breaks the build ... <?xml version="1.0" encoding="utf-8"?> -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 
+<!-- *************** Bring in Fedora entities *************** -->
 <!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml">
 %FEDORA-ENTITIES-EN;
 
@@ -24,7 +25,7 @@
 <!ENTITY CONVERTING SYSTEM "docs-converting-en.xml">
 <!ENTITY CVS SYSTEM "../common/cvs-en.xml">
 <!ENTITY ACKNOWLEDGMENTS SYSTEM "acknowledgments-en.xml">
-
+<!ENTITY STYLE SYSTEM "docs-style-en.xml">
 
 ]>
 
@@ -73,6 +74,8 @@
   
   &TUTORIAL;
 
+  &STYLE;
+
   &CONVERTING;
 
   &CVS;