aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml318
1 files changed, 0 insertions, 318 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml
deleted file mode 100644
index 3e78167d13..0000000000
--- a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ /dev/null
@@ -1,318 +0,0 @@
-<!-- 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: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.11 2001/04/09 00:33:47 dd 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.
- &ldquo;Don't use contractions&rdquo; 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. Seperate the last item from the others with
- a comma and the word &ldquo;and&rdquo;.</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, &ldquo;one&rdquo;,
- &ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
- &ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</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, &ldquo;the
- command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
- command&rdquo; 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>&hellip; in the filename
- <filename>/etc/rc.local</filename>&hellip;</para>
- </informalexample>
-
- <informalexample>
- <para>&hellip; in
- <filename>/etc/rc.local</filename>&hellip;</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 isn't a new sentence
- there.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>For more information about writing style, see <ulink
- url="http://www.bartleby.com/141/index.html">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>&lt;para&gt;</literal>,
- <emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
-
- <para>Text that appears in SGML contexts is generally written in upper
- case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
- <literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
- <literal>&lt;!entity&hellip;&gt;</literal> and
- <literal>&lt;!doctype&hellip;&gt;</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
- Emacs 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 don't take
- character data themselves, are always on a line by
- themselves.</para>
-
- <para>Tags like <sgmltag>para</sgmltag> and
- <sgmltag>term</sgmltag> don't 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>
- </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:
--->
-