Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Example Header File Up: AIPS++ Documentation System (rev 2) DRAFT Version Previous: Document Generation

Subsections

Document Type Definition

This appendix has the document type definition for the comment markup language. It is written in SGML syntax. The DTD defines ``elements'' and ``entities''. The elements are the lowest level of granularity with which SGML deals. The entities function much like macro; entity references are replaced by the ``body'' of the entity.

There are two basic kinds of entities, general and parameter. The primary reason a distinction is drawn between these two types of entities is so that the general entity name space is unique from the parameter entity name space. Parameter entities are typically used by the designer of the DTD. As a result, parameter entities are typically used within other entity or element definitions. This leaves the person writing a particular document free to use any names when defining general entities.

Entity definitions begin with ``<!entity''. So the definition of a general entity might look like:

<!entity dquot sdata '\{\tt "\}' >

This defines a general entity which can be used to insert ``double quotes'' into a document. This is done by placing a reference to the entity in the document, i.e. ``&dquot;''. Here the ``&'' introduces the entity reference and the ``;'' ends the entity reference. This double quote entity is defined in terms of the formatting language into which the SGML document will be translated, in this case L^ATEX. So these, entities must be changed for each SGML processor. For a plain ASCII system, the entity might look like:

<!entity dquot sdata '"' >

Parameter entities are defined and used in much the same way as general entities. Except that parameter entities are typically used by the DTD designer. The following is an example of a parameter entity definition:

<!entity \% bridgecontent "(p$|$warn$|$note$|$code$|$enum$|$list)" >

This defines a entity bridgecontent. The % indicates that this is a parameter entity instead of a general entity. This parameter entity is later used to define the elements that a <bridge> element can contain:

<!element bridge - o ((\%bridgecontent)*) >

The %bridgecontent entity reference is replace by the body of the entity, (p|warn|note |code|enum|list). Element definitions are introduced with the`` <!element'', as shown above. The element definition has four fields, the name e.g. ``bridge'', a pair of fields which indicate if the opening tag and closing tag are optional or required -- an ``o'' indicates that it is optional and an ``-'' indicates that it is required --, and a field which indicates the contents of the element. The syntax of the contents field is similar to lex:

``*'' - indicates zero or more occurrences
``+'' - indicates one or more occurrences
``?'' - indicates zero or one occurrence
``,'' - indicates a sequence, e.g. (foo,bar) is <foo> followed by <bar>
``|'' - indicates an ``or'', e.g. (foo|bar) means one of <foo> or <bar> must occur
``&'' - indicates an ``and'', e.g. (foo&bar) means <foo> and <bar> must occur, but in any order
``()'' - parentheses provide grouping

So, the <bridge> example above declares a <bridge> element which can in turn contain zero or more <p>, <warn>, <note>, <code>, <enum>, or <list> elements. The opening tag is required, but the closing tag is optional. Elements are the most basic information units handled by SGML. They serve a purpose very similar to productions in a grammar.

In addition to elements and entities, there are several ``special'' characters which are useful to know:

&#TAB; - Horizontal tab
&#RE; - Record end
&#RS; - Record start
&#RS;B - Record start followed by one or more spaces and/or tabs
&#RS;&#RE; - Empty record
&#RS;B&#RE; - Record containing only one or more spaces and/or tabs
B&#RE; - One or more trailing spaces and/or tabs
BB - Two or more spaces and/or tabs.

These ``invisible'' characters are most useful when trying to define keyboard shortcuts which prevent document preparers from having to enter all of the necessary tags. For instance, inserting paragraph tags can be made easer as follows:

<!entity psplit '</p><p>' >
<!shortref pmap "\&\#RS;B\&\#RE;" psplit 
                "\&\#RS;\&\#RE;" psplit >

This allows one to insert paragraph breaks by entering a blank line, i.e. a blank line or an empty line.

Parameter Entities

Sections

<!entity % divcontent @w"(p|warn|note|verbatim|literal| code|enum|list|descriptor|iodev|thrown)">
<!entity % bridgecontent "(p|warn|note|code|enum|list)" >