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 2012-05-21 14:54:44 +00:00
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
Show stats Download patch file Download diff file Expand all files Collapse all files

199
en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
View file

@ -33,27 +33,27 @@
<chapter id="writing-style"> <chapter id="writing-style">
<title>Writing Style</title> <title>Writing Style</title>
<para>In order to promote consistency between the myriad authors of the <para>In order to promote consistency between the myriad authors of
FreeBSD documentation, some guidelines have been drawn up for authors to the FreeBSD documentation, some guidelines have been drawn up for
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 spellings <para>There are several variants of English, with different
for the same word. Where spellings differ, use the American English spellings for the same word. Where spellings differ, use
variant. <quote>color</quote>, not <quote>colour</quote>, the American English variant. <quote>color</quote>, not
<quote>rationalize</quote>, not <quote>rationalise</quote>, and so <quote>colour</quote>, <quote>rationalize</quote>, not
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 case
of a contributed article, however the spelling must be of a contributed article, however the spelling must be
consistent within the whole document. The other documents consistent within the whole document. The other documents
such as books, web site, manual pages, etc. will have to use such as books, web site, manual pages, etc. will have to
American English.</para> use American English.</para>
</note> </note>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -62,11 +62,12 @@
<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 full. <para>Do not use contractions. Always spell the phrase out in
<quote>Don't use contractions</quote> would be wrong.</para> full. <quote>Don't use contractions</quote> would be
wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is more <para>Avoiding contractions makes for a more formal tone, is
precise, and is slightly easier for translators.</para> more precise, and is slightly easier for translators.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -74,9 +75,10 @@
<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 item from <para>In a list of items within a paragraph, separate each
the others with a comma. Separate the last item from the others with item from the others with a comma. Separate the last item
a comma and the word <quote>and</quote>.</para> 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>
@ -85,10 +87,12 @@
</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 two items, <quote>two</quote>, and <quote>three</quote>, or a list of
<quote>one</quote> and <quote>two and three</quote>?</para> 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> <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>
@ -100,24 +104,25 @@
<term>Avoid redundant phrases</term> <term>Avoid redundant phrases</term>
<listitem> <listitem>
<para>Try not to use redundant phrases. In particular, <quote>the <para>Try not to use redundant phrases. In particular,
command</quote>, <quote>the file</quote>, and <quote>man <quote>the command</quote>, <quote>the file</quote>, and
command</quote> are probably redundant.</para> <quote>man command</quote> are probably redundant.</para>
<para>These two examples show this for commands. The second example <para>These two examples show this for commands. The second
is preferred.</para> example is preferred.</para>
<informalexample> <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> sources.</para>
</informalexample> </informalexample>
<informalexample> <para>These two examples show this for filenames. The second
<para>Use <command>cvsup</command> to update your sources.</para> example is preferred.</para>
</informalexample>
<para>These two examples show this for filenames. The second example
is preferred.</para>
<informalexample> <informalexample>
<para>&hellip; in the filename <para>&hellip; in the filename
@ -129,8 +134,8 @@
<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 second <para>These two examples show this for manual references. The
example is preferred (the second example uses second example is preferred (the second example uses
<sgmltag>citerefentry</sgmltag>).</para> <sgmltag>citerefentry</sgmltag>).</para>
<informalexample> <informalexample>
@ -152,11 +157,11 @@
<application>Emacs</application>.</para> <application>Emacs</application>.</para>
<para>While it may be argued that a capital letter following <para>While it may be argued that a capital letter following
a period denotes a new sentence, this is not the case, especially a period denotes a new sentence, this is not the case,
in name usage. <quote>Jordan K. Hubbard</quote> is a good especially in name usage. <quote>Jordan K. Hubbard</quote>
example; it has a capital <literal>H</literal> following a is a good example; it has a capital <literal>H</literal>
period and a space, and there certainly is not a new sentence following a period and a space, and there certainly is not a
there.</para> new sentence there.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
@ -168,8 +173,9 @@
<sect1 id="writing-style-guide"> <sect1 id="writing-style-guide">
<title>Style Guide</title> <title>Style Guide</title>
<para>To keep the source for the documentation consistent when many different <para>To keep the source for the documentation consistent when
people are editing it, please follow these style conventions.</para> many different people are editing it, please follow these style
conventions.</para>
<sect2> <sect2>
<title>Letter Case</title> <title>Letter Case</title>
@ -177,9 +183,10 @@
<para>Tags are entered in lower case, <sgmltag>para</sgmltag>, <para>Tags are entered in lower case, <sgmltag>para</sgmltag>,
<emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para> <emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para>
<para>Text that appears in SGML contexts is generally written in upper <para>Text that appears in SGML contexts is generally written in
case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and upper case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis> <literal>&lt;!DOCTYPE&hellip;&gt;</literal>,
<emphasis>not</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> and <literal>&lt;!entity&hellip;&gt;</literal> and
<literal>&lt;!doctype&hellip;&gt;</literal>.</para> <literal>&lt;!doctype&hellip;&gt;</literal>.</para>
</sect2> </sect2>
@ -188,36 +195,36 @@
<title>Acronyms</title> <title>Acronyms</title>
<para>Acronyms should generally be spelled out the first time <para>Acronyms should generally be spelled out the first time
they appear in a document, as in: <quote>Network Time Protocol (<acronym they appear in a document, as in: <quote>Network Time Protocol
role="Network Time Protocol">NTP</acronym>)</quote>. After the (<acronym role="Network Time Protocol">NTP</acronym>)</quote>.
acronym has been defined, you should generally use the acronym After the acronym has been defined, you should generally use
only (not the whole term, unless it makes more sense the acronym only (not the whole term, unless it makes more
contextually to use the whole term). Usually, acronyms are sense contextually to use the whole term). Usually, acronyms
defined only one per document. But if you prefer, you can also are defined only one per document. But if you prefer, you can
define them the first time they appear in each chapter.</para> also define them the first time they appear in each
chapter.</para>
<para>The first three uses of an acronym should be enclosed in <para>The first three uses of an acronym should be enclosed in
<sgmltag>acronym</sgmltag> tags, with a <literal>role</literal> attribute <sgmltag>acronym</sgmltag> tags, with a
with the full term defined. This allows a link to the <literal>role</literal> attribute with the full term defined.
glossary to be created, and for mouseovers to be rendered with This allows a link to the glossary to be created, and for
the fully expanded term.</para> mouseovers to be rendered with the fully expanded term.</para>
</sect2> </sect2>
<sect2> <sect2>
<title>Indentation</title> <title>Indentation</title>
<para>Each file starts with indentation set at column 0, <para>Each file starts with indentation set at column 0,
<emphasis>regardless</emphasis> of the indentation level of the file <emphasis>regardless</emphasis> of the indentation level of
which might contain this one.</para> the file which might contain this one.</para>
<para>Opening tags increase the indentation level by 2 spaces. <para>Opening tags increase the indentation level by 2 spaces.
Closing tags decrease the indentation level by 2 spaces. Blocks Closing tags decrease the indentation level by 2 spaces.
of 8 spaces at the start of a line should be replaced with a tab. Blocks of 8 spaces at the start of a line should be replaced
Do not use with a tab. Do not use spaces in front of tabs, and do not
spaces in front of tabs, and do not add extraneous whitespace at the add extraneous whitespace at the end of a line. Content
end of a line. Content within elements should be indented by two spaces if the
within elements should be indented by two spaces if the content runs content runs over more than one line.</para>
over more than one line.</para>
<para>For example, the source for this section looks something <para>For example, the source for this section looks something
like:</para> like:</para>
@ -244,12 +251,12 @@ V
<para>If you use <application>Emacs</application> or <para>If you use <application>Emacs</application> or
<application>XEmacs</application> to edit the files then <application>XEmacs</application> to edit the files then
<literal>sgml-mode</literal> should be loaded automatically, and the <literal>sgml-mode</literal> should be loaded automatically,
<application>Emacs</application> local variables at the bottom of each file should enforce these and the <application>Emacs</application> local variables at
styles.</para> the bottom of each file should enforce these styles.</para>
<para><application>Vim</application> users might want to configure <para><application>Vim</application> users might want to
their editor with:</para> configure their editor with:</para>
<programlisting>augroup sgmledit <programlisting>augroup sgmledit
autocmd FileType sgml set formatoptions=cq2l " Special formatting options autocmd FileType sgml set formatoptions=cq2l " Special formatting options
@ -305,8 +312,8 @@ augroup END</programlisting>
<title>Separating Tags</title> <title>Separating Tags</title>
<para>Tags like <sgmltag>itemizedlist</sgmltag> which will <para>Tags like <sgmltag>itemizedlist</sgmltag> which will
always have further tags inside them, and in fact do not take always have further tags inside them, and in fact do not
character data themselves, are always on a line by take character data themselves, are always on a line by
themselves.</para> themselves.</para>
<para>Tags like <sgmltag>para</sgmltag> and <para>Tags like <sgmltag>para</sgmltag> and
@ -334,38 +341,40 @@ augroup END</programlisting>
<sect2> <sect2>
<title>White Space Changes</title> <title>White Space Changes</title>
<para>When committing changes, <emphasis>do not commit changes to the <para>When committing changes, <emphasis>do not commit changes
content at the same time as changes to the to the content at the same time as changes to the
formatting</emphasis>.</para> formatting</emphasis>.</para>
<para>This is so that the teams that convert the documentation to other <para>This is so that the teams that convert the documentation
languages can quickly see what content has actually changed in your to other languages can quickly see what content has actually
commit, without having to decide whether a line has changed because of changed in your commit, without having to decide whether a
the content, or just because it has been refilled.</para> 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 <para>For example, if you have added two sentences to a
that the line lengths on the paragraph now go over 80 columns, first paragraph, such that the line lengths on the paragraph now go
commit your change with the too-long line lengths. Then fix the line over 80 columns, first commit your change with the too-long
wrapping, and commit this second change. In the commit message for line lengths. Then fix the line wrapping, and commit this
the second change, be sure to indicate that this is a whitespace-only second change. In the commit message for the second change,
change, and that the translation team can ignore it.</para> be sure to indicate that this is a whitespace-only change, and
that the translation team can ignore it.</para>
</sect2> </sect2>
<sect2> <sect2>
<title>Non-Breaking Space</title> <title>Non-Breaking Space</title>
<para>Avoid line breaks in places where they look ugly <para>Avoid line breaks in places where they look ugly or make
or make it difficult to follow a sentence. Line breaks depend it difficult to follow a sentence. Line breaks depend on the
on the width of the chosen output medium. In particular, viewing width of the chosen output medium. In particular, viewing the
the HTML documentation with a text browser can lead to badly HTML documentation with a text browser can lead to badly
formatted paragraphs like the next one:</para> formatted paragraphs like the next one:</para>
<literallayout class="monospaced">Data capacity ranges from 40 MB to 15 <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
GB. Hardware compression &hellip;</literallayout> GB. Hardware compression &hellip;</literallayout>
<para>The general entity <literal>&amp;nbsp;</literal> prohibits <para>The general entity <literal>&amp;nbsp;</literal> prohibits
line breaks between parts belonging together. Use non-breaking line breaks between parts belonging together. Use
spaces in the following places:</para> non-breaking spaces in the following places:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -379,9 +388,10 @@ GB. Hardware compression &hellip;</literallayout>
</listitem> </listitem>
<listitem> <listitem>
<para>between multiword names (use with caution when applying this <para>between multiword names (use with caution when
to more than 3-4 word names like <quote>The FreeBSD Brazilian applying this to more than 3-4 word names like
Portuguese Documentation Project</quote>):</para> <quote>The FreeBSD Brazilian Portuguese Documentation
Project</quote>):</para>
<programlisting><![ CDATA [Sun&nbsp;Microsystems]]></programlisting> <programlisting><![ CDATA [Sun&nbsp;Microsystems]]></programlisting>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -395,8 +405,8 @@ GB. Hardware compression &hellip;</literallayout>
should be used in the FreeBSD Documentation Project. If the should be used in the FreeBSD Documentation Project. If the
word you are looking for is not in this list, then please word you are looking for is not in this list, then please
consult the <ulink consult the <ulink
url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
word list</ulink>.</para> word list</ulink>.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -471,7 +481,6 @@ GB. Hardware compression &hellip;</literallayout>
<para>web server</para> <para>web server</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</sect1> </sect1>
</chapter> </chapter>