[Doc-SIG] htmldoc.py and inspect.py
Ka-Ping Yee
ping@lfw.org
Thu, 1 Jun 2000 00:17:47 -0700 (PDT)
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