diff options
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.xml | 607 |
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: … in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <informalexample> - <para>Right: … in - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <para>Manual page references (the second example uses - <tag>citerefentry</tag> with the - <literal>&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><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, - <emphasis>not</emphasis> - <literal><!entity…></literal> and - <literal><!doctype…></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 &os; - system. Refer to the article <tag class="starttag">link - xlink:href="&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 …</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>57600&nbsp;bps</programlisting> - </listitem> - - <listitem> - <para>between program names and version numbers:</para> - <programlisting>&os;&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 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>&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> |