aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabor Kovesdan <gabor@FreeBSD.org>2012-09-14 08:32:33 +0000
committerGabor Kovesdan <gabor@FreeBSD.org>2012-09-14 08:32:33 +0000
commit6d02b0b3de63bb5db460d7fab32f043a4c98f675 (patch)
treed020be31de5a1e10d9f3d4db3719350b637b1dc5
parentd0231cb6febe4f846f2509e86a05dff6991fa461 (diff)
downloaddoc-6d02b0b3de63bb5db460d7fab32f043a4c98f675.tar.gz
doc-6d02b0b3de63bb5db460d7fab32f043a4c98f675.zip
- Partly update the fdp-primer for the new, XML-based documentation
Approved by: doceng (implicit)
Notes
Notes: svn path=/projects/sgml2xml/; revision=39528
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml2
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml12
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml2
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml17
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml142
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml749
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml22
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml8
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml2
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml18
10 files changed, 401 insertions, 573 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
index 097f3af6a6..bb03eb46df 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
+++ b/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>
diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
index eaa899d2ae..82c3ff7fb7 100644
--- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
+++ b/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"/>
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
index 931dba3ff1..ad64e28d31 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
+++ b/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>
diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
index 884613e0f1..ea6d299b49 100644
--- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
+++ b/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">
- <title>SGML</title>
+ <sect1 id="see-also-xml">
+ <title>XML</title>
<itemizedlist>
<listitem>
- <para><ulink url="http://www.oasis-open.org/cover/">The
- SGML/XML web page</ulink>, a comprehensive SGML
- resource</para>
- </listitem>
-
- <listitem>
- <para><ulink
- url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle
- introduction to SGML</ulink></para>
+ <para><ulink url="http://www.w3.org/XML/">W3C's XML page
+ SGML/XML web page</ulink></para>
</listitem>
</itemizedlist>
</sect1>
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 8f00e11b6b..14070de750 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -31,8 +31,8 @@
$FreeBSD$
-->
-<chapter id="sgml-markup">
- <title>SGML Markup</title>
+<chapter id="xml-markup">
+ <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">
- <title>HTML</title>
+ <sect1 id="xml-markup-xhtml">
+ <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
- <emphasis>strict</emphasis> and <emphasis>loose</emphasis>
+ 4.0 and then an XML-compliant version has also been created, which
+ 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
- in the <filename role="package">textproc/html</filename> port.
+ <para>The XHTML DTDs are available from the Ports&nbsp;Collection
+ 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
- version (also known as the level) of HTML that you want to
+ <para>There are a number of XHTML FPIs, depending upon the
+ 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
- comply with the loose version of HTML 4.0.</para>
+ <para>The majority of XHTML documents on the FreeBSD web site
+ 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
@@ -516,22 +522,6 @@
</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>
<para>If you have content that should be rendered in a fixed
@@ -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
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
index 933f9ed2a2..3f8473be14 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -31,20 +31,20 @@
$FreeBSD$
-->
-<chapter id="sgml-primer">
- <title>SGML Primer</title>
+<chapter id="xml-primer">
+ <title>XML Primer</title>
<para>The majority of FDP documentation is written in applications
- of SGML. This chapter explains exactly what that means, how to
+ of XML. This chapter explains exactly what that means, how to
read and understand the source to the documentation, and the sort
- of SGML tricks you will see used in the documentation.</para>
+ of XML tricks you will see used in the documentation.</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>
- <sect1 id="sgml-primer-overview">
+ <sect1 id="xml-primer-overview">
<title>Overview</title>
<para>Way back when, electronic text was simple to deal with.
@@ -127,26 +127,28 @@
is a first language that you use to write these other markup
languages. A <emphasis>meta markup language</emphasis>.</para>
- <para>This is exactly what the Standard Generalized Markup
- Language (SGML) is. Many markup languages have been written in
- SGML, including the two most used by the FDP, HTML and
+ <para>This is exactly what the eXtensible Markup
+ Language (XML) is. Many markup languages have been written in
+ XML, including the two most used by the FDP, XHTML and
DocBook.</para>
- <para>Each language definition is more properly called a Document
- Type Definition (DTD). The DTD specifies the name of the
- elements that can be used, what order they appear in (and
+ <para>Each language definition is more properly called a grammar,
+ vocabulary, schema or Document Type Definition (DTD). There
+ are various languages to specify an XML grammar, for example,
+ DTD (yes, it also means the specification language itself),
+ XML Schema (XSD) or RELANG NG. The schema specifies the name
+ of the elements that can be used, what order they appear in (and
whether some markup can be used inside other markup) and related
- information. A DTD is sometimes referred to as an
- <emphasis>application</emphasis> of SGML.</para>
+ information.</para>
- <para id="sgml-primer-validating">A DTD is a
+ <para 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
- forth. This makes it possible to write an SGML
- <emphasis>parser</emphasis> which reads in both the DTD and a
- document which claims to conform to the DTD. The parser can
- then confirm whether or not all the elements required by the DTD
+ forth. This makes it possible to write an XML
+ <emphasis>parser</emphasis> which reads in both the schema and a
+ document which claims to conform to the schema. The parser can
+ then confirm whether or not all the elements required by the vocabulary
are in the document in the right order, and whether there are
any errors in the markup. This is normally referred to as
<quote>validating the document</quote>.</para>
@@ -154,27 +156,27 @@
<note>
<para>This processing simply confirms that the choice of
elements, their ordering, and so on, conforms to that listed
- in the DTD. It does <emphasis>not</emphasis> check that you
+ in the grammar. It does <emphasis>not</emphasis> check that you
have used <emphasis>appropriate</emphasis> markup for the
content. If you tried to mark up all the filenames in your
document as function names, the parser would not flag this as
- an error (assuming, of course, that your DTD defines elements
+ an error (assuming, of course, that your schema defines elements
for filenames and functions, and that they are allowed to
appear in the same place).</para>
</note>
<para>It is likely that most of your contributions to the
Documentation Project will consist of content marked up in
- either HTML or DocBook, rather than alterations to the DTDs.
+ either XHTML or DocBook, rather than alterations to the schemas.
For this reason this book will not touch on how to write a
- DTD.</para>
+ vocabulary.</para>
</sect1>
- <sect1 id="sgml-primer-elements">
+ <sect1 id="xml-primer-elements">
<title>Elements, Tags, and Attributes</title>
- <para>All the DTDs written in SGML share certain characteristics.
- This is hardly surprising, as the philosophy behind SGML will
+ <para>All the vocabularies written in XML share certain characteristics.
+ This is hardly surprising, as the philosophy behind XML will
inevitably show through. One of the most obvious manifestations
of this philosophy is that of <emphasis>content</emphasis> and
<emphasis>elements</emphasis>.</para>
@@ -201,20 +203,20 @@
character names, and so on.</para>
<para>Notice how you can make this differentiation between
- different elements of the content without resorting to any SGML
+ different elements of the content without resorting to any XML
terms. It really is surprisingly straightforward. You could do
this with a highlighter pen and a printout of the book, using
different colors to indicate different chunks of content.</para>
<para>Of course, we do not have an electronic highlighter pen, so
we need some other way of indicating which element each piece of
- content belongs to. In languages written in SGML (HTML,
+ content belongs to. In languages written in XML (XHTML,
DocBook, et al) this is done by means of
<emphasis>tags</emphasis>.</para>
<para>A tag is used to identify where a particular element starts,
and where the element ends. <emphasis>The tag is not part of
- the element itself</emphasis>. Because each DTD was normally
+ the element itself</emphasis>. Because each grammar was normally
written to mark up specific types of information, each one will
recognize different elements, and will therefore have different
names for the tags.</para>
@@ -229,10 +231,9 @@
<example>
<title>Using an Element (Start and End Tags)</title>
- <para>HTML has an element for indicating that the content
+ <para>XHTML has an element for indicating that the content
enclosed by the element is a paragraph, called
- <sgmltag>p</sgmltag>. This element has both start and end
- tags.</para>
+ <sgmltag>p</sgmltag>.</para>
<programlisting><![CDATA[<p>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'
@@ -241,22 +242,35 @@
<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting>
</example>
- <para>Not all elements require an end tag. Some elements have no
- content. For example, in HTML you can indicate that you want a
- horizontal line to appear in the document. Obviously, this line
- has no content, so just the start tag is required for this
- element.</para>
+ <para>Some elements have no
+ content. For example, in XHTML you can indicate that you want a
+ horizontal line to appear in the document.</para>
+
+ <para>For such elements, that have no content at all, XML introduced
+ a shorthand form, which is ccompletely equivalent to the above
+ form:</para>
+
+ <programlisting><![CDATA[<hr/>]]></programlisting>
<example>
- <title>Using an Element (Start Tag Only)</title>
+ <title>Using an Element (Without Content)</title>
- <para>HTML has an element for indicating a horizontal rule,
+ <para>XHTML has an element for indicating a horizontal rule,
called <sgmltag>hr</sgmltag>. This element does not wrap
- content, so only has a start tag.</para>
+ content, so it looks like this.</para>
+
+ <programlisting><![CDATA[<p>One paragraph.</p>
+<hr></hr>
- <programlisting><![CDATA[<p>This is a paragraph.</p>
+<p>This is another paragraph. A horizontal rule separates this
+ from the previous paragraph.</p>]]></programlisting>
-<hr>
+ <para>For such elements, that have no content at all, XML introduced
+ a shorthand form, which is ccompletely equivalent to the above
+ form:</para>
+
+ <programlisting><![CDATA[<p>One paragraph.</p>
+<hr/>
<p>This is another paragraph. A horizontal rule separates this
from the previous paragraph.</p>]]></programlisting>
@@ -274,7 +288,7 @@
of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting>
</example>
- <para>The DTD will specify the rules detailing which elements can
+ <para>The grammar will specify the rules detailing which elements can
contain other elements, and exactly what they can
contain.</para>
@@ -288,7 +302,7 @@
element starts and end.</para>
<para>When this document (or anyone else knowledgeable about
- SGML) refers to <quote>the <sgmltag>p</sgmltag> tag</quote>
+ XML) refers 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
@@ -310,11 +324,11 @@
take the form
<literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
- <para>In sufficiently recent versions of HTML, the
+ <para>In XHTML, the
<sgmltag>p</sgmltag> element has an attribute called
<sgmltag>align</sgmltag>, which suggests an alignment
(justification) for the paragraph to the program displaying the
- HTML.</para>
+ XHTML.</para>
<para>The <literal>align</literal> attribute can take one of four
defined values, <literal>left</literal>,
@@ -333,9 +347,7 @@
<para>Some attributes will only take specific values, such as
<literal>left</literal> or <literal>justify</literal>. Others
- will allow you to enter anything you want. If you need to
- include quotes (<literal>"</literal>) within an attribute then
- use single quotes around the attribute value.</para>
+ will allow you to enter anything you want.</para>
<example>
<title>Single Quotes Around Attributes</title>
@@ -343,16 +355,17 @@
<programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting>
</example>
- <para>Sometimes you do not need to use quotes around attribute
- values at all. However, the rules for doing this are subtle,
- and it is far simpler just to <emphasis>always</emphasis> quote
- your attribute values.</para>
+ <para>XML requires you to quote each attribute value with either
+ single or double quotes. It is more habitual to use double quotes
+ but you may use single quotes, as well. Using single quotes is
+ practical if you want to include double quotes in the attribute
+ value.</para>
<para>The information on attributes, elements, and tags is stored
- in SGML catalogs. The various Documentation Project tools use
+ in XML catalogs. The various Documentation Project tools use
these catalog files to validate your work. The tools in
<filename role="package">textproc/docproj</filename> include a
- variety of SGML catalog files. The FreeBSD Documentation
+ variety of XML catalog files. The FreeBSD Documentation
Project includes its own set of catalog files. Your tools need
to know about both sorts of catalog files.</para>
@@ -380,7 +393,7 @@
to substitute the correct directory for your
language.)</para>
- <example id="sgml-primer-envars">
+ <example id="xml-primer-envars">
<title><filename>.profile</filename>, for &man.sh.1; and
&man.bash.1; Users</title>
@@ -415,14 +428,14 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA
<procedure>
<step>
- <para>Create <filename>example.sgml</filename>, and enter
+ <para>Create <filename>example.xml</filename>, and enter
the following text:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>An Example HTML File</title>
+ <title>An Example XHTML File</title>
</head>
<body>
@@ -436,30 +449,20 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA
</step>
<step>
- <para>Try to validate this file using an SGML parser.</para>
+ <para>Try to validate this file using an XML parser.</para>
<para>Part of
<filename role="package">textproc/docproj</filename> is
- the <command>onsgmls</command>
- <link linkend="sgml-primer-validating">validating
- parser</link>. Normally, <command>onsgmls</command>
- reads in a document marked up according to an SGML DTD and
- returns a copy of the document's Element Structure
- Information Set (ESIS, but that is not important right
- now).</para>
-
- <para>However, when <command>onsgmls</command> is given the
- <option>-s</option> parameter, <command>onsgmls</command>
- will suppress its normal output, and just print error
- messages. This makes it a useful way to check to see if
- your document is valid or not.</para>
-
- <para>Use <command>onsgmls</command> to check that your
- document is valid:</para>
-
- <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput></screen>
-
- <para>As you will see, <command>onsgmls</command> returns
+ the <command>xmllint</command>
+ <link linkend="xml-primer-validating">validating
+ parser</link>.</para>
+
+ <para>Use <command>xmllint</command> in the following way to
+ check that your document is valid:</para>
+
+ <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen>
+
+ <para>As you will see, <command>xmllint</command> returns
without displaying any output. This means that your
document validated successfully.</para>
</step>
@@ -470,91 +473,18 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA
<sgmltag>/title</sgmltag> tags, and re-run the
validation.</para>
- <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput>
-onsgmls:example.sgml:5:4:E: character data is not allowed here
-onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
-
- <para>The error output from <command>onsgmls</command> is
- organized into colon-separated groups, or columns.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Column</entry>
- <entry>Meaning</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>1</entry>
- <entry>The name of the program generating the error.
- This will always be
- <literal>onsgmls</literal>.</entry>
- </row>
-
- <row>
- <entry>2</entry>
- <entry>The name of the file that contains the
- error.</entry>
- </row>
-
- <row>
- <entry>3</entry>
- <entry>Line number where the error appears.</entry>
- </row>
-
- <row>
- <entry>4</entry>
- <entry>Column number where the error
- appears.</entry>
- </row>
-
- <row>
- <entry>5</entry>
-
- <entry>A one letter code indicating the nature of
- the message. <literal>I</literal> indicates an
- informational message, <literal>W</literal> is for
- warnings, and <literal>E</literal> is for errors
- <footnote><para>It is not always the fifth column
- either. <command>onsgmls -sv</command>
- displays <literal>onsgmls:I: "OpenSP" version
- "1.5.2"</literal> (depending on the
- installed version). As you can see, this is
- an informational message.</para></footnote>,
- and <literal>X</literal> is for
- cross-references. As you can see, these messages
- are errors.</entry>
- </row>
-
- <row>
- <entry>6</entry>
- <entry>The text of the message.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>Simply omitting the <sgmltag>title</sgmltag> tags has
- generated 2 different errors.</para>
-
- <para>The first error indicates that content (in this case,
- characters, rather than the start tag for an element) has
- occurred where the SGML parser was expecting something
- else. In this case, the parser was expecting to see one
- of the start tags for elements that are valid inside
- <sgmltag>head</sgmltag> (such as
- <sgmltag>title</sgmltag>).</para>
-
- <para>The second error is because <sgmltag>head</sgmltag>
- elements <emphasis>must</emphasis> contain a
- <sgmltag>title</sgmltag> element. Because it does not
- <command>onsgmls</command> considers that the element has
- not been properly finished. However, the closing tag
- indicates that the element has been closed before it has
- been finished.</para>
+ <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput>
+example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen>
+
+ <para>This line tells you 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>head</sgmltag> is the part, which
+ does not follow the rules described by the XHTML grammar.</para>
+
+ <para>Below this line <command>xmllint</command> will show you
+ the line where the error has been found and will also mark the
+ exact character position with a ^ sign.</para>
</step>
<step>
@@ -565,21 +495,20 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</sect2>
</sect1>
- <sect1 id="sgml-primer-doctype-declaration">
+ <sect1 id="xml-primer-doctype-declaration">
<title>The DOCTYPE Declaration</title>
- <para>The beginning of each document that you write must specify
- the name of the DTD that the document conforms to. This is so
- that SGML parsers can determine the DTD and ensure that the
- document does conform to it.</para>
-
- <para>This information is generally expressed on one line, in the
- DOCTYPE declaration.</para>
+ <para>The beginning of each document that you write may specify
+ the name of the DTD that the document conforms to in case you use
+ the DTD specification language. Other specification languages, like
+ XML Schema and RELAX NG are not referred in the source document.
+ This DOCTYPE declaration serves the XML parsers so that they can
+ determine the DTD and ensure that the document does conform to it.</para>
<para>A typical declaration for a document written to conform with
- version 4.0 of the HTML DTD looks like this:</para>
+ version 1.0 of the XHTML DTD looks like this:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">]]></programlisting>
<para>That line contains a number of different components.</para>
@@ -589,7 +518,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<listitem>
<para>Is the <emphasis>indicator</emphasis> that indicates
- that this is an SGML declaration. This line is declaring
+ that this is an XML declaration. This line is declaring
the document type.</para>
</listitem>
</varlistentry>
@@ -598,7 +527,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<term><literal>DOCTYPE</literal></term>
<listitem>
- <para>Shows that this is an SGML declaration for the
+ <para>Shows that this is an XML declaration for the
document type.</para>
</listitem>
</varlistentry>
@@ -608,29 +537,36 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<listitem>
<para>Names the first
- <link linkend="sgml-primer-elements">element</link> that
+ <link linkend="xml-primer-elements">element</link> that
will appear in the document.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>PUBLIC "-//W3C//DTD HTML
- 4.0//EN"</literal></term>
+ <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
<listitem>
<para>Lists the Formal Public Identifier (FPI)
<indexterm>
<primary>Formal Public Identifier</primary>
</indexterm>
- for the DTD that this document conforms to. Your SGML
+ for the DTD that this document conforms to. Your XML
parser will use this to find the correct DTD when
processing this document.</para>
<para><literal>PUBLIC</literal> is not a part of the FPI,
- but indicates to the SGML processor how to find the DTD
- referenced in the FPI. Other ways of telling the SGML
+ but indicates to the XML processor how to find the DTD
+ referenced in the FPI. Other ways of telling the XML
parser how to find the DTD are shown <link
- linkend="sgml-primer-fpi-alternatives">later</link>.</para>
+ linkend="xml-primer-fpi-alternatives">later</link>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>
+
+ <listitem>
+ <para>A local filename or an URL to find the DTD.</para>
</listitem>
</varlistentry>
@@ -651,7 +587,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<note>
<para>You do not need to know this, but it is useful
- background, and might help you debug problems when your SGML
+ background, and might help you debug problems when your XML
processor can not locate the DTD you are using.</para>
</note>
@@ -673,7 +609,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
Symbols//EN"</literal> lists
<literal>ISO 8879:1986</literal> as being the owner for
the set of entities for Greek symbols. ISO 8879:1986 is
- the ISO number for the SGML standard.</para>
+ the ISO number for the SGML standard, the predecessor
+ (and a superset) of XML.</para>
<para>Otherwise, this string will either look like
<literal>-//<replaceable>Owner</replaceable></literal>
@@ -715,7 +652,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
used only for DTD files, <literal>ELEMENT</literal> is
usually used for DTD fragments that contain only entity
or element declarations. <literal>TEXT</literal> is
- used for SGML content (text and tags).</para>
+ used for XML content (text and tags).</para>
</listitem>
</varlistentry>
@@ -726,7 +663,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>Any description you want to supply for the contents
of this file. This may include version numbers or any
short text that is meaningful to you and unique for the
- SGML system.</para>
+ XML system.</para>
</listitem>
</varlistentry>
@@ -745,7 +682,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<title><filename>catalog</filename> Files</title>
<para>If you use the syntax above and process this document
- using an SGML processor, the processor will need to have
+ using an XML processor, the processor will need to have
some way of turning the FPI into the name of the file on
your computer that contains the DTD.</para>
@@ -754,17 +691,19 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
contains lines that map FPIs to filenames. For example, if
the catalog file contained the line:</para>
- <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
+<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->
- <para>The SGML processor would know to look up the DTD from
- <filename>strict.dtd</filename> in the
- <filename>4.0</filename> subdirectory of whichever directory
+ <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting>
+
+ <para>The XML processor would know to look up the DTD from
+ <filename>transitional.dtd</filename> in the
+ <filename>1.0</filename> subdirectory of whichever directory
held the <filename>catalog</filename> file that contained
that line.</para>
<para>Look at the contents of
- <filename>/usr/local/share/sgml/html/catalog</filename>.
- This is the catalog file for the HTML DTDs that will have
+ <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
+ This is the catalog file for the XHTML DTDs that will have
been installed as part of the <filename
role="package">textproc/docproj</filename> port.</para>
</sect3>
@@ -773,7 +712,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<title><envar>SGML_CATALOG_FILES</envar></title>
<para>In order to locate a <filename>catalog</filename> file,
- your SGML processor will need to know where to look. Many
+ your XML processor will need to know where to look. Many
of them feature command line parameters for specifying the
path to one or more catalogs.</para>
@@ -804,12 +743,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</listitem>
</itemizedlist>
- <para>You should <link linkend="sgml-primer-envars">already
+ <para>You should <link linkend="xml-primer-envars">already
have done this</link>.</para>
</sect3>
</sect2>
- <sect2 id="sgml-primer-fpi-alternatives">
+ <sect2 id="xml-primer-fpi-alternatives">
<title>Alternatives to FPIs</title>
<para>Instead of using an FPI to indicate the DTD that the
@@ -822,7 +761,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
<para>The <literal>SYSTEM</literal> keyword indicates that the
- SGML processor should locate the DTD in a system specific
+ XML processor should locate the DTD in a system specific
fashion. This typically (but not always) means the DTD will
be provided as a filename.</para>
@@ -834,46 +773,46 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</sect2>
</sect1>
- <sect1 id="sgml-primer-sgml-escape">
+ <sect1 id="xml-primer-xml-escape">
<title>Escaping Back to SGML</title>
- <para>As mentioned earlier, SGML is only used when writing a DTD.
- This is not strictly true. There is certain SGML syntax that
+ <para>As mentioned earlier, XML is only used when writing a DTD.
+ This is not strictly true. There is certain XML 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 parser. Comments are entered using SGML syntax.
- Other uses for SGML syntax in your document will be shown later
+ ignored by the parser. Comments are entered using XML syntax.
+ Other uses for XML syntax in your document will be shown later
too.</para>
- <para>Obviously, you need some way of indicating to the SGML
+ <para>Obviously, you need some way of indicating to the XML
processor that the following content is not elements within the
- document, but is SGML that the parser should act upon.</para>
+ document, but is XML that the parser should act upon.</para>
<para>These sections are marked by
<literal>&lt;! ... &gt;</literal> in your document. Everything
- between these delimiters is SGML syntax as you might find within
+ between these delimiters is XML syntax as you might find within
a DTD.</para>
<para>As you may just have realized, the
- <link linkend="sgml-primer-doctype-declaration">DOCTYPE
- declaration</link> is an example of SGML syntax that you need
+ <link linkend="xml-primer-doctype-declaration">DOCTYPE
+ declaration</link> is an example of XML syntax that you need
to include in your document&hellip;</para>
</sect1>
- <sect1 id="sgml-primer-comments">
+ <sect1 id="xml-primer-comments">
<title>Comments</title>
- <para>Comments are an SGML construction, and are normally only
+ <para>Comments are an XML construction, and are normally only
valid inside a DTD. However, as
- <xref linkend="sgml-primer-sgml-escape"/> shows, it is possible
- to use SGML syntax within your document.</para>
+ <xref linkend="xml-primer-xml-escape"/> shows, it is possible
+ to use XML syntax within your document.</para>
- <para>The delimiter for SGML comments is the string
+ <para>The delimiter for XML comments is the string
<quote><literal>--</literal></quote>. The first occurrence of
this string opens a comment, and the second closes it.</para>
<example>
- <title>SGML Generic Comment</title>
+ <title>XML Generic Comment</title>
<programlisting>&lt;!-- test comment --></programlisting>
@@ -889,7 +828,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
-- doing multiline comments -->]]></programlisting>
</example>
- <![ %output.print; [
+ <![%output.print;[
<important>
<title>Use 2 Dashes</title>
@@ -906,24 +845,24 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
professional <emphasis>em-dash</emphasis>, and broken this
example in the process.</para>
- <para>The HTML, plain text, and RTF versions of this document
+ <para>The XHTML, plain text, and RTF versions of this document
are not affected.</para>
</important>
]]>
- <para>If you have used HTML before you may have been shown
+ <para>If you have used XHTML before you may have been shown
different rules for comments. In particular, you may think that
the string <literal>&lt;!--</literal> opens a comment, and it is
only closed by <literal>--&gt;</literal>.</para>
<para>This is <emphasis>not</emphasis> the case. A lot of web
- browsers have broken HTML parsers, and will accept that as
- valid. However, the SGML parsers used by the Documentation
+ browsers have broken XHTML parsers, and will accept that as
+ valid. However, the XML parsers used by the Documentation
Project are much stricter, and will reject documents that make
that error.</para>
<example>
- <title>Erroneous SGML Comments</title>
+ <title>Erroneous XML Comments</title>
<programlisting><![CDATA[
<!-- This is in the comment --
@@ -932,12 +871,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
-- back inside the comment -->]]></programlisting>
- <para>The SGML parser will treat this as though it were
+ <para>The XML parser will treat this as though it were
actually:</para>
<programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
- <para>This is not valid SGML, and may give confusing error
+ <para>This is not valid XML, and may give confusing error
messages.</para>
<programlisting><![CDATA[<!--------------- This is a very bad idea --------------->]]></programlisting>
@@ -948,7 +887,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<programlisting><![CDATA[<!--===================================================-->]]></programlisting>
<para>That is a (slightly) better approach, but it still
- potentially confusing to people new to SGML.</para>
+ potentially confusing to people new to XML.</para>
</example>
<sect2>
@@ -957,44 +896,44 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<procedure>
<step>
<para>Add some comments to
- <filename>example.sgml</filename>, and check that the file
- still validates using <command>onsgmls</command>.</para>
+ <filename>example.xml</filename>, and check that the file
+ still validates using <command>xmllint</command>.</para>
</step>
<step>
<para>Add some invalid comments to
- <filename>example.sgml</filename>, and see the error
- messages that <command>onsgmls</command> gives when it
+ <filename>example.xml</filename>, and see the error
+ messages that <command>xmllint</command> gives when it
encounters an invalid comment.</para>
</step>
</procedure>
</sect2>
</sect1>
- <sect1 id="sgml-primer-entities">
+ <sect1 id="xml-primer-entities">
<title>Entities</title>
<para>Entities are a mechanism for assigning names to chunks of
- content. As an SGML parser processes your document, any
+ content. As an XML parser processes your document, any
entities it finds are replaced by the content of the
entity.</para>
<para>This is a good way to have re-usable, easily changeable
- chunks of content in your SGML documents. It is also the only
+ chunks of content in your XML documents. It is also the only
way to include one marked up file inside another using
- SGML.</para>
+ XML.</para>
<para>There are two types of entities which can be used in two
different situations; <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para>
- <sect2 id="sgml-primer-general-entities">
+ <sect2 id="xml-primer-general-entities">
<title>General Entities</title>
- <para>You cannot use general entities in an SGML context
+ <para>You cannot use general entities in an XML context
(although you define them in one). They can only be used in
your document. Contrast this with <link
- linkend="sgml-primer-parameter-entities">parameter
+ linkend="xml-primer-parameter-entities">parameter
entities</link>.</para>
<para>Each general entity has a name. When you want to
@@ -1014,9 +953,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
your document.</para>
<para>You can also use general entities to enter characters that
- you could not otherwise include in an SGML document. For
+ you could not otherwise include in an XML document. For
example, <literal>&lt;</literal> and <literal>&amp;</literal>
- cannot normally appear in an SGML document. When the SGML
+ cannot normally appear in an XML document. When the XML
parser sees the <literal>&lt;</literal> symbol it assumes that
a tag (either a start tag or an end tag) is about to appear,
and when it sees the <literal>&amp;</literal> symbol it
@@ -1026,14 +965,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<literal>&amp;lt;</literal> and <literal>&amp;amp;</literal>
whenever you need to include one or other of these.</para>
- <para>A general entity can only be defined within an SGML
+ <para>A general entity can only be defined within an XML
context. Typically, this is done immediately after the
DOCTYPE declaration.</para>
<example>
<title>Defining General Entities</title>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version "3.0-RELEASE">
<!ENTITY last.version "2.2.7-RELEASE">
]>]]></programlisting>
@@ -1050,15 +990,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</example>
</sect2>
- <sect2 id="sgml-primer-parameter-entities">
+ <sect2 id="xml-primer-parameter-entities">
<title>Parameter Entities</title>
- <para>Like <link linkend="sgml-primer-general-entities">general
+ <para>Like <link linkend="xml-primer-general-entities">general
entities</link>, parameter entities are used to assign names
to reusable chunks of text. However, whereas general entities
can only be used within your document, parameter entities can
only be used within an <link
- linkend="sgml-primer-sgml-escape">SGML
+ linkend="xml-primer-xml-escape">XML
context</link>.</para>
<para>Parameter entities are defined in a similar way to general
@@ -1075,7 +1015,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<example>
<title>Defining Parameter Entities</title>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new "%param.some more %param.text">
@@ -1093,15 +1034,16 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<procedure>
<step>
<para>Add a general entity to
- <filename>example.sgml</filename>.</para>
+ <filename>example.xml</filename>.</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
]>
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>An Example HTML File</title>
+ <title>An Example XHTML File</title>
</head>
<!-- You might well have some comments in here as well -->
@@ -1120,94 +1062,86 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<step>
<para>Validate the document using
- <command>onsgmls</command>.</para>
+ <command>xmllint</command>.</para>
</step>
<step>
- <para>Load <filename>example.sgml</filename> into your web
+ <para>Load <filename>example.xml</filename> into your web
browser (you may need to copy it to
<filename>example.html</filename> before your browser
- recognizes it as an HTML document).</para>
+ recognizes it as an XHTML document).</para>
<para>Unless your browser is very advanced, you will not see
the entity reference <literal>&amp;version;</literal>
replaced with the version number. Most web browsers have
- very simplistic parsers which do not handle proper
- SGML<footnote><para>This is a shame. Imagine all the
- problems and hacks (such as Server Side Includes) that
- could be avoided if they
- did.</para></footnote>.</para>
+ very simplistic parsers which do not handle XML DTD
+ constructs. Furthermore, the closing <literal>]&lt;</literal>
+ of the XML context are not recognized properly by browser and
+ will probably be rendered.</para>
</step>
<step>
<para>The solution is to <emphasis>normalize</emphasis> your
- document using an SGML normalizer. The normalizer reads
- in valid SGML and outputs equally valid SGML which has
+ document using an XML normalizer. The normalizer reads
+ in valid XML and outputs equally valid XML which has
been transformed in some way. One of the ways in which
- the normalizer transforms the SGML is to expand all the
+ the normalizer transforms the XML is to expand all the
entity references in the document, replacing the entities
with the text that they represent.</para>
- <para>You can use <command>osgmlnorm</command> to do
- this.</para>
+ <para>You can use <command>xmllint</command> to do
+ this. It also has an option to drop the initial
+ DTD section so that the closing <literal>]&lt;</literal>
+ does not confuse browsers:</para>
- <screen>&prompt.user; <userinput>osgmlnorm example.sgml &gt; example.html</userinput></screen>
+ <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml &gt; example.html</userinput></screen>
<para>You should find a normalized (i.e., entity references
expanded) copy of your document in
<filename>example.html</filename>, ready to load into your
web browser.</para>
</step>
-
- <step>
- <para>If you look at the output from
- <command>osgmlnorm</command> you will see that it does not
- include a DOCTYPE declaration at the start. To include
- this you need to use the <option>-d</option>
- option:</para>
-
- <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml &gt; example.html</userinput></screen>
- </step>
</procedure>
</sect2>
</sect1>
- <sect1 id="sgml-primer-include">
+ <sect1 id="xml-primer-include">
<title>Using Entities to Include Files</title>
<para>Entities (both
- <link linkend="sgml-primer-general-entities">general</link> and
- <link linkend="sgml-primer-parameter-entities">parameter</link>)
+ <link linkend="xml-primer-general-entities">general</link> and
+ <link linkend="xml-primer-parameter-entities">parameter</link>)
are particularly useful when used to include one file inside
another.</para>
- <sect2 id="sgml-primer-include-using-gen-entities">
+ <sect2 id="xml-primer-include-using-gen-entities">
<title>Using General Entities to Include Files</title>
- <para>Suppose you have some content for an SGML book organized
+ <para>Suppose you have some content for an XML book organized
into files, one file per chapter, called
- <filename>chapter1.sgml</filename>,
- <filename>chapter2.sgml</filename>, and so forth, with a
- <filename>book.sgml</filename> file that will contain these
+ <filename>chapter1.xml</filename>,
+ <filename>chapter2.xml</filename>, and so forth, with a
+ <filename>book.xml</filename> file that will contain these
chapters.</para>
<para>In order to use the contents of these files as the values
for your entities, you declare them with the
- <literal>SYSTEM</literal> keyword. This directs the SGML
+ <literal>SYSTEM</literal> keyword. This directs the XML
parser to use the contents of the named file as the value of
the entity.</para>
<example>
<title>Using General Entities to Include Files</title>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
<!ENTITY chapter.2 SYSTEM "chapter2.sgml">
<!ENTITY chapter.3 SYSTEM "chapter3.sgml">
<!-- And so forth -->
]>
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
<!-- Use the entities to load in the chapters -->
&chapter.1;
@@ -1222,7 +1156,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
(<filename>chapter1.sgml</filename>,
<filename>chapter2.sgml</filename>, and so on)
<emphasis>must not</emphasis> start with a DOCTYPE
- declaration. This is a syntax error.</para>
+ declaration. This is a syntax error because entities
+ are low-level constructs and they are resolved before
+ any parsing happens.</para>
</warning>
</sect2>
@@ -1230,8 +1166,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<title>Using Parameter Entities to Include Files</title>
<para>Recall that parameter entities can only be used inside an
- SGML context. Why then would you want to include a file
- within an SGML context?</para>
+ XML context. Why then would you want to include a file
+ within an XML context?</para>
<para>You can use this to ensure that you can reuse your general
entities.</para>
@@ -1254,9 +1190,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
called <filename>chapters.ent</filename>. This file
contains the following:</para>
- <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
-<!ENTITY chapter.2 SYSTEM "chapter2.sgml">
-<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting>
+ <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml">
+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
+<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting>
<para>Now create a parameter entity to refer to the contents
of the file. Then use the parameter entity to load the file
@@ -1264,7 +1200,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
entities available for use. Then use the general entities
as before:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">
@@ -1272,7 +1209,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
%chapters;
]>
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
&chapter.1;
&chapter.2;
&chapter.3;
@@ -1288,9 +1225,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<procedure>
<step>
- <para>Create three files, <filename>para1.sgml</filename>,
- <filename>para2.sgml</filename>, and
- <filename>para3.sgml</filename>.</para>
+ <para>Create three files, <filename>para1.xml</filename>,
+ <filename>para2.xml</filename>, and
+ <filename>para3.xml</filename>.</para>
<para>Put content similar to the following in each
file:</para>
@@ -1299,19 +1236,20 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</step>
<step>
- <para>Edit <filename>example.sgml</filename> so that it
+ <para>Edit <filename>example.xml</filename> so that it
looks like this:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
-<!ENTITY para1 SYSTEM "para1.sgml">
-<!ENTITY para2 SYSTEM "para2.sgml">
-<!ENTITY para3 SYSTEM "para3.sgml">
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml">
]>
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>An Example HTML File</title>
+ <title>An Example XHTML File</title>
</head>
<body>
@@ -1326,15 +1264,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<step>
<para>Produce <filename>example.html</filename> by
- normalizing <filename>example.sgml</filename>.</para>
+ normalizing <filename>example.xml</filename>.</para>
- <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml &gt; example.html</userinput></screen>
+ <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
</step>
<step>
<para>Load <filename>example.html</filename> into your web
browser, and confirm that the
- <filename>para<replaceable>n</replaceable>.sgml</filename>
+ <filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
</step>
@@ -1350,16 +1288,17 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<procedure>
<step>
- <para>Edit <filename>example.sgml</filename> so that it
+ <para>Edit <filename>example.xml</filename> so that it
looks like this:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
-<!ENTITY % entities SYSTEM "entities.sgml"> %entities;
+ <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
+<!ENTITY % entities SYSTEM "entities.ent"> %entities;
]>
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>An Example HTML File</title>
+ <title>An Example XHTML File</title>
</head>
<body>
@@ -1374,26 +1313,26 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<step>
<para>Create a new file,
- <filename>entities.sgml</filename>, with this
+ <filename>entities.ent</filename>, with this
content:</para>
<programlisting><![CDATA[<!ENTITY version "1.1">
-<!ENTITY para1 SYSTEM "para1.sgml">
-<!ENTITY para2 SYSTEM "para2.sgml">
-<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting>
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting>
</step>
<step>
<para>Produce <filename>example.html</filename> by
- normalizing <filename>example.sgml</filename>.</para>
+ normalizing <filename>example.xml</filename>.</para>
- <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml &gt; example.html</userinput></screen>
+ <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
</step>
<step>
<para>Load <filename>example.html</filename> into your web
browser, and confirm that the
- <filename>para<replaceable>n</replaceable>.sgml</filename>
+ <filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
</step>
@@ -1402,22 +1341,22 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</sect2>
</sect1>
- <sect1 id="sgml-primer-marked-sections">
+ <sect1 id="xml-primer-marked-sections">
<title>Marked Sections</title>
- <para>SGML provides a mechanism to indicate that particular pieces
+ <para>XML provides a mechanism to indicate that particular pieces
of the document should be processed in a special way. These are
termed <quote>marked sections</quote>.</para>
<example>
<title>Structure of A Marked Section</title>
- <programlisting>&lt;![ <replaceable>KEYWORD</replaceable> [
+ <programlisting>&lt;![<replaceable>KEYWORD</replaceable>[
Contents of marked section
]]&gt;</programlisting>
</example>
- <para>As you would expect, being an SGML construct, a marked
+ <para>As you would expect, being an XML construct, a marked
section starts with <literal>&lt!</literal>.</para>
<para>The first square bracket begins to delimit the marked
@@ -1431,20 +1370,19 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>The marked section is finished by closing the two square
brackets, and then returning to the document context from the
- SGML context with <literal>&gt;</literal>.</para>
+ XGML context with <literal>&gt;</literal>.</para>
<sect2>
<title>Marked Section Keywords</title>
<sect3>
- <title><literal>CDATA</literal>,
- <literal>RCDATA</literal></title>
+ <title><literal>CDATA</literal></title>
<para>These keywords denote the marked sections
<emphasis>content model</emphasis>, and allow you to change
it from the default.</para>
- <para>When an SGML parser is processing a document it keeps
+ <para>When an XML parser is processing a document it keeps
track of what is called the <quote>content
model</quote>.</para>
@@ -1452,9 +1390,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
content the parser is expecting to see, and what it will do
with it when it finds it.</para>
- <para>The two content models you will probably find most
- useful are <literal>CDATA</literal> and
- <literal>RCDATA</literal>.</para>
+ <para>The content model you will probably find most
+ useful is <literal>CDATA</literal>.</para>
<para><literal>CDATA</literal> is for <quote>Character
Data</quote>. If the parser is in this content model then
@@ -1463,32 +1400,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<literal>&amp;</literal> symbols lose their special status,
and will be treated as ordinary 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 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 starting the beginning of a general
- entity.</para>
-
- <para>This is particularly useful if you are including some
- verbatim text that contains lots of <literal>&lt;</literal>
- and <literal>&amp;</literal> characters. While you could go
- through the text ensuring that every <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 <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>
-
<note>
- <para>When you use <literal>CDATA</literal> or
- <literal>RCDATA</literal> in examples of text marked up in
- SGML, keep in mind that the content of
+ <para>When you use <literal>CDATA</literal>
+ in examples of text marked up in
+ XML, keep in mind that the content of
<literal>CDATA</literal> is not validated. You have to
- check the included SGML text using other means. You
+ check the included XML text using other means. You
could, for example, write the example in another document,
validate the example code, and then paste it to your
<literal>CDATA</literal> content.</para>
@@ -1502,13 +1419,13 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<programlisting>&lt;para>Here is an example of how you would include some text
that contained many &lt;literal>&amp;lt;&lt;/literal>
and &lt;literal>&amp;amp;&lt;/literal> symbols. The sample
- text is a fragment of HTML. The surrounding text (&lt;para> and
+ text is a fragment of XHTML. The surrounding text (&lt;para> and
&lt;programlisting>) are from DocBook.&lt;/para>
&lt;programlisting>
- &lt;![CDATA[ <![ CDATA [
+ &lt;![CDATA[<![CDATA[
<p>This is a sample that shows you some of the elements within
- HTML. Since the angle brackets are used so many times, it is
+ XHTML. 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.</p>
@@ -1542,11 +1459,11 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<title>Using <literal>INCLUDE</literal> and
<literal>IGNORE</literal> in Marked Sections</title>
- <programlisting>&lt;![ INCLUDE [
+ <programlisting>&lt;![INCLUDE[
This text will be processed and included.
]]&gt;
-&lt;![ IGNORE [
+&lt;![IGNORE[
This text will not be processed or included.
]]&gt;</programlisting>
</example>
@@ -1556,50 +1473,50 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
it in comments.</para>
<para>It becomes more useful when you realize you can use
- <link linkend="sgml-primer-parameter-entities">parameter
- entities</link> to control this. Remember that parameter
- entities can only be used in SGML contexts, and the keyword
- of a marked section <emphasis>is</emphasis> an SGML
- context.</para>
+ <link linkend="xml-primer-parameter-entities">parameter
+ entities</link> to control this, yet this usage is limited
+ to entity files.</para>
<para>For example, suppose that you produced a hard-copy
version of some documentation and an electronic version. In
the electronic version you wanted to include some extra
content that was not to appear in the hard-copy.</para>
- <para>Create a parameter entity, and set its value to
- <literal>INCLUDE</literal>. Write your document, using
- marked sections to delimit content that should only appear
- in the electronic version. In these marked sections use the
- parameter entity in place of the keyword.</para>
-
- <para>When you want to produce the hard-copy version of the
- document, change the parameter entity's value to
- <literal>IGNORE</literal> and reprocess the document.</para>
+ <para>Create an entity file that defines general entities
+ to include each chapter and guard these definitions with
+ a parameter entity that can be set to either
+ <literal>INCLUDE</literal> or <literal>IGNORE</literal>
+ to control whether the entity is defined. After these
+ conditional general entity definitions, place one more
+ definition for each general entity to set them to an
+ empty value. This technique makes use of the fact that
+ entity definitions cannot be overridden but always the
+ first definition takes effect. So you can control the
+ inclusion of your chapter with the corrsponding parameter
+ entity; if you set it to <literal>INCLUDE</literal>, the
+ first general entity definition will be read and the
+ second one will be ignored but if you set it to
+ <literal>IGNORE</literal>, the first definition will be
+ ignored and the second one will take effect.</para>
<example>
<title>Using A Parameter Entity to Control a Marked
Section</title>
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
+ <programlisting>
&lt;!ENTITY % electronic.copy "INCLUDE">
-]]&gt;
-...
+&lt;![%electronic.copy;[
+&lt;!ENTITY chap.preface SYSTEM "preface.xml"&gt;
+]]&gt;
-&lt;![ %electronic.copy [
- This content should only appear in the electronic
- version of the document.
-]]&gt;</programlisting>
+&lt;!ENTITY chap.preface ""&gt;
+</programlisting>
<para>When producing the hard-copy version, change the
- entity's definition to:</para>
-
- <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"></programlisting>
+ parameter entity's definition to:</para>
- <para>On reprocessing the document, the marked sections that
- use <literal>%electronic.copy</literal> as their keyword
- will be ignored.</para>
+ <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"&gt;</programlisting>
</example>
</sect3>
</sect2>
@@ -1609,64 +1526,42 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<procedure>
<step>
- <para>Create a new file, <filename>section.sgml</filename>,
- that contains the following:</para>
-
- <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
-&lt;!ENTITY % text.output "INCLUDE">
-]&gt;
-
-&lt;html>
- &lt;head>
- &lt;title>An example using marked sections&lt;/title>
- &lt;/head>
-
- &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>
-
- &lt;![IGNORE[
- &lt;p>This paragraph will definitely not be included in the
- output.&lt;/p>
- ]]&gt;
-
- &lt;![ <![CDATA[%text.output]]> [
- &lt;p>This paragraph might appear in the output, or it
- might not.&lt;/p>
-
- &lt;p>Its appearance is controlled by the <![CDATA[%text.output]]>
- parameter entity.&lt;/p>
- ]]&gt;
- &lt;/body>
-&lt;/html></programlisting>
- </step>
+ <para>Modify the <filename>entities.ent</filename> file to contain
+ the following:</para>
- <step>
- <para>Normalize this file using <command>osgmlnorm</command>
- and examine the output. Notice which paragraphs have
- appeared, which have disappeared, and what has happened to
- the content of the CDATA marked section.</para>
+ <programlisting>&lt;!ENTITY version "1.1"&gt;
+&lt;!ENTITY % conditional.text "IGNORE"&gt;
+
+&lt;![%conditional.text;[
+&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
+]]&gt;
+
+&lt;!ENTITY para1 ""&gt;
+
+&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
+&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
</step>
<step>
- <para>Change the definition of the
- <literal>text.output</literal> entity from
- <literal>INCLUDE</literal> to <literal>IGNORE</literal>.
- Re-normalize the file, and examine the output to see what
- has changed.</para>
+ <para>Normalize the <filename>example.xml</filename> file and notice
+ that the conditional text is not present on the output document.
+ Now if you set the parameter entity guard to <literal>INCLUDE</literal>
+ and regenerate the normalized document, it will appear there again.
+ Of course, this method makes more sense if you have more conditional
+ chunks that depend on the same condition, for example, whether you are
+ generating printed or online text.</para>
</step>
</procedure>
</sect2>
</sect1>
- <sect1 id="sgml-primer-conclusion">
+ <sect1 id="xml-primer-conclusion">
<title>Conclusion</title>
- <para>That is the conclusion of this SGML primer. For reasons of
+ <para>That is the conclusion of this XML primer. For reasons of
space and complexity several things have not been covered in
depth (or at all). However, the previous sections cover enough
- SGML for you to be able to follow the organization of the FDP
+ XML for you to be able to follow the organization of the FDP
documentation.</para>
</sect1>
</chapter>
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
index 4867d25391..ab25b68972 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
+++ b/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
diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
index 2b1d16ddb6..9975364fa6 100644
--- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
+++ b/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>
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index a53a76c0a6..6bb2de2e09 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/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>
diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
index f06cde4928..89b2310641 100644
--- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
+++ b/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
- reformat some of the automatically generated HTML so
+ <para>An (X)HTML <quote>pretty printer</quote>, used to
+ 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
- role="package">textproc/html</filename>)</term>
+ <term>XHTML DTD (<filename
+ 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>