Update the SGML Primer chapter in FDP Primer:

- Eliminate a <blockquote> inside <para> (split <para> around <blockquote>)
- Use <sgmltag> markup where possible
- nsgmls does not always give error messages, just messages (those might
  contain information on errors)
- Eliminate first person narration
- Add missing full stops
- Add a missing <literal> markup for CDATA

Reviewed by:	blackend, danger, gabor, hrs, manolis, remko, trhodes

en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml

@@ -65,8 +65,8 @@
       like that, and our computers require some assistance before they can
       meaningfully process our text.</para>
 
-    <para>More precisely, they need help identifying what is what.  You or I
-      can look at
+    <para>More precisely, they need help identifying what is what.  Let's
+      look at this text:</para>
 
       <blockquote>
 	<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
@@ -74,7 +74,7 @@
 	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
       </blockquote>
 
-      and easily see which parts are filenames, which are commands to be typed
+    <para>It is easy to see which parts are filenames, which are commands to be typed
       in, which parts are references to manual pages, and so on.  But the
       computer processing the document cannot.  For this we need
       markup.</para>
@@ -204,15 +204,15 @@
 
     <para>For an element called <replaceable>element-name</replaceable> the
       start tag will normally look like
-      <literal>&lt;<replaceable>element-name</replaceable>&gt;</literal>.  The
+      <sgmltag><replaceable>element-name</replaceable></sgmltag>.  The
       corresponding closing tag for this element is
-      <literal>&lt;/<replaceable>element-name</replaceable>&gt;</literal>.</para>
+      <sgmltag>/<replaceable>element-name</replaceable></sgmltag>.</para>
 
     <example>
       <title>Using an element (start and end tags)</title>
 
       <para>HTML has an element for indicating that the content enclosed by
-	the element is a paragraph, called <literal>p</literal>.  This
+	the element is a paragraph, called <sgmltag>p</sgmltag>.  This
 	element has both start and end tags.</para>
       
       <programlisting><![ CDATA [<p>This is a paragraph.  It starts with the start tag for
@@ -231,7 +231,7 @@
       <title>Using an element (start tag only)</title>
 
       <para>HTML has an element for indicating a horizontal rule, called
-	<literal>hr</literal>.  This element does not wrap content, so only
+	<sgmltag>hr</sgmltag>.  This element does not wrap content, so only
 	has a start tag.</para>
 
       <programlisting><![ CDATA [<p>This is a paragraph.</p>
@@ -266,10 +266,10 @@
 	end.</para>
 
       <para>When this document (or anyone else knowledgeable about SGML) refers
-	to <quote>the &lt;p&gt; tag</quote> they mean the literal text
+	to <quote>the <sgmltag>p</sgmltag> tag</quote> they mean the literal text
 	consisting of the three characters <literal>&lt;</literal>,
 	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
-	<quote>the &lt;p&gt; element</quote> refers to the whole
+	<quote>the <sgmltag>p</sgmltag> element</quote> refers to the whole
 	element.</para>
 
       <para>This distinction <emphasis>is</emphasis> very subtle.  But keep it 
@@ -287,7 +287,7 @@
       <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
 
     <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag>
-      element has an attribute called <literal>align</literal>, which suggests
+      element has an attribute called <sgmltag>align</sgmltag>, which suggests
       an alignment (justification) for the paragraph to the program displaying
       the HTML.</para>
 
@@ -494,7 +494,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 
 		<row>
 		  <entry>6</entry>
-		  <entry>The text of the error message.</entry>
+		  <entry>The text of the message.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
@@ -519,7 +519,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 	</step>
 
 	<step>
-	  <para>Put the <literal>title</literal> element back in.</para>
+	  <para>Put the <sgmltag>title</sgmltag> element back in.</para>
 	</step>
       </procedure>
     </sect2>
@@ -781,7 +781,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
   <sect1 id="sgml-primer-sgml-escape">
     <title>Escaping back to SGML</title>
 
-    <para>Earlier in this primer I said that SGML is only used when writing a
+    <para>As mentioned earlier, SGML is only used when writing a
       DTD.  This is not strictly true.  There is certain SGML syntax that you
       will want to be able to use within your documents.  For example,
       comments can be included in your document, and will be ignored by the
@@ -1379,7 +1379,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 	  characters.</para>
 	
 	<para><literal>RCDATA</literal> is for <quote>Entity references and
-	  character data</quote> If the parser is in this content model then it
+	  character data</quote>.  If the parser is in this content model then it
 	  is expecting to see characters <emphasis>and</emphasis> entities.
 	  <literal>&lt;</literal> loses its special status, but
 	  <literal>&amp;</literal> will still be treated as
@@ -1392,7 +1392,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 	  <literal>&lt;</literal> is converted to a
 	  <literal>&amp;lt;</literal> and every <literal>&amp;</literal>
 	  is converted to a <literal>&amp;amp;</literal>, it can be
-	  easier to mark the section as only containing CDATA.  When the SGML
+	  easier to mark the section as only containing <literal>CDATA</literal>.  When the SGML
 	  parser encounters this it will ignore the
 	  <literal>&lt;</literal> and <literal>&amp;</literal> symbols
 	  embedded in the content.</para>
@@ -1534,7 +1534,7 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
   &lt;body>	    
     &lt;p>This paragraph &lt;![ CDATA [contains many &lt;
       characters (&lt; &lt; &lt; &lt; &lt;) so it is easier
-      to wrap it in a CDATA marked section ]]&gt;&lt;/p>
+      to wrap it in a CDATA marked section.]]&gt;&lt;/p>
 
     &lt;![ IGNORE [
     &lt;p>This paragraph will definitely not be included in the