Date: Sat, 13 Jul 2013 01:50:56 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42265 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer Message-ID: <201307130150.r6D1oulf033317@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 &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> - - <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> + 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>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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307130150.r6D1oulf033317>