2 General structure of a document according to the Oz DTD

<!DOCTYPE BOOK SYSTEM "ozdoc.dtd" [
<!-- entity declarations --> 
]>
<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 <!-- entity declarations --> 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 &nbsp; 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 &nbsp; (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.


Denys Duchier
Version 1.4.0 (20080702)