[Doc-SIG] XML Conversion Update

Sean Mc Grath sean@digitome.com
Sat, 28 Aug 1999 12:00:56 +0100

[Fred Drake]
>  A DTD that's too minimal will not be strong enough for writing the
>documentation.  A good DTD that's workable for all the documents
>is my personal requirement: only one DTD.  More than one increases the 
>learning curve for all authors and maintainers.

I want to apologise in advance because I have not got
the time right now to fully justify what I am about to say.

Please forgive this transgression -- I will find time
and post a justification as soon as I can!

DocBook is not the answer. If anything, DocBook is the

I am a strong believe in micro-document SGML/XML architectures.
i believe a micro-document approach better suites the
Python doc project. It has advantages on many fronts - authoring,
production, maintenance, content re-use.

Here is what I suggest:

We need N *small* DTDs where N is the number of different
*types* of information that make up the Python docs.
e.g. ModuleDoc, HowToDoc and so on. Each one if these
is an "information object" and parses to the DTD
for that class of object.

Using a simple "collection" DTD, information objects
are assembled into hierarchical structures for
management and publishing purposes:-

  <title>String Services</title>
    <object uri="xyx"/>
    <object uri="abc"/>
    <object uri="def"/>

Bottom line: One big DTD is not the way to go in my opinion.
We need N tiny DTDs - one for each class of information.
We then use a simple assembly DTD such as above to
gather together information objects for publishing

I cannot close without pointing out that this
microdocument architecture approach is very well
suited to processing with Python.

I have built Python based
publishing systems using it. Whilst down-translating
to, say, HTML only two small documents need to
be loaded into Python -- the collection file and
the information object being rendered.

Also, this architecture supports semantic
naming of information objects which is very, very
useful for cross-reference creation and management.

Also, it is a no-brainer Python script to
convert from a micro-document collection to
a monolithic DTD such as docbook so that we can
piggy-back on the existing docbook downtranslates:-)



P.S. The Pyxie Open Source project that I will be
kicking off with this book will have Python
software that can be used right away to prototype
a micro-document based Python Doc architecture.

<Sean uri="http://www.digitome.com/sean.html">
Developers Day co-Chair WWW9, April 2000, Amsterdam