svn commit: r42264 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer
Warren Block
wblock at FreeBSD.org
Sat Jul 13 01:34:36 UTC 2013
Author: wblock
Date: Sat Jul 13 01:34:35 2013
New Revision: 42264
URL: http://svnweb.freebsd.org/changeset/doc/42264
Log:
Continue editing the XML primer for clarity and to conform with modern
usage of the FDP tools. The hippo did not want to give up the stilts
and pogo stick, but eventually agreed that it was best for everyone.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Fri Jul 12 22:03:39 2013 (r42263)
+++ head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Sat Jul 13 01:34:35 2013 (r42264)
@@ -34,7 +34,7 @@
<chapter id="xml-primer">
<title>XML Primer</title>
- <para>Most FDP documentation is written with markup languages based
+ <para>Most <acronym>FDP</acronym> documentation is written with markup languages based
on <acronym>XML</acronym>. This chapter explains what that means,
how to read and understand the documentation source, and the
<acronym>XML</acronym> techniques used.</para>
@@ -133,13 +133,7 @@
<para>Each language definition is more properly called a grammar,
vocabulary, schema or Document Type Definition
(<acronym>DTD</acronym>). There are various languages to
- specify an <acronym>XML</acronym> grammar, for example,
- <acronym>DTD</acronym> (yes, it also means the specification
- language itself), <acronym>XML</acronym> Schema
- (<acronym>XSD</acronym>) or <acronym>RELANG NG</acronym>. 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.</para>
+ specify an <acronym>XML</acronym> grammar, or <emphasis>schema</emphasis>.</para>
<para id="xml-primer-validating">A schema is a
<emphasis>complete</emphasis> specification of all the elements
@@ -155,7 +149,7 @@
<quote>validating the document</quote>.</para>
<note>
- <para>This processing simply confirms that the choice of
+ <para>Validation confirms that the choice of
elements, their ordering, and so on, conforms to that listed
in the grammar. It does <emphasis>not</emphasis> check
whether <emphasis>appropriate</emphasis> markup has been used
@@ -166,7 +160,7 @@
allowed to appear in the same place).</para>
</note>
- <para>It is likely that most contributions to the Documentation
+ <para>Most contributions to the Documentation
Project will be content marked up in either
<acronym>XHTML</acronym> or DocBook, rather than alterations to
the schemas. For this reason, this book will not touch on how
@@ -585,7 +579,7 @@ example.xml:5: element head: validity er
<sect2>
<title>Formal Public Identifiers
- (<acronym>FPI</acronym>s)</title>
+ (<acronym>FPI</acronym>)</title>
<indexterm significance="preferred">
<primary>Formal Public Identifier</primary>
@@ -712,7 +706,7 @@ example.xml:5: element head: validity er
<acronym>DTD</acronym> is called
<filename>transitional.dtd</filename> in the
<filename>1.0</filename> subdirectory of the directory that
- held the <filename>catalog</filename> file.</para>
+ held <filename>catalog</filename>.</para>
<para>Examine the contents of
<filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
@@ -725,7 +719,7 @@ example.xml:5: element head: validity er
<sect3>
<title><envar>SGML_CATALOG_FILES</envar></title>
- <para>To locate a <filename>catalog</filename> file, the
+ <para>To locate a <filename>catalog</filename>, the
<acronym>XML</acronym> processor must know where to look.
Many feature command line parameters for specifying the path
to one or more catalogs.</para>
@@ -787,102 +781,80 @@ example.xml:5: element head: validity er
</sect1>
<sect1 id="xml-primer-xml-escape">
- <title>Escaping Back to SGML</title>
+ <title>Escaping Back to <acronym>XML</acronym></title>
- <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 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 XML
- processor that the following content is not elements within the
- document, but is XML that the parser should act upon.</para>
-
- <para>These sections are marked by
- <literal><! ... ></literal> in your document. Everything
- between these delimiters is XML syntax as you might find within
- a DTD.</para>
-
- <para>As you may just have realized, the
+ <para>Some of the underlying <acronym>XML</acronym> syntax can be
+ useful within documents. For
+ example, comments can be included in the document, and will be
+ ignored by the parser. Comments are entered using <acronym>XML</acronym> syntax.
+ Other uses for <acronym>XML</acronym> syntax will be shown later.</para>
+
+ <para><acronym>XML</acronym> sections begin with a
+ <literal><!</literal> tag and end with a
+ <literal>></literal>. These sections contain instructions
+ for the parser rather than elements of the document. Everything
+ between these tags is <acronym>XML</acronym> syntax. The
<link linkend="xml-primer-doctype-declaration">DOCTYPE
- declaration</link> is an example of XML syntax that you need
- to include in your document…</para>
+ declaration</link> shown earlier is an example of <acronym>XML</acronym> syntax included in the document.</para>
</sect1>
<sect1 id="xml-primer-comments">
<title>Comments</title>
- <para>Comments are an XML construction, and are normally only
- valid inside a DTD. However, as
+ <para>Comments are an <acronym>XML</acronym> construct, and are normally only
+ valid inside a <acronym>DTD</acronym>. However, as
<xref linkend="xml-primer-xml-escape"/> shows, it is possible
- to use XML syntax within your document.</para>
+ to use <acronym>XML</acronym> syntax within the document.</para>
<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>XML Generic Comment</title>
-
- <programlisting><!-- test comment --></programlisting>
+ <title><acronym>XML</acronym> Generic Comment</title>
- <programlisting><![CDATA[
-<!-- This is inside the comment -->
+ <programlisting><!-- This is inside the comment -->
-<!-- This is another comment -->
+<!-- This is another comment -->
-<!-- This is one way
- of doing multiline comments -->
+<!-- This is one way
+ of doing multiline comments -->
-<!-- This is another way of --
- -- doing multiline comments -->]]></programlisting>
+<!-- This is another way of --
+ -- doing multiline comments --></programlisting>
</example>
- <para>If you have used XHTML before you may have been shown
- different rules for comments. In particular, you may think that
+ <para><acronym>XHTML</acronym> user may be familiar with
+ different rules for comments. In particular, it is often believed that
the string <literal><!--</literal> opens a comment, and it is
only closed by <literal>--></literal>.</para>
- <para>This is <emphasis>not</emphasis> the case. A lot of web
- 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
+ <para>This is <emphasis>not</emphasis> correct. Many web
+ browsers have broken <acronym>XHTML</acronym> parsers, and will accept incorrect input as
+ valid. However, the <acronym>XML</acronym> parsers used by the Documentation
+ Project are more strict, and will reject documents with
that error.</para>
<example>
- <title>Erroneous XML Comments</title>
+ <title>Erroneous <acronym>XML</acronym> Comments</title>
- <programlisting><![CDATA[
-<!-- This is in the comment --
+ <programlisting><!-- This is in the comment --
THIS IS OUTSIDE THE COMMENT!
- -- back inside the comment -->]]></programlisting>
+ -- back inside the comment --></programlisting>
- <para>The XML parser will treat this as though it were
+ <para>The <acronym>XML</acronym> parser will treat this as though it were
actually:</para>
<programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting>
- <para>This is not valid XML, and may give confusing error
+ <para>That is not valid <acronym>XML</acronym>, and may give confusing error
messages.</para>
-
- <programlisting><![CDATA[<!--------------- This is a very bad idea --------------->]]></programlisting>
-
- <para>As the example suggests, <emphasis>do not</emphasis> write
- comments like that.</para>
-
- <programlisting><![CDATA[<!--===================================================-->]]></programlisting>
-
- <para>That is a (slightly) better approach, but it still
- potentially confusing to people new to XML.</para>
</example>
<sect2>
- <title>For You to Do…</title>
+ <title>To Do…</title>
<procedure>
<step>
@@ -905,150 +877,144 @@ example.xml:5: element head: validity er
<title>Entities</title>
<para>Entities are a mechanism for assigning names to chunks of
- content. As an XML parser processes your document, any
+ content. As an <acronym>XML</acronym> parser processes a 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 XML documents. It is also the only
+ chunks of content in <acronym>XML</acronym> documents. It is also the only
way to include one marked up file inside another using
- XML.</para>
+ <acronym>XML</acronym>.</para>
- <para>There are two types of entities which can be used in two
- different situations; <emphasis>general entities</emphasis> and
+ <para>There are two types of entities for two
+ different situations: <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para>
<sect2 id="xml-primer-general-entities">
<title>General Entities</title>
- <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="xml-primer-parameter-entities">parameter
- entities</link>.</para>
-
- <para>Each general entity has a name. When you want to
- reference a general entity (and therefore include whatever
- text it represents in your document), you write
- <literal>&<replaceable>entity-name</replaceable>;</literal>.
- For example, suppose you had an entity called
- <literal>current.version</literal> which expanded to the
- current version number of your product. You could
+ <para>General entities are used to assign names to reusable
+ chunks of text. These entities can only be used in the
+ document. They cannot be used in an
+ <acronym>XML</acronym> context.</para>
+
+ <para>To include the text of a general entity in the document, include
+ <literal>&<replaceable>entity-name</replaceable>;</literal> in the text.
+ For example, consider a general entity called
+ <literal>current.version</literal> which expands to the
+ current version number of a product. To use it in the document,
write:</para>
- <programlisting><![CDATA[<para>The current version of our product is
- ¤t.version;.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>The current version of our product is
+ ¤t.version;.<sgmltag class="endtag">para</sgmltag></programlisting>
- <para>When the version number changes you can simply change the
- definition of the value of the general entity and reprocess
- your document.</para>
+ <para>When the version number changes, edit the
+ definition of the general entity, replacing the value. Then reprocess
+ the document.</para>
- <para>You can also use general entities to enter characters that
- you could not otherwise include in an XML document. For
+ <para>General entities can also be used to enter characters that
+ could not otherwise be included in an <acronym>XML</acronym> document. For
example, <literal><</literal> and <literal>&</literal>
- cannot normally appear in an XML document. When the XML
- parser sees the <literal><</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>&</literal> symbol it
- assumes the next text will be the name of an entity.</para>
-
- <para>Fortunately, you can use the two general entities
- <literal><</literal> and <literal>&</literal>
- whenever you need to include one or other of these.</para>
+ cannot normally appear in an <acronym>XML</acronym> document. The <acronym>XML</acronym>
+ parser sees the <literal><</literal> symbol as the start of
+ a tag. Likewise, when the
+ <literal>&</literal> symbol is seen, the next text is expected to
+ be an entity name.</para>
+
+ <para>These symbols can be included by using two predefined general entities:
+ <literal><</literal> and <literal>&</literal>.</para>
- <para>A general entity can only be defined within an XML
- context. Typically, this is done immediately after the
+ <para>General entities can only be defined within an <acronym>XML</acronym>
+ context. Such definitions are usually done immediately after the
DOCTYPE declaration.</para>
<example>
<title>Defining General Entities</title>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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>
+<!ENTITY current.version "3.0-RELEASE">
+<!ENTITY last.version "2.2.7-RELEASE">
+]></programlisting>
- <para>Notice how the DOCTYPE declaration has been extended by
+ <para>The DOCTYPE declaration has been extended by
adding a square bracket at the end of the first line. The
two entities are then defined over the next two lines,
- before the square bracket is closed, and then the DOCTYPE
+ the square bracket is closed, and then the DOCTYPE
declaration is closed.</para>
- <para>The square brackets are necessary to indicate that we
- are extending the DTD indicated by the DOCTYPE
- declaration.</para>
+ <para>The square brackets are necessary to indicate that
+ the DTD indicated by the DOCTYPE
+ declaration is being extended.</para>
</example>
</sect2>
<sect2 id="xml-primer-parameter-entities">
<title>Parameter Entities</title>
- <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
+ <para>Parameter entities, like <link linkend="xml-primer-general-entities">general
+ entities</link>, are used to assign names
+ to reusable chunks of text. But
+ parameter entities can
only be used within an <link
linkend="xml-primer-xml-escape">XML
context</link>.</para>
- <para>Parameter entities are defined in a similar way to general
- entities. However, instead of using
- <literal>&<replaceable>entity-name</replaceable>;</literal>
- to refer to them, use
- <literal>%<replaceable>entity-name</replaceable>;</literal>
- <footnote><para><emphasis>P</emphasis>arameter entities use
- the <emphasis>P</emphasis>ercent
- symbol.</para></footnote>. The definition also includes
+ <para>Parameter entity definitons are similar to those for general
+ entities. However, parameter entries are included with
+ <literal>%<replaceable>entity-name</replaceable>;</literal>.
+ The definition also includes
the <literal>%</literal> between the <literal>ENTITY</literal>
keyword and the name of the entity.</para>
+ <para>For a mnemonic, think <quote><emphasis>P</emphasis>arameter entities use
+ the <emphasis>P</emphasis>ercent
+ symbol</quote>.</para>
+
<example>
<title>Defining Parameter Entities</title>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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">
+<!ENTITY % param.some "some">
+<!ENTITY % param.text "text">
+<!ENTITY % param.new "%param.some more %param.text">
-<!-- %param.new now contains "some more text" -->
-]>]]></programlisting>
+<!-- %param.new now contains "some more text" -->
+]></programlisting>
</example>
-
- <para>This may not seem particularly useful. It will be.</para>
</sect2>
<sect2>
- <title>For You to Do…</title>
+ <title>To Do…</title>
<procedure>
<step>
<para>Add a general entity to
<filename>example.xml</filename>.</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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 version "1.1">
+]>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title>An Example XHTML File</title>
- </head>
+<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+ <sgmltag class="starttag">head</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
+ <sgmltag class="endtag">head</sgmltag>
- <!-- You might well have some comments in here as well -->
+ <!-- There may be some comments in here as well -->
- <body>
- <p>This is a paragraph containing some text.</p>
+ <sgmltag class="starttag">body</sgmltag>
+ <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag>
- <p>This paragraph contains some more text.</p>
+ <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag>
- <p align="right">This paragraph might be right-justified.</p>
+ <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag>
- <p>The current version of this document is: &version;</p>
- </body>
-</html>]]></programlisting>
+ <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag>
+ <sgmltag class="endtag">body</sgmltag>
+<sgmltag class="endtag">html</sgmltag></programlisting>
</step>
<step>
@@ -1057,41 +1023,38 @@ example.xml:5: element head: validity er
</step>
<step>
- <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 XHTML document).</para>
-
- <para>Unless your browser is very advanced, you will not see
- the entity reference <literal>&version;</literal>
- replaced with the version number. Most web browsers have
- very simplistic parsers which do not handle XML DTD
- constructs. Furthermore, the closing
- <literal>]<</literal> of the XML context are not
- recognized properly by browser and will probably be
- rendered.</para>
+ <para>Load <filename>example.xml</filename> into a web
+ browser. It may have to be copied to
+ <filename>example.html</filename> before the browser
+ recognizes it as an <acronym>XHTML</acronym> document.</para>
+
+ <para>Older browsers with simple parsers may not render
+ this file as expected. The entity reference <literal>&version;</literal> may not be replaced by
+ the version number, or the <acronym>XML</acronym> context closing
+ <literal>]<</literal> may not be
+ recognized and instead shown in the output.</para>
</step>
<step>
- <para>The solution is to <emphasis>normalize</emphasis> your
- 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 XML is to expand all the
+ <para>The solution is to <emphasis>normalize</emphasis> the
+ document with an <acronym>XML</acronym> normalizer. The normalizer reads
+ valid <acronym>XML</acronym> and writes equally valid <acronym>XML</acronym> which has
+ been transformed in some way. One way
+ the normalizer transforms the input is by expanding all the
entity references in the document, replacing the entities
with the text that they represent.</para>
- <para>You can use <command>xmllint</command> to do
+ <para><command>xmllint</command> can be used for
this. It also has an option to drop the initial
- DTD section so that the closing <literal>]<</literal>
+ <acronym>DTD</acronym> section so that the closing <literal>]<</literal>
does not confuse browsers:</para>
<screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml > 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
+ <para>A normalized copy of the document with entities expanded
+ is produced in
+ <filename>example.html</filename>, ready to load into a
web browser.</para>
</step>
</procedure>
@@ -1101,46 +1064,46 @@ example.xml:5: element head: validity er
<sect1 id="xml-primer-include">
<title>Using Entities to Include Files</title>
- <para>Entities (both
+ <para>Both
<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
+ <link linkend="xml-primer-parameter-entities">parameter</link> entities
+ are particularly useful for including one file inside
another.</para>
<sect2 id="xml-primer-include-using-gen-entities">
<title>Using General Entities to Include Files</title>
- <para>Suppose you have some content for an XML book organized
+ <para>Consider some content for an <acronym>XML</acronym> book organized
into files, one file per chapter, called
<filename>chapter1.xml</filename>,
<filename>chapter2.xml</filename>, and so forth, with a
- <filename>book.xml</filename> file that will contain these
+ <filename>book.xml</filename> 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 XML
- parser to use the contents of the named file as the value of
+ for entities, they are declared with the
+ <literal>SYSTEM</literal> keyword. This directs the <acronym>XML</acronym>
+ parser to include 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 XHTML 1.0 Transitional//EN"
+ <programlisting><!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.xml">
-<!ENTITY chapter.2 SYSTEM "chapter2.xml">
-<!ENTITY chapter.3 SYSTEM "chapter3.xml">
-<!-- And so forth -->
-]>
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <!-- Use the entities to load in the chapters -->
-
- &chapter.1;
- &chapter.2;
- &chapter.3;
-</html>]]></programlisting>
+<!ENTITY chapter.1 SYSTEM "chapter1.xml">
+<!ENTITY chapter.2 SYSTEM "chapter2.xml">
+<!ENTITY chapter.3 SYSTEM "chapter3.xml">
+<!-- And so forth -->
+]>
+
+<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+ <!-- Use the entities to load in the chapters -->
+
+ &chapter.1;
+ &chapter.2;
+ &chapter.3;
+<sgmltag class="endtag">html</sgmltag></programlisting>
</example>
<warning>
@@ -1158,60 +1121,59 @@ example.xml:5: element head: validity er
<sect2>
<title>Using Parameter Entities to Include Files</title>
- <para>Recall that parameter entities can only be used inside an
- XML context. Why then would you want to include a file
- within an XML context?</para>
+ <para>Parameter entities can only be used inside an
+ <acronym>XML</acronym> context. Including a file in an
+ <acronym>XML</acronym> context can be used
+ to ensure that general
+ entities are reusable.</para>
- <para>You can use this to ensure that you can reuse your general
- entities.</para>
-
- <para>Suppose that you had many chapters in your document, and
- you reused these chapters in two different books, each book
+ <para>Suppose that there are many chapters in the document, and
+ these chapters were reused in two different books, each book
organizing the chapters in a different fashion.</para>
- <para>You could list the entities at the top of each book, but
- this quickly becomes cumbersome to manage.</para>
+ <para>The entities could be listed at the top of each book, but
+ that quickly becomes cumbersome to manage.</para>
<para>Instead, place the general entity definitions inside one
file, and use a parameter entity to include that file within
- your document.</para>
+ the document.</para>
<example>
<title>Using Parameter Entities to Include Files</title>
- <para>First, place your entity definitions in a separate file,
- called <filename>chapters.ent</filename>. This file
- contains the following:</para>
-
- <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml">
-<!ENTITY chapter.2 SYSTEM "chapter2.xml">
-<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting>
+ <para>Place the entity definitions in a separate file
+ called <filename>chapters.ent</filename> and
+ containing this text:</para>
+
+ <programlisting><!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
+ <para>Create a parameter entity to refer to the contents
of the file. Then use the parameter entity to load the file
into the document, which will then make all the general
entities available for use. Then use the general entities
as before:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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">
+<!-- Define a parameter entity to load in the chapter general entities -->
+<!ENTITY % chapters SYSTEM "chapters.ent">
-<!-- Now use the parameter entity to load in this file -->
+<!-- Now use the parameter entity to load in this file -->
%chapters;
-]>
+]>
-<html xmlns="http://www.w3.org/1999/xhtml">
- &chapter.1;
- &chapter.2;
- &chapter.3;
-</html>]]></programlisting>
+<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+ &chapter.1;
+ &chapter.2;
+ &chapter.3;
+<sgmltag class="endtag">html</sgmltag></programlisting>
</example>
</sect2>
<sect2>
- <title>For You to Do…</title>
+ <title>To Do…</title>
<sect3>
<title>Use General Entities to Include Files</title>
@@ -1222,37 +1184,37 @@ example.xml:5: element head: validity er
<filename>para2.xml</filename>, and
<filename>para3.xml</filename>.</para>
- <para>Put content similar to the following in each
+ <para>Put content like this in each
file:</para>
- <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting>
+ <programlisting><sgmltag class="starttag">p</sgmltag>This is the first paragraph.<sgmltag class="endtag">p</sgmltag></programlisting>
</step>
<step>
<para>Edit <filename>example.xml</filename> so that it
looks like this:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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.xml">
-<!ENTITY para2 SYSTEM "para2.xml">
-<!ENTITY para3 SYSTEM "para3.xml">
-]>
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title>An Example XHTML File</title>
- </head>
-
- <body>
- <p>The current version of this document is: &version;</p>
-
- ¶1;
- ¶2;
- ¶3;
- </body>
-</html>]]></programlisting>
+<!ENTITY version "1.1">
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml">
+]>
+
+<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+ <sgmltag class="starttag">head</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
+ <sgmltag class="endtag">head</sgmltag>
+
+ <sgmltag class="starttag">body</sgmltag>
+ <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag>
+
+ ¶1;
+ ¶2;
+ ¶3;
+ <sgmltag class="endtag">body</sgmltag>
+<sgmltag class="endtag">html</sgmltag></programlisting>
</step>
<step>
@@ -1263,8 +1225,8 @@ example.xml:5: element head: validity er
</step>
<step>
- <para>Load <filename>example.html</filename> into your web
- browser, and confirm that the
+ <para>Load <filename>example.html</filename> into the web
+ browser and confirm that the
<filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
@@ -1276,7 +1238,7 @@ example.xml:5: element head: validity er
<title>Use Parameter Entities to Include Files</title>
<note>
- <para>You must have taken the previous steps first.</para>
+ <para>The previous steps must have completed before this step.</para>
</note>
<procedure>
@@ -1284,35 +1246,35 @@ example.xml:5: element head: validity er
<para>Edit <filename>example.xml</filename> so that it
looks like this:</para>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ <programlisting><!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;
-]>
+<!ENTITY % entities SYSTEM "entities.ent"> %entities;
+]>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title>An Example XHTML File</title>
- </head>
-
- <body>
- <p>The current version of this document is: &version;</p>
-
- ¶1;
- ¶2;
- ¶3;
- </body>
-</html>]]></programlisting>
+<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag>
+ <sgmltag class="starttag">head</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag>
+ <sgmltag class="endtag">head</sgmltag>
+
+ <sgmltag class="starttag">body</sgmltag>
+ <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag>
+
+ ¶1;
+ ¶2;
+ ¶3;
+ <sgmltag class="endtag">body</sgmltag>
+<sgmltag class="endtag">html</sgmltag></programlisting>
</step>
<step>
- <para>Create a new file,
- <filename>entities.ent</filename>, with this
+ <para>Create a new file called
+ <filename>entities.ent</filename> with this
content:</para>
- <programlisting><![CDATA[<!ENTITY version "1.1">
-<!ENTITY para1 SYSTEM "para1.xml">
-<!ENTITY para2 SYSTEM "para2.xml">
-<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting>
+ <programlisting><!ENTITY version "1.1">
+<!ENTITY para1 SYSTEM "para1.xml">
+<!ENTITY para2 SYSTEM "para2.xml">
+<!ENTITY para3 SYSTEM "para3.xml"></programlisting>
</step>
<step>
@@ -1323,8 +1285,8 @@ example.xml:5: element head: validity er
</step>
<step>
- <para>Load <filename>example.html</filename> into your web
- browser, and confirm that the
+ <para>Load <filename>example.html</filename> into the web
+ browser and confirm that the
<filename>para<replaceable>n</replaceable>.xml</filename>
files have been included in
<filename>example.html</filename>.</para>
@@ -1337,9 +1299,9 @@ example.xml:5: element head: validity er
<sect1 id="xml-primer-marked-sections">
<title>Marked Sections</title>
- <para>XML provides a mechanism to indicate that particular pieces
+ <para><acronym>XML</acronym> 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>
+ called <quote>marked sections</quote>.</para>
<example>
<title>Structure of a Marked Section</title>
@@ -1349,101 +1311,93 @@ example.xml:5: element head: validity er
]]></programlisting>
</example>
- <para>As you would expect, being an XML construct, a marked
+ <para>As expected of an <acronym>XML</acronym> construct, a marked
section starts with <literal><!</literal>.</para>
- <para>The first square bracket begins to delimit the marked
+ <para>The first square bracket begins the marked
section.</para>
<para><replaceable>KEYWORD</replaceable> describes how this marked
- section should be processed by the parser.</para>
+ section is to be processed by the parser.</para>
- <para>The second square bracket indicates that the content of the
- marked section starts here.</para>
+ <para>The second square bracket indicates the start of the
+ marked section's content.</para>
<para>The marked section is finished by closing the two square
brackets, and then returning to the document context from the
- XGML context with <literal>></literal>.</para>
+ <acronym>XML</acronym> context with <literal>></literal>.</para>
- <sect2>
+ <sect2 id="xml-primer-marked-section-keywords">
<title>Marked Section Keywords</title>
- <sect3>
+ <sect3 id="xml-primer-cdata">
<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 XML parser is processing a document it keeps
- track of what is called the <quote>content
+ <para>When an <acronym>XML</acronym> parser is processing a document, it keeps
+ track of the <quote>content
model</quote>.</para>
- <para>Briefly, the content model describes what sort of
- content the parser is expecting to see, and what it will do
- with it when it finds it.</para>
+ <para>The content model describes the
+ content the parser is expecting to see and what it will do
+ with that content.</para>
- <para>The content model you will probably find most
- useful is <literal>CDATA</literal>.</para>
+ <para>The
+ <literal>CDATA</literal> content model is one of the most useful.</para>
<para><literal>CDATA</literal> is for
- <quote>Character Data</quote>. If the parser is in this
- content model then it is expecting to see characters, and
- characters only. In this model the <literal><</literal>
+ <quote>Character Data</quote>. When the parser is in this
+ content model, it expects to see only characters.
+ In this model the <literal><</literal>
and <literal>&</literal> symbols lose their special
status, and will be treated as ordinary characters.</para>
<note>
- <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 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>
+ <para>When using <literal>CDATA</literal> in examples of
+ text marked up in <acronym>XML</acronym>, remember that the content of
+ <literal>CDATA</literal> is not validated. The
+ included text must be check with other means.
+ For example, the content could be written in another document,
+ validated, and then pasted into the
+ <literal>CDATA</literal> section.</para>
</note>
- <!-- The nesting of CDATA within the next example is disgusting -->
<example>
<title>Using a <literal>CDATA</literal> Marked
Section</title>
- <programlisting><para>Here is an example of how you would include some text
- that contained many <literal><</literal>
- and <literal>&</literal> symbols. The sample
- text is a fragment of XHTML. The surrounding text (<para> and
- <programlisting>) are from DocBook.</para>
-
-<programlisting>
- <![CDATA[<![CDATA[
- <p>This is a sample that shows you some of the elements within
- 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>
-
- <ul>
- <li>This is a listitem</li>
- <li>This is a second listitem</li>
- <li>This is a third listitem</li>
- </ul>
-
- <p>This is the end of the example.</p>]]>
- ]]>
-</programlisting></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>Here is an example of how to include some text that contains
+ many <sgmltag class="starttag">literal</sgmltag><<sgmltag class="endtag">literal</sgmltag> and <sgmltag class="starttag">literal</sgmltag>&<sgmltag class="endtag">literal</sgmltag>
+ symbols. The sample text is a fragment of
+ <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>. The surrounding text (<sgmltag class="starttag">para</sgmltag> and
+ <sgmltag class="starttag">programlisting</sgmltag>) are from DocBook.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">programlisting</sgmltag><![CDATA[<sgmltag class="starttag">p</sgmltag>This is a sample that shows some of the
+ elements within <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>. Since the angle
+ brackets are used so many times, it is simpler to say the whole
+ example is a CDATA marked section than to use the entity names for
+ the left and right angle brackets throughout.<sgmltag class="endtag">p</sgmltag>
+
+ <sgmltag class="starttag">ul</sgmltag>
+ <sgmltag class="starttag">li</sgmltag>This is a listitem<sgmltag class="endtag">li</sgmltag>
+ <sgmltag class="starttag">li</sgmltag>This is a second listitem<sgmltag class="endtag">li</sgmltag>
+ <sgmltag class="starttag">li</sgmltag>This is a third listitem<sgmltag class="endtag">li</sgmltag>
+ <sgmltag class="endtag">ul</sgmltag>
- <para>If you look at the source for this document you will
- see this technique used throughout.</para>
+ <sgmltag class="starttag">p</sgmltag>This is the end of the example.<sgmltag class="endtag">p</sgmltag>]]><sgmltag class="endtag">programlisting</sgmltag></programlisting>
</example>
</sect3>
- <sect3>
+ <sect3 id="xml-primer-include-ignore">
<title><literal>INCLUDE</literal> and
<literal>IGNORE</literal></title>
- <para>If the keyword is <literal>INCLUDE</literal> then the
- contents of the marked section will be processed. If the
- keyword is <literal>IGNORE</literal> then the marked section
+ <para>When the keyword is <literal>INCLUDE</literal>, then the
+ contents of the marked section will be processed. When the
+ keyword is <literal>IGNORE</literal>, the marked section
is ignored and will not be processed. It will not appear in
the output.</para>
@@ -1460,18 +1414,18 @@ example.xml:5: element head: validity er
]]></programlisting>
</example>
- <para>By itself, this is not too useful. If you wanted to
- remove text from your document you could cut it out, or wrap
- it in comments.</para>
+ <para>By itself, this is not too useful. Text to be
+ removed from the document could be cut out, or wrapped
+ in comments.</para>
- <para>It becomes more useful when you realize you can use
+ <para>It becomes more useful when controlled by
<link linkend="xml-primer-parameter-entities">parameter
- entities</link> to control this, yet this usage is limited
+ entities</link>, 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
+ <para>For example, suppose that documentation was produced in a hard-copy
+ version and an electronic version. Some extra text is desired in
+ the electronic version
content that was not to appear in the hard-copy.</para>
<para>Create an entity file that defines general entities
@@ -1482,12 +1436,12 @@ example.xml:5: element head: validity er
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
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list