9 Marked Sections

It is occasionally convenient to mark some portion of a text for special treatment by the SGML parser. Certain portions of legal boilerplate, for example, might need to be included or omitted systematically, depending on the state or country in which the document was intended to be valid. (Thus the statement ``Liability is limited to $50,000.'' might need to be included in Delaware, but excluded in Maryland.) Technical manuals for related products might share a great deal of information but differ in some details; it might be convenient to maintain all the information for the entire set of related products in a single document, selecting at display or print time only those portions relevant to one specific product. (Thus, a discussion of how to change the oil in a car might use the same text for most steps, but offer different advice on removing the carburetor, depending on the specific engine model in question.)

SGML provides the marked section construct to handle such practical requirements of document production. In general, as the examples above are intended to suggest, it is more obviously useful in the production of new texts than in the encoding of pre-existing texts. Most users of the TEI encoding scheme will never need to use marked sections, and may wish to skip the remainder of this discussion. The TEI DTD makes extensive use of marked sections, however, and this section should be read and understood carefully by anyone wishing to follow in detail the discussions in chapter chapter 3 : Structure of the TEI Document Type Definition.

The `special processing' offered for marked sections in SGML can be of several types, each associated with one of the following keywords:

INCLUDE The marked section should be included in the document and processed normally.
IGNORE The marked section should be ignored entirely; if the SGML application program produces output from the document, the marked section will be excluded from the document.
CDATA The marked section may contain strings of characters which look like SGML tags or entity references, but which should not be recognized as such by the SGML parser. (These Guidelines use such CDATA marked sections to enclose the examples of SGML tagging.)
RCDATA The marked section may contain strings of characters which look like SGML tags, but which should not be recognized as such by the SGML parser; entity references, on the other hand, may be present and should be recognized and expanded as normal.
TEMP The passage included in the marked section is a temporary part of the document; the marked section is used primarily to indicate its location, so that it can be removed or revised conveniently later.

When a marked section occurs in the text, it is preceded by a marked-section start string, which contains one or more keywords from the list above; its end is marked by a marked-section close string. The second and last lines of the following example are the start and close of a marked section to be ignored:

 In such cases, the bank will reimburse the customer for all losses.
 <![ IGNORE [
 Liability is limited to $50,000.
 ]]>

Of the marked section keywords, the most important for understanding the TEI DTD are INCLUDE and IGNORE; these can be used to include and exclude portions of a document --- or a DTD --- selectively, so as to adjust it to relevant circumstances (e.g. to allow a user to select portions of the DTD relevant to the document in question).

The literal keywords INCLUDE and IGNORE, however, are not much use in adjusting a DTD or a document to a user's requirements, however. (To change the text above to include the excluded sentence, for example, a user would have to edit the text manually and change IGNORE to INCLUDE. It might be thought just as easy to add and delete the sentence manually.) But the keywords need not be given as literal values; they can be represented by a parameter entity reference. In a document with many sentences which should be included only in Maryland, for example, each such sentence can be included in a marked section whose keyword is represented by a reference to a parameter entity named Maryland. The earlier example would then be:

 In such cases, the bank will reimburse the customer for all losses.
 <![ %Maryland; [
 Liability is limited to $50,000.
 ]]>

When the entity Maryland is defined as IGNORE, the marked sections so marked will all be excluded. If the definition is changed to the following, the marked sections will be included in the document:

 <!ENTITY % Maryland 'INCLUDE'>

When parameter entities are used in this way to control marked sections in a DTD, the external DTD file normally contains a default declaration. If the user wishes to override the default (as by including the Maryland sections), adding an appropriate declaration to the DTD subset suffices to override the default. [See note 12]

The examples of parameter entity declarations at the end of the preceding section can now be better understood. The declarations

 <!ENTITY % TEI.prose 'INCLUDE'>
 <!ENTITY % TEI.extensions.dtd SYSTEM 'mystuff.dtd'>

have the effect of including in the DTD all the sections marked as relevant to prose, since in the external DTD files such sections are all included in marked sections controlled by the parameter entity TEI.prose. They also override the default declaration of TEI.extensions.dtd (which declares this entity as an empty string), so as to include the file mystuff.dtd in the DTD.

Back to table of contents
On to next section
Back to previous section