- Definitively upgrade to DocBook 5.0

1 files changed, 126 insertions, 132 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
index 1a436f380b..b25fc313a5 100644
--- a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
@@ -30,8 +30,7 @@
 
      $FreeBSD$
 -->
-
-<chapter id="xml-primer">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer">
   <title>XML Primer</title>
 
   <para>Most <acronym>FDP</acronym> documentation is written with
@@ -41,11 +40,10 @@
     used.</para>
 
   <para>Portions of this section were inspired by Mark Galassi's
-    <ulink
-      url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
-      Going With DocBook</ulink>.</para>
+    <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
+      Going With DocBook</link>.</para>
 
-  <sect1 id="xml-primer-overview">
+  <sect1 xml:id="xml-primer-overview">
     <title>Overview</title>
 
     <para>In the original days of computers, electronic text was
@@ -108,9 +106,9 @@
     <para>The previous example is actually represented in this
       document like this:</para>
 
-    <programlisting><sgmltag class="starttag">para</sgmltag>To remove <sgmltag class="starttag">filename</sgmltag>/tmp/foo<sgmltag class="endtag">filename</sgmltag>, use &amp;man.rm.1;.<sgmltag class="endtag">para</sgmltag>
+    <programlisting><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &amp;man.rm.1;.<tag class="endtag">para</tag>
 
-<sgmltag class="starttag">screen</sgmltag>&amp;prompt.user; <sgmltag class="starttag">userinput</sgmltag>rm /tmp/foo<sgmltag class="endtag">userinput</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting>
+<tag class="starttag">screen</tag>&amp;prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting>
 
     <para>The markup is clearly separate from the content.</para>
 
@@ -137,7 +135,7 @@
       specify an <acronym>XML</acronym> grammar, or
       <emphasis>schema</emphasis>.</para>
 
-    <para id="xml-primer-validating">A schema is a
+    <para xml:id="xml-primer-validating">A schema is a
       <emphasis>complete</emphasis> specification of all the elements
       that are allowed to appear, the order in which they should
       appear, which elements are mandatory, which are optional, and so
@@ -169,7 +167,7 @@
       to write a vocabulary.</para>
   </sect1>
 
-  <sect1 id="xml-primer-elements">
+  <sect1 xml:id="xml-primer-elements">
     <title>Elements, Tags, and Attributes</title>
 
     <para>All the vocabularies written in <acronym>XML</acronym> share
@@ -222,23 +220,21 @@
 
     <para>For an element called
       <replaceable>element-name</replaceable> the start tag will
-      normally look like <sgmltag
-	class="starttag"><replaceable>element-name</replaceable></sgmltag>.
-      The corresponding closing tag for this element is <sgmltag
-	class="endtag"><replaceable>element-name</replaceable></sgmltag>.</para>
+      normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.
+      The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>
 
     <example>
       <title>Using an Element (Start and End Tags)</title>
 
       <para><acronym>XHTML</acronym> has an element for indicating
 	that the content enclosed by the element is a paragraph,
-	called <sgmltag>p</sgmltag>.</para>
+	called <tag>p</tag>.</para>
 
-      <programlisting><sgmltag class="starttag">p</sgmltag>This is a paragraph.  It starts with the start tag for
+      <programlisting><tag class="starttag">p</tag>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
-  element.<sgmltag class="endtag">p</sgmltag>
+  element.<tag class="endtag">p</tag>
 
-<sgmltag class="starttag">p</sgmltag>This is another paragraph.  But this one is much shorter.<sgmltag class="endtag">p</sgmltag></programlisting>
+<tag class="starttag">p</tag>This is another paragraph.  But this one is much shorter.<tag class="endtag">p</tag></programlisting>
     </example>
 
     <para>Some elements have no content.  For example, in
@@ -251,22 +247,22 @@
       <title>Using an Element Without Content</title>
 
       <para><acronym>XHTML</acronym> has an element for indicating a
