aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml607
1 files changed, 0 insertions, 607 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
deleted file mode 100644
index 6116b4d6a3..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
+++ /dev/null
@@ -1,607 +0,0 @@
-<?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.
-
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="writing-style">
- <title>Writing Style</title>
-
- <sect1 xml:id="writing-style-tips">
- <title>Tips</title>
-
- <para>Technical documentation can be improved by consistent use of
- several principles. Most of these can be classified into three
- goals: <emphasis>be clear</emphasis>,
- <emphasis>be complete</emphasis>, and
- <emphasis>be concise</emphasis>. These goals can conflict with
- each other. Good writing consists of a balance between
- them.</para>
-
- <sect2 xml:id="writing-style-be-clear">
- <title>Be Clear</title>
-
- <para>Clarity is extremely important. The reader may be a
- novice, or reading the document in a second language. Strive
- for simple, uncomplicated text that clearly explains the
- concepts.</para>
-
- <para>Avoid flowery or embellished speech, jokes, or colloquial
- expressions. Write as simply and clearly as possible. Simple
- text is easier to understand and translate.</para>
-
- <para>Keep explanations as short, simple, and clear as possible.
- Avoid empty phrases like <quote>in order to</quote>, which
- usually just means <quote>to</quote>. Avoid potentially
- patronizing words like <quote>basically</quote>. Avoid Latin
- terms like <quote>i.e.,</quote> or <quote>cf.</quote>, which
- may be unknown outside of academic or scientific
- groups.</para>
-
- <para>Write in a formal style. Avoid addressing the reader
- as <quote>you</quote>. For example, say
- <quote>copy the file to <filename>/tmp</filename></quote>
- rather than <quote>you can copy the file to
- <filename>/tmp</filename></quote>.</para>
-
- <para>Give clear, correct, <emphasis>tested</emphasis> examples.
- A trivial example is better than no example. A good example
- is better yet. Do not give bad examples, identifiable by
- apologies or sentences like <quote>but really it should never
- be done that way</quote>. Bad examples are worse than no
- examples. Give good examples, because <emphasis>even when
- warned not to use the example as shown</emphasis>, the
- reader will usually just use the example as shown.</para>
-
- <para>Avoid <emphasis>weasel words</emphasis> like
- <quote>should</quote>, <quote>might</quote>,
- <quote>try</quote>, or <quote>could</quote>. These words
- imply that the speaker is unsure of the facts, and
- create doubt in the reader.</para>
-
- <para>Similarly, give instructions as imperative commands: not
- <quote>you should do this</quote>, but merely
- <quote>do this</quote>.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-be-complete">
- <title>Be Complete</title>
-
- <para>Do not make assumptions about the reader's abilities or
- skill level. Tell them what they need to know. Give links to
- other documents to provide background information without
- having to recreate it. Put yourself in the reader's place,
- anticipate the questions they will ask, and answer
- them.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-be-concise">
- <title>Be Concise</title>
-
- <para>While features should be documented completely, sometimes
- there is so much information that the reader cannot easily
- find the specific detail needed. The balance between being
- complete and being concise is a challenge. One approach is to
- have an introduction, then a <quote>quick start</quote>
- section that describes the most common situation, followed by
- an in-depth reference section.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="writing-style-guidelines">
- <title>Guidelines</title>
-
- <para>To promote consistency between the myriad authors of the
- &os; 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> is
- 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:</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>Do not use redundant phrases. In particular,
- <quote>the command</quote>, <quote>the file</quote>, and
- <quote>man command</quote> are often redundant.</para>
-
- <para>For example, commands:</para>
-
- <informalexample>
- <para>Wrong: Use the <command>svn</command> command to
- update sources.</para>
- </informalexample>
-
- <informalexample>
- <para>Right: Use <command>svn</command> to update
- sources.</para>
- </informalexample>
-
- <para>Filenames:</para>
-
- <informalexample>
- <para>Wrong: &hellip; in the filename
- <filename>/etc/rc.local</filename>&hellip;</para>
- </informalexample>
-
- <informalexample>
- <para>Right: &hellip; in
- <filename>/etc/rc.local</filename>&hellip;</para>
- </informalexample>
-
- <para>Manual page references (the second example uses
- <tag>citerefentry</tag> with the
- <literal>&amp;man.csh.1;</literal> entity):.</para>
-
- <informalexample>
- <para>Wrong: See <command>man csh</command> for more
- information.</para>
- </informalexample>
-
- <informalexample>
- <para>Right: See &man.csh.1;.</para>
- </informalexample>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Two spaces between sentences</term>
-
- <listitem>
- <para>Always use two spaces between sentences, as it
- improves readability and eases use of tools such as
- <application>Emacs</application>.</para>
-
- <para>A period and spaces followed by a capital letter
- does not always mark a new sentence, especially in names.
- <quote>Jordan K. Hubbard</quote> is a good example. It
- has a capital <literal>H</literal> following a period and
- a space, and is certainly not a new sentence.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>For more information about writing style, see <link
- xlink:href="http://www.bartleby.com/141/">Elements of
- Style</link>, by William Strunk.</para>
- </sect1>
-
- <sect1 xml: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 xml:id="writing-style-letter-case">
- <title>Letter Case</title>
-
- <para>Tags are entered in lower case, <tag>para</tag>,
- <emphasis>not</emphasis> <tag>PARA</tag>.</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 xml:id="writing-style-acronyms">
- <title>Acronyms</title>
-
- <para>Acronyms should be defined the first time they appear in a
- document, as in:
- <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>.
- After the acronym has been defined, use the acronym alone
- unless it makes more sense contextually to use the whole term.
- Acronyms are usually defined only once per chapter or per
- document.</para>
-
- <para>All acronyms should be enclosed in
- <tag>acronym</tag> tags.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-indentation">
- <title>Indentation</title>
-
- <para>The first line in each file starts with no indentation,
- <emphasis>regardless</emphasis> of the indentation level of
- the file which might contain the current file.</para>
-
- <para>Opening tags increase the indentation level by two spaces.
- Closing tags decrease the indentation level by two spaces.
- Blocks of eight 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 like
- this:</para>
-
- <programlisting><tag class="starttag">chapter</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">sect2</tag>
- <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>The first line in each file starts with no indentation,
- <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of
- the file which might contain the current file.<tag class="endtag">para</tag>
-
- ...
- <tag class="endtag">sect2</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">chapter</tag></programlisting>
-
- <para>Tags containing long attributes follow the same
- rules. Following the indentation rules in this case helps
- editors and writers see which content is inside the
- tags:</para>
-
- <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link
- linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag>
- section if there are problems booting. Powering down and
- disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk
- will allow it to be kept as an offline backup.<tag class="endtag">para</tag>
-
-<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &amp;os;
- system. Refer to the article <tag class="starttag">link
- xlink:href="&amp;url.articles.gjournal-desktop;"</tag>Implementing UFS
- Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed
- instructions.<tag class="endtag">para</tag></programlisting>
-
- <para>When an element is too long to fit on the remainder of a
- line without wrapping, moving the start tag to the next line
- can make the source easier to read. In this example, the
- <literal>systemitem</literal> element has been moved to the
- next line to avoid wrapping and indenting:</para>
-
- <programlisting><tag class="starttag">para</tag>With file flags, even
- <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be
- prevented from removing or altering files.<tag class="endtag">para</tag></programlisting>
-
- <para>Configurations to help various text editors conform to
- these guidelines can be found in
- <xref linkend="editor-config"/>.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-tag-style">
- <title>Tag Style</title>
-
- <sect3 xml:id="writing-style-tag-style-spacing">
- <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><tag class="starttag">article lang='en'</tag>
- <tag class="starttag">articleinfo</tag>
- <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag>
-
- <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag>
-
- <tag class="starttag">abstract</tag>
- <tag class="starttag">para</tag>...
- ...
- ...<tag class="endtag">para</tag>
- <tag class="endtag">abstract</tag>
- <tag class="endtag">articleinfo</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-
- <tag class="starttag">sect1</tag>
- <tag class="starttag">title</tag>...<tag class="endtag">title</tag>
-
- <tag class="starttag">para</tag>...<tag class="endtag">para</tag>
- <tag class="endtag">sect1</tag>
-<tag class="endtag">article</tag></programlisting>
- </informalexample>
- </sect3>
-
- <sect3 xml:id="writing-style-tag-style-separating">
- <title>Separating Tags</title>
-
- <para>Tags like <tag>itemizedlist</tag> 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 <tag>para</tag> and
- <tag>term</tag> 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 xml:id="writing-style-whitespace-changes">
- <title>Whitespace Changes</title>
-
- <para><emphasis>Do not commit changes
- to content at the same time as changes to
- formatting</emphasis>.</para>
-
- <para>When content and whitespace changes are kept separate,
- translation teams can easily see whether a change was content
- that must be translated or only whitespace.</para>
-
- <para>For example, if two sentences have been added to a
- paragraph so that the line lengths now go
- over 80 columns, first commit the change with the too-long
- lines. Then fix the line wrapping, and commit this
- second change. In the commit message for the second change,
- indicate that this is a whitespace-only change that can be
- ignored by translators.</para>
- </sect2>
-
- <sect2 xml:id="writing-style-nonbreaking-space">
- <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 &hellip;</literallayout>
-
- <para>The general entity <literal>&amp;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>57600&amp;nbsp;bps</programlisting>
- </listitem>
-
- <listitem>
- <para>between program names and version numbers:</para>
- <programlisting>&amp;os;&amp;nbsp;9.2</programlisting>
- </listitem>
-
- <listitem>
- <para>between multiword names (use with caution when
- applying this to more than 3-4 word names like
- <quote>The &os; Brazilian Portuguese Documentation
- Project</quote>):</para>
- <programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1 xml:id="writing-style-word-list">
- <title>Word List</title>
-
- <para>This list of words shows the correct spelling and
- capitalization when used in &os; documentation. If a word is
- not on this list, ask about it on the &a.doc;.</para>
-
- <informaltable frame="none" pgwide="0">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Word</entry>
- <entry>XML Code</entry>
- <entry>Notes</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>CD-ROM</entry>
-
- <entry><tag
- class="starttag">acronym</tag><literal>CD-ROM</literal><tag
- class="endtag">acronym</tag></entry>
- </row>
-
- <row>
- <entry>DoS (Denial of Service)</entry>
- <entry><tag
- class="starttag">acronym</tag><literal>DoS</literal><tag
- class="endtag">acronym</tag></entry>
- </row>
-
- <row>
- <entry>email</entry>
- </row>
-
- <row>
- <entry>file system</entry>
- </row>
-
- <row>
- <entry>IPsec</entry>
- </row>
-
- <row>
- <entry>Internet</entry>
- </row>
-
- <row>
- <entry>manual page</entry>
- </row>
-
- <row>
- <entry>mail server</entry>
- </row>
-
- <row>
- <entry>name server</entry>
- </row>
-
- <row>
- <entry>Ports Collection</entry>
- </row>
-
- <row>
- <entry>read-only</entry>
- </row>
-
- <row>
- <entry>Soft Updates</entry>
- </row>
-
- <row>
- <entry>stdin</entry>
- <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>stdout</entry>
- <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>stderr</entry>
- <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry>
- </row>
-
- <row>
- <entry>Subversion</entry>
-
- <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry>
- <entry>Do not refer to the Subversion application as
- <literal>SVN</literal> in upper case. To refer to the
- command, use <tag
- class="starttag">command</tag><literal>svn</literal><tag
- class="endtag">command</tag>.</entry>
- </row>
-
- <row>
- <entry>&unix;</entry>
- <entry><literal>&amp;unix;</literal></entry>
- </row>
-
- <row>
- <entry>userland</entry>
- <entry />
- <entry>things that apply to user space, not the
- kernel</entry>
- </row>
-
- <row>
- <entry>web server</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-</chapter>