# 5 Description of all elements

Since the content models are already provided by the BNF grammar above, they will not be repeated here.

`BOOK`

`FRONT`

  This is a container for descriptive information about the document. Beside title, author and abstract, you may also have `META` elements that make (property) statements about the document.

  > `<META name="ozversion" value="3.0">`

`TITLE`

  This is used by `FRONT`, sectioning elements such as `CHAPTER`, `FIGURE`, `TABLE`.

`AUTHOR`
`AUTHOR.EXTERN`

  `AUTHOR` currently does not have internal structure. It simply contains the name of an author of the current document. It is recommended to use `AUTHOR.EXTERN` instead, which allows to refer to an entry in an external author database:

  `TO`

    denotes the external author database

  `KEY`

    denotes the entry in that database

`META`

  Makes a (property) statement about the document.

  > `<META name="ozversion" value="3.0">`

  A possible application is to state at what elements the document should be split into different HTML files.

  > `<META name="html.split" value="chapter.foo">`

  where `chapter.foo` would probably be the ID of a chapter in the document. Arbitrary such statements can be made. Neither the name nor the value attribute is restricted.

`ABSTRACT`

`BODY`

`CHAPTER`

`SECTION`

  can also be called `SECT1`

`SUBSECTION`

  can also be called `SECT2`

`SUBSUBSECTION`

  can also be called `SECT3`

`P`

  the usual container for text and phrase elements

`PARA`

  like `P`, but requires a `TITLE`. Thus:

  > `<PARA><TITLE>Invoking the zapper</TITLE>...</PARA>`

  might be rendered with an inline title in bold face. In the Oz documentation, there many paragraphs which are ``about'' a topic. This is typically rendered as a normal paragraph, but with the topic mentioned in the margin. Such paragraphs could be coded as follows:

  > `<PARA CLASS=APROPOS><TITLE>Kinded variables</TITLE>...</PARA>`

  Where `CLASS=APROPOS` is intended to indicate that the `TITLE` should be interpreted as the topic of the paragraph.

`DIV`

  its purpose is to group together paragraphs. For example:

  > `<DIV CLASS=WARNING><P>...<P>...<P>...</DIV>`

  could be used to markup an extended warning. This might be rendered with a colored background and heading saying ``Warning!''.

`LIST`

  flexible element for marking up lists of all kinds. A LaTeX-like itemize is simply:

  > `<LIST>
  > <ITEM>...
  > <ITEM>...
  > </LIST>`

  a LaTeX-like enumerate is obtained through attribute `ENUM`:

  > `<LIST ENUM>
  > <ITEM>...
  > <ITEM>...
  > </LIST>`

  a LaTeX-like description can be obtained by having one or more `ENTRY` elements before an `ITEM`:

  > `<LIST>
  > <ENTRY>...
  > <ENTRY>...
  > <ITEM>...
  > <ENTRY>...
  > <ITEM><P.SILENT//
  > </LIST>`

  For describing such things as procedures, a `SYNOPSIS` element may optionally follow an `ENTRY` and is intended to show how the procedure is to be invoked (typically with parameters annotated with modes):

  > `<LIST CLASS=EXPORTS>
  > <ENTRY><<Map>>
  > <SYNOPSIS><<{Map ?+{L1} ?+{F} ??{L2}}>>
  > <ITEM>...
  > </LIST>`

  Note the use of `CLASS=EXPORTS` to suggest that the list is describing the exports of a module.

`MATH`
`MATH.EXTERN`
`MATH.CHOICE`

  the Oz Documentation DTD does not prescribe a specific marking scheme for math. Instead it lets the author pick an arbitrary notation. This notation is selected by the `TYPE` attribute (default is LaTeX).

  > `<MATH>x^2+y^2=z^2</MATH>`

  since rendering math on different media can be tricky, the author may also supply a choice of alternative notations:

  > `<MATH.CHOICE>
  > <MATH LATEX>x^2+y^2=z^2</MATH>
  > <MATH HTML><![ RCDATA [X<SUP>2</SUP>+Y<SUP>2</SUP>=Z<SUP>2</SUP></MATH>]]>
  > <MATH.EXTERN TO="file:fermat.gif" TYPE=gif>
  > </MATH.CHOICE>`

  Here the same math material is coded using three different notations. The last one refers to an external resource: the gif file `fermat.gif`. Note that `MATH` has content, but MATH.EXTERN is empty.

