[Doc-SIG] htmldoc.py and inspect.py
Walter Doerwald
walter@livinglogic.de
Tue, 06 Jun 2000 18:47:24 +0200
At 09:17 01.06.00, Ka-Ping Yee wrote:
>On Wed, 31 May 2000, Walter Doerwald wrote:
> >
> > But eventually someone has to implement some structured text docstring.
> > Plain ASCII dumps just don't cut it anymore.
>
>Hmm. I have two answers to that:
>
> (a) What is the burning need to structure the text anyway?
I might want to do an <ol type=3D"a">, like you tried to do here.
Or any other feature of HTML, like tables, paragraphs, <dl>s
Unicode characters, links, ...
And of course be can have any kind of markup we like.
Some day we might even generate class hierarchy diagrams in SVG.
> What information do you expect to need to automatically
> extract from within individual docstrings? Since they
> are really for human consumption, and at the level of
> entire docstrings, not little pieces, plain ASCII really
> does get you 90% of the way. ("man" still works pretty
> well, right?)
But AFAIK man *does* use syntactic markup.
> (b) Sure, i grant you that a little style and formatting
> might be nice. (But only "nice", not "essential".
One mans niceties are another mans essentials. >;)
> The only thing that seems close to essential might be
> marking symbol names and code fragments.) Anyway, in
> this case, i like Paul's suggestion very much: we'll
> just provide a hook for you to do your own parsing
> and formatting, and that leaves the door open for you
> to implement structured text if you want.
That doesn't solve the problem: Either I write my docstrings
in XML or I don't. A simple ASCII parser doesn't make the XML
in the docstring go away.
>Hmm. Maybe a third answer:
>
> (c) Even though right now the state of existing docstrings
> makes for a minimal payoff from using structured text,
> i can see a particular structured text standard getting
> much more established by the time, say, Python 3000
> arrives -- when the document-generating tool is mature,
> and we are ready to overhaul everything, then it may
> actually be possible to declare, "This is the standard
> way to write docstrings." Then a big payoff is possible.
Sounds good.
> > And when you use XML you can convert this to practically any format
> > that is out there (PDF, TeX, ASCII, ...)
>
>No one will bother to write XML by hand in their code. Really.
>I mean it. To take an example from MathML, who on earth is going
>to write
>
> <apply>
> <plus/>
> <mn>x</mn>
> <mn>y</mn>
> </apply>
>
>instead of writing x+y? I count a factor of at least 15.
You picked one of the worst examples there is.
>[...]
Bye,
Walter D=F6rwald