486 lines
15 KiB
XML
486 lines
15 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- 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>
|
|
|
|
<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>
|
|
|
|
<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>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>
|
|
|
|
<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 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>
|
|
|
|
<sect2>
|
|
<title>Letter Case</title>
|
|
|
|
<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>
|
|
<literal><!entity…></literal> and
|
|
<literal><!doctype…></literal>.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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>
|
|
|
|
<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>
|
|
</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>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>
|
|
|
|
<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>
|
|
|
|
...
|
|
</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>
|
|
|
|
<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
|
|
autocmd FileType sgml set textwidth=70 " Wrap lines at 70 columns
|
|
autocmd FileType sgml set shiftwidth=2 " Automatically indent
|
|
autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces
|
|
autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab
|
|
autocmd FileType sgml set autoindent " Automatic indentation
|
|
augroup END</programlisting>
|
|
|
|
</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 lang='en'>
|
|
<articleinfo>
|
|
<title>NIS</title>
|
|
|
|
<pubdate>October 1999</pubdate>
|
|
|
|
<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 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
|
|
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>
|
|
|
|
<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 id="writing-style-word-list">
|
|
<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>CD-ROM</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Ports Collection</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>IPsec</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Internet</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MHz</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Soft Updates</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Unix</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>disk label</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>email</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>file system</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>manual page</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>mail server</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>name server</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>null-modem</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>web server</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
</chapter>
|