2 General structure of a document according to the Oz DTD

<!DOCTYPE BOOK SYSTEM "ozdoc.dtd" [  ]> <BOOK> <FRONT> <TITLE>...</TITLE> <AUTHOR>...</AUTHOR> <AUTHOR>...</AUTHOR> <META name=comic content="foo.ps"> <ABSTRACT>...</ABSTRACT> <BODY> <CHAPTER><TITLE>...</TITLE> ... <PART> <TITLE>...</TITLE> <CHAPTER><TITLE>...</TITLE> ... <CHAPTER><TITLE>...</TITLE> ... <PART> <TITLE>...</TITLE> <CHAPTER><TITLE>...</TITLE> ... <CHAPTER><TITLE>...</TITLE> ... <BACK> <BIB.EXTERN ...> ... </BOOK>

2.1 Entity Declarations

2.1.1 Macros

entities are a bit like macros. You can add entity declarations where it says  above. For example:

<!ENTITY quux "Guy L. Steele JR.">

would allow you to type &quux; in your document, and that would automatically be replaced by ``Guy L. Steele JR''.

2.1.2 Include Files

Another application of entities is to denote files to be included:

<!ENTITY section1 SYSTEM "section1-draft.sgml">

would allow you to type &section1; in your document, and that would be replaced by the contents of file section1-draft.sgml.

2.1.3 Processing Instructions

Sometimes it is useful to introduce entities that do not expand to text, but should instead be interpreted by the processing system. This is what a processing instruction is for.

<!ENTITY nbsp PI "NON-BREAKING-SPACE">

an occurrence of   in your document will result in an occurrence of the processing instruction object identified as NON-BREAKING-SPACE. What to do with it is up to the processing system. For example, the LaTeX converter might replace it by ~ and the HTML converter by the HTML entity   (surprise, surprise!).

I recommend that processing instructions be given names that begin with the prefix PI:, e. g.:

<!ENTITY nbsp PI "PI:NBSP">

2.1.4 Marked Section

It is possible to conditionally include a part of the document:

<![ %HTML; [...]]>

would include ... iff %HTML; is a (parameter) entity defined as INCLUDE, i.e. if there is an entity declaration of the form:

<!ENTITY % HTML "INCLUDE">

Normally, the ``entity declarations'' section of your document would contain:

<!ENTITY % LATEX "IGNORE"> <!ENTITY % HTML "IGNORE">

Thus causing marked sections marked with %LATEX; and %HTML; to be ignored by default. This is normally overriden on the command line, when invoking the SGML parser, nsgmls:

nsgmls -iHTML ...

this causes the declaration

<!ENTITY % LATEX "INCLUDE">

to override the one in your document. Don't abuse marked sections. A typical use is, in the DOCTYPE header of your document, to select which entity declarations you want to use according to the target format for processing.

<!DOCTYPE BOOK SYSTEM "ozdoc.dtd" [ <!ENTITY % HTML "IGNORE"> <!ENTITY % LATEX "IGNORE"> <![ %HTML; [ <!ENTITY target.format "HTML"> ]]> <![ %LATEX; [ <!ENTITY target.format "\LaTeX{}"> ]]> ]>

This would allow you to type &target.format; in your document and have it expand to either HTML or \LaTeX{} according to the target format select on nsgmls's command-line.