139 lines
4.6 KiB
Text
139 lines
4.6 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.
|
|
|
|
$Id: chapter.sgml,v 1.2 1999-07-14 19:27:15 nik Exp $
|
|
-->
|
|
|
|
<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>Do not use contractions</term>
|
|
|
|
<listitem>
|
|
<para>Do not use contractions. Always spell the phrase out in full.
|
|
“Don't use contractions” would be wrong.</para>
|
|
|
|
<para>Avoiding contractions makes for a more formal tone, is more
|
|
precise, and slightly easier for translators.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Use the serial comma</term>
|
|
|
|
<listitem>
|
|
<para>In a list of items within a paragraph, seperate each item from
|
|
the others with a comma. Seperate the last item from the others with
|
|
a comma and the word “and”.</para>
|
|
|
|
<para>For example, look at the following quote;</para>
|
|
|
|
<blockquote>
|
|
<para>This is a list of one, two and three items.</para>
|
|
</blockquote>
|
|
|
|
<para>Is this a list of three items, “one”,
|
|
“two”, and “three”, or a list of two items,
|
|
“one” and “two and three”?</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, “the
|
|
command”, “the file”, and “man
|
|
command” 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>
|
|
</variablelist>
|
|
</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:
|
|
-->
|
|
|