2bfcee3890
Reviewed by: Lukasz Bojarski <ni@merkury.pol.lublin.pl> Approved by: murray, alex (mentor)
440 lines
13 KiB
Text
440 lines
13 KiB
Text
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
|
|
|
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
|
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code (SGML DocBook) must retain the above
|
|
copyright notice, this list of conditions and the following
|
|
disclaimer as the first lines of this file unmodified.
|
|
|
|
2. Redistributions in compiled form (transformed to other DTDs,
|
|
converted to PDF, PostScript, RTF and other formats) must reproduce
|
|
the above copyright notice, this list of conditions and the
|
|
following disclaimer in the documentation and/or other materials
|
|
provided with the distribution.
|
|
|
|
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
|
|
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
|
|
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
$FreeBSD$
|
|
-->
|
|
|
|
<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>
|
|
|
|
<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>
|
|
</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>These two examples show this for commands. The second example
|
|
is preferred.</para>
|
|
|
|
<informalexample>
|
|
<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>
|
|
|
|
<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>
|
|
<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>
|
|
|
|
<sect1>
|
|
<title>Style guide</title>
|
|
|
|
<para>To keep the source for the Handbook consistent when many different
|
|
people are editing it, please follow these style conventions.</para>
|
|
|
|
<sect2>
|
|
<title>Letter case</title>
|
|
|
|
<para>Tags are entered in lower case, <literal><para></literal>,
|
|
<emphasis>not</emphasis> <literal><PARA></literal>.</para>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<para>Every start tag increases the indentation level by 2 spaces, and
|
|
every end tag decreases the indentation level by 2 spaces. Replace
|
|
as many leading spaces with tabs as appropriate. 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>
|
|
|
|
<programlisting><![ CDATA [+--- This is column 0
|
|
V
|
|
<chapter>
|
|
<title>...</title>
|
|
|
|
<sect1>
|
|
<title>...</title>
|
|
|
|
<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>
|
|
|
|
<para>Every start tag increases the indentation level by 2 spaces, and
|
|
every end tag decreases the indentation level by 2 spaces. Content
|
|
within elements should be indented by two spaces if the content runs
|
|
over more than one line.</para>
|
|
|
|
...
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>]]></programlisting>
|
|
|
|
<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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Tag style</title>
|
|
|
|
<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>
|
|
|
|
<informalexample>
|
|
<programlisting><![ CDATA [<article>
|
|
<articleinfo>
|
|
<title>NIS</title>
|
|
|
|
<pubdate>October 1999</pubdata>
|
|
|
|
<abstract>
|
|
<para>...
|
|
...
|
|
...</para>
|
|
</abstract>
|
|
</articleinfo>
|
|
|
|
<sect1>
|
|
<title>...</title>
|
|
|
|
<para>...</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>...</title>
|
|
|
|
<para>...</para>
|
|
</sect1>
|
|
</article>]]></programlisting>
|
|
</informalexample>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<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
|
|
themselves.</para>
|
|
|
|
<para>Tags like <sgmltag>para</sgmltag> and
|
|
<sgmltag>term</sgmltag> do not need other tags to contain
|
|
normal character data, and their contents begin immediately
|
|
after the tag, <emphasis>on the same line</emphasis>.</para>
|
|
|
|
<para>The same applies to when these two types of tags
|
|
close.</para>
|
|
|
|
<para>This leads to an obvious problem when mixing these
|
|
tags.</para>
|
|
|
|
<para>When a starting tag which cannot contain character data
|
|
directly follows a tag of the type that requires other tags
|
|
within it to use character data, they are on separate lines.
|
|
The second tag should be properly indented.</para>
|
|
|
|
<para>When a tag which can contain character data closes
|
|
directly after a tag which cannot contain character data
|
|
closes, they co-exist on the same line.</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<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
|
|
formatting</emphasis>.</para>
|
|
|
|
<para>This is so that the teams that convert the Handbook 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>Nonbreaking 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
|
|
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 nonbreaking
|
|
spaces in the following places:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>between numbers and units:</para>
|
|
<programlisting><![ CDATA [57600 bps]]></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>between program names and version numbers:</para>
|
|
<programlisting><![ CDATA [FreeBSD 4.7]]></programlisting>
|
|
</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>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Word list</title>
|
|
|
|
<para>The following is a small list of words spelled the way they
|
|
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>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>2.2.X</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>4.X-STABLE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CDROM</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>FreeBSD Ports Collection</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Internet</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MHz</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Unix</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>email</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>file system</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>manual page(s)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>mail server</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>name server</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>ports collection</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>web server</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-declaration: "../chapter.decl"
|
|
sgml-indent-data: t
|
|
sgml-omittag: nil
|
|
sgml-always-quote-attributes: t
|
|
sgml-parent-document: ("../book.sgml" "part" "chapter")
|
|
End:
|
|
-->
|
|
|