[Doc-SIG] htmldoc.py and inspect.py

[Walter Doerwald]

At 18:54 30.05.00, Ka-Ping Yee wrote:
>At 15:09 30.05.00, Juergen Hermann wrote:
> > I'm currently using pdoc.py, and I will definitely will give your script
> > a look. What I would like VERY much would be a Python doc system that
> > shares as much as possible with the JavaDoc/DOC++/Doxygen world,
> > especially the "commands" to provide semantic markup (like \param spam).
>
>On Tue, 30 May 2000, Walter [iso-8859-1] D=F6rwald wrote:
> > I would prefer if the semantic markup would use XML. XML was designed
> > to be used for stuff like that
>
>This was a decision i made about the philosophy of the doc
>generation script.  I chose to have it display the docstrings
>exactly as they are in the code.  This makes the script small,
>predictable, and incapable of screwing up in any significant way. [1]
>
>Also this avoids the entire issue of exactly what particular
>structured-text formatting conventions you're going to use.

But eventually someone has to implement some structured text docstring.
Plain ASCII dumps just don't cut it anymore.

And when you use XML you can convert this to practically any format
that is out there (PDF, TeX, ASCII, ...)

The display of docstring inside Python does not have to be
a plain dump of the docstring. How about a man-style display
build into Python? This could be done either via man or via a
ASCII web browser or ...

>I do like structured text (indeed, WikiWiki is WwWonderful)

WwWhat?

>but you should see just how long discussions can go on and on
>about how best to do this sort of thing.
>
>Better to just get something done and working and out there
>than continue debating, i think.

Well I started to implement an XML documentation package
as an example from my HTML generator XIST
(ftp://titan.bnbt.de/pub/livinglogic/xist/), but as this
was only meant to be an example, I'll probably cancel the
project. You might take a look at it. Perhaps it's possible
to combine both.

>By the way, that's a very unusual middle name, Walter. :)

50 years of computer science and I still can't type my name
into an email. I'm really impressed! :-(

Bye,
         Walter D=F6rwald

>[...]