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

[Walter Doerwald]

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