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

[Ka-Ping Yee]

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?
        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?)

    (b) Sure, i grant you that a little style and formatting
        might be nice.  (But only "nice", not "essential".
        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.

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.

> 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.

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

*sigh*  I know, it makes me really sad, too.


-- ?!ng

"To be human is to continually change.  Your desire to remain as you are
is what ultimately limits you."
    -- The Puppet Master, Ghost in the Shell