Date: Thu, 20 Jun 2013 16:46:55 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41971 - head/en_US.ISO8859-1/books/fdp-primer/writing-style Message-ID: <201306201646.r5KGktTe093581@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Thu Jun 20 16:46:55 2013 New Revision: 41971 URL: http://svnweb.freebsd.org/changeset/doc/41971 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu Jun 20 16:40:42 2013 (r41970) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu Jun 20 16:46:55 2013 (r41971) @@ -54,7 +54,7 @@ concepts.</para> <para>Avoid flowery or embellished speech, jokes, or colloquial - expressions. Write as simply and clearly as possible. Simple + 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. @@ -108,142 +108,145 @@ <sect1 id="writing-style-guidelines"> <title>Guidelines</title> - <para>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>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> 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. Separate the last item - from the others with a comma and the word - <quote>and</quote>.</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, <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>Try not to use redundant phrases. In particular, - <quote>the command</quote>, <quote>the file</quote>, and - <quote>man command</quote> are probably redundant.</para> + <para>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>Use American English Spelling</term> - <para>These two examples show this for commands. The second - example is preferred.</para> + <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> - <informalexample> - <para>Use the command <command>svn</command> to update - your sources.</para> - </informalexample> + <varlistentry> + <term>Do not use contractions</term> - <informalexample> - <para>Use <command>svn</command> to update your - sources.</para> - </informalexample> + <listitem> + <para>Do not use contractions. Always spell the phrase out + in full. <quote>Don't use contractions</quote> 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> - <para>These two examples show this for filenames. The second - example is preferred.</para> + <varlistentry> + <term>Use the serial comma</term> - <informalexample> - <para>… in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> + <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, 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, <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> - <informalexample> - <para>… in - <filename>/etc/rc.local</filename>…</para> - </informalexample> + <varlistentry> + <term>Avoid redundant phrases</term> - <para>These two examples show this for manual references. The - second example is preferred (the second example uses - <sgmltag>citerefentry</sgmltag>).</para> + <listitem> + <para>Try not to use redundant phrases. In particular, + <quote>the command</quote>, <quote>the file</quote>, and + <quote>man command</quote> are probably redundant.</para> + + <para>These two examples show this for commands. The second + example is preferred.</para> + + <informalexample> + <para>Use the command <command>svn</command> to update + your sources.</para> + </informalexample> + + <informalexample> + <para>Use <command>svn</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> - <informalexample> - <para>See <command>man csh</command> for more - information.</para> - </informalexample> + <varlistentry> + <term>Two spaces at the end of sentences</term> - <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 is not a - new sentence there.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about writing style, see <ulink - url="http://www.bartleby.com/141/">Elements of - Style</ulink>, by William Strunk.</para> + <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 is not a new sentence + there.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>For more information about writing style, see <ulink + url="http://www.bartleby.com/141/">Elements of + Style</ulink>, by William Strunk.</para> </sect1> <sect1 id="writing-style-guide">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306201646.r5KGktTe093581>