Whitespace-only fixes. Translators, please ignore.
This commit is contained in:
Warren Block
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
|
|
@ -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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>
|
||||
<para>For example, look at the following:</para>
|
||||
|
||||
<blockquote>
|
||||
<para>This is a list of one, two and three items.</para>
|
||||
</blockquote>
|
||||
<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>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>
|
||||
<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>
|
||||
<blockquote>
|
||||
<para>This is a list of one, two, and three items.</para>
|
||||
</blockquote>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Avoid redundant phrases</term>
|
||||
<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>
|
||||
<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>
|
||||
<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 the command <command>svn</command> to update
|
||||
your sources.</para>
|
||||
</informalexample>
|
||||
|
||||
<informalexample>
|
||||
<para>Use <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>
|
||||
<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 the filename
|
||||
<filename>/etc/rc.local</filename>…</para>
|
||||
</informalexample>
|
||||
|
||||
<informalexample>
|
||||
<para>… in
|
||||
<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>
|
||||
<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 <command>man csh</command> for more
|
||||
information.</para>
|
||||
</informalexample>
|
||||
|
||||
<informalexample>
|
||||
<para>See &man.csh.1;.</para>
|
||||
</informalexample>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Two spaces at the end of sentences</term>
|
||||
<informalexample>
|
||||
<para>See &man.csh.1;.</para>
|
||||
</informalexample>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term>Two spaces at the end of sentences</term>
|
||||
|
||||
<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>
|
||||
<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>For more information about writing style, see <ulink
|
||||
url="http://www.bartleby.com/141/">Elements of
|
||||
Style</ulink>, by William Strunk.</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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue