From owner-svn-doc-head@FreeBSD.ORG Sat Jul 13 01:34:36 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 01EEA4DF; Sat, 13 Jul 2013 01:34:35 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id E5A221B79; Sat, 13 Jul 2013 01:34:35 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6D1YZEj028128; Sat, 13 Jul 2013 01:34:35 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6D1YZBI028127; Sat, 13 Jul 2013 01:34:35 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307130134.r6D1YZBI028127@svn.freebsd.org> From: Warren Block Date: Sat, 13 Jul 2013 01:34:35 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42264 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 13 Jul 2013 01:34:36 -0000 Author: wblock Date: Sat Jul 13 01:34:35 2013 New Revision: 42264 URL: http://svnweb.freebsd.org/changeset/doc/42264 Log: Continue editing the XML primer for clarity and to conform with modern usage of the FDP tools. The hippo did not want to give up the stilts and pogo stick, but eventually agreed that it was best for everyone. Modified: head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Fri Jul 12 22:03:39 2013 (r42263) +++ head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml Sat Jul 13 01:34:35 2013 (r42264) @@ -34,7 +34,7 @@ XML Primer - Most FDP documentation is written with markup languages based + 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. @@ -133,13 +133,7 @@ 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, for example, - DTD (yes, it also means the specification - language itself), XML Schema - (XSD) or RELANG NG. The - schema specifies the name of the elements that can be used, what - order they appear in (and whether some markup can be used inside - other markup) and related information. + specify an XML grammar, or schema. A schema is a complete specification of all the elements @@ -155,7 +149,7 @@ validating the document. - This processing simply confirms that the choice of + Validation confirms that the choice of elements, their ordering, and so on, conforms to that listed in the grammar. It does not check whether appropriate markup has been used @@ -166,7 +160,7 @@ allowed to appear in the same place). - It is likely that most contributions to the Documentation + Most contributions to the Documentation Project will be content marked up in either XHTML or DocBook, rather than alterations to the schemas. For this reason, this book will not touch on how @@ -585,7 +579,7 @@ example.xml:5: element head: validity er Formal Public Identifiers - (<acronym>FPI</acronym>s) + (FPI) Formal Public Identifier @@ -712,7 +706,7 @@ example.xml:5: element head: validity er DTD is called transitional.dtd in the 1.0 subdirectory of the directory that - held the catalog file. + held catalog. Examine the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. @@ -725,7 +719,7 @@ example.xml:5: element head: validity er <envar>SGML_CATALOG_FILES</envar> - To locate a catalog file, the + To locate a catalog, the XML processor must know where to look. Many feature command line parameters for specifying the path to one or more catalogs. @@ -787,102 +781,80 @@ example.xml:5: element head: validity er - Escaping Back to SGML + Escaping Back to <acronym>XML</acronym> - As mentioned earlier, XML is only used when writing a DTD. - This is not strictly true. There is certain XML syntax that - you will want to be able to use within your documents. For - example, comments can be included in your document, and will be - ignored by the parser. Comments are entered using XML syntax. - Other uses for XML syntax in your document will be shown later - too. - - Obviously, you need some way of indicating to the XML - processor that the following content is not elements within the - document, but is XML that the parser should act upon. - - These sections are marked by - <! ... > in your document. Everything - between these delimiters is XML syntax as you might find within - a DTD. - - As you may just have realized, the + 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. + + XML sections begin with a + <! tag and end with a + >. These sections contain instructions + for the parser rather than elements of the document. Everything + between these tags is XML syntax. The DOCTYPE - declaration is an example of XML syntax that you need - to include in your document… + declaration shown earlier is an example of XML syntax included in the document. Comments - Comments are an XML construction, and are normally only - valid inside a DTD. However, as + Comments are an XML construct, and are normally only + valid inside a DTD. However, as shows, it is possible - to use XML syntax within your document. + to use XML syntax within the document. The delimiter for XML comments is the string --. The first occurrence of this string opens a comment, and the second closes it. - XML Generic Comment - - <!-- test comment --> + <acronym>XML</acronym> Generic Comment - + <!-- This is inside the comment --> - +<!-- This is another comment --> - +<!-- This is one way + of doing multiline comments --> -]]> +<!-- This is another way of -- + -- doing multiline comments --> - If you have used XHTML before you may have been shown - different rules for comments. In particular, you may think 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 the case. A lot of web - browsers have broken XHTML parsers, and will accept that as - valid. However, the XML parsers used by the Documentation - Project are much stricter, and will reject documents that make + 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 XML Comments + Erroneous <acronym>XML</acronym> Comments - <!-- This is in the comment -- THIS IS OUTSIDE THE COMMENT! - -- back inside the comment -->]]> + -- back inside the comment --> - The XML parser will treat this as though it were + The XML parser will treat this as though it were actually: <!THIS IS OUTSIDE THE COMMENT> - This is not valid XML, and may give confusing error + That is not valid XML, and may give confusing error messages. - - ]]> - - As the example suggests, do not write - comments like that. - - ]]> - - That is a (slightly) better approach, but it still - potentially confusing to people new to XML. - For You to Do… + To Do… @@ -905,150 +877,144 @@ example.xml:5: element head: validity er Entities Entities are a mechanism for assigning names to chunks of - content. As an XML parser processes your document, any + 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 your XML documents. It is also the only + chunks of content in XML documents. It is also the only way to include one marked up file inside another using - XML. + XML. - There are two types of entities which can be used in two - different situations; general entities and + There are two types of entities for two + different situations: general entities and parameter entities. General Entities - You cannot use general entities in an XML context - (although you define them in one). They can only be used in - your document. Contrast this with parameter - entities. - - Each general entity has a name. When you want to - reference a general entity (and therefore include whatever - text it represents in your document), you write - &entity-name;. - For example, suppose you had an entity called - current.version which expanded to the - current version number of your product. You could + General entities are used to assign names to reusable + chunks of text. These entities can only be used in the + document. They cannot be used in an + 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 + current.version which expands to the + current version number of a product. To use it in the document, write: - The current version of our product is - ¤t.version;.]]> + paraThe current version of our product is + &current.version;.para - When the version number changes you can simply change the - definition of the value of the general entity and reprocess - your document. + When the version number changes, edit the + definition of the general entity, replacing the value. Then reprocess + the document. - You can also use general entities to enter characters that - you could not otherwise include in an XML document. For + 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. When the XML - parser sees the < symbol it assumes that - a tag (either a start tag or an end tag) is about to appear, - and when it sees the & symbol it - assumes the next text will be the name of an entity. - - Fortunately, you can use the two general entities - &lt; and &amp; - whenever you need to include one or other of these. + 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. + + These symbols can be included by using two predefined general entities: + &lt; and &amp;. - A general entity can only be defined within an XML - context. Typically, this is done immediately after the + General entities can only be defined within an XML + context. Such definitions are usually done immediately after the DOCTYPE declaration. Defining General Entities - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - - -]>]]> +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]> - Notice how the DOCTYPE declaration has been extended by + The DOCTYPE declaration has been extended by adding a square bracket at the end of the first line. The two entities are then defined over the next two lines, - before the square bracket is closed, and then the DOCTYPE + the square bracket is closed, and then the DOCTYPE declaration is closed. - The square brackets are necessary to indicate that we - are extending the DTD indicated by the DOCTYPE - declaration. + The square brackets are necessary to indicate that + the DTD indicated by the DOCTYPE + declaration is being extended. Parameter Entities - Like general - entities, parameter entities are used to assign names - to reusable chunks of text. However, whereas general entities - can only be used within your document, parameter entities can + 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 entities are defined in a similar way to general - entities. However, instead of using - &entity-name; - to refer to them, use - %entity-name; - Parameter entities use - the Percent - symbol.. The definition also includes + 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. + For a mnemonic, think Parameter entities use + the Percent + symbol. + Defining Parameter Entities - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - - - +<!ENTITY % param.some "some"> +<!ENTITY % param.text "text"> +<!ENTITY % param.new "%param.some more %param.text"> - -]>]]> +<!-- %param.new now contains "some more text" --> +]> - - This may not seem particularly useful. It will be. - For You to Do… + To Do… Add a general entity to example.xml. - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - -]> +<!ENTITY version "1.1"> +]> - - - An Example XHTML File - +html xmlns="http://www.w3.org/1999/xhtml" + head + titleAn Example XHTML Filetitle + head - + <!-- There may be some comments in here as well --> - -

