svn commit: r41971 - head/en_US.ISO8859-1/books/fdp-primer/writing-style

Warren Block wblock at FreeBSD.org
Thu Jun 20 16:46:55 UTC 2013


Author: wblock
Date: Thu Jun 20 16:46:55 2013
New Revision: 41971
URL: http://svnweb.freebsd.org/changeset/doc/41971

Log:
  Whitespace-only fixes.  Translators, please ignore.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Thu Jun 20 16:40:42 2013	(r41970)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Thu Jun 20 16:46:55 2013	(r41971)
@@ -54,7 +54,7 @@
 	concepts.</para>
 
       <para>Avoid flowery or embellished speech, jokes, or colloquial
-	expressions. Write as simply and clearly as possible.  Simple
+	expressions.  Write as simply and clearly as possible.  Simple
 	text is easier to understand and translate.</para>
 
       <para>Keep explanations as short, simple, and clear as possible.
@@ -108,142 +108,145 @@
   <sect1 id="writing-style-guidelines">
     <title>Guidelines</title>
 
-  <para>To promote consistency between the myriad authors of
-    the FreeBSD documentation, some guidelines have been drawn up for
-    authors to follow.</para>
-
-  <variablelist>
-    <varlistentry>
-      <term>Use American English Spelling</term>
-
-      <listitem>
-	<para>There are several variants of English, with different
-	  spellings for the same word.  Where spellings differ, use
-	  the American English variant.  <quote>color</quote>, not
-	  <quote>colour</quote>, <quote>rationalize</quote>, not
-	  <quote>rationalise</quote>, and so on.</para>
-
-	<note>
-	  <para>The use of British English may be accepted in the case
-	    of a contributed article, however the spelling must be
-	    consistent within the whole document.  The other documents
-	    such as books, web site, manual pages, etc. will have to
-	    use American English.</para>
-	</note>
-      </listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term>Do not use contractions</term>
-
-      <listitem>
-	<para>Do not use contractions.  Always spell the phrase out in
-	  full.  <quote>Don't use contractions</quote> would be
-	  wrong.</para>
-
-	<para>Avoiding contractions makes for a more formal tone, is
-	  more precise, and is slightly easier for translators.</para>
-      </listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term>Use the serial comma</term>
-
-      <listitem>
-	<para>In a list of items within a paragraph, separate each
-	  item from the others with a comma.  Separate the last item
-	  from the others with a comma and the word
-	  <quote>and</quote>.</para>
-
-	<para>For example, look at the following:</para>
-
-	<blockquote>
-	  <para>This is a list of one, two and three items.</para>
-	</blockquote>
-
-	<para>Is this a list of three items, <quote>one</quote>,
-	  <quote>two</quote>, and <quote>three</quote>, or a list of
-	  two items, <quote>one</quote> and <quote>two and
-	    three</quote>?</para>
-
-	<para>It is better to be explicit and include a serial
-	  comma:</para>
-
-	<blockquote>
-	  <para>This is a list of one, two, and three items.</para>
-	</blockquote>
-      </listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term>Avoid redundant phrases</term>
-
-      <listitem>
-	<para>Try not to use redundant phrases.  In particular,
-	  <quote>the command</quote>, <quote>the file</quote>, and
-	  <quote>man command</quote> are probably redundant.</para>
+    <para>To promote consistency between the myriad authors of the
+      FreeBSD documentation, some guidelines have been drawn up for
+      authors to follow.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>Use American English Spelling</term>
 
-	<para>These two examples show this for commands.  The second
-	  example is preferred.</para>
+	<listitem>
+	  <para>There are several variants of English, with different
+	    spellings for the same word.  Where spellings differ, use
+	    the American English variant.  <quote>color</quote>, not
+	    <quote>colour</quote>, <quote>rationalize</quote>, not
+	    <quote>rationalise</quote>, and so on.</para>
+
+	  <note>
+	    <para>The use of British English may be accepted in the
+	      case of a contributed article, however the spelling must
+	      be consistent within the whole document.  The other
+	      documents such as books, web site, manual pages, etc.
+	      will have to use American English.</para>
+	  </note>
+	</listitem>
+      </varlistentry>
 
-	<informalexample>
-	  <para>Use the command <command>svn</command> to update
-	    your sources.</para>
-	</informalexample>
+      <varlistentry>
+	<term>Do not use contractions</term>
 
-	<informalexample>
-	  <para>Use <command>svn</command> to update your
-	    sources.</para>
-	</informalexample>
+	<listitem>
+	  <para>Do not use contractions.  Always spell the phrase out
+	    in full.  <quote>Don't use contractions</quote> would be
+	    wrong.</para>
+
+	  <para>Avoiding contractions makes for a more formal tone, is
+	    more precise, and is slightly easier for
+	    translators.</para>
+	</listitem>
+      </varlistentry>
 
