- Partly update the fdp-primer for the new, XML-based documentation

Approved by:	doceng (implicit)

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

@@ -46,7 +46,7 @@
     <listitem>
       <para>Know what you need to build the FDP documentation, in
 	addition to those mentioned in the
-	<link linkend="tools">SGML tools chapter</link>.</para>
+	<link linkend="tools">XML tools chapter</link>.</para>
     </listitem>
 
     <listitem>

en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml

@@ -34,7 +34,7 @@
 <appendix id="examples">
   <title>Examples</title>
 
-  <para>This appendix contains example SGML files and command lines
+  <para>This appendix contains example XML files and command lines
     you can use to convert them from one output format to another.  If
     you have successfully installed the Documentation Project tools
     then you should be able to use these examples directly.</para>
@@ -42,7 +42,7 @@
   <para>These examples are not exhaustive&mdash;they do not contain
     all the elements you might want to use, particularly in your
     document's front matter.  For more examples of DocBook markup you
-    should examine the SGML source for this and other documents,
+    should examine the XML source for this and other documents,
     available in the <application>svn</application>
     <literal>doc</literal> repository, or available online starting at
     <ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para>
@@ -60,7 +60,8 @@
     <example>
       <title>DocBook <sgmltag>book</sgmltag></title>
 
-      <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+      <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <book lang='en'>
   <bookinfo>
@@ -112,7 +113,8 @@
     <example>
       <title>DocBook <sgmltag>article</sgmltag></title>
 
-      <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+      <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <article lang='en'>
   <articleinfo>
@@ -269,7 +271,7 @@
       <example id="examples-docbook-postscript">
 	<title>Converting DocBook to Postscript</title>
 
-	<para>The source SGML file must be converted to a &tex;
+	<para>The source XML file must be converted to a &tex;
 	  file.</para>
 
 	<screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/>

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

@@ -63,7 +63,7 @@
     </listitem>
 
     <listitem>
-      <para>Be able to read and understand the SGML source code for
+      <para>Be able to read and understand the XML source code for
 	the documentation maintained by the FDP.</para>
     </listitem>
 

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

@@ -35,7 +35,7 @@
   <title>See Also</title>
 
   <para>This document is deliberately not an exhaustive discussion of
-    SGML, the DTDs listed, and the FreeBSD Documentation Project.  For
+    XML, the DTDs listed, and the FreeBSD Documentation Project.  For
     more information about these, you are encouraged to see the
     following web sites.</para>
 
@@ -55,20 +55,13 @@
     </itemizedlist>
   </sect1>
 
-  <sect1 id="see-also-sgml">
+  <sect1 id="see-also-xml">
-    <title>SGML</title>
+    <title>XML</title>
 
     <itemizedlist>
       <listitem>
-	<para><ulink url="http://www.oasis-open.org/cover/">The
+	<para><ulink url="http://www.w3.org/XML/">W3C's XML page
-	    SGML/XML web page</ulink>, a comprehensive SGML
+	    SGML/XML web page</ulink></para>
-	  resource</para>
-      </listitem>
-
-      <listitem>
-	<para><ulink
-	    url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle
-	    introduction to SGML</ulink></para>
       </listitem>
     </itemizedlist>
   </sect1>

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

@@ -31,8 +31,8 @@
      $FreeBSD$
 -->
 
-<chapter id="sgml-markup">
+<chapter id="xml-markup">
-  <title>SGML Markup</title>
+  <title>XML Markup</title>
 
   <para>This chapter describes the two markup languages you will
     encounter when you contribute to the FreeBSD documentation
@@ -63,46 +63,49 @@
       line break (and other processing) when it is encountered.</para>
   </note>
 
-  <sect1 id="sgml-markup-html">
+  <sect1 id="xml-markup-xhtml">
-    <title>HTML</title>
+    <title>XHTML</title>
 
-    <para>HTML, the HyperText Markup Language, is the markup language
+    <para>XHTML is the XML version of the HyperText Markup Language,
+      which is the markup language
       of choice on the World Wide Web.  More information can be found
       at <ulink url="http://www.w3.org/"></ulink>.</para>
 
-    <para>HTML is used to markup pages on the FreeBSD web site.  It
+    <para>XHTML is used to markup pages on the FreeBSD web site.  It
       should not (generally) be used to mark up other documentation,
       since DocBook offers a far richer set of elements to choose
