- Simplify <URL: link> notation

- Capitalize and add non-breakable spaces to "Ports Collection"
- s/of/or in "number of rows of columns"
- Mark up some attributes and literals with <literal> elements
- Eliminate first-person narration
- Add more generalization to the text, refer to the Handbook as an
  example
- Update path names of the Handbook sources
- Add missing text to the <blockquote> example
- Add a table with borders to the examples
- Simplify some parts of the manual page markup example
- Fix all sendmail-related manual page sections
- Fix example of <hostid>
- Remove <informalexample> tags from the <screen> example
- Add missing parentheses

Reviewed by:	gabor, manolis, rene
Obtained from:	The FreeBSD Hungarian Documentation Project

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

@@ -64,7 +64,7 @@
     
     <para>HTML, the HyperText Markup Language, is the markup language of
       choice on the World Wide Web.  More information can be found at
-      &lt;URL:<ulink url="http://www.w3.org/"></ulink>&gt;.</para>
+      <ulink url="http://www.w3.org/"></ulink>.</para>
 
     <para>HTML is used to markup pages on the FreeBSD web site.  It should not
       (generally) be used to mark up other documentation, 
@@ -77,7 +77,7 @@
       latest, 4.0 (available in both <emphasis>strict</emphasis> and
       <emphasis>loose</emphasis> variants).</para>
 	  
-    <para>The HTML DTDs are available from the ports collection in the
+    <para>The HTML DTDs are available from the Ports&nbsp;Collection in the
       <filename role="package">textproc/html</filename> port.  They are automatically
       installed as part of the <filename role="package">textproc/docproj</filename>
       port.</para>
@@ -392,7 +392,7 @@
 
 	<para>A cell can span multiple rows and columns.  To indicate this,
 	  add the <literal>rowspan</literal> and/or <literal>colspan</literal>
-	  attributes, with values indicating the number of rows of columns
+	  attributes, with values indicating the number of rows or columns
 	  that should be spanned.</para>
 
 	<example>
@@ -555,7 +555,7 @@
 
 	  <listitem>
 	    <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
-	      attribute set to a number between 1 and 7.  The default font size
+	      attribute set to a number between <literal>1</literal> and <literal>7</literal>.  The default font size
 	      is <literal>3</literal>.  This approach is deprecated.</para>
 	  </listitem>
 	</orderedlist>
@@ -570,7 +570,7 @@
   this text is <big>slightly bigger</big>.</p>
 
 <p>This text is <font size="-1">slightly smaller</font>.  But
-  this text is <font size="+1">slightly bigger</font.</p>
+  this text is <font size="+1">slightly bigger</font>.</p>
 
 <p>This text is <font size="2">slightly smaller</font>.  But
   this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
@@ -689,7 +689,7 @@
 	title.</para>
     </note>
     
-    <para>The DocBook DTD is available from the ports collection in the
+    <para>The DocBook DTD is available from the Ports&nbsp;Collection in the
       <filename role="package">textproc/docbook</filename> port.  It is automatically
       installed as part of the <filename role="package">textproc/docproj</filename>
       port.</para>
@@ -717,8 +717,8 @@
 	  touch with &a.doceng;.</para>
       </note>
 
-      <para>The FreeBSD extensions are not (currently) in the ports
+      <para>The &os; extensions are not (currently) in the Ports&nbsp;Collection.
-	collection.  They are stored in the FreeBSD CVS tree, as <ulink
+	They are stored in the &os; CVS tree, as <ulink
 	url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
     </sect2>
 
@@ -742,7 +742,7 @@
       <para>A book is organized into <sgmltag>chapter</sgmltag>s.  This is a
 	mandatory requirement.  There may be <sgmltag>part</sgmltag>s between
 	the book and the chapter to provide another layer of organization.
-	The Handbook is arranged in this way.</para>
+	For example, the Handbook is arranged in this way.</para>
 
       <para>A chapter may (or may not) contain one or more sections.  These
 	are indicated with the <sgmltag>sect1</sgmltag> element.  If a section
@@ -770,7 +770,7 @@
 	document, the <ulink url="&url.books.faq;/index.html">FreeBSD
 	  FAQ</ulink>, and the <ulink
 	  url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> are
-	all marked up as books.</para>
+	all marked up as books, for example.</para>
 
       <sect3>
 	<title>Starting a Book</title>
@@ -1055,6 +1055,8 @@
 
 	  <para>Appearance:</para>
 	  
+	  <para>A small excerpt from the US Constitution:</para>
+
 	  <blockquote>
 	    <title>Preamble to the Constitution of the United States</title>
 	    
@@ -1120,6 +1122,7 @@
 </warning>]]></programlisting>
 	  </example>
 	  
+	<para>Appearance:</para>
 	<!-- Need to do this outside of the example -->
 	<warning>
 	  <para>Installing FreeBSD may make you want to delete Windows from
@@ -1390,7 +1393,7 @@ main(void)
 	  
 	  <para>Use:</para>
 	  
