... where would I begin if I wanted to tackle such a thing?

I forgot to mention was that you should also look at: - spec/docutils.dtd: This is the authority on the standard Docutils elements and their relationships. It may give you some clues about the semantics of Docutils document tree nodes. - "Project Policies" in spec/notes.txt: This is an overview of how the Docutils project is set up, and some guidelines that will help make development go smoothly. (Also online at http://docutils.sf.net/spec/notes.html#project-policies) As always, feedback is welcome. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

I've been lurking here for quite a while, but thought I would weigh in quickly on the issue of DocBook output, since I spent a good portion of the last year working with about a dozen developers creating a DocBook-based documentation system for a research programming and specification language. We experimented with "custom" markup syntaxes, automatic DocBook generation from source code, etc., and the experience was not as pleasant or fruitful as I had initially hoped. Basically, DocBook is the 400-lb. gorilla of markup formats. Most of our developers never used more than a 12-25 of the several hundred available element types, simply because there were too many to remember the proper nesting and attribute declaration policies for. The semantic richness of fully "DocBook-ized" documentation is impressive, but the time involved in actually placing more than basic structural and keyword markup around the text proved prohibitive in most cases. WRT to the choice of top-level element ('book', 'chapter', 'article', et. al.), I would have to recommend starting with the Simplified DTD, unless you're going to allow some sort of inline directive in the source to make the chapter, section, and appendix blocks explicit. Of course, you could just create one "default" template which included a "global" foreword, and then had chapters assigned to each source file in the original document, but it seems like an awful lot of work just for something that's usually intended to be an precursor format for HTML, PDF, or LaTeX final output. If you're seriously committed to DocBook output, though, might it not be easier to simply use an XSLT stylesheet to convert the DocUtils "native" XML format (basically just a dump of the internal document node structure, IIRC) into DocBook, rather than a seperate Python implementation? I'm a die-hard Python user, as well, but XSLT really is a great tool for this kind of deep tree walking and transformation task, esp. when your input and output are already both going to be XML documents. One specific "gotcha" to keep an eye out for: DocBook tables are painful, compared to HTML. Web browsers, and even other document publishing tools, are pretty good about making a "best guess" attempt at laying out simple tables according to their contents, with little or no explicit size information from the author, but most of the DocBook rendering tools I've used tend to mangle any table that doesn't include explicit column widths. In short, personally, I don't see any real use to DocBook output if HTML and PDF are already available with any degree of customizable formatting. Of course, that doesn't exclude the possibility that you might really want/need DocBook and XMLspec. So, now that I've done my soapboxing for the day, it's time for some breakfast. Good luck, either way. Lennon Day-Reynolds P.S.: To everyone who's contributed to the Doc-SIG, reST, etc., I say, "Good work!" Things are starting to look really good, guys and gals. On Saturday, June 15, 2002, at 09:56 PM, Dethe Elza wrote:

OK, thanks for the feedback.

For reference, Simplified Docbook (current draft) is at: http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml The DTD is specifically aimed at documents with root <Article>.

And the XMLspec info is at: http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm

I've done a bit more of my homework and read through the HTML writer, which looks clear enough. Sometimes I forget how easy it is to read the source in Python. Of course, it helps when the project is well-organized. Kudos to you.

I've also joined the mailing lists, will load from CVS later.

Thanks and I hope to be of some help.

--Dethe

-- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/

_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig

Lennon Day-Reynolds mail: lennon@day-reynolds.com www: http://day-reynolds.com/lennon/