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-head
mailing list