-	horizontal rule, called <sgmltag>hr</sgmltag>.  This element
+	horizontal rule, called <tag>hr</tag>.  This element
 	does not wrap content, so it looks like this:</para>
 
-      <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag>
-<sgmltag class="starttag">hr</sgmltag><sgmltag class="endtag">hr</sgmltag>
+      <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
+<tag class="starttag">hr</tag><tag class="endtag">hr</tag>
 
-<sgmltag class="starttag">p</sgmltag>This is another paragraph.  A horizontal rule separates this
-  from the previous paragraph.<sgmltag class="endtag">p</sgmltag></programlisting>
+<tag class="starttag">p</tag>This is another paragraph.  A horizontal rule separates this
+  from the previous paragraph.<tag class="endtag">p</tag></programlisting>
 
       <para>The shorthand version consists of a single tag:</para>
 
-      <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag>
-<sgmltag class="emptytag">hr</sgmltag>
+      <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag>
+<tag class="emptytag">hr</tag>
 
-<sgmltag class="starttag">p</sgmltag>This is another paragraph.  A horizontal rule separates this
-  from the previous paragraph.<sgmltag class="endtag">p</sgmltag></programlisting>
+<tag class="starttag">p</tag>This is another paragraph.  A horizontal rule separates this
+  from the previous paragraph.<tag class="endtag">p</tag></programlisting>
     </example>
 
     <para>As shown above, elements can contain other elements.  In the
@@ -275,10 +271,10 @@
       and so on.</para>
 
     <example>
-      <title>Elements Within Elements; <sgmltag>em</sgmltag></title>
+      <title>Elements Within Elements; <tag>em</tag></title>
 
-      <programlisting><sgmltag class="starttag">p</sgmltag>This is a simple <sgmltag class="starttag">em</sgmltag>paragraph<sgmltag class="endtag">em</sgmltag> where some
-  of the <sgmltag class="starttag">em</sgmltag>words<sgmltag class="endtag">em</sgmltag> have been <sgmltag class="starttag">em</sgmltag>emphasized<sgmltag class="endtag">em</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting>
+      <programlisting><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some
+  of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting>
     </example>
 
     <para>The grammar consists of rules that describe which elements
@@ -296,11 +292,11 @@
 
       <para>When this document (or anyone else knowledgeable about
 	<acronym>XML</acronym>) refers to
-	<quote>the <sgmltag class="starttag">p</sgmltag> tag</quote>
+	<quote>the <tag class="starttag">p</tag> 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 <sgmltag>p</sgmltag> element</quote> refers to the
+	<quote>the <tag>p</tag> element</quote> refers to the
 	whole element.</para>
 
       <para>This distinction <emphasis>is</emphasis> very subtle.  But
@@ -316,15 +312,15 @@
     <para>An element's attributes are written
       <emphasis>inside</emphasis> the start tag for that element, and
       take the form
-      <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
+      <literal>attribute-name="attribute-value"</literal>.</para>
 
-    <para>In <acronym>XHTML</acronym>, the <sgmltag>p</sgmltag>
+    <para>In <acronym>XHTML</acronym>, the <tag>p</tag>
       element has an attribute called
-      <sgmltag class="attribute">align</sgmltag>, which suggests an
+      <tag class="attribute">align</tag>, which suggests an
       alignment (justification) for the paragraph to the program
       displaying the <acronym>XHTML</acronym>.</para>
 
-    <para>The <sgmltag class="attribute">align</sgmltag> attribute can
+    <para>The <tag class="attribute">align</tag> attribute can
       take one of four defined values, <literal>left</literal>,
       <literal>center</literal>, <literal>right</literal> and
       <literal>justify</literal>.  If the attribute is not specified
@@ -333,10 +329,10 @@
     <example>
       <title>Using an Element with an Attribute</title>
 
-      <programlisting><sgmltag class="starttag">p align="left"</sgmltag>The inclusion of the align attribute
-  on this paragraph was superfluous, since the default is left.<sgmltag class="endtag">p</sgmltag>
+      <programlisting><tag class="starttag">p align="left"</tag>The inclusion of the align attribute
+  on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag>
 
-<sgmltag class="starttag">p align="center"</sgmltag>This may appear in the center.<sgmltag class="endtag">p</sgmltag></programlisting>
+<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting>
     </example>
 
     <para>Some attributes only take specific values, such as
@@ -346,7 +342,7 @@
     <example>
       <title>Single Quotes Around Attributes</title>
 
-      <programlisting><sgmltag class="starttag">p align='right'</sgmltag>I am on the right!<sgmltag class="endtag">p</sgmltag></programlisting>
+      <programlisting><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting>
     </example>
 
     <para>Attribute values in <acronym>XML</acronym> must be enclosed
@@ -371,7 +367,7 @@
       <procedure>
 	<step>
 	  <para>Install
-	    <filename role="package">textproc/docproj</filename> from
+	    <package>textproc/docproj</package> from
 	    the &os; Ports Collection.  This is a
 	    <emphasis>meta-port</emphasis> that downloads and installs
 	    the standard programs and supporting files needed by the
@@ -385,7 +381,7 @@
 	    <replaceable>en_US.ISO8859-1</replaceable> with the
 	    appropriate directory for the target language.</para>
 
-	  <example id="xml-primer-envars">
+	  <example xml:id="xml-primer-envars">
 	    <title><filename>.profile</filename>, for &man.sh.1; and
 	      &man.bash.1; Users</title>
 
@@ -423,28 +419,28 @@ setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/sh
 	  <para>Create <filename>example.xml</filename>, and enter
 	    this text:</para>
 
-	  <programlisting><sgmltag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</sgmltag>
+	  <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag>
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
-  <sgmltag class="starttag">head</sgmltag>
-    <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
-  <sgmltag class="endtag">head</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
+  <tag class="starttag">head</tag>
+    <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
+  <tag class="endtag">head</tag>
 
-  <sgmltag class="starttag">body</sgmltag>
-    <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag>
+  <tag class="starttag">body</tag>
+    <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag>
+    <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag>
-  <sgmltag class="endtag">body</sgmltag>
-<sgmltag class="endtag">html</sgmltag></programlisting>
+    <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
+  <tag class="endtag">body</tag>
+<tag class="endtag">html</tag></programlisting>
 	</step>
 
 	<step>
 	  <para>Try to validate this file using an
 	    <acronym>XML</acronym> parser.</para>
 
-	  <para><filename role="package">textproc/docproj</filename>
+	  <para><package>textproc/docproj</package>
 	    includes the <command>xmllint</command>
 	    <link linkend="xml-primer-validating">validating
 	      parser</link>.</para>
@@ -462,8 +458,8 @@ setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/sh
 	<step>
 	  <para>See what happens when required elements are omitted.
 	    Delete the line with the
-	    <sgmltag class="starttag">title</sgmltag> and
-	    <sgmltag class="endtag">/title</sgmltag> tags, and re-run
+	    <tag class="starttag">title</tag> and
+	    <tag class="endtag">/title</tag> tags, and re-run
 	    the validation.</para>
 
 	  <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput>
@@ -472,7 +468,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <para>This shows that the validation error comes from the
 	    <replaceable>fifth</replaceable> line of the
 	    <replaceable>example.xml</replaceable> file and that the
-	    content of the <sgmltag class="starttag">head</sgmltag> is
+	    content of the <tag class="starttag">head</tag> is
 	    the part which does not follow the rules of the
 	    <acronym>XHTML</acronym> grammar.</para>
 
@@ -482,13 +478,13 @@ example.xml:5: element head: validity error : Element head content does not foll
 	</step>
 
 	<step>
-	  <para>Replace the <sgmltag>title</sgmltag> element.</para>
+	  <para>Replace the <tag>title</tag> element.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-doctype-declaration">
+  <sect1 xml:id="xml-primer-doctype-declaration">
     <title>The DOCTYPE Declaration</title>
 
     <para>The beginning of each document can specify the name of the
@@ -501,7 +497,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       version 1.0 of the <acronym>XHTML</acronym>
       <acronym>DTD</acronym> looks like this:</para>
 
-    <programlisting><sgmltag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</sgmltag></programlisting>
+    <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting>
 
     <para>That line contains a number of different components.</para>
 
@@ -555,8 +551,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	    <acronym>DTD</acronym> referenced in the
 	    <acronym>FPI</acronym>.  Other ways of telling the
 	    <acronym>XML</acronym> parser how to find the
-	    <acronym>DTD</acronym> are shown <link
-	      linkend="xml-primer-fpi-alternatives">later</link>.</para>
+	    <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
 	</listitem>
       </varlistentry>
 
@@ -620,9 +615,9 @@ example.xml:5: element head: validity error : Element head content does not foll
 	      superset) of <acronym>XML</acronym>.</para>
 
 	    <para>Otherwise, this string will either look like
-	      <literal>-//<replaceable>Owner</replaceable></literal>
+	      <literal>-//Owner</literal>
 	      or
-	      <literal>+//<replaceable>Owner</replaceable></literal>
+	      <literal>+//Owner</literal>
 	      (notice the only difference is the leading
 	      <literal>+</literal> or <literal>-</literal>).</para>
 
@@ -714,8 +709,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
 	  This is the catalog file for the <acronym>XHTML</acronym>
 	  <acronym>DTD</acronym>s that were installed as part of the
-	  <filename
-	    role="package">textproc/docproj</filename> port.</para>
+	  <package>textproc/docproj</package> port.</para>
       </sect3>
 
       <sect3>
@@ -756,7 +750,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       </sect3>
     </sect2>
 
-    <sect2 id="xml-primer-fpi-alternatives">
+    <sect2 xml:id="xml-primer-fpi-alternatives">
       <title>Alternatives to <acronym>FPI</acronym>s</title>
 
       <para>Instead of using an <acronym>FPI</acronym> to indicate the
@@ -767,7 +761,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 
       <para>The syntax is slightly different:</para>
 
-      <programlisting><sgmltag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</sgmltag></programlisting>
+      <programlisting><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting>
 
       <para>The <literal>SYSTEM</literal> keyword indicates that the
 	<acronym>XML</acronym> processor should locate the
@@ -782,7 +776,7 @@ example.xml:5: element head: validity error : Element head content does not foll
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-xml-escape">
+  <sect1 xml:id="xml-primer-xml-escape">
     <title>Escaping Back to <acronym>XML</acronym></title>
 
     <para>Some of the underlying <acronym>XML</acronym> syntax can be
@@ -802,7 +796,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 
   </sect1>
 
-  <sect1 id="xml-primer-comments">
+  <sect1 xml:id="xml-primer-comments">
     <title>Comments</title>
 
     <para>Comments are an <acronym>XML</acronym> construct, and are
@@ -877,7 +871,7 @@ example.xml:5: element head: validity error : Element head content does not foll
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-entities">
+  <sect1 xml:id="xml-primer-entities">
     <title>Entities</title>
 
     <para>Entities are a mechanism for assigning names to chunks of
@@ -894,7 +888,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       situations: <emphasis>general entities</emphasis> and
       <emphasis>parameter entities</emphasis>.</para>
 
-    <sect2 id="xml-primer-general-entities">
+    <sect2 xml:id="xml-primer-general-entities">
       <title>General Entities</title>
 
       <para>General entities are used to assign names to reusable
@@ -904,14 +898,14 @@ example.xml:5: element head: validity error : Element head content does not foll
 
       <para>To include the text of a general entity in the document,
 	include
-	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>
+	<literal>&amp;entity-name;</literal>
 	in the text.  For example, consider a general entity called
 	<literal>current.version</literal> which expands to the
 	current version number of a product.  To use it in the
 	document, write:</para>
 
-      <programlisting><sgmltag class="starttag">para</sgmltag>The current version of our product is
-  &amp;current.version;.<sgmltag class="endtag">para</sgmltag></programlisting>
+      <programlisting><tag class="starttag">para</tag>The current version of our product is
+  &amp;current.version;.<tag class="endtag">para</tag></programlisting>
 
       <para>When the version number changes, edit the definition of
 	the general entity, replacing the value.  Then reprocess the
@@ -955,7 +949,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       </example>
     </sect2>
 
-    <sect2 id="xml-primer-parameter-entities">
+    <sect2 xml:id="xml-primer-parameter-entities">
       <title>Parameter Entities</title>
 
       <para>Parameter entities, like
@@ -968,7 +962,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       <para>Parameter entity definitons are similar to those for
 	general entities.  However, parameter entries are included
 	with
-	<literal>%<replaceable>entity-name</replaceable>;</literal>.
+	<literal>%entity-name;</literal>.
 	The definition also includes the <literal>%</literal> between
 	the <literal>ENTITY</literal> keyword and the name of the
 	entity.</para>
@@ -1004,23 +998,23 @@ example.xml:5: element head: validity error : Element head content does not foll
 &lt;!ENTITY version "1.1"&gt;
 ]&gt;
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
-  <sgmltag class="starttag">head</sgmltag>
-    <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
-  <sgmltag class="endtag">head</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
+  <tag class="starttag">head</tag>
+    <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
+  <tag class="endtag">head</tag>
 
   &lt;!-- There may be some comments in here as well --&gt;
 
-  <sgmltag class="starttag">body</sgmltag>
-    <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag>
+  <tag class="starttag">body</tag>
+    <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag>
+    <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag>
+    <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">p</sgmltag>The current version of this document is: &amp;version;<sgmltag class="endtag">p</sgmltag>
-  <sgmltag class="endtag">body</sgmltag>
-<sgmltag class="endtag">html</sgmltag></programlisting>
+    <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
+  <tag class="endtag">body</tag>
+<tag class="endtag">html</tag></programlisting>
 	</step>
 
 	<step>
@@ -1068,7 +1062,7 @@ example.xml:5: element head: validity error : Element head content does not foll
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-include">
+  <sect1 xml:id="xml-primer-include">
     <title>Using Entities to Include Files</title>
 
     <para>Both
@@ -1077,7 +1071,7 @@ example.xml:5: element head: validity error : Element head content does not foll
       entities are particularly useful for including one file inside
       another.</para>
 
-    <sect2 id="xml-primer-include-using-gen-entities">
+    <sect2 xml:id="xml-primer-include-using-gen-entities">
       <title>Using General Entities to Include Files</title>
 
       <para>Consider some content for an <acronym>XML</acronym> book
@@ -1104,13 +1098,13 @@ example.xml:5: element head: validity error : Element head content does not foll
 &lt;!-- And so forth --&gt;
 ]&gt;
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
   &lt;!-- Use the entities to load in the chapters --&gt;
 
   &amp;chapter.1;
   &amp;chapter.2;
   &amp;chapter.3;
-<sgmltag class="endtag">html</sgmltag></programlisting>
+<tag class="endtag">html</tag></programlisting>
       </example>
 
       <warning>
@@ -1170,11 +1164,11 @@ example.xml:5: element head: validity error : Element head content does not foll
 %chapters;
 ]&gt;
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
   &amp;chapter.1;
   &amp;chapter.2;
   &amp;chapter.3;
-<sgmltag class="endtag">html</sgmltag></programlisting>
+<tag class="endtag">html</tag></programlisting>
       </example>
     </sect2>
 
@@ -1192,7 +1186,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 
 	    <para>Put content like this in each file:</para>
 
-	    <programlisting><sgmltag class="starttag">p</sgmltag>This is the first paragraph.<sgmltag class="endtag">p</sgmltag></programlisting>
+	    <programlisting><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting>
 	  </step>
 
 	  <step>
@@ -1207,19 +1201,19 @@ example.xml:5: element head: validity error : Element head content does not foll
 &lt;!ENTITY para3 SYSTEM "para3.xml"&gt;
 ]&gt;
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
-  <sgmltag class="starttag">head</sgmltag>
-    <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
-  <sgmltag class="endtag">head</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
+  <tag class="starttag">head</tag>
+    <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
+  <tag class="endtag">head</tag>
 
-  <sgmltag class="starttag">body</sgmltag>
-    <sgmltag class="starttag">p</sgmltag>The current version of this document is: &amp;version;<sgmltag class="endtag">p</sgmltag>
+  <tag class="starttag">body</tag>
+    <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
 
     &amp;para1;
     &amp;para2;
     &amp;para3;
-  <sgmltag class="endtag">body</sgmltag>
-<sgmltag class="endtag">html</sgmltag></programlisting>
+  <tag class="endtag">body</tag>
+<tag class="endtag">html</tag></programlisting>
 	  </step>
 
 	  <step>
@@ -1232,7 +1226,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <step>
 	    <para>Load <filename>example.html</filename> into the web
 	      browser and confirm that the
-	      <filename>para<replaceable>n</replaceable>.xml</filename>
+	      <filename>paran.xml</filename>
 	      files have been included in
 	      <filename>example.html</filename>.</para>
 	  </step>
@@ -1257,19 +1251,19 @@ example.xml:5: element head: validity error : Element head content does not foll
 &lt;!ENTITY % entities SYSTEM "entities.ent"&gt; %entities;
 ]&gt;
 
-<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
-  <sgmltag class="starttag">head</sgmltag>
-    <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
-  <sgmltag class="endtag">head</sgmltag>
+<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
+  <tag class="starttag">head</tag>
+    <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag>
+  <tag class="endtag">head</tag>
 
-  <sgmltag class="starttag">body</sgmltag>
-    <sgmltag class="starttag">p</sgmltag>The current version of this document is: &amp;version;<sgmltag class="endtag">p</sgmltag>
+  <tag class="starttag">body</tag>
+    <tag class="starttag">p</tag>The current version of this document is: &amp;version;<tag class="endtag">p</tag>
 
     &amp;para1;
     &amp;para2;
     &amp;para3;
-  <sgmltag class="endtag">body</sgmltag>
-<sgmltag class="endtag">html</sgmltag></programlisting>
+  <tag class="endtag">body</tag>
+<tag class="endtag">html</tag></programlisting>
 	  </step>
 
 	  <step>
@@ -1293,7 +1287,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <step>
 	    <para>Load <filename>example.html</filename> into the web
 	      browser and confirm that the
-	      <filename>para<replaceable>n</replaceable>.xml</filename>
+	      <filename>paran.xml</filename>
 	      files have been included in
 	      <filename>example.html</filename>.</para>
 	  </step>
@@ -1302,7 +1296,7 @@ example.xml:5: element head: validity error : Element head content does not foll
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-marked-sections">
+  <sect1 xml:id="xml-primer-marked-sections">
     <title>Marked Sections</title>
 
     <para><acronym>XML</acronym> provides a mechanism to indicate that
@@ -1334,10 +1328,10 @@ example.xml:5: element head: validity error : Element head content does not foll
       <acronym>XML</acronym> context with
       <literal>&gt;</literal>.</para>
 
-    <sect2 id="xml-primer-marked-section-keywords">
+    <sect2 xml:id="xml-primer-marked-section-keywords">
       <title>Marked Section Keywords</title>
 
