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 index d4cac87418..46d352a9d9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml @@ -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>