Whitespace-only cleanups. Translators, please ignore.
This commit is contained in:
Warren Block
parent
9fb390caa3
commit
0041e1e330
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42265
1 changed files with 158 additions and 151 deletions
|
|
@ -34,10 +34,11 @@
|
|||
<chapter id="xml-primer">
|
||||
<title>XML Primer</title>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<para>Portions of this section were inspired by Mark Galassi's
|
||||
<ulink
|
||||
|
|
@ -133,7 +134,8 @@
|
|||
<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, or <emphasis>schema</emphasis>.</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
|
||||
|
|
@ -784,10 +786,10 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<title>Escaping Back to <acronym>XML</acronym></title>
|
||||
|
||||
<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>
|
||||
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
|
||||
|
|
@ -795,15 +797,17 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
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> shown earlier is an example of <acronym>XML</acronym> syntax included in the 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 <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
|
||||
<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 <acronym>XML</acronym> syntax within the document.</para>
|
||||
|
||||
<para>The delimiter for XML comments is the string
|
||||
|
|
@ -824,16 +828,16 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
-- doing multiline comments --></programlisting>
|
||||
</example>
|
||||
|
||||
<para><acronym>XHTML</acronym> user may be familiar with
|
||||
different rules for comments. In particular, it is often believed 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> 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>
|
||||
<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 <acronym>XML</acronym> Comments</title>
|
||||
|
|
@ -844,13 +848,13 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
|
||||
-- back inside the comment --></programlisting>
|
||||
|
||||
<para>The <acronym>XML</acronym> parser will treat this as though it were
|
||||
actually:</para>
|
||||
<para>The <acronym>XML</acronym> parser will treat this as
|
||||
though it were actually:</para>
|
||||
|
||||
<programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting>
|
||||
|
||||
<para>That is not valid <acronym>XML</acronym>, and may give confusing error
|
||||
messages.</para>
|
||||
<para>That is not valid <acronym>XML</acronym>, and may give
|
||||
confusing error messages.</para>
|
||||
</example>
|
||||
|
||||
<sect2>
|
||||
|
|
@ -877,17 +881,17 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<title>Entities</title>
|
||||
|
||||
<para>Entities are a mechanism for assigning names to chunks of
|
||||
content. As an <acronym>XML</acronym> parser processes a document, any
|
||||
entities it finds are replaced by the content of the
|
||||
entity.</para>
|
||||
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 <acronym>XML</acronym> documents. It is also the only
|
||||
way to include one marked up file inside another using
|
||||
<acronym>XML</acronym>.</para>
|
||||
chunks of content in <acronym>XML</acronym> documents. It is
|
||||
also the only way to include one marked up file inside another
|
||||
using <acronym>XML</acronym>.</para>
|
||||
|
||||
<para>There are two types of entities for 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">
|
||||
|
|
@ -898,35 +902,37 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
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
|
||||
<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>
|
||||
current version number of a product. To use it in the
|
||||
document, write:</para>
|
||||
|
||||
<programlisting><sgmltag class="starttag">para</sgmltag>The current version of our product is
|
||||
&current.version;.<sgmltag class="endtag">para</sgmltag></programlisting>
|
||||
|
||||
<para>When the version number changes, edit the
|
||||
definition of the general entity, replacing the value. Then reprocess
|
||||
the document.</para>
|
||||
<para>When the version number changes, edit the definition of
|
||||
the general entity, replacing the value. Then reprocess the
|
||||
document.</para>
|
||||
|
||||
<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 <acronym>XML</acronym> document. The <acronym>XML</acronym>
|
||||
could not otherwise be included in an <acronym>XML</acronym>
|
||||
document. For example, <literal><</literal> and
|
||||
<literal>&</literal> 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>
|
||||
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>&lt;</literal> and <literal>&amp;</literal>.</para>
|
||||
<para>These symbols can be included by using two predefined
|
||||
general entities: <literal>&lt;</literal> and
|
||||
<literal>&amp;</literal>.</para>
|
||||
|
||||
<para>General entities can only be defined within an <acronym>XML</acronym>
|
||||
context. Such definitions are usually done immediately after the
|
||||
DOCTYPE declaration.</para>
|
||||
<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>
|
||||
|
|
@ -937,39 +943,39 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<!ENTITY last.version "2.2.7-RELEASE">
|
||||
]></programlisting>
|
||||
|
||||
<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,
|
||||
the square bracket is closed, and then the DOCTYPE
|
||||
declaration is closed.</para>
|
||||
<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, the
|
||||
square bracket is closed, and then the DOCTYPE declaration
|
||||
is closed.</para>
|
||||
|
||||
<para>The square brackets are necessary to indicate that
|
||||
the DTD indicated by the DOCTYPE
|
||||
declaration is being extended.</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>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
|
||||
<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 entity definitons are similar to those for general
|
||||
entities. However, parameter entries are included with
|
||||
<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>
|
||||
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>
|
||||
<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>
|
||||
|
|
@ -1026,36 +1032,37 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<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>
|
||||
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> 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>
|
||||
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><command>xmllint</command> can be used for
|
||||
this. It also has an option to drop the initial
|
||||
<acronym>DTD</acronym> section so that the closing <literal>]<</literal>
|
||||
does not confuse browsers:</para>
|
||||
<para><command>xmllint</command> can be used for this. It
|
||||
also has an option to drop the initial
|
||||
<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>A normalized copy of the document with entities expanded
|
||||
is produced in
|
||||
<filename>example.html</filename>, ready to load into a
|
||||
web browser.</para>
|
||||
<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>
|
||||
</sect2>
|
||||
|
|
@ -1066,15 +1073,15 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
|
||||
<para>Both
|
||||
<link linkend="xml-primer-general-entities">general</link> and
|
||||
<link linkend="xml-primer-parameter-entities">parameter</link> entities
|
||||
are particularly useful for including 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>Consider some content for an <acronym>XML</acronym> book organized
|
||||
into files, one file per chapter, called
|
||||
<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> that will contain these
|
||||
|
|
@ -1082,9 +1089,9 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
|
||||
<para>In order to use the contents of these files as the values
|
||||
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>
|
||||
<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>
|
||||
|
|
@ -1112,9 +1119,9 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
(<filename>chapter1.xml</filename>,
|
||||
<filename>chapter2.xml</filename>, and so on)
|
||||
<emphasis>must not</emphasis> start with a DOCTYPE
|
||||
declaration. This is a syntax error because entities
|
||||
are low-level constructs and they are resolved before
|
||||
any parsing happens.</para>
|
||||
declaration. This is a syntax error because entities are
|
||||
low-level constructs and they are resolved before any
|
||||
parsing happens.</para>
|
||||
</warning>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -1124,8 +1131,7 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<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>
|
||||
to ensure that general entities are reusable.</para>
|
||||
|
||||
<para>Suppose that there are many chapters in the document, and
|
||||
these chapters were reused in two different books, each book
|
||||
|
|
@ -1184,8 +1190,7 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<filename>para2.xml</filename>, and
|
||||
<filename>para3.xml</filename>.</para>
|
||||
|
||||
<para>Put content like this in each
|
||||
file:</para>
|
||||
<para>Put content like this in each file:</para>
|
||||
|
||||
<programlisting><sgmltag class="starttag">p</sgmltag>This is the first paragraph.<sgmltag class="endtag">p</sgmltag></programlisting>
|
||||
</step>
|
||||
|
|
@ -1238,7 +1243,8 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<title>Use Parameter Entities to Include Files</title>
|
||||
|
||||
<note>
|
||||
<para>The previous steps must have completed before this step.</para>
|
||||
<para>The previous steps must have completed before this
|
||||
step.</para>
|
||||
</note>
|
||||
|
||||
<procedure>
|
||||
|
|
@ -1299,9 +1305,10 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<sect1 id="xml-primer-marked-sections">
|
||||
<title>Marked Sections</title>
|
||||
|
||||
<para><acronym>XML</acronym> provides a mechanism to indicate that particular pieces
|
||||
of the document should be processed in a special way. These are
|
||||
called <quote>marked sections</quote>.</para>
|
||||
<para><acronym>XML</acronym> provides a mechanism to indicate that
|
||||
particular pieces of the document should be processed in a
|
||||
special way. These are called
|
||||
<quote>marked sections</quote>.</para>
|
||||
|
||||
<example>
|
||||
<title>Structure of a Marked Section</title>
|
||||
|
|
@ -1314,8 +1321,7 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<para>As expected of an <acronym>XML</acronym> construct, a marked
|
||||
section starts with <literal><!</literal>.</para>
|
||||
|
||||
<para>The first square bracket begins the marked
|
||||
section.</para>
|
||||
<para>The first square bracket begins the marked section.</para>
|
||||
|
||||
<para><replaceable>KEYWORD</replaceable> describes how this marked
|
||||
section is to be processed by the parser.</para>
|
||||
|
|
@ -1325,7 +1331,8 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
|
||||
<para>The marked section is finished by closing the two square
|
||||
brackets, and then returning to the document context from the
|
||||
<acronym>XML</acronym> context with <literal>></literal>.</para>
|
||||
<acronym>XML</acronym> context with
|
||||
<literal>></literal>.</para>
|
||||
|
||||
<sect2 id="xml-primer-marked-section-keywords">
|
||||
<title>Marked Section Keywords</title>
|
||||
|
|
@ -1337,30 +1344,30 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<emphasis>content model</emphasis>, and allow you to change
|
||||
it from the default.</para>
|
||||
|
||||
<para>When an <acronym>XML</acronym> parser is processing a document, it keeps
|
||||
track of the <quote>content
|
||||
model</quote>.</para>
|
||||
<para>When an <acronym>XML</acronym> parser is processing a
|
||||
document, it keeps track of the
|
||||
<quote>content model</quote>.</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
|
||||
<literal>CDATA</literal> content model is one of the most useful.</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>. 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>
|
||||
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 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,
|
||||
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>
|
||||
|
|
@ -1423,27 +1430,26 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
entities</link>, yet this usage is limited
|
||||
to entity files.</para>
|
||||
|
||||
<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>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
|
||||
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
|
||||
<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 the
|
||||
first definition always takes effect. So the
|
||||
inclusion of the chapter is controlled with the corresponding parameter
|
||||
entity. Set to <literal>INCLUDE</literal>, the
|
||||
first general entity definition will be read and the
|
||||
second one will be ignored. Set to
|
||||
<literal>IGNORE</literal>, the first definition will be
|
||||
ignored and the second one will take effect.</para>
|
||||
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 the first definition
|
||||
always takes effect. So the inclusion of the chapter is
|
||||
controlled with the corresponding parameter entity. Set to
|
||||
<literal>INCLUDE</literal>, the first general entity
|
||||
definition will be read and the second one will be ignored.
|
||||
Set 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
|
||||
|
|
@ -1504,10 +1510,11 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<sect1 id="xml-primer-conclusion">
|
||||
<title>Conclusion</title>
|
||||
|
||||
<para>That is the conclusion of this <acronym>XML</acronym> primer. For reasons of
|
||||
space and complexity, several things have not been covered in
|
||||
depth (or at all). However, the previous sections cover enough
|
||||
<acronym>XML</acronym> to introduce the organization of the <acronym>FDP</acronym>
|
||||
<para>That is the conclusion of this <acronym>XML</acronym>
|
||||
primer. For reasons of space and complexity, several things
|
||||
have not been covered in depth (or at all). However, the
|
||||
previous sections cover enough <acronym>XML</acronym> to
|
||||
introduce the organization of the <acronym>FDP</acronym>
|
||||
documentation.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue