More simplification and cleanups, replacement of CDATA sections with

sgmltags.

1 files changed, 55 insertions, 61 deletions

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 bee9d1c540..885e02e80d 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
@@ -119,7 +119,7 @@
     <title>Guidelines</title>
 
     <para>To promote consistency between the myriad authors of the
-      FreeBSD documentation, some guidelines have been drawn up for
+      &os; documentation, some guidelines have been drawn up for
       authors to follow.</para>
 
     <variablelist>
@@ -148,7 +148,7 @@
 
 	<listitem>
 	  <para>Do not use contractions.  Always spell the phrase out
-	    in full.  <quote>Don't use contractions</quote> would be
+	    in full.  <quote>Don't use contractions</quote> is
 	    wrong.</para>
 
 	  <para>Avoiding contractions makes for a more formal tone, is
@@ -166,7 +166,7 @@
 	    from the others with a comma and the word
 	    <quote>and</quote>.</para>
 
-	  <para>For example, look at the following:</para>
+	  <para>For example:</para>
 
 	  <blockquote>
 	    <para>This is a list of one, two and three items.</para>
@@ -190,47 +190,44 @@
 	<term>Avoid redundant phrases</term>
 
 	<listitem>
-	  <para>Try not to use redundant phrases.  In particular,
+	  <para>Do not use redundant phrases.  In particular,
 	    <quote>the command</quote>, <quote>the file</quote>, and
-	    <quote>man command</quote> are probably redundant.</para>
+	    <quote>man command</quote> are often redundant.</para>
 
-	  <para>These two examples show this for commands.  The second
-	    example is preferred.</para>
+	  <para>For example, commands:</para>
 
 	  <informalexample>
-	    <para>Use the command <command>svn</command> to update
-	      your sources.</para>
+	    <para>Wrong:  Use the command <command>svn</command> to update
+	      sources.</para>
 	  </informalexample>
 
 	  <informalexample>
-	    <para>Use <command>svn</command> to update your
+	    <para>Right:  Use <command>svn</command> to update
 	      sources.</para>
 	  </informalexample>
 
-	  <para>These two examples show this for filenames.  The
-	    second example is preferred.</para>
+	  <para>Filenames:</para>
 
 	  <informalexample>
-	    <para>&hellip; in the filename
+	    <para>Wrong:  &hellip; in the filename
 	      <filename>/etc/rc.local</filename>&hellip;</para>
 	  </informalexample>
 
 	  <informalexample>
-	    <para>&hellip; in
+	    <para>Right:  &hellip; in
 	      <filename>/etc/rc.local</filename>&hellip;</para>
 	  </informalexample>
 
-	  <para>These two examples show this for manual references.
-	    The second example is preferred (the second example uses
-	    <sgmltag>citerefentry</sgmltag>).</para>
+	  <para>Manual page references (the second example uses
+	    <sgmltag>citerefentry</sgmltag> with the <literal>&amp;man.csh.1;</literal> entity):.</para>
 
 	  <informalexample>
-	    <para>See <command>man csh</command> for more
+	    <para>Wrong:  See <command>man csh</command> for more
 	      information.</para>
 	  </informalexample>
 
 	  <informalexample>
-	    <para>See &man.csh.1;.</para>
+	    <para>Right:  See &man.csh.1;.</para>
 	  </informalexample>
 	</listitem>
       </varlistentry>
@@ -239,7 +236,7 @@
 	<term>Two spaces between sentences</term>
 
 	<listitem>
-	  <para>Always use two spaces between sentences, as this
+	  <para>Always use two spaces between sentences, as it
 	    improves readability and eases use of tools such as
 	    <application>Emacs</application>.</para>
 
@@ -300,16 +297,15 @@
 	<emphasis>regardless</emphasis> of the indentation level of
 	the file which might contain the current file.</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
