Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1556
News FAQ
Search Home


next up previous contents index
Next: Example Header File Up: Documentation 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 LATEX. 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: 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:

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

Paragraphs

Elements

Sections

Paragraphs

Warnings and Notations

Literal Sections

Lists

Titles

Class Categories

Descriptors

Device I/O

Exceptions

General Entities (for LATEX)

Required Because of Tags

Typically Unnecessary


next up previous contents index
Next: Example Header File Up: Documentation Previous: Document Generation   Contents   Index
Please send questions or comments about AIPS++ to aips2-request@nrao.edu.
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.

Return to AIPS++ Home Page
2006-10-15