======================================
				  G E N O T D
		       A DTD-to-OTD Translation Utility
		    ======================================

Design and documentation by David Sklar
Software by Pierre Richard



******> WHAT AN INSTALLATION OF GENOTD LOOKS LIKE

WARNING TO PC-BASED USERS: If you pkunzip without the -d option, 
you will get an incorrect installation directory.  
Only with the -d option will you get the directory
tree shown below!

   ./    (this represents the "installation directory" of your choice)
      genotd.exe   (executable)
      otddefs.ent  (data file needed by executable)
      data/
          config/	(If you do not have this several-layer hierarchy
               ...	 under data/, you installed genotd incorrectly.)
          dtd/
               ...
	  ents/
               ...

Note that your current directory must be the installation directory
when you launch GENOTD.


========================================================================


STEP 1.  BECOME FAMILIAR WITH DynaTag OUTPUT-OBJECT TYPES

You must first become familiar with the four output-object types:
	Paragraph-level object
	Character-level object
	Container (also called a "block container")
	TOC-level container (represented by its associated title bearer)

The best way to do that is to experiment with the use of DynaTag.  Note that
DynaTag's AutoMap feature automatically creates output objects of only the
first two types (paragraph-level and character-level).



2.  ANNOTATE YOUR DTD

Make a copy of your DTD and annotate that copy.

Add the following lines near the very top:
	<!ENTITY otddefs SYSTEM "./otddefs.ent">
	%otddefs;

Then, visit the declaration of each element type and determine whether the
element type is a possible destination for a DynaTag mapping operation.  If it
is, determine which of the four output-object types is the most appropriate
"category" for the element type.

Then, add an annotation to the ATTLIST declaration for that element type.  (If
the element type does not already have an ATTLIST declaration, then create one
for it so you have a place to put the annotations.)


If you feel the element type should be listed as a paragraph-level object,
add the following to the ATTLIST for that element type:
	%otd-para

For example, consider this declaration of an element designed to contain a
one-paragraph notice or warning:
	<!ELEMENT notice - - (#PCDATA)>
	<!ATTLIST notice 
		type (note|warning|caution) #REQUIRED>

After annotating the ATTLIST to specify that it is a DynaTag paragraph object,
the ATTLIST will look like this:
	<!ATTLIST notice 
		type (note|warning|caution) #REQUIRED
		%otd-para>

Be very careful to distinguish between element types that are paragraph-level
versus element types that should really be considered block containers.  For
example, an element type that represents a list item should be considered to be
a block container if its content model includes (for example) tables or the
possibility of multiple paragraphs.
	

If you feel the element type should be listed as a character-level object,
add the following to the ATTLIST for that element type:
	%otd-clf


If you feel the element type should be listed as a block container,
add the following to the ATTLIST for that element type:
	%otd-block


If you feel the element type is a TOC-level container, then you also need to
determine the proper section-level number (a number from 1 to 31, inclusive)
and determine the GI of the element (which must be a legal direct child) that
serves as its title bearer.  For example, consider this declaration of a
high-level container called PART:
	<!ELEMENT part - - (TITLE, CHAPTER*)>

If you determine that a "part" is a level-3 container and that its title bearer
is its TITLE child, annotate it by adding the following ATTLIST decl:
	<!ATTLIST part
		%otd-sect-level "3"
		%otd-title-bearer "TITLE">


Note that you should never modify an <!ELEMENT declaration; all annotations are
performed via annotating <!ATTLIST declarations.
	



STEP 3.  GENERATE AN OTD

'Cd' to the installation directory.

Feed the annotated DTD to the GENOTD program:
	genotd my.dtd

GENOTD always emits a file called "out.otd".




STEP 4.  INSTALL THE OTD

Here you have two choices.

A.  Copy the out.otd into an existing project directory, renaming it so
it replaces the project's existing OTD.  This technique is risky if the project
already has rules; if the new OTD is not a superset of the original OTD, some
of the rules will be damaged because they refer to output objects that no
longer are declared.  So use this technique only with great care.

B. Copy the out.otd into the dtagdata/otds directory and give it a name
(e.g. cals.otd, docbook.otd) that reflects its source.  Once an OTD is
installed in the dtagdata/otds directory, it becomes available to the user of
DynaTag during project creation.  WARNING: when a new project choose an otd
from dtagdata/otds, it make a local copy of the .otd file; thus, updating the
.otd file in the dtagdata/otds directory has no effect on existing projects.

===========================================================================

One final note: If your DTD is currently still under development, it may not be
wise to annotate a *copy* of it, because you will have to perform extra work to
keep the two (the original and the copy) in synch.  Be aware that annotating a
DTD with the "%otd..."  annotations is a benign action: it has no side-effects
that would affect the DTD's useability.  For example, a document instance that
conforms to the original (unannotated) DTD also conforms to the annotated one.
So you may wish to consider annotating the DTD that you are actually working
on, rather than worrying about keeping two separate DTDs in synch.