This is a paragraph containing some text.

+ body + pThis is a paragraph containing some text.p -

This paragraph contains some more text.

+ pThis paragraph contains some more text.p -

This paragraph might be right-justified.

+ p align="right"This paragraph might be right-justified.p -

The current version of this document is: &version;

- -]]> + pThe current version of this document is: &version;p + body +html @@ -1057,41 +1023,38 @@ example.xml:5: element head: validity er - Load example.xml into your web - browser (you may need to copy it to - example.html before your browser - recognizes it as an XHTML document). - - Unless your browser is very advanced, you will not see - the entity reference &version; - replaced with the version number. Most web browsers have - very simplistic parsers which do not handle XML DTD - constructs. Furthermore, the closing - ]< of the XML context are not - recognized properly by browser and will probably be - rendered. + 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. - The solution is to normalize your - document using an XML normalizer. The normalizer reads - in valid XML and outputs equally valid XML which has - been transformed in some way. One of the ways in which - the normalizer transforms the XML is to expand all the + 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. - You can use xmllint to do + xmllint can be used for this. It also has an option to drop the initial - DTD section so that the closing ]< + DTD section so that the closing ]< does not confuse browsers: &prompt.user; xmllint --noent --dropdtd example.xml > example.html - You should find a normalized (i.e., entity references - expanded) copy of your document in - example.html, ready to load into your + A normalized copy of the document with entities expanded + is produced in + example.html, ready to load into a web browser. @@ -1101,46 +1064,46 @@ example.xml:5: element head: validity er Using Entities to Include Files - Entities (both + Both general and - parameter) - are particularly useful when used to include one file inside + parameter entities + are particularly useful for including one file inside another. Using General Entities to Include Files - Suppose you have some content for an XML book organized + 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 file that will contain these + book.xml that will contain these chapters. In order to use the contents of these files as the values - for your entities, you declare them with the - SYSTEM keyword. This directs the XML - parser to use the contents of the named file as the value of + for entities, they are declared with the + 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 - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - - - - -]> - - - - - &chapter.1; - &chapter.2; - &chapter.3; -]]> +<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"> +<!-- And so forth --> +]> + +html xmlns="http://www.w3.org/1999/xhtml" + <!-- Use the entities to load in the chapters --> + + &chapter.1; + &chapter.2; + &chapter.3; +html @@ -1158,60 +1121,59 @@ example.xml:5: element head: validity er Using Parameter Entities to Include Files - Recall that parameter entities can only be used inside an - XML context. Why then would you want to include a file - within an XML context? + 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. - You can use this to ensure that you can reuse your general - entities. - - Suppose that you had many chapters in your document, and - you reused these chapters in two different books, each book + Suppose that there are many chapters in the document, and + these chapters were reused in two different books, each book organizing the chapters in a different fashion. - You could list the entities at the top of each book, but - this quickly becomes cumbersome to manage. + The entities could be listed at the top of each book, but + that quickly becomes cumbersome to manage. Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within - your document. + the document. Using Parameter Entities to Include Files - First, place your entity definitions in a separate file, - called chapters.ent. This file - contains the following: - - - -]]> + Place the entity definitions in a separate file + called chapters.ent and + containing this text: + + <!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"> - Now create a parameter entity to refer to the contents + Create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before: - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - - +<!-- Define a parameter entity to load in the chapter general entities --> +<!ENTITY % chapters SYSTEM "chapters.ent"> - +<!-- Now use the parameter entity to load in this file --> %chapters; -]> +]> - - &chapter.1; - &chapter.2; - &chapter.3; -]]> +html xmlns="http://www.w3.org/1999/xhtml" + &chapter.1; + &chapter.2; + &chapter.3; +html - For You to Do… + To Do… Use General Entities to Include Files @@ -1222,37 +1184,37 @@ example.xml:5: element head: validity er para2.xml, and para3.xml. - Put content similar to the following in each + Put content like this in each file: - This is the first paragraph.

]]> + pThis is the first paragraph.p Edit example.xml so that it looks like this: - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - - - - -]> - - - - An Example XHTML File - - - -