-      from.  Consequently, you will normally only encounter HTML pages
+      from.  Consequently, you will normally only encounter XHTML pages
       if you are writing for the web site.</para>
 
     <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
-      and the latest, 4.0 (available in both
+      4.0 and then an XML-compliant version has also been created, which
-      <emphasis>strict</emphasis> and <emphasis>loose</emphasis>
+      is called XHTML and the latest widespread version of it is
+      XHTML 1.0(available in both
+      <emphasis>strict</emphasis> and <emphasis>transitional</emphasis>
       variants).</para>
 
-    <para>The HTML DTDs are available from the Ports&nbsp;Collection
+    <para>The XHTML DTDs are available from the Ports&nbsp;Collection
-      in the <filename role="package">textproc/html</filename> port.
+      in the <filename role="package">textproc/xhtml</filename> port.
       They are automatically installed as part of the <filename
 	role="package">textproc/docproj</filename> port.</para>
 
     <sect2>
       <title>Formal Public Identifier (FPI)</title>
 
-      <para>There are a number of HTML FPIs, depending upon the
+      <para>There are a number of XHTML FPIs, depending upon the
-	version (also known as the level) of HTML that you want to
+	version (also known as the level) of XHTML that you want to
 	declare your document to be compliant with.</para>
 
-      <para>The majority of HTML documents on the FreeBSD web site
+      <para>The majority of XHTML documents on the FreeBSD web site
-	comply with the loose version of HTML 4.0.</para>
+	comply with the transitional version of XHTML 1.0.</para>
 
-      <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
+      <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
     </sect2>
 
     <sect2>
       <title>Sectional Elements</title>
 
-      <para>An HTML document is normally split into two sections.  The
+      <para>An XHTML document is normally split into two sections.  The
 	first section, called the <emphasis>head</emphasis>, contains
 	meta-information about the document, such as its title, the
 	name of the author, the parent document, and so on.  The
@@ -115,9 +118,9 @@
 	<sgmltag>html</sgmltag> element.</para>
 
       <example>
-	<title>Normal HTML Document Structure</title>
+	<title>Normal XHTML Document Structure</title>
 
-	<programlisting>&lt;html>
+	<programlisting>&lt;html xmlns="http://www.w3.org/1999/xhtml">
   &lt;head>
 	  &lt;title><replaceable>The Document's Title</replaceable>&lt;/title>
   &lt;/head>
@@ -137,7 +140,7 @@
       <sect3>
 	<title>Headings</title>
 
-	<para>HTML allows you to denote headings in your document, at
+	<para>XHTML allows you to denote headings in your document, at
 	  up to six different levels.</para>
 
 	<para>The largest and most prominent heading is
@@ -169,7 +172,7 @@
 <!-- Content for the second section goes here -->]]></programlisting>
 	</example>
 
-	<para>Generally, an HTML page should have one first level
+	<para>Generally, an HXTML page should have one first level
 	  heading (<sgmltag>h1</sgmltag>).  This can contain many
 	  second level headings (<sgmltag>h2</sgmltag>), which can in
 	  turn contain many third level headings.  Each
@@ -198,7 +201,7 @@
       <sect3>
 	<title>Paragraphs</title>
 
-	<para>HTML supports a single paragraph element,
+	<para>XHTML supports a single paragraph element,
 	  <sgmltag>p</sgmltag>.</para>
 
 	<example>
@@ -493,7 +496,7 @@
       <sect3>
 	<title>Emphasizing Information</title>
 
-	<para>You have two levels of emphasis available in HTML,
+	<para>You have two levels of emphasis available in XHTML,
 	  <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
 	  <sgmltag>em</sgmltag> is for a normal level of emphasis and
 	  <sgmltag>strong</sgmltag> indicates stronger
@@ -502,7 +505,10 @@
 	<para>Typically, <sgmltag>em</sgmltag> is rendered in italic
 	  and <sgmltag>strong</sgmltag> is rendered in bold.  This is
 	  not always the case, however, and you should not rely on
-	  it.</para>
+	  it.  According to best practices, webpages only hold
+	  structural and semantical information and stylesheets are
+	  later applied to use these two so you should think of
+	  semantics not formatting when using these tags.</para>
 
 	<example>
 	  <title><sgmltag>em</sgmltag> and
