[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 question. 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:- <collection> <level> <title>Library</title> <title>String Services</title> <object uri="xyx"/> <object uri="abc"/> <object uri="def"/> </level> </level> </collection> 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 purposes. 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:-) yours-in-an-awful-rush-because-I-am-supposed-to-finish-"XML- processing-with-Python"-for-Prentice-Hall-this-weekend-ly, Sean 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 <uri>http://www.www9.org</uri> </Sean>