The current version of this document is: &version;

- - ¶1; - ¶2; - ¶3; - -]]> +<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> +]> + +html xmlns="http://www.w3.org/1999/xhtml" + head + titleAn Example XHTML Filetitle + head + + body + pThe current version of this document is: &version;p + + &para1; + &para2; + &para3; + body +html @@ -1263,8 +1225,8 @@ example.xml:5: element head: validity er - Load example.html into your web - browser, and confirm that the + Load example.html into the web + browser and confirm that the paran.xml files have been included in example.html. @@ -1276,7 +1238,7 @@ example.xml:5: element head: validity er Use Parameter Entities to Include Files - You must have taken the previous steps first. + The previous steps must have completed before this step. @@ -1284,35 +1246,35 @@ example.xml:5: element head: validity er Edit example.xml so that it looks like this: - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ - %entities; -]> +<!ENTITY % entities SYSTEM "entities.ent"> %entities; +]> - - - An Example XHTML File - - - -

The current version of this document is: &version;

- - ¶1; - ¶2; - ¶3; - -]]> +html xmlns="http://www.w3.org/1999/xhtml" + head + titleAn Example XHTML Filetitle + head + + body + pThe current version of this document is: &version;p + + &para1; + &para2; + &para3; + body +html - Create a new file, - entities.ent, with this + Create a new file called + entities.ent with this content: - - - -]]> + <!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> @@ -1323,8 +1285,8 @@ example.xml:5: element head: validity er - Load example.html into your web - browser, and confirm that the + Load example.html into the web + browser and confirm that the paran.xml files have been included in example.html. @@ -1337,9 +1299,9 @@ example.xml:5: element head: validity er Marked Sections - XML provides a mechanism to indicate that particular pieces + XML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are - termed marked sections. + called marked sections. Structure of a Marked Section @@ -1349,101 +1311,93 @@ example.xml:5: element head: validity er ]]> - As you would expect, being an XML construct, a marked + As expected of an XML construct, a marked section starts with <!. - The first square bracket begins to delimit the marked + The first square bracket begins the marked section. KEYWORD describes how this marked - section should be processed by the parser. + section is to be processed by the parser. - The second square bracket indicates that the content of the - marked section starts here. + The second square bracket indicates the start of the + marked section's content. The marked section is finished by closing the two square brackets, and then returning to the document context from the - XGML context with >. + XML context with >. - + Marked Section Keywords - + <literal>CDATA</literal> These keywords denote the marked sections content model, and allow you to change it from the default. - When an XML parser is processing a document it keeps - track of what is called the content + When an XML parser is processing a document, it keeps + track of the content model. - Briefly, the content model describes what sort of - content the parser is expecting to see, and what it will do - with it when it finds it. + The content model describes the + content the parser is expecting to see and what it will do + with that content. - The content model you will probably find most - useful is CDATA. + The + CDATA content model is one of the most useful. CDATA is for - Character Data. If the parser is in this - content model then it is expecting to see characters, and - characters only. In this model the < + 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. - When you use CDATA in examples of - text marked up in XML, keep in mind that the content of - CDATA is not validated. You have to - check the included XML text using other means. You could, - for example, write the example in another document, - validate the example code, and then paste it to your - CDATA content. + 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, + validated, and then pasted into the + CDATA section. - Using a <literal>CDATA</literal> Marked Section - <para>Here is an example of how you would include some text - that contained many <literal>&lt;</literal> - and <literal>&amp;</literal> symbols. The sample - text is a fragment of XHTML. The surrounding text (<para> and - <programlisting>) are from DocBook.</para> - -<programlisting> - <![CDATA[This is a sample that shows you some of the elements within - XHTML. Since the angle brackets are used so many times, it is - simpler to say the whole example is a CDATA marked section - than to use the entity names for the left and right angle - brackets throughout.

- -
    -
  • This is a listitem
    • -
  • This is a second listitem
    • -
  • This is a third listitem
    • -
- -

This is the end of the example.

]]> - ]]> -</programlisting> + paraHere is an example of how to include some text that contains + many literal&lt;literal and literal&amp;literal + symbols. The sample text is a fragment of + acronymXHTMLacronym. The surrounding text (para and + programlisting) are from DocBook.para + +programlisting<![CDATA[pThis is a sample that shows some of the + elements within acronymXHTMLacronym. Since the angle + brackets are used so many times, it is simpler to say the whole + example is a CDATA marked section than to use the entity names for + the left and right angle brackets throughout.p + + ul + liThis is a listitemli + liThis is a second listitemli + liThis is a third listitemli + ul - If you look at the source for this document you will - see this technique used throughout. + pThis is the end of the example.p]]>programlisting - + <literal>INCLUDE</literal> and <literal>IGNORE</literal> - If the keyword is INCLUDE then the - contents of the marked section will be processed. If the - keyword is IGNORE then the marked section + When the keyword is INCLUDE, then the + contents of the marked section will be processed. When the + keyword is IGNORE, the marked section is ignored and will not be processed. It will not appear in the output. @@ -1460,18 +1414,18 @@ example.xml:5: element head: validity er ]]> - By itself, this is not too useful. If you wanted to - remove text from your document you could cut it out, or wrap - it in comments. + By itself, this is not too useful. Text to be + removed from the document could be cut out, or wrapped + in comments. - It becomes more useful when you realize you can use + It becomes more useful when controlled by parameter - entities to control this, yet this usage is limited + entities, yet this usage is limited to entity files. - For example, suppose that you produced a hard-copy - version of some documentation and an electronic version. In - the electronic version you wanted to include some extra + 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 @@ -1482,12 +1436,12 @@ example.xml:5: element head: validity er conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of the fact that - entity definitions cannot be overridden but always the - first definition takes effect. So you can control the - inclusion of your chapter with the corrsponding parameter *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***