c4ab126805
enough for most people, and gets it into the repository, making it easier for others to add to as necessary. This has not (yet) been turned on in the upper level Makefile or listed on the web site yet, I want to get some more feedback from readers first. It should be "made visible" later this week.
137 lines
4.6 KiB
Text
137 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.
|
|
-->
|
|
|
|
<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:
|
|
-->
|
|
|