DTD's for Python

[David Durand]

>Hi David.
>
>I'm writing for some technical advice.

Sure, and I'm afraid that I'm continuing the tradition of computer
scientists who study the "important problems." I don't follow all the
details of all the DTDs and tools avaialble out there, so I may miss one or
more obvious right things...

> I'm on the Python DOC-SIG, and
>we're once again considering what the right way to encode the Python
>documentation is, especially the library reference.  Right now it's in
>pretty simple LaTeX, but we'd like to go to a real markup language, with
>all the advantages that represents.

>I threw in the idea of using the
>Linux LDP tool which is basically the QWERTZ DTD and SGML.  Someone
>objected to the coarse nature of that DTD.  Someone else suggested using
>XML.

The Linux tools already work in one of your major target environments,
which is possibly a big factor. If they are easy to tailor, you could use
some of their code as a starting point to getting things to work nicely.
Docbook is a well-reputed DTD, though I confess to never having read it.
Both Eve Maler and Terry Allen are sharp, experienced people. There must be
some existing PD tools for it, but I'm afraid I don't know what they are. I
think that Docbook comes from the Davenport group stuff (but I might be
wrong). You can check this page and see:
   http://www.ora.com/davenport/index.html

Cost 2.0 is a much improved tool, but slumming it in TCL would probably
turn your stomach.

XML is a great language, but the tools are not there right now (though
there are _2_ draft parsers in Java). You can parse XML with simple Perl
scripts, and that in fact is how the current XML docs wend their way from
XML->HTML and XML->RTF... But you'd probably be rolling your own. On the
other hand having XML support in the Python web-browser would be an
impressive thing, so maybe there's a volunteer out there to do the coding.

>Do you have any bright ideas?  Our concerns are:
>
>  - Free [The language reference was just changed to FrameMaker and that
>    caused quite a ruckus, even though people just want to print it].

You can do decent SGML->Postscript with Frame, I think. That might be good
for your output needs... Of course, if you're backing off from the frame
decision, then this is not acceptable.

>  - Conversion to PostScript and HTML relatively easy and full-featured
>    Has to look good, of course.

On of the harder things with SGML of any flavor, of course, as someone has
to write the scripts or macros to _make_ it look good.

>  - Allow the creation of a Python-specific DTD (with markup of
>    syntactic elements for example).

You can extend almost any DTD pretty easily. You probably want to still the
big, document striucture parts, and then play around with specialized
elements for code examples, and maybe the reference sections, where a lot
of navigational help would be useful.

>  - HTML which does smart things with references to other parts of the
>    document (==HREF's).
> 
Again, it comes down to the scripts you write to do the conversion.You
could just munch on SP output like everyone else in the world does. I'd
also happily give you my YASP/TCL interface, but someone would have to move
it to Python (I assume), and it's not really documented...

When you get things a bit more narrowed down I may be of more help. Don't
forget Robin Cover's SGML pages -- it may take you a morning to read, but
they are _very_ complete.

>Cheers,
>
>--david

_________________________________________
David Durand              dgd@cs.bu.edu  \  david@dynamicDiagrams.com
Boston University Computer Science        \  Sr. Analyst
http://www.cs.bu.edu/students/grads/dgd/   \  Dynamic Diagrams
--------------------------------------------\  http://dynamicDiagrams.com/
MAPA: mapping for the WWW                    \__________________________



_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________