@@ -515,22 +521,6 @@
 	</example>
       </sect3>
 
-      <sect3>
-	<title>Bold and Italics</title>
-
-	<para>Because HTML includes presentational markup, you can
-	  also indicate that particular content should be rendered in
-	  bold or italic.  The elements are <sgmltag>b</sgmltag> and
-	  <sgmltag>i</sgmltag> respectively.</para>
-
-	<example>
-	  <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
-
-	  <programlisting><![CDATA[<p><b>This</b> is in bold, while <i>this</i> is
-  in italics.</p>]]></programlisting>
-	</example>
-      </sect3>
-
       <sect3>
 	<title>Indicating Fixed-Pitch Text</title>
 
@@ -548,65 +538,13 @@
   <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
 	</example>
       </sect3>
-
-      <sect3>
-	<title>Content Size</title>
-
-	<para>You can indicate that content should be shown in a
-	  larger or smaller font.  There are three ways of doing
-	  this.</para>
-
-	<orderedlist>
-	  <listitem>
-	    <para>Use <sgmltag>big</sgmltag> and
-	      <sgmltag>small</sgmltag> around the content you wish to
-	      change size.  These tags can be nested, so
-	      <literal>&lt;big&gt;&lt;big&gt;This is much
-		bigger&lt;/big&gt;&lt;/big&gt;</literal> is
-	      possible.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Use <sgmltag>font</sgmltag> with the
-	      <literal>size</literal> attribute set to
-	      <literal>+1</literal> or <literal>-1</literal>
-	      respectively.  This has the same effect as using
-	      <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>.
-	      However, the use of this approach is deprecated.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Use <sgmltag>font</sgmltag> with the
-	      <literal>size</literal> 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>
-
-	<example>
-	  <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
-	    <sgmltag>font</sgmltag></title>
-
-	  <para>The following fragments all do the same thing.</para>
-
-	  <programlisting><![CDATA[<p>This text is <small>slightly smaller</small>.  But
-  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>
-
-<p>This text is <font size="2">slightly smaller</font>.  But
-  this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
-	</example>
-      </sect3>
     </sect2>
 
     <sect2>
       <title>Links</title>
 
       <note>
-	<para>Links are also in-line elements.</para>
+	<para>Links are also inline elements.</para>
       </note>
 
       <sect3>
@@ -644,20 +582,20 @@
 	  anchors that you can link to.</para>
 
 	<para>Anchors are indicated with <sgmltag>a</sgmltag> and the
-	  <literal>name</literal> attribute instead of
+	  <literal>id</literal> attribute instead of
 	  <literal>href</literal>.</para>
 
 	<example>
-	  <title>Using <literal>&lt;a name="..."&gt;</literal></title>
+	  <title>Using <literal>&lt;a id="..."&gt;</literal></title>
 
 	  <para>Use:</para>
 
-	  <programlisting><![CDATA[<p><a name="para1">This</a> paragraph can be referenced
+	  <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced
   in other links with the name <tt>para1</tt>.</p>]]></programlisting>
 	</example>
 
 	<para>To link to a named part of a document, write a normal
-	  link to that document, but include the name of the anchor
+	  link to that document, but include the id of the anchor
 	  after a <literal>#</literal> symbol.</para>
 
 	<example>
@@ -691,7 +629,7 @@
     </sect2>
   </sect1>
 
-  <sect1 id="sgml-markup-docbook">
+  <sect1 id="xml-markup-docbook">
     <title>DocBook</title>
 
     <para>DocBook was originally developed by HaL Computer Systems and
@@ -703,7 +641,7 @@
       Since 1998 it is maintained by the <ulink
 	url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
 	DocBook Technical Committee</ulink>.  As such, and unlike
-      LinuxDoc and HTML, DocBook is very heavily oriented towards
+      LinuxDoc and XHTML, DocBook is very heavily oriented towards
       markup that describes <emphasis>what</emphasis> something is,
       rather than describing <emphasis>how</emphasis> it should be
       presented.</para>
@@ -760,7 +698,7 @@
 	for DocBook customizations, the FPI for the FreeBSD extended
 	DocBook DTD is:</para>
 
-	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
+	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
     </sect2>
 
     <sect2>
@@ -1804,7 +1742,7 @@ This is the file called 'foo2'</screen>
 	  manual page section.</para>
 
 	<para>This can be cumbersome to write, and so a series of
-	  <link linkend="sgml-primer-general-entities">general
+	  <link linkend="xml-primer-general-entities">general
 	    entities</link> have been created to make this easier.
 	  Each entity takes the form
 	  <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
@@ -2568,7 +2506,7 @@ IMAGES+= fig3.png
 
 	<para>You must be careful when you separate your documentation
 	  into smaller files (see
-	  <xref linkend="sgml-primer-include-using-gen-entities"/>) in
+	  <xref linkend="xml-primer-include-using-gen-entities"/>) in
 	  different directories.</para>
 
 	<para>Suppose you have a book with three chapters, and the

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

@@ -83,7 +83,7 @@
 	  subdirectories to further categorize the information.  For
 	  example, the files that comprise the &man.make.1;
 	  infrastructure are in <filename>share/mk</filename>, while
-	  the additional SGML support files (such as the FreeBSD
+	  the additional XML support files (such as the FreeBSD
 	  extended DocBook DTD) are in
 	  <filename>share/sgml</filename>.</seg>
       </seglistitem>
@@ -124,7 +124,7 @@
 	<seg>Documentation marked up as a DocBook
 	  <sgmltag>article</sgmltag> (or equivalent).  Reasonably
 	  short, and broken up into sections.  Normally only available
-	  as one HTML file.</seg>
+	  as one XHTML file.</seg>
       </seglistitem>
 
       <seglistitem>
@@ -133,7 +133,7 @@
 	<seg>Documentation marked up as a DocBook
 	  <sgmltag>book</sgmltag> (or equivalent).  Book length, and
 	  broken up into chapters.  Normally available as both one
-	  large HTML file (for people with fast connections, or who
+	  large XHTML file (for people with fast connections, or who
 	  want to print it easily from a browser) and as a collection
 	  of linked, smaller files.</seg>
       </seglistitem>
@@ -195,7 +195,7 @@
 	  <title><filename>Makefile</filename></title>
 
 	  <para>The <filename>Makefile</filename> defines some
-	    variables that affect how the SGML source is converted to
+	    variables that affect how the XML source is converted to
 	    other formats, and lists the various source files that
 	    make up the Handbook.  It then includes the standard
 	    <filename>doc.project.mk</filename> file, to bring in the
@@ -208,16 +208,16 @@
 
 	  <para>This is the top level document in the Handbook.  It
 	    contains the Handbook's <link
-	      linkend="sgml-primer-doctype-declaration">DOCTYPE
+	      linkend="xml-primer-doctype-declaration">DOCTYPE
 	      declaration</link>, as well as the elements that
 	    describe the Handbook's structure.</para>
 
 	  <para><filename>book.sgml</filename> uses <link
-	      linkend="sgml-primer-parameter-entities">parameter
+	      linkend="xml-primer-parameter-entities">parameter
 	      entities</link> to load in the files with the
 	    <filename>.ent</filename> extension.  These files
 	    (described later) then define <link
-	      linkend="sgml-primer-general-entities">general
+	      linkend="xml-primer-general-entities">general
 	      entities</link> that are used throughout the rest of the
 	    Handbook.</para>
 	</sect4>
@@ -246,7 +246,7 @@
 	    the entire contents of the chapter will be held in this
 	    file.</para>
 
-	  <para>When the HTML version of the Handbook is produced,
+	  <para>When the XHTML version of the Handbook is produced,
 	    this will yield <filename>kernelconfig.html</filename>.
 	    This is because of the <literal>id</literal> value, and is
 	    not related to the name of the directory.</para>
@@ -260,7 +260,7 @@
 	    Handbook chapter are stored within <filename
 	      class="directory">share/images/books/handbook</filename>.
 	    Note that localized version of these images should be
-	    placed in the same directory as the SGML sources for each
+	    placed in the same directory as the XML sources for each
 	    chapter.  Namespace collisions would be inevitable, and it
 	    is easier to work with several directories with a few
 	    files in them than it is to work with one directory that
@@ -283,12 +283,12 @@
 	  </important>
 
 	  <para>Each <filename>chapter.sgml</filename> file will not
-	    be a complete SGML document.  In particular, they will not
+	    be a complete XML document.  In particular, they will not
 	    have their own DOCTYPE lines at the start of the
 	    files.</para>
 
 	  <para>This is unfortunate as it makes it impossible to treat
-	    these as generic SGML files and simply convert them to
+	    these as generic XML files and simply convert them to
 	    HTML, RTF, PS, and other formats in the same way the main
 	    Handbook is generated.  This <emphasis>would</emphasis>
 	    force you to rebuild the Handbook every time you want to

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

@@ -40,7 +40,7 @@
     Panorama, SPICE, JSSS, FOSI, CSS, and DSSSL.</para>
 
   <para>For DocBook, we are using stylesheets written in DSSSL.  For
-    HTML we are using CSS.</para>
+    XHTML we are using CSS.</para>
 
   <sect1 id="stylesheets-dsssl">
     <title>* DSSSL</title>
@@ -69,7 +69,7 @@
 
     <para>Cascading Stylesheets (CSS) are a mechanism for attaching
       style information (font, weight, size, color, and so forth) to
-      elements in an HTML document without abusing HTML to do
+      elements in an XHTML document without abusing XHTML to do
       so.</para>
 
     <sect2>
@@ -77,10 +77,10 @@
 
       <para>The FreeBSD DSSSL stylesheets include a reference to a
 	stylesheet, <filename>docbook.css</filename>, which is
-	expected to appear in the same directory as the HTML files.
+	expected to appear in the same directory as the XHTML files.
 	The project-wide CSS file is copied from
 	<filename>doc/share/misc/docbook.css</filename> when documents
-	are converted to HTML, and is installed automatically.</para>
+	are converted to XHTML, and is installed automatically.</para>
     </sect2>
   </sect1>
 </chapter>

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

@@ -39,7 +39,7 @@
 
     <para>Use a disk with sufficient free space.  You may need
       anything from 200&nbsp;MB to over 500&nbsp;MB, depending on the
-      method you choose.  This space will hold the SGML tools, a
+      method you choose.  This space will hold the XML tools, a
       subset of the <application>svn</application> tree, temporary
       build space and the installed web pages.</para>
 

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

@@ -81,7 +81,7 @@
       These slave ports define the <makevar>JADETEX</makevar> variable
       for you, therefore they will install the same suite of
       applications on your machine.  Note that you can produce only
-      HTML or ASCII text output if you do not install
+      XHTML or ASCII text output if you do not install
       <application>JadeTeX</application>.  PostScript or PDF output
       requires &tex;.</para>
   </tip>
@@ -94,7 +94,7 @@
 
       <para>These programs are required before you can usefully work
 	with the FreeBSD documentation, and they will allow you to
-	convert the documentation to HTML, plain text, and RTF
+	convert the documentation to XHTML, plain text, and RTF
 	formats.  They are all included in <filename
 	  role="package">textproc/docproj</filename>.</para>
 
@@ -115,8 +115,8 @@
 	    (<filename role="package">www/tidy</filename>)</term>
 
 	  <listitem>
-	    <para>An HTML <quote>pretty printer</quote>, used to
+	    <para>An (X)HTML <quote>pretty printer</quote>, used to
-	      reformat some of the automatically generated HTML so
+	      reformat some of the automatically generated pages so
 	      that it is easier to follow.</para>
 	  </listitem>
 	</varlistentry>
@@ -127,7 +127,7 @@
 
 	  <listitem>
 	    <para>A text-mode WWW browser that can also convert
-	      HTML files to plain text.</para>
+	      XHTML files to plain text.</para>
 	  </listitem>
 	</varlistentry>
 
@@ -154,11 +154,11 @@
 
       <variablelist>
 	<varlistentry>
-	  <term>HTML DTD (<filename
+	  <term>XHTML DTD (<filename
-	      role="package">textproc/html</filename>)</term>
+	      role="package">textproc/xhtml</filename>)</term>
 
 	  <listitem>
-	    <para>HTML is the markup language of choice for the World
+	    <para>XHTML is the markup language of choice for the World
 	      Wide Web, and is used throughout the FreeBSD web
 	      site.</para>
 	  </listitem>
@@ -282,7 +282,7 @@
       </variablelist>
 
       <para>If anyone has recommendations for other software that is
-	useful when manipulating SGML documents, please let &a.doceng;
+	useful when manipulating XML documents, please let &a.doceng;
 	know, so they can be added to this list.</para>
     </sect2>
   </sect1>