Date: Mon, 21 May 2012 14:54:44 +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: r38872 - head/en_US.ISO8859-1/books/fdp-primer/writing-style Message-ID: <201205211454.q4LEsi2L062346@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon May 21 14:54:44 2012 New Revision: 38872 URL: http://svn.freebsd.org/changeset/doc/38872 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Mon May 21 14:43:21 2012 (r38871) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Mon May 21 14:54:44 2012 (r38872) @@ -32,112 +32,117 @@ <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> - + + <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>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> + <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> + 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>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> + <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>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> - + <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>These two examples show this for commands. The second example - is preferred.</para> - + <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>cvsup</command> to update your - sources.</para> + <para>Use the command <command>cvsup</command> to update + your sources.</para> </informalexample> - + <informalexample> - <para>Use <command>cvsup</command> to update your sources.</para> + <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> - + + <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 + + <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> @@ -152,11 +157,11 @@ <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> + 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> @@ -168,8 +173,9 @@ <sect1 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> + <para>To keep the source for the documentation consistent when + many different people are editing it, please follow these style + conventions.</para> <sect2> <title>Letter Case</title> @@ -177,9 +183,10 @@ <para>Tags are entered in lower case, <sgmltag>para</sgmltag>, <emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para> - <para>Text that appears in SGML contexts is generally written in upper - case, <literal><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> + <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> @@ -188,36 +195,36 @@ <title>Acronyms</title> <para>Acronyms should generally be spelled out the first time - they appear in a document, as in: <quote>Network Time Protocol (<acronym - role="Network Time Protocol">NTP</acronym>)</quote>. After the - acronym has been defined, you should generally use the acronym - only (not the whole term, unless it makes more sense - contextually to use the whole term). Usually, acronyms are - defined only one per document. But if you prefer, you can also - define them the first time they appear in each chapter.</para> + they appear in a document, as in: <quote>Network Time Protocol + (<acronym role="Network Time Protocol">NTP</acronym>)</quote>. + After the acronym has been defined, you should generally use + the acronym only (not the whole term, unless it makes more + sense contextually to use the whole term). Usually, acronyms + are defined only one per document. But if you prefer, you can + also define them the first time they appear in each + chapter.</para> <para>The first three uses of an acronym should be enclosed in - <sgmltag>acronym</sgmltag> tags, with a <literal>role</literal> attribute - with the full term defined. This allows a link to the - glossary to be created, and for mouseovers to be rendered with - the fully expanded term.</para> + <sgmltag>acronym</sgmltag> tags, with a + <literal>role</literal> attribute with the full term defined. + This allows a link to the glossary to be created, and for + mouseovers to be rendered with the fully expanded term.</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> + <emphasis>regardless</emphasis> of the indentation level of + the file which might contain this one.</para> <para>Opening tags increase the indentation level by 2 spaces. - Closing tags decrease the indentation level by 2 spaces. Blocks - of 8 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> + Closing tags decrease the indentation level by 2 spaces. + Blocks of 8 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 something like:</para> @@ -244,12 +251,12 @@ V <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 - <application>Emacs</application> local variables at the bottom of each file should enforce these - styles.</para> + <literal>sgml-mode</literal> should be loaded automatically, + and the <application>Emacs</application> local variables at + the bottom of each file should enforce these styles.</para> - <para><application>Vim</application> users might want to configure - their editor with:</para> + <para><application>Vim</application> users might want to + configure their editor with:</para> <programlisting>augroup sgmledit autocmd FileType sgml set formatoptions=cq2l " Special formatting options @@ -267,7 +274,7 @@ augroup END</programlisting> <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> @@ -305,8 +312,8 @@ augroup END</programlisting> <title>Separating Tags</title> <para>Tags like <sgmltag>itemizedlist</sgmltag> which will - always have further tags inside them, and in fact do not take - character data themselves, are always on a line by + 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 <sgmltag>para</sgmltag> and @@ -334,38 +341,40 @@ augroup END</programlisting> <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 + <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 documentation 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> + + <para>This is so that the teams that convert the documentation + 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> <sect2> <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 + <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> + line breaks between parts belonging together. Use + non-breaking spaces in the following places:</para> <itemizedlist> <listitem> @@ -379,10 +388,11 @@ GB. Hardware compression …</lite </listitem> <listitem> - <para>between multiword names (use with caution when applying this - to more than 3-4 word names like <quote>The FreeBSD Brazilian - Portuguese Documentation Project</quote>):</para> - <programlisting><![ CDATA [Sun Microsystems]]></programlisting> + <para>between multiword names (use with caution when + applying this to more than 3-4 word names like + <quote>The FreeBSD Brazilian Portuguese Documentation + Project</quote>):</para> + <programlisting><![ CDATA [Sun Microsystems]]></programlisting> </listitem> </itemizedlist> </sect2> @@ -395,8 +405,8 @@ GB. Hardware compression …</lite should be used in the FreeBSD Documentation Project. If the word you are looking for is not in this list, then please consult the <ulink - url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly - word list</ulink>.</para> + url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly + word list</ulink>.</para> <itemizedlist> <listitem> @@ -471,7 +481,6 @@ GB. Hardware compression …</lite <para>web server</para> </listitem> </itemizedlist> - </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205211454.q4LEsi2L062346>