-      <sect3 id="xml-primer-cdata">
+      <sect3 xml:id="xml-primer-cdata">
 	<title><literal>CDATA</literal></title>
 
 	<para>These keywords denote the marked sections
@@ -1376,29 +1370,29 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <title>Using a <literal>CDATA</literal> Marked
 	    Section</title>
 
-	  <programlisting><sgmltag class="starttag">para</sgmltag>Here is an example of how to include some text that contains
-  many <sgmltag class="starttag">literal</sgmltag>&amp;lt;<sgmltag class="endtag">literal</sgmltag> and <sgmltag class="starttag">literal</sgmltag>&amp;amp;<sgmltag class="endtag">literal</sgmltag>
+	  <programlisting><tag class="starttag">para</tag>Here is an example of how to include some text that contains
+  many <tag class="starttag">literal</tag>&amp;lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;amp;<tag class="endtag">literal</tag>
   symbols.  The sample text is a fragment of
-  <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>.  The surrounding text (<sgmltag class="starttag">para</sgmltag> and
-  <sgmltag class="starttag">programlisting</sgmltag>) are from DocBook.<sgmltag class="endtag">para</sgmltag>
+  <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>.  The surrounding text (<tag class="starttag">para</tag> and
+  <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag>
 
-<sgmltag class="starttag">programlisting</sgmltag>&lt;![CDATA[<sgmltag class="starttag">p</sgmltag>This is a sample that shows some of the
-  elements within <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>.  Since the angle
+<tag class="starttag">programlisting</tag>&lt;![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the
+  elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>.  Since the angle
   brackets are used so many times, it is simpler to say the whole
   example is a CDATA marked section than to use the entity names for
-  the left and right angle brackets throughout.<sgmltag class="endtag">p</sgmltag>
+  the left and right angle brackets throughout.<tag class="endtag">p</tag>
 
-    <sgmltag class="starttag">ul</sgmltag>
-      <sgmltag class="starttag">li</sgmltag>This is a listitem<sgmltag class="endtag">li</sgmltag>
-      <sgmltag class="starttag">li</sgmltag>This is a second listitem<sgmltag class="endtag">li</sgmltag>
-      <sgmltag class="starttag">li</sgmltag>This is a third listitem<sgmltag class="endtag">li</sgmltag>
-    <sgmltag class="endtag">ul</sgmltag>
+    <tag class="starttag">ul</tag>
+      <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag>
+      <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag>
+      <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag>
+    <tag class="endtag">ul</tag>
 
-    <sgmltag class="starttag">p</sgmltag>This is the end of the example.<sgmltag class="endtag">p</sgmltag>]]&gt;<sgmltag class="endtag">programlisting</sgmltag></programlisting>
+    <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]&gt;<tag class="endtag">programlisting</tag></programlisting>
 	</example>
       </sect3>
 
-      <sect3 id="xml-primer-include-ignore">
+      <sect3 xml:id="xml-primer-include-ignore">
 	<title><literal>INCLUDE</literal> and
 	  <literal>IGNORE</literal></title>
 
@@ -1455,7 +1449,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	  <title>Using a Parameter Entity to Control a Marked
 	    Section</title>
 
-	  <programlisting>&lt;!ENTITY % electronic.copy "INCLUDE">
+	  <programlisting>&lt;!ENTITY % electronic.copy "INCLUDE"&gt;
 
 &lt;![%electronic.copy;[
 &lt;!ENTITY chap.preface	SYSTEM "preface.xml"&gt;
@@ -1507,7 +1501,7 @@ example.xml:5: element head: validity error : Element head content does not foll
     </sect2>
   </sect1>
 
-  <sect1 id="xml-primer-conclusion">
+  <sect1 xml:id="xml-primer-conclusion">
     <title>Conclusion</title>
 
     <para>That is the conclusion of this <acronym>XML</acronym>