| << Prev | - Up - | Next >> |
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:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Thus you can write: <<{List.map ?+{L1} ?+{F} ??{L2}}>>
VAR may occur in ordinary text and also in CODE elements. VAR serves to identify
programming language variables
meta variables
environment variables
non-terminal symbols in a grammar
. The choice is determined by attribute TYPE.
TYPE indicates the type of object represented by the VAR element.
programming language variable
meta variable
environment variable
grammar non-terminal
MODE The MODE attribute further describes the expected modes of parameters to builtins and library procedures.
input (determined)
output (usually free)
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 |
|
|
|
|
|
|
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 NOTEs, 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
indicates that this element begins a new rule body. Usually this is rendered with an initial symbol like ::=
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 +=
indicates the start of the next alternative rewriting. Usually this is rendered with initial symbol |
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.
| << Prev | - Up - | Next >> |