-	  <programlisting><![ CDATA [<informaltable frame="none" pgwide="1">
+	  <programlisting><![ CDATA [<informaltable pgwide="1">
   <tgroup cols="2">
     <thead>
       <row>
@@ -1415,7 +1418,7 @@ main(void)
 	  
 	  <para>Appearance:</para>
 	  
-	  <informaltable frame="none" pgwide="1">
+	  <informaltable pgwide="1">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
@@ -1703,7 +1706,7 @@ This is the file called 'foo2'</screen>
 	<title>Applications, Commands, Options, and Cites</title>
 	
 	<para>You will frequently want to refer to both applications and
-	  commands when writing for the Handbook.  The distinction between
+	  commands when writing documentation.  The distinction between
 	  them is simple: an application is the name for a suite (or possibly
 	  just 1) of programs that fulfil a particular task.  A command is the
 	  name of a program that the user can run.</para>
@@ -1780,7 +1783,7 @@ This is the file called 'foo2'</screen>
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
-  </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
+  </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
   programs.</para>
 
 <para>One of the command line parameters to <citerefentry>
@@ -1799,13 +1802,7 @@ This is the file called 'foo2'</screen>
 	    <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
 	      <manvolnum>8</manvolnum>
-	    </citerefentry>, <citerefentry>
+	    </citerefentry>, &man.mailq.1;, and &man.newaliases.1; programs.</para>
-	      <refentrytitle>mailq</refentrytitle>
-	      <manvolnum>8</manvolnum>
-	    </citerefentry>, and <citerefentry>
-	      <refentrytitle>newaliases</refentrytitle>
-	      <manvolnum>8</manvolnum>
-	    </citerefentry> programs.</para>
 	  
 	  <para>One of the command line parameters to <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
@@ -1833,8 +1830,8 @@ This is the file called 'foo2'</screen>
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
-  found in <filename class="directory">/usr/doc/en/handbook/</filename>.  The first
+  found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.  The first
-  file is called <filename>handbook.sgml</filename> in that
+  file is called <filename>book.sgml</filename> in that
   directory.  You should also see a <filename>Makefile</filename>
   and a number of files with a <filename>.ent</filename>
   extension.</para>]]></programlisting>
@@ -1955,11 +1952,11 @@ This is the file called 'foo2'</screen>
 	  
 	<variablelist>
 	  <varlistentry>
-	    <term>No role attribute, or
+	    <term>No <literal>role</literal> attribute, or
 	      <literal>role="hostname"</literal></term>
 	    
 	    <listitem>
-	      <para>With no role attribute (i.e.,
+	      <para>With no <literal>role</literal> attribute (i.e.,
 		<sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) the
 		marked up information is the simple hostname, such as
 		<literal>freefall</literal> or <literal>wcarchive</literal>.
@@ -2037,13 +2034,13 @@ This is the file called 'foo2'</screen>
 <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
   contains a number of different hosts, including
   <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
-  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
+  <hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>
 
 <para>When adding an IP alias to an interface (using
   <command>ifconfig</command>) <emphasis>always</emphasis> use a
   netmask of <hostid role="netmask">255.255.255.255</hostid>
   (which can also be expressed as <hostid
-    role="netmask">0xffffffff</hostid>.</para>
+    role="netmask">0xffffffff</hostid>).</para>
 
 <para>The MAC address uniquely identifies every network card
   in existence.  A typical MAC address looks like <hostid
@@ -2064,7 +2061,7 @@ This is the file called 'foo2'</screen>
 	    <command>ifconfig</command>) <emphasis>always</emphasis> use a
 	    netmask of <hostid role="netmask">255.255.255.255</hostid> (which
 	    can also be expressed as <hostid
-	      role="netmask">0xffffffff</hostid>.</para>
+	      role="netmask">0xffffffff</hostid>).</para>
 
 	  <para>The MAC address uniquely identifies every network card in
 	    existence.  A typical MAC address looks like <hostid
@@ -2161,8 +2158,8 @@ This is the file called 'foo2'</screen>
 	<title>Literal Text</title>
 	
 	<para>You will often need to include <quote>literal</quote> text in the
-	  Handbook.  This is text that is excerpted from another file, or
+	  documentation.  This is text that is excerpted from another file, or
-	  which should be copied from the Handbook into another file
+	  which should be copied from the documentation into another file
 	  verbatim.</para>
 
 	<para>Some of the time, <sgmltag>programlisting</sgmltag> will be
@@ -2210,9 +2207,7 @@ This is the file called 'foo2'</screen>
 	  
 	  <para>Use:</para>
 	  
-	  <programlisting><![ CDATA [<informalexample>
+	  <programlisting><![ CDATA [<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
-  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
-</informalexample>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
@@ -2279,7 +2274,7 @@ This is the file called 'foo2'</screen>
 
       <important>
 	<para>Image support in the documentation is currently extremely
-	  experimental.  I think the mechanisms described here are unlikely to
+	  experimental.  The mechanisms described here are unlikely to
 	  change, but that is not guaranteed.</para>
 
 	<para>You will also need to install the
@@ -2464,7 +2459,7 @@ IMAGES+= fig3.png
 	  <filename>chapter1/chapter.sgml</filename>,
 	  <filename>chapter2/chapter.sgml</filename>, and
 	  <filename>chapter3/chapter.sgml</filename>.  If each chapter has
-	  images associated with it, I suggest you place those images in each
+	  images associated with it, it is suggested to place those images in each
 	  chapter's subdirectory (<filename>chapter1/</filename>,
 	  <filename>chapter2/</filename>, and
 	  <filename>chapter3/</filename>).</para>