<!DOCTYPE BOOK SYSTEM "ozdoc.dtd" [
<!ENTITY ETC PI "PI:ETC">
<!ENTITY % proglang.values.local "|SGML|SHELL|LATEX">
<!ENTITY LATEX PI "PI:LATEX">
<!ENTITY EG    PI "PI:EG">
<!ENTITY NOOP  "">
<!ELEMENT TAG - - RCDATA -- contains one or more SGML element names -->
<!ELEMENT ATTRIB - - RCDATA -- an SGML attribute -->
<!ENTITY % p.mix.local "|TAG|ATTRIB">
<!ENTITY NIX "<P.SILENT//">
]>
<BOOK PROGLANG=SGML>
    <META NAME="html.split" value="chapter.intro">
    <META NAME="html.split" value="chapter.docstruct">
    <META NAME="html.split" value="chapter.bnf">
    <META NAME="html.split" value="chapter.principles">
    <META NAME="html.split" value="chapter.description">
    <META NAME="html.split" value="chapter.extending">
    <META NAME="html.split" value="chapter.editing">
    <META NAME="proglang.mode" arg1="shell" arg2="shell-script-mode">
    <TITLE>Oz Documentation DTD
    <AUTHOR.EXTERN TO="author.db" KEY="Denys.Duchier">
    <CHAPTER ID=chapter.intro>
      <TITLE/Introduction/

      <P>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.</P>

      <P>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.</P>

      <SECTION>
	<TITLE/Introduction to SGML/

	<P>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.</P>

	<P>Thus <CODE><![ RCDATA [<AUTHOR>...</AUTHOR>]]></CODE> is
	the concrete syntax for the scope of an <NAME TYPE=TAG/AUTHOR/
	element.</P>

      <SECTION>
	<TITLE/Relationship to HTML/

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

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

      <SECTION>
	<TITLE/Notational Tricks/

	<P>The Oz Documentation DTD, supports the following
	abbreviations for tags:
	<CODE DISPLAY>
	  <![ RCDATA [<TITLE>Kinded Variables</TITLE>]]>
	</CODE>
	may be written
	<CODE DISPLAY>
	  <![ RCDATA [<TITLE/Kinded Variables/]]>
	</CODE></P>
	
	<P>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:
	<CODE DISPLAY>
	  <![ RCDATA [<TITLE/one <Q/two/ three <Q>four</Q> five/]]>
	</CODE>
	is equivalent to
	<CODE DISPLAY>
	  <![ RCDATA [<TITLE>one <Q>two</Q> three <Q>four</Q> five</TITLE>]]>
	</CODE>

      <SECTION>
	<TITLE/Omitting Tags/

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

    <CHAPTER ID=chapter.docstruct>
      <TITLE/General structure of a document according to the Oz DTD/

      <P><CODE DISPLAY>
<![ RCDATA [
<!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>
]]></CODE>

      <SECTION>
	<TITLE/Entity Declarations/

	<SUBSECTION>
	  <TITLE/Macros/

	  <P>entities are a bit like macros.  You can add entity
	declarations where it says <CODE><![ RCDATA
	[<!-- entity declarations -->]]></CODE> above.
	For example:
	<CODE DISPLAY><![ RCDATA
	[<!ENTITY quux "Guy L. Steele JR.">]]></CODE>
	would allow you to type <CODE><![ CDATA [&quux;]]></CODE> in
	your document, and that would automatically be replaced by
	<Q/Guy L. Steele JR/.</P>

	<SUBSECTION>
	  <TITLE/Include Files/

	  <P>Another application of entities is to denote files to be
	  included: <CODE DISPLAY><![ CDATA
	  [<!ENTITY section1 SYSTEM "section1-draft.sgml">]]></CODE>
	  would allow you to type <CODE><![ CDATA
	  [&section1;]]></CODE> in your document, and
	  that would be replaced by the contents of file
	  <FILE/section1-draft.sgml/.</P>

	<SUBSECTION>
	  <TITLE/Processing Instructions/

	  <P>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. <CODE DISPLAY><![ CDATA
	  [<!ENTITY nbsp PI "NON-BREAKING-SPACE">]]></CODE>
	  an occurrence of <CODE><![ CDATA [&nbsp;]]></CODE> in your
	  document will result in an occurrence of the processing
	  instruction object identified as <NAME
	  TYPE=PI/NON-BREAKING-SPACE/.  What to do with it is up to
	  the processing system.  For example, the &LATEX; converter
	  might replace it by <SAMP/~/ and the HTML converter by the
	  HTML entity <CODE><![ CDATA [&nbsp;]]></CODE> (surprise,
	  surprise!).</P>

	  <P>I recommend that processing instructions be given names
	  that begin with the prefix <SAMP/PI:/, &EG;:
	  <CODE DISPLAY><![ CDATA
	  [<!ENTITY nbsp PI "PI:NBSP">]]></CODE></P>

	<SUBSECTION>
	  <TITLE/Marked Section/

	  <P>It is possible to conditionally include a part of the
	  document:
	  <CODE DISPLAY><&NOOP;![ %&NOOP;HTML; [...]]&NOOP;></CODE>
	  would include <CODE/.../ iff <CODE/%&NOOP;HTML;/ is a
	  (parameter) entity defined as <CODE/INCLUDE/, i.e. if there
	  is an entity declaration of
	  the form: <CODE DISPLAY><![ CDATA
	  [<!ENTITY % HTML "INCLUDE">]]></CODE></P>

	  <P>Normally, the <Q/entity declarations/ section of your
	  document would contain: <CODE DISPLAY><![ CDATA [
<!ENTITY % LATEX "IGNORE">
<!ENTITY % HTML  "IGNORE">]]></CODE>
	  Thus causing marked sections marked with <CODE><![ CDATA
	  [%LATEX;]]></CODE> and <CODE><![ CDATA [%HTML;]]></CODE> to
	  be ignored by default.  This is normally overriden on the
	  command line, when invoking the SGML parser, <NAME
	  TYPE=PROGRAM/nsgmls/:
	  <CODE DISPLAY PROGLANG=SHELL>nsgmls -iHTML ...</CODE>
	  this causes the declaration
	  <CODE DISPLAY><![ CDATA
	  [<!ENTITY % LATEX "INCLUDE">]]></CODE>
	  to override the one in your document.  Don't abuse marked
	  sections. A typical use is, in the <CODE/DOCTYPE/ header of
	  your document, to select which entity declarations you want
	  to use according to the target format for processing.
<CODE DISPLAY><![ CDATA [
<!DOCTYPE BOOK SYSTEM "ozdoc.dtd" [
<!ENTITY % HTML  "IGNORE">
<!ENTITY % LATEX "IGNORE">
<!]]>[ %&NOOP;HTML;  [<![ CDATA [
<!ENTITY target.format "HTML">]]>
]]&NOOP;>
<&NOOP;![ %&NOOP;LATEX; [<![ CDATA [
<!ENTITY target.format "\LaTeX{}">]]>
]]&NOOP;>
]>
</CODE>
	  This would allow you to type <CODE><![ CDATA
	  [&target.format;]]></CODE> in your document and have it
	  expand to either HTML or <CODE PROGLANG=LATEX/\LaTeX{}/
	  according to the target format select on nsgmls's
	  command-line.</P>

    <CHAPTER ID=chapter.bnf>
      <TITLE/BNF Description of the DTD/

      <P>This description is a simplified idealization of the DTD.  It
	provides an intuitive overview of the element hierarchy.  
	Identifiers such as &EG; <TAG/TITLE/ denote elements, whereas
	identifiers such as &EG; <VAR TYPE=GRAMMAR/TEXT or PHRASE/ denote
	non-terminal symbols in this BNF description.
	<GRAMMAR.RULE>
	  <GRAMMAR.HEAD><TAG/FOO/</GRAMMAR.HEAD>
	  <GRAMMAR.ALT><TAG/BAR/ <TAG/BAZ/</GRAMMAR.RULE>
	means that the contents of element <TAG/FOO/ must consist of a
	<TAG/BAR/ element followed by a <TAG/BAZ/ element.  Whereas:
	<GRAMMAR.RULE>
	  <VAR GRAMMAR/FOO/
	  <GRAMMAR.ALT><TAG/BAR/ <TAG/BAZ/</GRAMMAR.RULE>
	means that non-terminal ?={FOO} can be rewritten to the
	sequence <TAG/BAR/ <TAG/BAZ/.</P>

      <P>The annotation <CODE/+?={INDEXING}/ in the rule for
	<TAG/BOOK/ indicates that the elements represented by
	non-terminal ?={INDEXING} are allowed to occur
	anywhere within the scope of element <TAG/BOOK/.</P>

      <P><GRAMMAR>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/BOOK//
	    <GRAMMAR.ALT><TAG/FRONT/ <TAG/BODY/ <TAG/BACK/?
	      <GRAMMAR.NOTE>+?={INDEXING}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/FRONT//
	    <GRAMMAR.ALT><TAG/TITLE/ ?={AUTHOR}* <TAG/META/*
	      <TAG/ABSTRACT/?</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/BODY//
	    <GRAMMAR.ALT><TAG/CHAPTER/* <TAG/PART/*
	      <TAG/APPENDIX/*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CHAPTER//
	    <GRAMMAR.ALT><TAG/TITLE/? ?={P}*
	      <TAG/SECTION/*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SECTION//
	    <GRAMMAR.ALT><TAG/TITLE/? ?={P}*
	      <TAG/SUBSECTION/*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SUBSECTION//
	    <GRAMMAR.ALT><TAG/TITLE/? ?={P}*
	      <TAG/SUBSUBSECTION/*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SUBSUBSECTION//
	    <GRAMMAR.ALT><TAG/TITLE/? ?={P}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/?={P}/
	    <GRAMMAR.ALT><TAG/P/</GRAMMAR.ALT>
	    <GRAMMAR.ALT OR><TAG/PARA/</GRAMMAR.ALT>
	    <GRAMMAR.ALT OR><TAG/DIV/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/P//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PARA//
	    <GRAMMAR.ALT><TAG/TITLE/ ?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/DIV//
	    <GRAMMAR.ALT><TAG/TITLE/? ?={P}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/TITLE//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/?={TEXT or PHRASE}/
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.ALT>
	    <GRAMMAR.ALT OR>?={PHRASE}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/LIST//
	    <GRAMMAR.ALT><TAG/ITEM/*</GRAMMAR.ALT>
	    <GRAMMAR.ALT OR>(<TAG/ENTRY/ <TAG/SYNOPSIS/?
	      <TAG/ITEM/)*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/ITEM//
	    <GRAMMAR.ALT>?={...P}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/ENTRY//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SYNOPSIS//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/?={...P}/
	    <GRAMMAR.ALT>?={TEXT or PHRASE}* ?={P}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/?={PHRASE}/
	    <GRAMMAR.ALT/<TAG/MATH//
	    <GRAMMAR.ALT OR/<TAG/MATH.EXTERN//
	    <GRAMMAR.ALT OR/<TAG/MATH.CHOICE//
	    <GRAMMAR.ALT OR/<TAG/PICTURE//
	    <GRAMMAR.ALT OR/<TAG/PICTURE.EXTERN//
	    <GRAMMAR.ALT OR/<TAG/PICTURE.CHOICE//
	    <GRAMMAR.ALT OR/<TAG/CODE//
	    <GRAMMAR.ALT OR/<TAG/CODE.EXTERN//
	    <GRAMMAR.ALT OR/<TAG/VAR//
	    <GRAMMAR.ALT OR/<TAG/REF//
	    <GRAMMAR.ALT OR/<TAG/PTR//
	    <GRAMMAR.ALT OR/<TAG/REF.EXTERN//
	    <GRAMMAR.ALT OR/<TAG/PTR.EXTERN//
	    <GRAMMAR.ALT OR/<TAG/FILE//
	    <GRAMMAR.ALT OR/<TAG/KBD//
	    <GRAMMAR.ALT OR/<TAG/KEY//
	    <GRAMMAR.ALT OR/<TAG/SAMP//
	    <GRAMMAR.ALT OR/<TAG/NAME//
	    <GRAMMAR.ALT OR/<TAG/Q//
	    <GRAMMAR.ALT OR/<TAG/SPAN//
	    <GRAMMAR.ALT OR/<TAG/DEF//
	    <GRAMMAR.ALT OR/<TAG/FIGURE//
	    <GRAMMAR.ALT OR/<TAG/NOTE//
	    <GRAMMAR.ALT OR/<TAG/GRAMMAR//
	    <GRAMMAR.ALT OR/<TAG/GRAMMAR.RULE//
	    <GRAMMAR.ALT OR/<TAG/TABLE//
	    <GRAMMAR.ALT OR/<TAG/CHUNK//
	  </GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/MATH//
	    <GRAMMAR.ALT/?={TEXT}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/MATH.EXTERN//
	    <GRAMMAR.ALT/?={EMPTY}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/MATH.CHOICE//
	    <GRAMMAR.ALT>(<TAG/MATH/ | <TAG/MATH.EXTERN/)+</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PICTURE//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PICTURE.EXTERN//
	    <GRAMMAR.ALT>?={EMPTY}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PICTURE.CHOICE//
	    <GRAMMAR.ALT>(<TAG/PICTURE/ | <TAG/PICTURE.EXTERN/)+</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CODE//
	    <GRAMMAR.ALT>(?={TEXT}<TAG/VAR/|<TAG/SPAN/)*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CODE.EXTERN//
	    <GRAMMAR.ALT>?={EMPTY}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/VAR//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/REF//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PTR//
	    <GRAMMAR.ALT>?={EMPTY}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/REF.EXTERN//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/PTR.EXTERN//
	    <GRAMMAR.ALT>?={EMPTY}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/FILE//
	    <GRAMMAR.ALT>(?={TEXT} | <TAG/VAR/)*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/KBD//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/KEY//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SAMP//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/NAME//
	    <GRAMMAR.ALT>?={TEXT}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/Q//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SPAN//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/DEF//
	    <GRAMMAR.ALT>?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/FIGURE//
	    <GRAMMAR.ALT><TAG/TITLE/? <TAG/CAPTION/? <TAG/PHRASE/*
	      ?={P}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CAPTION//
	    <GRAMMAR.ALT>?={...P}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/NOTE//
	    <GRAMMAR.ALT>?={...P}</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/?={INDEXING}/
	    <GRAMMAR.ALT/<TAG/INDEX//</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/INDEX//
	    <GRAMMAR.ALT/<TAG/AND/+ <TAG/SEE/?/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/AND//
	    <GRAMMAR.ALT/?={TEXT or PHRASE}*/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/SEE//
	    <GRAMMAR.ALT/<TAG/AND/+/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/GRAMMAR//
	    <GRAMMAR.ALT/<TAG/GRAMMAR.RULE/+/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/GRAMMAR.RULE//
	    <GRAMMAR.ALT/<TAG/VAR/ <TAG/GRAMMAR.ALT/+/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/GRAMMAR.ALT//
	    <GRAMMAR.ALT/?={TEXT or PHRASE}*
	      <TAG/GRAMMAR.NOTE/?/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/GRAMMAR.NOTE//
	    <GRAMMAR.ALT/?={TEXT or PHRASE}*</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/TABLE//
	    <GRAMMAR.ALT/<TAG/TITLE/? <TAG/TR/+/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/TR//
	    <GRAMMAR.ALT/(<TAG/TD/ | <TAG/TH/)+/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/TD//
	    <GRAMMAR.ALT/?={...P}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/TR//
	    <GRAMMAR.ALT/?={...P}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/BACK//
	    <GRAMMAR.ALT/(<TAG/META/ | <TAG/BIB.EXTERN/)*/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/BIB.EXTERN//
	    <GRAMMAR.ALT/?={EMPTY}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/AUTHOR//
	    <GRAMMAR.ALT/?={TEXT}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/AUTHOR.EXTERN//
	    <GRAMMAR.ALT/?={EMPTY}/</GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CHUNK//
	    <GRAMMAR.ALT/<TAG/TITLE/ (?={TEXT} | <TAG/CHUNK.REF/)*/
	  </GRAMMAR.RULE>
	  <GRAMMAR.RULE>
	    <GRAMMAR.HEAD/<TAG/CHUNK.REF//
	    <GRAMMAR.ALT/?={TEXT or PHRASE}*/
	  </GRAMMAR.RULE>
	</GRAMMAR></P>

    <CHAPTER ID=chapter.principles>
      <TITLE/General Principles of the DTD/

      <SECTION>
	<TITLE/Common Attributes/
	<P>All elements accept the following attributes:
	  <LIST>
	    <ENTRY><ATTRIB/ID/
	    <ITEM>A document-wide unique identifier that makes it
		possible to refer to the element:
		<CODE DISPLAY><![ RCDATA
		[<P ID=FOO>...</P>	...	<PTR TO=FOO>]]></CODE>
	    <ENTRY><ATTRIB/CLASS/
	    <ITEM>a space separated list of arbitrary identifiers that
		further specify the element.
		<CODE DISPLAY><![ RCDATA
		[<NOTE CLASS=FOOT>...</NOTE>]]></CODE>
		would serve to indicate a footnote.
		<CODE DISPLAY><![ RCDATA
		[<FIGURE FLOAT CLASS=PROGRAM>...</FIGURE>]]></CODE>
		would indicate that this floating figure contains a
		program.
	    <ENTRY><ATTRIB/LANG/
	    <ITEM>a standard 2 character code for a language.  It
		indicates the default language within the scope of the
		element and is inherited unless explicitly overriden.
		It serves &EG; to obtain appropriate language
		dependent services such as hyphenation and quote
		delimiters.
		<LIST>
		  <ENTRY><NAME TYPE="SGML.IDENT"/EN/
		  <ITEM>english
		  <ENTRY><NAME TYPE="SGML.IDENT"/DE/
		  <ITEM>german
		  <ENTRY><NAME TYPE="SGML.IDENT"/FR/
		  <ITEM>french
		</LIST>
	    <ENTRY><ATTRIB/PROGLANG/
	    <ITEM>this is rather similar to attribute LANG but for
		programming languages.
		<LIST>
		  <ENTRY><NAME TYPE="SGML.IDENT"/OZ/
		  <ITEM>&NIX;
		  <ENTRY><NAME TYPE="SGML.IDENT"/GUMP/
		  <ITEM>&NIX;
		  <ENTRY><NAME TYPE="SGML.IDENT"/C/
		  <ITEM>&NIX;
		  <ENTRY><NAME TYPE="SGML.IDENT"/CC/
		  <ITEM><NAME TYPE="PROG.LANG"/C++/
		  <ENTRY><NAME TYPE="SGML.IDENT"/ELISP/
		  <ITEM><NAME TYPE="PROG.LANG"/Emacs Lisp/
		</LIST>
	  </LIST>

      <SECTION>
	<TITLE>Display/Inline phrase elements</TITLE>

	<P>Phrase elements are contained in paragraphs.  But they can
	  be either inline or displayed, and some can be either.
	  <TAG/NAME/ is always rendered inline.  <TAG/MATH/ is usually
	  inline, but can be rendered displayed through the use of the
	  <ATTRIB/DISPLAY/ attribute: 
	  <CODE DISPLAY><![ RCDATA [<MATH DISPLAY>...</MATH>]]></CODE>
	  Lists are usually displayed, but you could request an inline
	  enumeration as follows:
	  <CODE DISPLAY><![ RCDATA [<LIST INLINE ENUM>...</LIST>]]></CODE>
	  The default of whether to be inline or displayed is whatever
	  makes the most sense for the element.  When both are
	  possible, the non default case can be explicitly requested
	  using either <ATTRIB/INLINE/ or <ATTRIB/DISPLAY/. </P>

      <SECTION>
	<TITLE/External Resources/

	<P>some elements have variants whose data comes from an
	  external resource rather than from within the document
	  itself: the name of such an element is obtained by
	  concatenating <CODE/.EXTERN/ to the usual name, &EG;:
	  <CODE DISPLAY><![ RCDATA [
<PTR.EXTERN     TO='...'>
<MATH.EXTERN    TO='...'>
<PICTURE.EXTERN TO='...'>]]></CODE></P>

      <SECTION>
	<TITLE/References/

	<P>some elements can make references either to some other
	  element within the document or to some external resource.
	  This is effected through attribute <ATTRIB/TO/ and may be
	  further specified with attribute <ATTRIB/KEY/. </P>

	<P>For references within the same document <ATTRIB/TO/ should
	  have as value an <CODE/ID/; for external references, the
	  value is arbitrary, but usually follows a recognizable
	  syntax such as a url.  <ATTRIB/KEY/ is arbitrary, its
	  interpretation will depend on the kind of thing which is
	  being referred to.</P>

    <CHAPTER ID=chapter.description>
      <TITLE/Description of all elements/

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

      <P><LIST CLASS="TAGS">
	  <ENTRY><TAG/BOOK/
	  <ITEM>&NIX;
	  <ENTRY><TAG/FRONT/
	  <ITEM>This is a container for descriptive information about
	      the document. Beside title, author and abstract, you may
	      also have <TAG/META/ elements that make (property)
	      statements about the document.
	      <CODE DISPLAY><![ RCDATA
		[<META name="ozversion" value="3.0">]]></CODE>
	  <ENTRY><TAG/TITLE/
	  <ITEM>This is used by <TAG/FRONT/, sectioning elements such
	      as <TAG/CHAPTER/, <TAG/FIGURE/, <TAG/TABLE/.
	  <ENTRY><TAG/AUTHOR/
	  <ENTRY><TAG/AUTHOR.EXTERN/
	  <ITEM><TAG/AUTHOR/ currently does not have internal
	      structure.  It simply contains the name of an author of
	      the current document.  It is recommended to use
	      <TAG/AUTHOR.EXTERN/ instead, which allows to refer to an
	      entry in an external author database:
	      <LIST CLASS="ATTRIBS">
		<ENTRY><ATTRIB/TO/
		<ITEM>denotes the external author database
		<ENTRY><ATTRIB/KEY/
		<ITEM>denotes the entry in that database
	      </LIST>
	  <ENTRY><TAG/META/
	  <ITEM>Makes a (property) statement about the document.
	      <CODE DISPLAY><![ RCDATA
		[<META name="ozversion" value="3.0">]]></CODE>
	      A possible application is to state at what elements the
	      document should be split into different HTML files.
	      <CODE DISPLAY><![ RCDATA
		[<META name="html.split" value="chapter.foo">]]></CODE>
	      where <CODE/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.
	  <ENTRY><TAG/ABSTRACT/
	  <ITEM>&NIX;
	  <ENTRY><TAG/BODY/
	  <ITEM>&NIX;
	  <ENTRY><TAG/CHAPTER/
	  <ITEM>&NIX;
	  <ENTRY><TAG/SECTION/
	  <ITEM>can also be called <TAG/SECT1/
	  <ENTRY><TAG/SUBSECTION/
	  <ITEM>can also be called <TAG/SECT2/
	  <ENTRY><TAG/SUBSUBSECTION/
	  <ITEM>can also be called <TAG/SECT3/
	  <ENTRY><TAG/P/
	  <ITEM>the usual container for text and phrase elements
	  <ENTRY><TAG/PARA/
	  <ITEM>like <TAG/P/, but requires a <TAG/TITLE/.  Thus:
	      <CODE DISPLAY><![ RCDATA
[<PARA><TITLE>Invoking the zapper</TITLE>...</PARA>]]></CODE>
	      might be rendered with an inline title in bold face.  In
	      the Oz documentation, there many paragraphs which are
	      <Q/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:
	      <CODE DISPLAY><![ RCDATA 
[<PARA CLASS=APROPOS><TITLE>Kinded variables</TITLE>...</PARA>]]></CODE>
	      Where <CODE/CLASS=APROPOS/ is intended to indicate that
	      the <TAG/TITLE/ should be interpreted as the topic of
	      the paragraph.
	  <ENTRY><TAG/DIV/
	  <ITEM>its purpose is to group together paragraphs.  For
	      example:
	      <CODE DISPLAY><![ RCDATA
[<DIV CLASS=WARNING><P>...<P>...<P>...</DIV>]]></CODE>
	      could be used to markup an extended warning.  This might
	      be rendered with a colored background and heading saying
	      <Q/Warning!/.
	      <ENTRY><TAG/LIST/
	  <ITEM>flexible element for marking up lists of all kinds.  A
	      LaTeX-like <NAME TYPE="LATEX.ENV"/itemize/ is simply:
	      <CODE DISPLAY><![ RCDATA [
<LIST>
  <ITEM>...
  <ITEM>...
</LIST>]]></CODE>
	      a LaTeX-like <NAME TYPE="LATEX.ENV"/enumerate/ is
	      obtained through attribute <ATTRIB/ENUM/:
	      <CODE DISPLAY><![ RCDATA [
<LIST ENUM>
  <ITEM>...
  <ITEM>...
</LIST>]]></CODE>
	      a LaTeX-like <NAME TYPE="LATEX.ENV"/description/ can be
	      obtained by having one or more <TAG/ENTRY/ elements
	      before an <TAG/ITEM/:
	      <CODE DISPLAY><![ RCDATA [
<LIST>
  <ENTRY>...
  <ENTRY>...
  <ITEM>...
  <ENTRY>...
  <ITEM>&NIX;
</LIST>]]></CODE>
	      For describing such things as procedures, a
	      <TAG/SYNOPSIS/ element may optionally follow an
	      <TAG/ENTRY/ and is intended to show how the procedure
	      is to be invoked (typically with parameters annotated
	      with modes):
	      <CODE DISPLAY><![ RCDATA [
<LIST CLASS=EXPORTS>
  <ENTRY><<Map>>
  <SYNOPSIS><<{Map ?+{L1} ?+{F} ??{L2}}>>
  <ITEM>...
</LIST>]]></CODE>
	      Note the use of <CODE/CLASS=EXPORTS/ to suggest that the
	      list is describing the exports of a module.
	  <ENTRY><TAG/MATH/
	  <ENTRY><TAG/MATH.EXTERN/
	  <ENTRY><TAG/MATH.CHOICE/
	  <ITEM>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 <ATTRIB/TYPE/ attribute (default is LaTeX).
	      <CODE DISPLAY><![ RCDATA [<MATH>x^2+y^2=z^2</MATH>]]></CODE>
	      since rendering math on different media can be tricky,
	      the author may also supply a choice of alternative
	      notations:
	      <CODE DISPLAY><![ RCDATA [
<MATH.CHOICE>
  <MATH LATEX>x^2+y^2=z^2</MATH>
  <MATH HTML><&NOOP;![ RCDATA [X<SUP>2</SUP>+Y<SUP>2</SUP>=Z<SUP>2</SUP></MATH>]&NOOP;]>
  <MATH.EXTERN TO="file:fermat.gif" TYPE=gif>
</MATH.CHOICE>]]></CODE>
	      Here the same math material is coded using three different
	      notations. The last one refers to an external resource:
	      the gif file <FILE/fermat.gif/. Note that <TAG/MATH/ has
	      content, but MATH.EXTERN is empty.
	  <ENTRY><TAG/PICTURE/
	  <ENTRY><TAG/PICTURE.EXTERN/
	  <ENTRY><TAG/PICTURE.CHOICE/
	  <ITEM>this is similar in design to the <TAG/MATH/ elements.
	  <ENTRY><TAG/CODE/
	  <ENTRY><TAG/CODE.EXTERN/
	  <ITEM><TAG/CODE/ contains program code in a programming
	      language; which programming language may be specified
	      using the <ATTRIB/PROGLANG/ attribute. All elements
	      accept the <ATTRIB/PROGLANG/ attribute: it indicates the
	      default programming language in <TAG/CODE/-like elements
	      whithin its scope. Thus, a document starting with:
	      <CODE DISPLAY><![ RCDATA [<BOOK PROGLANG=C>]]></CODE>
	      would normally assume that the programming language is
	      <NAME TYPE="PROG.LANG"/C/, unless this is overriden by
	      an element with an explicit <ATTRIB/PROGLANG/ attribute.
	      The choice of programming language may serve to obtain
	      appropriate highlighting of code.
	    <P><TAG/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 <TAG/VAR/ and <TAG/SPAN/ are also permitted.
	    <PARA><TITLE/Code Abbreviations/
	      For convenience, the Oz Documentation DTD supports the
	      following abbreviations:
	      <TABLE>
		<TR>
		  <TD><CODE><![ CDATA [<<...>>]]></CODE>
		  <TD><CODE><![ RCDATA
			[<CODE>...</CODE>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [<<<...>>>]]></CODE>
		  <TD><CODE><![ RCDATA
			[<CODE DISPLAY>...</CODE>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [?+{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR MODE=IN  >X</VAR>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [??{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR MODE=OUT >X</VAR>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [?*{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR MODE=CIN >X</VAR>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [?@{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR MODE=CNIN>X</VAR>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [?_{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR          >X</VAR>]]></CODE>
		<TR>
		  <TD><CODE><![ CDATA [?{X}]]></CODE>
		  <TD><CODE><![ RCDATA [<VAR TYPE=META>X</VAR>]]></CODE>
	      </TABLE>
	      Thus you can write:
	      <CODE><![ CDATA
		[<<{List.map ?+{L1} ?+{F} ??{L2}}>>]]></CODE>
	  <ENTRY><TAG/VAR/
	  <ITEM>may occur in ordinary text and also in
	      <TAG/CODE/ elements.  <TAG/VAR/ serves to
	      identify <LIST INLINE ENUM><ITEM>programming language
	      variables <ITEM>meta variables <ITEM>environment
	      variables <ITEM>non-terminal symbols in a
	      grammar</LIST>.  The choice is determined by attribute
	      <ATTRIB/TYPE/.
	      <LIST CLASS="ATTRIBS">
		<ENTRY><ATTRIB/TYPE/
		<ITEM>indicates the type of object represented by the
		    <TAG/VAR/ element.
		    <LIST>
		      <ENTRY><NAME TYPE="SGML.IDENT"/PROG/
		      <ITEM>programming language variable
		      <ENTRY><NAME TYPE="SGML.IDENT"/META/
		      <ITEM>meta variable
		      <ENTRY><NAME TYPE="SGML.IDENT"/ENV/
 		      <ITEM>environment variable
		      <ENTRY><NAME TYPE="SGML.IDENT"/GRAMMAR/
		      <ITEM>grammar non-terminal
		    </LIST>
		<ENTRY><ATTRIB/MODE/
		<ITEM>The <ATTRIB/MODE/ attribute further describes
		    the expected modes of parameters to builtins and
		    library procedures.
		    <LIST>
		      <ENTRY><NAME TYPE="SGML.IDENT"/IN/
		      <ITEM>input (determined)
		      <ENTRY><NAME TYPE="SGML.IDENT"/OUT/
		      <ITEM>output (usually free)
		      <ENTRY><NAME TYPE="SGML.IDENT"/CIN/
		      <ITEM>&NIX;
		      <ENTRY><NAME TYPE="SGML.IDENT"/CNIN/
		      <ITEM>&NIX;
		    </LIST>
	      </LIST>
	  <ENTRY><TAG/PTR/
	  <ENTRY><TAG/REF/
	  <ENTRY><TAG/PTR.EXTERN/
	  <ENTRY><TAG/REF.EXTERN/
	  <ITEM>serve for cross-references.  For cross-references
	      within the same document, use <TAG/PTR/ or <TAG/REF/.
	      <TAG/PTR/ is empty and <TAG/REF/ has content.
	      <CODE DISPLAY><![ RCDATA
		[<REF TO=FOO>The definition of foo</REF>]]></CODE>
	      might produce a hyperlink in HTML and insert reference
	      text like <Q/Definition 3.2, page 17/ in &LATEX;.
	      <CODE DISPLAY><![CDATA[<PTR TO=FOO>]]></CODE>
	      might insert a hyperlink with content <Q/Definition 3.2/
	      in HTML and again insert <Q/Definition 3.2, page 17/ in
	      &LATEX;.  <CODE/FOO/ is the ID of the element containing
	      the definition of interest.  Somewhere else in the
	      document there would be an element like:
	      <CODE DISPLAY><![ RCDATA [
<PARA CLASS=DEFINITION ID=FOO>
  <TITLE>Procedure <&NOOP;<Foo>&NOOP;></TITLE>
  ...
</PARA>]]></CODE>
	      If the element pointed to is a <TAG/NOTE/, then in HTML,
	      <TAG/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 <ATTRIB/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.
	    <P>When the object that needs to be referenced does not
	      reside within the current document, we must make an
	      <Q/external/ reference.  Such references cannot take
	      advantage of the ID mechanism of SGML. Instead, the
	      <ATTRIB/TO/ attribute contains data which it is up to
	      the processing system to properly interpret, perhaps
	      aided by a <ATTRIB/CLASS/ attribute.  Often, <ATTRIB/TO/
	      will contain a url:
	      <CODE DISPLAY><![ RCDATA [
Visit <REF.EXTERN TO="http://www.ps.uni-sb.de/oz/">the Oz home
page</REF.EXTERN>]]></CODE>
	      But it can contain other data for which a conventional
	      interpretation has been assigned in the processing
	      system.  Thus, we might refer to the <NAME
		TYPE=TITLE>Open Programming Manual</NAME> as follows:
	      <CODE DISPLAY><![ RCDATA [
For details about IO programming, see <PTR.EXTERN
TO="ozdoc:open">.]]></CODE>
	  <ENTRY><TAG/FILE/
	  <ITEM>borrowed from <NAME TYPE=TOOL/Texinfo/.  marks up a
	      file name:
	      <CODE DISPLAY><![ RCDATA
		[<FILE>/usr/local/oz/README</FILE>]]></CODE>
	  <ENTRY><TAG/KBD/
	  <ITEM>borrowed from <NAME TYPE=TOOL/Texinfo/.  marks up
	      keyboard input:
	      <CODE DISPLAY><![ RCDATA [<KBD>M-a</KBD>]]></CODE>
	  <ENTRY><TAG/KEY/
	  <ITEM>borrowed from <NAME TYPE=TOOL/Texinfo/.  marks up the
	      conventional name for a key on a keyboard:
	      <CODE DISPLAY><![ RCDATA [<KEY>RET</KEY>]]></CODE>
	      However, this can also be marked up using <TAG/NAME/:
	      <CODE DISPLAY><![ RCDATA
		[<NAME TYPE=KEY>RET</NAME>]]></CODE>
	  <ENTRY><TAG/SAMP/
	  <ITEM>borrowed from <NAME TYPE=TOOL/Texinfo/.  marks up a
	      literal example of a sequence of characters:
	      <CODE DISPLAY><![ RCDATA [<SAMP>foo</SAMP>]]></CODE>
	  <ENTRY><TAG/NAME/
	  <ITEM>marks text that names an object; which kind of object
	      should be indicated using the <ATTRIB/TYPE/ attribute:
	      <TABLE>
		<TITLE/Examples uses of the <ATTRIB/TYPE/ attribute/
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=FICTIONAL.CREATURE>Gump</>]]></CODE>
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=TOOL>Gump</>]]></CODE>
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=CHAR>NUL</>]]></CODE>
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=PERSON>Denys Duchier</>]]></CODE>
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=KEY>RET</>]]></CODE>
		<TR>
		  <TD><CODE><![ RCDATA
			[<NAME TYPE=OS>Linux</>]]></CODE>
	      </TABLE>
	  <ENTRY><TAG/Q/
	  <ITEM>marks quoted phrases:
	      <CODE DISPLAY><![ RCDATA [
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!]]></CODE>
	      or
	      <CODE DISPLAY><![ RCDATA [
Here goes another one of Microsoft's <Q
CLASS=SOCALLED>upgrades</Q>; down the drain, where it belongs!]]></CODE>
	  <ENTRY><TAG/SPAN/
	  <ITEM>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 (&EG; for cross
	      reference purposes) or a <ATTRIB/CLASS/ for whatever
	      purpose was not anticipated by the DTD.
	      <CODE DISPLAY><![ RCDATA
[<SPAN ID=FOO>...</> ... <PTR TO=FOO> ...]]></CODE>
	  <ENTRY><TAG/DEF/
	  <ITEM>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 <ATTRIB/CLASS/ attribute to indicate 
	      what kind of term is being defined.
	  <ENTRY><TAG/FIGURE/
	  <ITEM>a figure contains displayed material.  It may have an
	      optional <TAG/TITLE/, and an optional <TAG/CAPTION/
	      containing a longer description.  Here is an example
	      adapted from the TEI DTD documentation:
	      <CODE DISPLAY><![ RCDATA [
<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>]]></CODE>
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/FLOAT/
		<ITEM>A <TAG/FIGURE/ may also float outside of the
		    main flow of the document. This can be indicated
		    by attribute <ATTRIB/FLOAT/:
		    <CODE DISPLAY><![ RCDATA
			[<FIGURE FLOAT>...</FIGURE>]]></CODE>
		<ENTRY><ATTRIB/CLASS/
		<ITEM>The <ATTRIB/CLASS/ attribute should be used to
		    indicate what kind of a figure it is:
		    <CODE DISPLAY><![ RCDATA
			[<FIGURE FLOAT CLASS=PICTURE>...</FIGURE>]]></CODE>
		    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 (&EG; here: a list
		    of pictures).
	      </LIST>
	  <ENTRY><TAG/NOTE/
	  <ITEM>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
	      <ATTRIB/CLASS/ should be used to indicate what kind of
	      <TAG/NOTE/ is intended.
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/FOOT/
		<ITEM>since footnotes are a major application of
		    <TAG/NOTE/s, the attribute <ATTRIB/FOOT/ can be
		    used instead of <CODE/CLASS=FOOT/:
		    <CODE DISPLAY>
		      <![ RCDATA [<NOTE FOOT>...</NOTE>]]>
		      =
		      <![ RCDATA [<NOTE CLASS=FOOT>...</NOTE>]]></CODE>
	      </LIST>
	  <ENTRY><TAG/INDEX/
	  <ITEM><TAG/INDEX/ is allowed everywhere in the scope of the
	      <TAG/BOOK/ element.
	      <CODE DISPLAY><![ RCDATA [<INDEX>foo</INDEX>]]></CODE>
	      When several levels of indexing are required, they can
	      be entered separated by <CODE><![CDATA[<AND>]]></CODE>:
	      <CODE DISPLAY><![ RCDATA
		[<INDEX>foo<AND>bar<AND>baz</INDEX>]]></CODE>
	      The <ATTRIB/CLASS/ attribute can be used to support
	      multiple kinds of indexes:
	      <CODE DISPLAY><![ RCDATA [
<INDEX CLASS=PERSON>Maupassant</INDEX>
<INDEX CLASS=PROCEDURE>FoldL</INDEX>]]></CODE>
<!-- not supported by translator yet:
	      For a <Q/see/ reference:
	      <CODE DISPLAY><![ RCDATA [
<INDEX>un<AND>deux<SEE>one<AND>two<AND>french</INDEX>]]></CODE>
-->
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/SEE/
		<ITEM>allows one index to refer to another by ID, and
		    is a way to mark up a <Q/see/ reference:
		    <CODE DISPLAY><![ RCDATA [
<INDEX ID=one.two.fr>one<AND>two<AND>french</INDEX>
...
<INDEX SEE=one.two.fr>un<AND>deux</INDEX>]]></CODE>
		<ENTRY><ATTRIB/SORT.AS/
		<ITEM>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 <ATTRIB/SORT.AS/
		    attribute is intended to supply text to use for
		    sorting instead of the contents.
		<ENTRY><ATTRIB/SCOPE/
		<ITEM>To index a range of pages, you may supply one or
		    more element IDs as the value of the
		    <ATTRIB/SCOPE/ attribute.
		    <CODE DISPLAY><![ RCDATA
[<INDEX SCOPE=section.bar>foo<AND>bar</INDEX>]]></CODE>
		    would associate to this index entry the range of
		    pages covered by the element whose ID is
		    <CODE/section.bar/.
		    <CODE DISPLAY><![ RCDATA
[<INDEX SCOPE="par.bar1 par.bar2">foo<AND>bar</INDEX>]]></CODE>
		    would associate with the entry the range of pages
		    covered by the two elements with ID
		    <CODE/par.bar1/ and <CODE/par.bar2/ (presumably
		    consecutive).
	      </LIST>
	  <ENTRY><TAG/GRAMMAR/
	  <ENTRY><TAG/GRAMMAR.RULE/
	  <ENTRY><TAG/GRAMMAR.ALT/
	  <ENTRY><TAG/GRAMMAR.NOTE/
	  <ITEM>formal syntactic definitions often make use of
	      BNF-like notation. A <TAG/GRAMMAR.RULE/ marks up a
	      grammatical production.  The body of the rule consists
	      of a sequence of <TAG/GRAMMAR.ALT/ elements.  Each
	      <TAG/GRAMMAR.ALT/ element may end with a
	      <TAG/GRAMMAR.NOTE/ element that provides an inline
	      comment for the element. <TAG/GRAMMAR/ contains a
	      sequence of <TAG/GRAMMAR.RULE/ elements that belong
	      together: it could provide the additional service of
	      ensuring pleasant vertical alignment.
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/TYPE/
		<ITEM><TAG/GRAMMAR.ALT/ can be further specified using
		    attribute TYPE
		    <LIST CLASS=ATTRIB.VALUES>
		      <ENTRY><NAME TYPE=SGML.IDENT/DEF/
		      <ITEM>indicates that this element begins a new
			  rule body.  Usually this is rendered with an
			  initial symbol like <SAMP/::=/
		      <ENTRY><NAME TYPE=SGML.IDENT/ADD/
		      <ITEM>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
			  <SAMP/+=/
		      <ENTRY><NAME TYPE=SGML.IDENT/OR/
		      <ITEM>indicates the start of the next
			  alternative rewriting.  Usually this is
		      rendered with initial symbol <SAMP/|/
		      <ENTRY><NAME TYPE=SGML.IDENT/SPACE/
		      <ITEM>indicates the continuation of the previous
			  <TAG/GRAMMAR.ALT/ element. Usually this is
			  rendered by breaking to a newline but
			  omitting any initial symbol
		    </LIST>
	      </LIST>
	  <ENTRY><TAG/TABLE/
	  <ENTRY><TAG/TR/
	  <ENTRY><TAG/TD/
	  <ENTRY><TAG/TH/
	  <ITEM>a <TAG/TABLE/ consist of rows marked with <TAG/TR/.  A
	      row consists of a sequence of data <TAG/TD/ and header
	      <TAG/TH/ cells, each of which may span several columns
	      as specified by attribute <ATTRIB/COLSPAN/.
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/COLSPAN/
		<ITEM>for <TAG/TH/ and <TAG/TD/, indicates the number
		    of column spanned by the element. When omitted,
		    the cell spans exactly one column.
	      </LIST>
	  <ENTRY><TAG/BACK/
	  <ITEM>container for back-matter material, such as
	      <TAG/BIB.EXTERN/ for bibliographic entries.
	  <ENTRY><TAG/BIB.EXTERN/
	  <ITEM>refers to a specific entry denoted by attribute
	      <ATTRIB/KEY/ in an external bibliographic database
	      denoted by <ATTRIB/TO/.
	      <CODE DISPLAY><![ RCDATA
[<BIB.EXTERN ID=ZIPPY TO="weirdo.bib" KEY="elzippo91">]]></CODE>
	      <LIST CLASS=ATTRIBS>
		<ENTRY><ATTRIB/ID/
		<ITEM>the <ATTRIB/ID/ makes it possible to <Q/cite/
		    the entry:
		    <CODE DISPLAY><![CDATA[<PTR TO=ZIPPY>]]></CODE>
		<ENTRY><ATTRIB/TO/
		<ITEM>denotes an external bibliographic database from
		    which the actual contents of the bibliographic
		    entry will have to be extracted. 
		<ENTRY><ATTRIB/KEY/
		<ITEM>denotes the desired entry in the external
		    bibliographic database.
	      </LIST>
	  <ENTRY><TAG/CHUNK/
	  <ITEM>provides literate programming support.  A chunk of
code is named by its <TAG/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
<TAG/CHUNK.REF/.
	  <ENTRY><TAG/CHUNK.REF/
	  <ITEM>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.
	</LIST></P>

    <CHAPTER ID=chapter.extending>
      <TITLE/Extending the DTD/

      <P>For a particular document, it may be desirable to slightly
modify or extend the DTD.  You can do this by defining
<CODE/input.local/ as a <CODE/SYSTEM/ entity referring to a file
containg the required definitions.  This file is read after the
generic attribute entities have been declared, but before the
remaining entities having to do with content models.</P>

      <P>Thus the file can contain declarations for additional
elements that can take advantage of the generic attribute entities,
and it can override the content model parameter entities if necessary
(this is because the 1st declaration of an entity wins, subsequent
declarations for the same entity are ignored).</P>

      <P>Normally, at the most, you should consider adding some
phrasal elements.  This can be done simply by defining parameter
entity <CODE/p.mix.local/:
<CODE DISPLAY>
<![ RCDATA [<!ENTITY % p.mix.local "| foo | bar">]]></CODE>
Note the leading vertical bar: it is required because
<CODE/p.mix.local/ is concatenated to the end of a disjunction of
elements.</P>

      <P>The typical way to extend the DTD is to place your
declarations in a file, say <FILE/myaddons.sgml/, which may also
contain a definition of <CODE/p.mix.local/ as shown above.  Then your
document should use a <CODE/DOCTYPE/ header of the form:
<CODE DISPLAY><![ CDATA [
<DOCTYPE BOOK SYSTEM "ozdoc.dtd" [
<!ENTITY % input.local SYSTEM "myaddons.sgml">
]>]]></CODE></P>

    <CHAPTER ID=chapter.editing>
      <TITLE/Editing SGML Documents/

      <P>The <NAME TYPE=TOOL/PSGML/ package for <NAME TYPE=TOOL/emacs/
provides a very nice editing environment for SGML documents.  You
might put the following in your <FILE>~/.emacs</FILE> file:
<CODE DISPLAY PROGLANG=ELISP>
(setq load-path (cons "?{PSGML_DIR}" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</CODE>
where ?{PSGML_DIR} is the directory in which <NAME TYPE=TOOL/PSGML/ is
installed.  At our lab, this directory is:
<FILE>/project/ps/emacs/lisp/psgml</FILE></P>

      <P>To turn on fontification of SGML document, also add the
following:
<CODE DISPLAY PROGLANG=ELISP>(setq sgml-set-face 't)</CODE>
You may also specify what font faces to use for highlighting.  Here is
what I (Denys) am using today:
<CODE DISPLAY PROGLANG=ELISP>
(setq sgml-markup-faces
  '((start-tag . font-lock-reference-face)
    (end-tag   . font-lock-reference-face)
    (comment   . font-lock-comment-face  )
    (pi        . font-lock-keyword-face  )
    (sgml      . font-lock-type-face     )
    (doctype   . font-lock-type-face     )
    (entity    . font-lock-keyword-face  )
    (shortref  . font-lock-reference-face)))
</CODE>
Strangely enough, when you open an SGML file for editing, the
fontification process always waits for 6 seconds of idleness before it
actually gets going.  This is annoying, but hard coded.</P>

      <!-- parsed dtd -->
      <P>For each document, <CODE PROGLANG=ELISP/psgml-mode/ parses
the DTD and uses this information to help editing (it knows what is
legal, where).  Normally it uses the <CODE><![ RCDATA
[<!DOCTYPE ...>]]></CODE> declaration at the top of the document to
find theDTD.  There are 2 common cases where that doesn't work well:
when the DTD is in a location that <NAME TYPE=TOOL/PSGML/ cannot find
and when editing part of a document in a separate file that doesn't
have the <CODE/DOCTYPE/ declaration.</P>

      <P>In such cases it is easier to load a <Q/parsed DTD/; it is
also much faster. The easiest way to save a parsed DTD is to create,
in the directory where the DTD is located, a file containing the
following line:
<CODE DISPLAY>&lt;!DOCTYPE ?{ELEM} SYSTEM "?{DTD}"&gt;</CODE>
and to invoke <Q/Parse DTD/ and then <Q/Save Parsed DTD/ from the DTD
menu. Then, when editing a partial document, you can manually invoke
<Q/Load Parsed DTD/ from that same menu.</P>

      <!-- fill mode -->
      <P><CODE PROGLANG=ELISP>fill-mode</CODE> is also nice to get
automatic line breaking, but, in my experience, it is better to turn
<CODE PROGLANG=ELISP/adaptive-fill-mode/ off, otherwise, due to the
indentation of nested element, you'll soon be writing in a very narrow
column at the right of the page. For example, you might add the
following code at the end of and SGML document:
<CODE DISPLAY PROGLANG=ELISP>
&lt;!--
Local Variables:
mode: sgml
mode: auto-fill
adaptive-fill-mode: nil
End:
--&gt;
</CODE>
as far as SGML is concerned, this is a comment, but is meaningful to
<NAME TYPE=TOOL/emacs/.
</P>
</BOOK>
<!--
Local Variables:
mode: sgml
mode: auto-fill
sgml-indent-data: nil
adaptive-fill-mode: nil
End:
-->