`PICTURE`
`PICTURE.EXTERN`
`PICTURE.CHOICE`

  this is similar in design to the `MATH` elements.

`CODE`
`CODE.EXTERN`

  `CODE` contains program code in a programming language; which programming language may be specified using the `PROGLANG` attribute. All elements accept the `PROGLANG` attribute: it indicates the default programming language in `CODE`-like elements whithin its scope. Thus, a document starting with:

  > `<BOOK PROGLANG=C>`

  would normally assume that the programming language is C, unless this is overriden by an element with an explicit `PROGLANG` attribute. The choice of programming language may serve to obtain appropriate highlighting of code.

  `CODE` contains mostly raw program text. Sometimes, however, it is desirable to annotate variables within the code, for example with mode specifications, or simply to indicate a meta-variable (as opposed to a language level variable). For this reason occurrences of `VAR` and `SPAN` are also permitted.

  Code Abbreviations

  For convenience, the Oz Documentation DTD supports the following abbreviations:

  `<<...>>` | `<CODE>...</CODE>`
  `<<<...>>>` | `<CODE DISPLAY>...</CODE>`
  `?+{X}` | `<VAR MODE=IN >X</VAR>`
  `??{X}` | `<VAR MODE=OUT >X</VAR>`
  `?*{X}` | `<VAR MODE=CIN >X</VAR>`
  `?@{X}` | `<VAR MODE=CNIN>X</VAR>`
  `?_{X}` | `<VAR >X</VAR>`
  `?{X}` | `<VAR TYPE=META>X</VAR>`

  Thus you can write: `<<{List.map ?+{L1} ?+{F} ??{L2}}>>`

`VAR`

  may occur in ordinary text and also in `CODE` elements. `VAR` serves to identify

  1. programming language variables

  2. meta variables

  3. environment variables

  4. non-terminal symbols in a grammar

  . The choice is determined by attribute `TYPE`.

  `TYPE`

    indicates the type of object represented by the `VAR` element.

    PROG

      programming language variable

    META

      meta variable

    ENV

      environment variable

    GRAMMAR

      grammar non-terminal

  `MODE`

    The `MODE` attribute further describes the expected modes of parameters to builtins and library procedures.

    IN

      input (determined)

    OUT

      output (usually free)

    CIN

    CNIN

`PTR`
`REF`
`PTR.EXTERN`
`REF.EXTERN`

  serve for cross-references. For cross-references within the same document, use `PTR` or `REF`. `PTR` is empty and `REF` has content.

  > `<REF TO=FOO>The definition of foo</REF>`

  might produce a hyperlink in HTML and insert reference text like ``Definition 3.2, page 17'' in LaTeX.

  > `<PTR TO=FOO>`

  might insert a hyperlink with content ``Definition 3.2'' in HTML and again insert ``Definition 3.2, page 17'' in LaTeX. `FOO` is the ID of the element containing the definition of interest. Somewhere else in the document there would be an element like:

  > `<PARA CLASS=DEFINITION ID=FOO>
  > <TITLE>Procedure <<Foo>></TITLE>
  > ...
  > </PARA>`

  If the element pointed to is a `NOTE`, then in HTML, `PTR` might be replaced by an hyperlinked-icon, and in LaTeX it could be replaced by an integer refering to the note by number. The cross-reference may be further specified using attribute `CLASS`, but often it is sufficient for the processing system to look at the element that is pointed to to determine what kind of reference is intended.

  When the object that needs to be referenced does not reside within the current document, we must make an ``external'' reference. Such references cannot take advantage of the ID mechanism of SGML. Instead, the `TO` attribute contains data which it is up to the processing system to properly interpret, perhaps aided by a `CLASS` attribute. Often, `TO` will contain a url:

  > `Visit <REF.EXTERN TO="http://www.ps.uni-sb.de/oz/">the Oz home
  > page</REF.EXTERN>`

  But it can contain other data for which a conventional interpretation has been assigned in the processing system. Thus, we might refer to the Open Programming Manual as follows:

  > `For details about IO programming, see <PTR.EXTERN
  > TO="ozdoc:open">.`

