Whitespace-only fixes. Translators, please ignore.
This commit is contained in:
Warren Block
parent
0fcdcf3172
commit
fe83da9b8f
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38872
1 changed files with 127 additions and 118 deletions
|
|
@ -32,112 +32,117 @@
|
|||
|
||||
<chapter id="writing-style">
|
||||
<title>Writing Style</title>
|
||||
|
||||
<para>In order to promote consistency between the myriad authors of the
|
||||
FreeBSD documentation, some guidelines have been drawn up for authors to
|
||||
follow.</para>
|
||||
|
||||
|
||||
<para>In order 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>
|
||||
<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>
|
||||
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>
|
||||
<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>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>
|
||||
|
||||
<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>These two examples show this for commands. The second example
|
||||
is preferred.</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>cvsup</command> to update your
|
||||
<para>Use the command <command>cvsup</command> to update
|
||||
your sources.</para>
|
||||
</informalexample>
|
||||
|
||||
<informalexample>
|
||||
<para>Use <command>cvsup</command> to update your
|
||||
sources.</para>
|
||||
</informalexample>
|
||||
|
||||
<informalexample>
|
||||
<para>Use <command>cvsup</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
|
||||
<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
|
||||
|
||||
<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>
|
||||
|
|
@ -152,11 +157,11 @@
|
|||
<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>
|
||||
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>
|
||||
|
|
@ -168,8 +173,9 @@
|
|||
<sect1 id="writing-style-guide">
|
||||
<title>Style Guide</title>
|
||||
|
||||
<para>To keep the source for the documentation consistent when many different
|
||||
people are editing it, please follow these style conventions.</para>
|
||||
<para>To keep the source for the documentation consistent when
|
||||
many different people are editing it, please follow these style
|
||||
conventions.</para>
|
||||
|
||||
<sect2>
|
||||
<title>Letter Case</title>
|
||||
|
|
@ -177,9 +183,10 @@
|
|||
<para>Tags are entered in lower case, <sgmltag>para</sgmltag>,
|
||||
<emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para>
|
||||
|
||||
<para>Text that appears in SGML contexts is generally written in upper
|
||||
case, <literal><!ENTITY…></literal>, and
|
||||
<literal><!DOCTYPE…></literal>, <emphasis>not</emphasis>
|
||||
<para>Text that appears in SGML contexts is generally written in
|
||||
upper case, <literal><!ENTITY…></literal>, and
|
||||
<literal><!DOCTYPE…></literal>,
|
||||
<emphasis>not</emphasis>
|
||||
<literal><!entity…></literal> and
|
||||
<literal><!doctype…></literal>.</para>
|
||||
</sect2>
|
||||
|
|
@ -188,36 +195,36 @@
|
|||
<title>Acronyms</title>
|
||||
|
||||
<para>Acronyms should generally be spelled out the first time
|
||||
they appear in a document, as in: <quote>Network Time Protocol (<acronym
|
||||
role="Network Time Protocol">NTP</acronym>)</quote>. After the
|
||||
acronym has been defined, you should generally use the acronym
|
||||
only (not the whole term, unless it makes more sense
|
||||
contextually to use the whole term). Usually, acronyms are
|
||||
defined only one per document. But if you prefer, you can also
|
||||
define them the first time they appear in each chapter.</para>
|
||||
they appear in a document, as in: <quote>Network Time Protocol
|
||||
(<acronym role="Network Time Protocol">NTP</acronym>)</quote>.
|
||||
After the acronym has been defined, you should generally use
|
||||
the acronym only (not the whole term, unless it makes more
|
||||
sense contextually to use the whole term). Usually, acronyms
|
||||
are defined only one per document. But if you prefer, you can
|
||||
also define them the first time they appear in each
|
||||
chapter.</para>
|
||||
|
||||
<para>The first three uses of an acronym should be enclosed in
|
||||
<sgmltag>acronym</sgmltag> tags, with a <literal>role</literal> attribute
|
||||
with the full term defined. This allows a link to the
|
||||
glossary to be created, and for mouseovers to be rendered with
|
||||
the fully expanded term.</para>
|
||||
<sgmltag>acronym</sgmltag> tags, with a
|
||||
<literal>role</literal> attribute with the full term defined.
|
||||
This allows a link to the glossary to be created, and for
|
||||
mouseovers to be rendered with the fully expanded term.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Indentation</title>
|
||||
|
||||
<para>Each file starts with indentation set at column 0,
|
||||
<emphasis>regardless</emphasis> of the indentation level of the file
|
||||
which might contain this one.</para>
|
||||
<emphasis>regardless</emphasis> of the indentation level of
|
||||
the file which might contain this one.</para>
|
||||
|
||||
<para>Opening tags increase the indentation level by 2 spaces.
|
||||
Closing tags decrease the indentation level by 2 spaces. Blocks
|
||||
of 8 spaces at the start of a line should be replaced with a tab.
|
||||
Do not use
|
||||
spaces in front of tabs, and do not add extraneous whitespace at the
|
||||
end of a line. Content
|
||||
within elements should be indented by two spaces if the content runs
|
||||
over more than one line.</para>
|
||||
Closing tags decrease the indentation level by 2 spaces.
|
||||
Blocks of 8 spaces at the start of a line should be replaced
|
||||
with a tab. Do not use spaces in front of tabs, and do not
|
||||
add extraneous whitespace at the end of a line. Content
|
||||
within elements should be indented by two spaces if the
|
||||
content runs over more than one line.</para>
|
||||
|
||||
<para>For example, the source for this section looks something
|
||||
like:</para>
|
||||
|
|
@ -244,12 +251,12 @@ V
|
|||
|
||||
<para>If you use <application>Emacs</application> or
|
||||
<application>XEmacs</application> to edit the files then
|
||||
<literal>sgml-mode</literal> should be loaded automatically, and the
|
||||
<application>Emacs</application> local variables at the bottom of each file should enforce these
|
||||
styles.</para>
|
||||
<literal>sgml-mode</literal> should be loaded automatically,
|
||||
and the <application>Emacs</application> local variables at
|
||||
the bottom of each file should enforce these styles.</para>
|
||||
|
||||
<para><application>Vim</application> users might want to configure
|
||||
their editor with:</para>
|
||||
<para><application>Vim</application> users might want to
|
||||
configure their editor with:</para>
|
||||
|
||||
<programlisting>augroup sgmledit
|
||||
autocmd FileType sgml set formatoptions=cq2l " Special formatting options
|
||||
|
|
@ -267,7 +274,7 @@ augroup END</programlisting>
|
|||
|
||||
<sect3>
|
||||
<title>Tag Spacing</title>
|
||||
|
||||
|
||||
<para>Tags that start at the same indent as a previous tag
|
||||
should be separated by a blank line, and those that are not
|
||||
at the same indent as a previous tag should not:</para>
|
||||
|
|
@ -305,8 +312,8 @@ augroup END</programlisting>
|
|||
<title>Separating Tags</title>
|
||||
|
||||
<para>Tags like <sgmltag>itemizedlist</sgmltag> which will
|
||||
always have further tags inside them, and in fact do not take
|
||||
character data themselves, are always on a line by
|
||||
always have further tags inside them, and in fact do not
|
||||
take character data themselves, are always on a line by
|
||||
themselves.</para>
|
||||
|
||||
<para>Tags like <sgmltag>para</sgmltag> and
|
||||
|
|
@ -334,38 +341,40 @@ augroup END</programlisting>
|
|||
<sect2>
|
||||
<title>White Space Changes</title>
|
||||
|
||||
<para>When committing changes, <emphasis>do not commit changes to the
|
||||
content at the same time as changes to the
|
||||
<para>When committing changes, <emphasis>do not commit changes
|
||||
to the content at the same time as changes to the
|
||||
formatting</emphasis>.</para>
|
||||
|
||||
<para>This is so that the teams that convert the documentation to other
|
||||
languages can quickly see what content has actually changed in your
|
||||
commit, without having to decide whether a line has changed because of
|
||||
the content, or just because it has been refilled.</para>
|
||||
|
||||
<para>For example, if you have added two sentences to a paragraph, such
|
||||
that the line lengths on the paragraph now go over 80 columns, first
|
||||
commit your change with the too-long line lengths. Then fix the line
|
||||
wrapping, and commit this second change. In the commit message for
|
||||
the second change, be sure to indicate that this is a whitespace-only
|
||||
change, and that the translation team can ignore it.</para>
|
||||
<para>This is so that the teams that convert the documentation
|
||||
to other languages can quickly see what content has actually
|
||||
changed in your commit, without having to decide whether a
|
||||
line has changed because of the content, or just because it
|
||||
has been refilled.</para>
|
||||
|
||||
<para>For example, if you have added two sentences to a
|
||||
paragraph, such that the line lengths on the paragraph now go
|
||||
over 80 columns, first commit your change with the too-long
|
||||
line lengths. Then fix the line wrapping, and commit this
|
||||
second change. In the commit message for the second change,
|
||||
be sure to indicate that this is a whitespace-only change, and
|
||||
that the translation team can ignore it.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Non-Breaking Space</title>
|
||||
|
||||
<para>Avoid line breaks in places where they look ugly
|
||||
or make it difficult to follow a sentence. Line breaks depend
|
||||
on the width of the chosen output medium. In particular, viewing
|
||||
the HTML documentation with a text browser can lead to badly
|
||||
<para>Avoid line breaks in places where they look ugly or make
|
||||
it difficult to follow a sentence. Line breaks depend on the
|
||||
width of the chosen output medium. In particular, viewing the
|
||||
HTML documentation with a text browser can lead to badly
|
||||
formatted paragraphs like the next one:</para>
|
||||
|
||||
<literallayout class="monospaced">Data capacity ranges from 40 MB to 15
|
||||
GB. Hardware compression …</literallayout>
|
||||
|
||||
<para>The general entity <literal>&nbsp;</literal> prohibits
|
||||
line breaks between parts belonging together. Use non-breaking
|
||||
spaces in the following places:</para>
|
||||
line breaks between parts belonging together. Use
|
||||
non-breaking spaces in the following places:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -379,10 +388,11 @@ GB. Hardware compression …</literallayout>
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>between multiword names (use with caution when applying this
|
||||
to more than 3-4 word names like <quote>The FreeBSD Brazilian
|
||||
Portuguese Documentation Project</quote>):</para>
|
||||
<programlisting><![ CDATA [Sun Microsystems]]></programlisting>
|
||||
<para>between multiword names (use with caution when
|
||||
applying this to more than 3-4 word names like
|
||||
<quote>The FreeBSD Brazilian Portuguese Documentation
|
||||
Project</quote>):</para>
|
||||
<programlisting><![ CDATA [Sun Microsystems]]></programlisting>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
|
@ -395,8 +405,8 @@ GB. Hardware compression …</literallayout>
|
|||
should be used in the FreeBSD Documentation Project. If the
|
||||
word you are looking for is not in this list, then please
|
||||
consult the <ulink
|
||||
url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
|
||||
word list</ulink>.</para>
|
||||
url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
|
||||
word list</ulink>.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -471,7 +481,6 @@ GB. Hardware compression …</literallayout>
|
|||
<para>web server</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue