diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml deleted file mode 100644 index 69c3f6c25c..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml +++ /dev/null @@ -1,340 +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.7 2000/01/16 22:13:09 asmodai 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 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 “and”.</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, “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> - <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><para></literal>, - <emphasis>not</emphasis> <literal><PARA></literal>.</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> - <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> - - <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> - <artheader> - <title>NIS</title> - - <pubdate>October 1999</pubdata> - - <abstract> - <para>... - ... - ...</para> - </abstract> - </artheader> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> -</article>]]></programlisting> - </informalexample> - </sect3> - - <sect3> - <title>Special tags</title> - - <para>Some tags just don't follow the indenting rules of the - previous section; <sgmltag>screen</sgmltag> and - <sgmltag>programlisting</sgmltag> should always be - left-aligned.</para> - - <informalexample> - <programlisting><![ RCDATA [<informalexample> -<programlisting> -… -</programlisting> -</informalexample>]]></programlisting> - </informalexample> - - <para><sgmltag>informalexample</sgmltag> also should be - left-aligned when it wraps a <sgmltag>screen</sgmltag> or - <sgmltag>programlisting</sgmltag>.</para> - - <para>These examples should be separated from the rest of the - content by a blank line before and after.</para> - </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: ---> - |