`FILE`

  borrowed from Texinfo. marks up a file name:

  > `<FILE>/usr/local/oz/README</FILE>`

`KBD`

  borrowed from Texinfo. marks up keyboard input:

  > `<KBD>M-a</KBD>`

`KEY`

  borrowed from Texinfo. marks up the conventional name for a key on a keyboard:

  > `<KEY>RET</KEY>`

  However, this can also be marked up using `NAME`:

  > `<NAME TYPE=KEY>RET</NAME>`

`SAMP`

  borrowed from Texinfo. marks up a literal example of a sequence of characters:

  > `<SAMP>foo</SAMP>`

`NAME`

  marks text that names an object; which kind of object should be indicated using the `TYPE` attribute:

  Examples uses of the `TYPE` attribute
  `<NAME TYPE=FICTIONAL.CREATURE>Gump</>`
  `<NAME TYPE=TOOL>Gump</>`
  `<NAME TYPE=CHAR>NUL</>`
  `<NAME TYPE=PERSON>Denys Duchier</>`
  `<NAME TYPE=KEY>RET</>`
  `<NAME TYPE=OS>Linux</>`

`Q`

  marks quoted phrases:

  > `Man, I hated that book! You hang in there through all that
  > dreary prose and for his big finale, his major piece of bloody
  > wisdom, all he's got to tell you is <Q LANG=FR>La vie, ça n'est
  > jamais si bon ni si mauvais qu'on croit</Q>. Bummer, man!
  > What a let down!`

  or

  > `Here goes another one of Microsoft's <Q
  > CLASS=SOCALLED>upgrades</Q>; down the drain, where it belongs!`

`SPAN`

  this element has no particular semantics but serves mainly to mark an otherwise undistinguished piece of text so that it can be assigned an ID (e. g. for cross reference purposes) or a `CLASS` for whatever purpose was not anticipated by the DTD.

  > `<SPAN ID=FOO>...</> ... <PTR TO=FOO> ...`

`DEF`

  marks the defining occurrence of a term or phrase. It would probably be used to contribute an entry in a glossary section. It should probably be further specified using the `CLASS` attribute to indicate what kind of term is being defined.

`FIGURE`

  a figure contains displayed material. It may have an optional `TITLE`, and an optional `CAPTION` containing a longer description. Here is an example adapted from the TEI DTD documentation:

  > `<FIGURE>
  > <TITLE>Mr Fezziwig's Ball</TITLE>
  > <CAPTION>A Cruikshank engraving showing Mr Fezziwig leading
  > a group of revellers</CAPTION>
  > <PICTURE.EXTERN TO="fezziwig.jpg">
  > </FIGURE>`

  `FLOAT`

    A `FIGURE` may also float outside of the main flow of the document. This can be indicated by attribute `FLOAT`:

    > `<FIGURE FLOAT>...</FIGURE>`

  `CLASS`

    The `CLASS` attribute should be used to indicate what kind of a figure it is:

    > `<FIGURE FLOAT CLASS=PICTURE>...</FIGURE>`

    Such an indication makes it possible to automatically generate a caption label that indicates this type and to cross-reference the figure in the appropriate list (e. g. here: a list of pictures).

`NOTE`

  another kind of normally floating material. The difference between a floating figure and a note is that the latter usually leaves a trace in the main flow of the document. For example, footnotes typically leave a superscripted integer behind. The attribute `CLASS` should be used to indicate what kind of `NOTE` is intended.

  `FOOT`

    since footnotes are a major application of `NOTE`s, the attribute `FOOT` can be used instead of `CLASS=FOOT`:

    > `<NOTE FOOT>...</NOTE>
    > =
    > <NOTE CLASS=FOOT>...</NOTE>`

