os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes. Translators, please ignore.

Browse source
This commit is contained in:
Warren Block 2013-06-20 16:46:55 +00:00
parent 0bd302297a
commit da1e22a104
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=41971
1 changed files with 113 additions and 110 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

223
en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
View file

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