-	<para>These two examples show this for filenames.  The second
-	  example is preferred.</para>
+      <varlistentry>
+	<term>Use the serial comma</term>
 
-	<informalexample>
-	  <para>… in the filename
-	    <filename>/etc/rc.local</filename>…</para>
-	</informalexample>
+	<listitem>
+	  <para>In a list of items within a paragraph, separate each
+	    item from the others with a comma.  Separate the last item
+	    from the others with a comma and the word
+	    <quote>and</quote>.</para>
+
+	  <para>For example, look at the following:</para>
+
+	  <blockquote>
+	    <para>This is a list of one, two and three items.</para>
+	  </blockquote>
+
+	  <para>Is this a list of three items, <quote>one</quote>,
+	    <quote>two</quote>, and <quote>three</quote>, or a list of
+	    two items, <quote>one</quote> and <quote>two and
+	      three</quote>?</para>
+
+	  <para>It is better to be explicit and include a serial
+	    comma:</para>
+
+	  <blockquote>
+	    <para>This is a list of one, two, and three items.</para>
+	  </blockquote>
+	</listitem>
+      </varlistentry>
 
-	<informalexample>
-	  <para>… in
-	    <filename>/etc/rc.local</filename>…</para>
-	</informalexample>
+      <varlistentry>
+	<term>Avoid redundant phrases</term>
 
-	<para>These two examples show this for manual references.  The
-	  second example is preferred (the second example uses
-	  <sgmltag>citerefentry</sgmltag>).</para>
+	<listitem>
+	  <para>Try not to use redundant phrases.  In particular,
+	    <quote>the command</quote>, <quote>the file</quote>, and
+	    <quote>man command</quote> are probably redundant.</para>
+
+	  <para>These two examples show this for commands.  The second
+	    example is preferred.</para>
+
+	  <informalexample>
+	    <para>Use the command <command>svn</command> to update
+	      your sources.</para>
+	  </informalexample>
+
+	  <informalexample>
+	    <para>Use <command>svn</command> to update your
+	      sources.</para>
+	  </informalexample>
+
+	  <para>These two examples show this for filenames.  The
+	    second example is preferred.</para>
+
+	  <informalexample>
+	    <para>… in the filename
+	      <filename>/etc/rc.local</filename>…</para>
+	  </informalexample>
+
+	  <informalexample>
+	    <para>… in
+	      <filename>/etc/rc.local</filename>…</para>
+	  </informalexample>
+
+	  <para>These two examples show this for manual references.
+	    The second example is preferred (the second example uses
+	    <sgmltag>citerefentry</sgmltag>).</para>
+
+	  <informalexample>
+	    <para>See <command>man csh</command> for more
+	      information.</para>
+	  </informalexample>
+
+	  <informalexample>
+	    <para>See &man.csh.1;.</para>
+	  </informalexample>
+	</listitem>
+      </varlistentry>
 
-	<informalexample>
-	  <para>See <command>man csh</command> for more
-	    information.</para>
-	</informalexample>
+      <varlistentry>
+	<term>Two spaces at the end of sentences</term>
 
-	<informalexample>
-	  <para>See &man.csh.1;.</para>
-	</informalexample>
-      </listitem>
-    </varlistentry>
-    <varlistentry>
-      <term>Two spaces at the end of sentences</term>
-
-      <listitem>
-	<para>Always use two spaces at the end of sentences, as this
-	  improves readability, and eases use of tools such as
-	  <application>Emacs</application>.</para>
-
-	<para>While it may be argued that a capital letter following
-	  a period denotes a new sentence, this is not the case,
-	  especially in name usage.  <quote>Jordan K. Hubbard</quote>
-	  is a good example; it has a capital <literal>H</literal>
-	  following a period and a space, and there certainly is not a
-	  new sentence there.</para>
-      </listitem>
-    </varlistentry>
-  </variablelist>
-
-  <para>For more information about writing style, see <ulink
-      url="http://www.bartleby.com/141/">Elements of
-      Style</ulink>, by William Strunk.</para>
+	<listitem>
+	  <para>Always use two spaces at the end of sentences, as this
+	    improves readability, and eases use of tools such as
+	    <application>Emacs</application>.</para>
+
+	  <para>While it may be argued that a capital letter following
+	    a period denotes a new sentence, this is not the case,
+	    especially in name usage.
+	    <quote>Jordan K. Hubbard</quote> is a good example; it has
+	    a capital <literal>H</literal> following a period and a
+	    space, and there certainly is not a new sentence
+	    there.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>For more information about writing style, see <ulink
+	url="http://www.bartleby.com/141/">Elements of
+	Style</ulink>, by William Strunk.</para>
   </sect1>
 
   <sect1 id="writing-style-guide">


More information about the svn-doc-all mailing list