1 Introduction

The Oz Documentation DTD provides a means to markup technical documentation so that it is easy to convert it to alternative publication formats such as LaTeX and HTML.

A second advantage of declarative markup is that extra value can be automatically added. For example, code fragments can be automatically highlighted according to the programming language used, text can be automatically hyphenated according to the natural language in effect, cross-references, index entries, and hyperlinks can be automatically introduced.

1.1 Introduction to SGML

You can think of an SGML document as a tree of nested elements. SGML itself is simply a language for creating document grammars; such a grammar is called a DTD: a Document Type Definition. It defines both an abstract syntax, consisting of elements, and a concrete syntax consisting of tags.

Thus <AUTHOR>...</AUTHOR> is the concrete syntax for the scope of an AUTHOR element.

1.2 Relationship to HTML

HTML is an SGML application: it uses SGML to define a DTD, i.e. an abstract and a concrete syntax for hypertext documents.

The Oz Documentation DTD is also an SGML application, for the same reasons. It defines an abstract and a concrete syntax for Oz documents.

1.3 Notational Tricks

The Oz Documentation DTD, supports the following abbreviations for tags:

          <TITLE>Kinded Variables</TITLE>

may be written

          <TITLE/Kinded Variables/

This abbreviation is supported for all elements. The restriction is that the text occurring between the 2 slashes cannot itself contain a slash in its non-markup content. However, elements can be nested within, even those using this form of abbreviation:

          <TITLE/one <Q/two/ three <Q>four</Q> five/

is equivalent to

          <TITLE>one <Q>two</Q> three <Q>four</Q> five</TITLE>

1.4 Omitting Tags

In the Oz Documentation DTD, end tags of sectioning elements such as CHAPTER and P can be omitted. Ditto for ITEM and some other few elements. Phrase elements however require an end tag.

Denys Duchier
Version 1.4.0 (20080702)