`INDEX`

  `INDEX` is allowed everywhere in the scope of the `BOOK` element.

  > `<INDEX>foo</INDEX>`

  When several levels of indexing are required, they can be entered separated by `<AND>`:

  > `<INDEX>foo<AND>bar<AND>baz</INDEX>`

  The `CLASS` attribute can be used to support multiple kinds of indexes:

  > `<INDEX CLASS=PERSON>Maupassant</INDEX>
  > <INDEX CLASS=PROCEDURE>FoldL</INDEX>`

  `SEE`

    allows one index to refer to another by ID, and is a way to mark up a ``see'' reference:

    > `<INDEX ID=one.two.fr>one<AND>two<AND>french</INDEX>
    > ...
    > <INDEX SEE=one.two.fr>un<AND>deux</INDEX>`

  `SORT.AS`

    For each level of indexing, it may be necessary to distinguish between the text used as the content of the entry and the text used to perform sorting on the labels. The `SORT.AS` attribute is intended to supply text to use for sorting instead of the contents.

  `SCOPE`

    To index a range of pages, you may supply one or more element IDs as the value of the `SCOPE` attribute.

    > `<INDEX SCOPE=section.bar>foo<AND>bar</INDEX>`

    would associate to this index entry the range of pages covered by the element whose ID is `section.bar`.

    > `<INDEX SCOPE="par.bar1 par.bar2">foo<AND>bar</INDEX>`

    would associate with the entry the range of pages covered by the two elements with ID `par.bar1` and `par.bar2` (presumably consecutive).

`GRAMMAR`
`GRAMMAR.RULE`
`GRAMMAR.ALT`
`GRAMMAR.NOTE`

  formal syntactic definitions often make use of BNF-like notation. A `GRAMMAR.RULE` marks up a grammatical production. The body of the rule consists of a sequence of `GRAMMAR.ALT` elements. Each `GRAMMAR.ALT` element may end with a `GRAMMAR.NOTE` element that provides an inline comment for the element. `GRAMMAR` contains a sequence of `GRAMMAR.RULE` elements that belong together: it could provide the additional service of ensuring pleasant vertical alignment.

  `TYPE`

    `GRAMMAR.ALT` can be further specified using attribute TYPE

    DEF

      indicates that this element begins a new rule body. Usually this is rendered with an initial symbol like `::=`

    ADD

      indicates that this element begins a new rule body to be added as an additional alternative to the alternatives previously defined for the head non-terminal. Usually this is rendered with an initial symbol like `+=`

    OR

      indicates the start of the next alternative rewriting. Usually this is rendered with initial symbol `|`

    SPACE

      indicates the continuation of the previous `GRAMMAR.ALT` element. Usually this is rendered by breaking to a newline but omitting any initial symbol

`TABLE`
`TR`
`TD`
`TH`

  a `TABLE` consist of rows marked with `TR`. A row consists of a sequence of data `TD` and header `TH` cells, each of which may span several columns as specified by attribute `COLSPAN`.

  `COLSPAN`

    for `TH` and `TD`, indicates the number of column spanned by the element. When omitted, the cell spans exactly one column.

`BACK`

  container for back-matter material, such as `BIB.EXTERN` for bibliographic entries.

`BIB.EXTERN`

  refers to a specific entry denoted by attribute `KEY` in an external bibliographic database denoted by `TO`.

  > `<BIB.EXTERN ID=ZIPPY TO="weirdo.bib" KEY="elzippo91">`

  `ID`

    the `ID` makes it possible to ``cite'' the entry:

    > `<PTR TO=ZIPPY>`

  `TO`

    denotes an external bibliographic database from which the actual contents of the bibliographic entry will have to be extracted.

  `KEY`

    denotes the desired entry in the external bibliographic database.

`CHUNK`

  provides literate programming support. A chunk of code is named by its `title`. There may be several chunks with the same title: their code is concatenated. A chunk may be used as a macro to insert code into another chunk: this is effected by `CHUNK.REF`.

`CHUNK.REF`

  Its content is (the text of) the title of a chunk. It is intended to denote the concatenated code of all chunks with this title.