svn commit: r42265 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer
Warren Block
wblock at FreeBSD.org
Sat Jul 13 01:50:57 UTC 2013
Author: wblock
Date: Sat Jul 13 01:50:56 2013
New Revision: 42265
URL: http://svnweb.freebsd.org/changeset/doc/42265
Log:
Whitespace-only cleanups. Translators, please ignore.
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 Sat Jul 13 01:34:35 2013 (r42264)
+++ head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Sat Jul 13 01:50:56 2013 (r42265)
@@ -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 er
<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 er
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 er
-- 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 er
-- 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 er
<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 er
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
¤t.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>
-
- <para>These symbols can be included by using two predefined general entities:
- <literal><</literal> and <literal>&</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>
+ 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>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 er
<!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 square brackets are necessary to indicate that
- the DTD indicated by the DOCTYPE
- declaration is being extended.</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>
</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>
-
- <para>For a mnemonic, think <quote><emphasis>P</emphasis>arameter entities use
- the <emphasis>P</emphasis>ercent
- symbol</quote>.</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>
<example>
<title>Defining Parameter Entities</title>
@@ -1026,36 +1032,37 @@ example.xml:5: element head: validity er
<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>
-
- <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>
+ 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>
<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 er
<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 er
<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 er
(<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 er
<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 er
<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 er
<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 er
<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 er
<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 er
<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 er
<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 er
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>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>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
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 er
<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>
More information about the svn-doc-all
mailing list