From 0041e1e3304405d709c4c9238c7113ea7e803ce0 Mon Sep 17 00:00:00 2001 From: Warren Block Date: Sat, 13 Jul 2013 01:50:56 +0000 Subject: [PATCH] Whitespace-only cleanups. Translators, please ignore. --- .../books/fdp-primer/xml-primer/chapter.xml | 309 +++++++++--------- 1 file changed, 158 insertions(+), 151 deletions(-) diff --git a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml index dac479496b..21f356e496 100644 --- a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml @@ -34,10 +34,11 @@ XML Primer - Most FDP documentation is written with markup languages based - on XML. This chapter explains what that means, - how to read and understand the documentation source, and the - XML techniques used. + Most FDP documentation is written with + markup languages based on XML. This chapter + explains what that means, how to read and understand the + documentation source, and the XML techniques + used. Portions of this section were inspired by Mark Galassi's Each language definition is more properly called a grammar, vocabulary, schema or Document Type Definition (DTD). There are various languages to - specify an XML grammar, or schema. + specify an XML grammar, or + schema. A schema is a complete specification of all the elements @@ -784,10 +786,10 @@ example.xml:5: element head: validity error : Element head content does not foll Escaping Back to <acronym>XML</acronym> Some of the underlying XML 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 XML syntax. - Other uses for XML syntax will be shown later. + useful within documents. For example, comments can be included + in the document, and will be ignored by the parser. Comments + are entered using XML syntax. Other uses for + XML syntax will be shown later. XML sections begin with a <! 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 XML syntax. The DOCTYPE - declaration shown earlier is an example of XML syntax included in the document. + declaration shown earlier is an example of + XML syntax included in the document. + Comments - Comments are an XML construct, and are normally only - valid inside a DTD. However, as - shows, it is possible + Comments are an XML construct, and are + normally only valid inside a DTD. However, + as shows, it is possible to use XML syntax within the document. 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 --> - XHTML user may be familiar with - different rules for comments. In particular, it is often believed that + XHTML user may be familiar with different + rules for comments. In particular, it is often believed that the string <!-- opens a comment, and it is only closed by -->. - This is not correct. Many web - browsers have broken XHTML parsers, and will accept incorrect input as - valid. However, the XML parsers used by the Documentation - Project are more strict, and will reject documents with - that error. + This is not correct. Many web browsers + have broken XHTML parsers, and will accept + incorrect input as valid. However, the XML + parsers used by the Documentation Project are more strict, and + will reject documents with that error. Erroneous <acronym>XML</acronym> Comments @@ -844,13 +848,13 @@ example.xml:5: element head: validity error : Element head content does not foll -- back inside the comment --> - The XML parser will treat this as though it were - actually: + The XML parser will treat this as + though it were actually: <!THIS IS OUTSIDE THE COMMENT> - That is not valid XML, and may give confusing error - messages. + That is not valid XML, and may give + confusing error messages. @@ -877,17 +881,17 @@ example.xml:5: element head: validity error : Element head content does not foll Entities Entities are a mechanism for assigning names to chunks of - content. As an XML parser processes a document, any - entities it finds are replaced by the content of the - entity. + content. As an XML parser processes a + document, any entities it finds are replaced by the content of + the entity. This is a good way to have re-usable, easily changeable - chunks of content in XML documents. It is also the only - way to include one marked up file inside another using - XML. + chunks of content in XML documents. It is + also the only way to include one marked up file inside another + using XML. - There are two types of entities for two - different situations: general entities and + There are two types of entities for two different + situations: general entities and parameter 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 XML context. - To include the text of a general entity in the document, include - &entity-name; in the text. - For example, consider a general entity called + To include the text of a general entity in the document, + include + &entity-name; + in the text. For example, consider a general entity called current.version which expands to the - current version number of a product. To use it in the document, - write: + current version number of a product. To use it in the + document, write: paraThe current version of our product is &current.version;.para - When the version number changes, edit the - definition of the general entity, replacing the value. Then reprocess - the document. + When the version number changes, edit the definition of + the general entity, replacing the value. Then reprocess the + document. General entities can also be used to enter characters that - could not otherwise be included in an XML document. For - example, < and & - cannot normally appear in an XML document. The XML + could not otherwise be included in an XML + document. For example, < and + & cannot normally appear in an + XML document. The XML parser sees the < symbol as the start of - a tag. Likewise, when the - & symbol is seen, the next text is expected to - be an entity name. + a tag. Likewise, when the & symbol is + seen, the next text is expected to be an entity name. - These symbols can be included by using two predefined general entities: - &lt; and &amp;. + These symbols can be included by using two predefined + general entities: &lt; and + &amp;. - General entities can only be defined within an XML - context. Such definitions are usually done immediately after the - DOCTYPE declaration. + General entities can only be defined within an + XML context. Such definitions are usually + done immediately after the DOCTYPE declaration. Defining General Entities @@ -937,39 +943,39 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY last.version "2.2.7-RELEASE"> ]> - 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. + 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. - The square brackets are necessary to indicate that - the DTD indicated by the DOCTYPE - declaration is being extended. + The square brackets are necessary to indicate that the + DTD indicated by the DOCTYPE declaration is being + extended. Parameter Entities - Parameter entities, like general - entities, are used to assign names - to reusable chunks of text. But - parameter entities can - only be used within an XML + Parameter entities, like + general + entities, are used to assign names to reusable chunks + of text. But parameter entities can only be used within an + XML context. - Parameter entity definitons are similar to those for general - entities. However, parameter entries are included with + Parameter entity definitons are similar to those for + general entities. However, parameter entries are included + with %entity-name;. - The definition also includes - the % between the ENTITY - keyword and the name of the entity. + The definition also includes the % between + the ENTITY keyword and the name of the + entity. - For a mnemonic, think Parameter entities use - the Percent - symbol. + For a mnemonic, think + Parameter entities use the + Percent symbol. Defining Parameter Entities @@ -1026,36 +1032,37 @@ example.xml:5: element head: validity error : Element head content does not foll Load example.xml into a web browser. It may have to be copied to example.html before the browser - recognizes it as an XHTML document. - - Older browsers with simple parsers may not render - this file as expected. The entity reference &version; may not be replaced by - the version number, or the XML context closing - ]< may not be - recognized and instead shown in the output. + recognizes it as an XHTML + document. + Older browsers with simple parsers may not render this + file as expected. The entity reference + &version; may not be replaced by + the version number, or the XML context + closing ]< may not be recognized and + instead shown in the output. The solution is to normalize the - document with an XML normalizer. The normalizer reads - valid XML and writes equally valid XML 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. + document with an XML normalizer. The + normalizer reads valid XML and writes + equally valid XML 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. - xmllint can be used for - this. It also has an option to drop the initial - DTD section so that the closing ]< - does not confuse browsers: + xmllint can be used for this. It + also has an option to drop the initial + DTD section so that the closing + ]< does not confuse browsers: &prompt.user; xmllint --noent --dropdtd example.xml > example.html - A normalized copy of the document with entities expanded - is produced in - example.html, ready to load into a - web browser. + A normalized copy of the document with entities + expanded is produced in example.html, + ready to load into a web browser. @@ -1066,15 +1073,15 @@ example.xml:5: element head: validity error : Element head content does not foll Both general and - parameter entities - are particularly useful for including one file inside + parameter + entities are particularly useful for including one file inside another. Using General Entities to Include Files - Consider some content for an XML book organized - into files, one file per chapter, called + Consider some content for an XML book + organized into files, one file per chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml that will contain these @@ -1082,9 +1089,9 @@ example.xml:5: element head: validity error : Element head content does not foll In order to use the contents of these files as the values for entities, they are declared with the - SYSTEM keyword. This directs the XML - parser to include the contents of the named file as the value of - the entity. + SYSTEM keyword. This directs the + XML parser to include the contents of the + named file as the value of the entity. Using General Entities to Include Files @@ -1112,9 +1119,9 @@ example.xml:5: element head: validity error : Element head content does not foll (chapter1.xml, chapter2.xml, and so on) must not start with a DOCTYPE - declaration. This is a syntax error because entities - are low-level constructs and they are resolved before - any parsing happens. + declaration. This is a syntax error because entities are + low-level constructs and they are resolved before any + parsing happens. @@ -1124,8 +1131,7 @@ example.xml:5: element head: validity error : Element head content does not foll Parameter entities can only be used inside an XML context. Including a file in an XML context can be used - to ensure that general - entities are reusable. + to ensure that general entities are reusable. 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 para2.xml, and para3.xml. - Put content like this in each - file: + Put content like this in each file: pThis is the first paragraph.p @@ -1238,7 +1243,8 @@ example.xml:5: element head: validity error : Element head content does not foll Use Parameter Entities to Include Files - The previous steps must have completed before this step. + The previous steps must have completed before this + step. @@ -1299,9 +1305,10 @@ example.xml:5: element head: validity error : Element head content does not foll Marked Sections - XML provides a mechanism to indicate that particular pieces - of the document should be processed in a special way. These are - called marked sections. + XML provides a mechanism to indicate that + particular pieces of the document should be processed in a + special way. These are called + marked sections. Structure of a Marked Section @@ -1314,8 +1321,7 @@ example.xml:5: element head: validity error : Element head content does not foll As expected of an XML construct, a marked section starts with <!. - The first square bracket begins the marked - section. + The first square bracket begins the marked section. KEYWORD describes how this marked section is to be processed by the parser. @@ -1325,7 +1331,8 @@ example.xml:5: element head: validity error : Element head content does not foll The marked section is finished by closing the two square brackets, and then returning to the document context from the - XML context with >. + XML context with + >. Marked Section Keywords @@ -1337,30 +1344,30 @@ example.xml:5: element head: validity error : Element head content does not foll content model, and allow you to change it from the default. - When an XML parser is processing a document, it keeps - track of the content - model. + When an XML parser is processing a + document, it keeps track of the + content model. The content model describes the content the parser is expecting to see and what it will do with that content. - The - CDATA content model is one of the most useful. + The CDATA content model is one of the + most useful. CDATA is for Character Data. When the parser is in this - content model, it expects to see only characters. - In this model the < - and & symbols lose their special - status, and will be treated as ordinary characters. + content model, it expects to see only characters. In this + model the < and + & symbols lose their special status, + and will be treated as ordinary characters. When using CDATA in examples of - text marked up in XML, remember that the content of - CDATA 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 XML, remember that + the content of CDATA 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 CDATA section. @@ -1423,27 +1430,26 @@ example.xml:5: element head: validity error : Element head content does not foll entities, yet this usage is limited to entity files. - 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. + 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. - 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 - INCLUDE or IGNORE - to control whether the entity is defined. After these + 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 + INCLUDE or IGNORE 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 INCLUDE, the - first general entity definition will be read and the - second one will be ignored. Set to - IGNORE, the first definition will be - ignored and the second one will take effect. + 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 + INCLUDE, the first general entity + definition will be read and the second one will be ignored. + Set to IGNORE, the first definition will + be ignored and the second one will take effect. 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 - That is the conclusion of this XML primer. For reasons of - space and complexity, several things have not been covered in - depth (or at all). However, the previous sections cover enough - XML to introduce the organization of the FDP + That is the conclusion of this XML + primer. For reasons of space and complexity, several things + have not been covered in depth (or at all). However, the + previous sections cover enough XML to + introduce the organization of the FDP documentation.