Date: Mon, 22 Jul 2013 03:57:40 +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: r42368 - head/en_US.ISO8859-1/books/fdp-primer/writing-style Message-ID: <201307220357.r6M3vehk002360@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon Jul 22 03:57:40 2013 New Revision: 42368 URL: http://svnweb.freebsd.org/changeset/doc/42368 Log: Spelling correction. Explain that two spaces come between sentences, not at the beginning or end of a sentence. Modernize the acronym guidelines. 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 Mon Jul 22 01:45:43 2013 (r42367) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Mon Jul 22 03:57:40 2013 (r42368) @@ -38,7 +38,7 @@ <title>Tips</title> <para>Technical documentation can be improved by consistent use of - several principes. Most of these can be classified into three + 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 @@ -236,20 +236,19 @@ </varlistentry> <varlistentry> - <term>Two spaces at the end of sentences</term> + <term>Two spaces between sentences</term> <listitem> - <para>Always use two spaces at the end of sentences, as this - improves readability, and eases use of tools such as + <para>Always use two spaces between 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 + <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 there certainly is not a new sentence - there.</para> + space, and is certainly not a new sentence.</para> </listitem> </varlistentry> </variablelist> @@ -283,21 +282,18 @@ <sect2> <title>Acronyms</title> - <para>Acronyms should generally be spelled out the first time + <para>Acronyms should 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 + (<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. Usually, acronyms + are defined only one per document. But they can also be + defined the first time they appear in a chapter.</para> <para>All acronyms 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.</para> </sect2> <sect2> @@ -338,9 +334,9 @@ V </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, + <para><application>Emacs</application> or + <application>XEmacs</application> should load + <literal>sgml-mode</literal> automatically, and the <application>Emacs</application> local variables at the bottom of each file should enforce these styles.</para>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307220357.r6M3vehk002360>