+      <para>Opening tags increase the indentation level by two spaces.
+	Closing tags decrease the indentation level by two spaces.
+	Blocks of eight 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>
+      <para>For example, the source for this section looks like this:</para>
 
       <programlisting><sgmltag class="starttag">chapter</sgmltag>
   <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag>
@@ -345,31 +341,31 @@
 	  at the same indent as a previous tag should not:</para>
 
 	<informalexample>
-	  <programlisting><![CDATA[<article lang='en'>
-  <articleinfo>
-    <title>NIS</title>
+	  <programlisting><sgmltag class="starttag">article lang='en'</sgmltag>
+  <sgmltag class="starttag">articleinfo</sgmltag>
+    <sgmltag class="starttag">title</sgmltag>NIS<sgmltag class="endtag">title</sgmltag>
 
-    <pubdate>October 1999</pubdate>
+    <sgmltag class="starttag">pubdate</sgmltag>October 1999<sgmltag class="endtag">pubdate</sgmltag>
 
-    <abstract>
-      <para>...
+    <sgmltag class="starttag">abstract</sgmltag>
+      <sgmltag class="starttag">para</sgmltag>...
 	...
-	...</para>
-    </abstract>
-  </articleinfo>
+	...<sgmltag class="endtag">para</sgmltag>
+    <sgmltag class="endtag">abstract</sgmltag>
+  <sgmltag class="endtag">articleinfo</sgmltag>
 
-  <sect1>
-    <title>...</title>
+  <sgmltag class="starttag">sect1</sgmltag>
+    <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag>
 
-    <para>...</para>
-  </sect1>
+    <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag>
+  <sgmltag class="endtag">sect1</sgmltag>
 
-  <sect1>
-    <title>...</title>
+  <sgmltag class="starttag">sect1</sgmltag>
+    <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag>
 
-    <para>...</para>
-  </sect1>
-</article>]]></programlisting>
+    <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag>
+  <sgmltag class="endtag">sect1</sgmltag>
+<sgmltag class="endtag">article</sgmltag></programlisting>
 	</informalexample>
       </sect3>
 
@@ -404,25 +400,23 @@
     </sect2>
 
     <sect2>
-      <title>White Space Changes</title>
+      <title>Whitespace Changes</title>
 
-      <para>When committing changes, <emphasis>do not commit changes
-	  to the content at the same time as changes to the
+      <para><emphasis>Do not commit changes
+	  to content at the same time as changes to
 	  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>When content and whitespace changes are kept separate, translation teams
+	can easily see whether a change was content that must be translated
+	or only whitespace.</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
+      <para>For example, if two sentences have been added to a
+	paragraph so that the line lengths now go
+	over 80 columns, first commit the change with the too-long
+	lines.  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>
+	indicate that this is a whitespace-only change that can be
+	ignored by translators.</para>
     </sect2>
 
     <sect2>
@@ -444,18 +438,18 @@ GB.  Hardware compression &hellip;</literallayout>
       <itemizedlist>
 	<listitem>
 	  <para>between numbers and units:</para>
-	  <programlisting><![CDATA[57600&nbsp;bps]]></programlisting>
+	  <programlisting>57600&amp;nbsp;bps</programlisting>
 	</listitem>
 
 	<listitem>
 	  <para>between program names and version numbers:</para>
-	  <programlisting><![CDATA[FreeBSD&nbsp;4.7]]></programlisting>
+	  <programlisting>&amp;os;&amp;nbsp;9.2</programlisting>
 	</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
+	    <quote>The &os; Brazilian Portuguese Documentation
 	      Project</quote>):</para>
 	  <programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
 	</listitem>
@@ -467,7 +461,7 @@ GB.  Hardware compression &hellip;</literallayout>
     <title>Word List</title>
 
     <para>This list of words shows the correct spelling and
-      capitalization when used in FreeBSD Documentation.  If a word is
+      capitalization when used in &os; documentation.  If a word is
       not on this list, ask about it on the &a.doc;.</para>
 
     <informaltable frame="none" pgwide="0">