[Doc-SIG] On David Ascher's Rant

[M.-A. Lemburg]

Manuel Gutierrez Algaba wrote:
> 
> On Sat, 27 Nov 1999, M.-A. Lemburg wrote:
> > > 1) The current Python documentation is, in my opinion, just fine.  I think
> 
> It's fine if you read it all of it, NOT FOR SEARCHING, FOR SEARCHING
> IS NOT FINE.

Hmm, not sure I can follow you here: there is a very nice index
which helps you pin-point most details and if you use the PDF
version you even get full-text search at no extra cost.

> > >    There is at least one proposal to index in-code Python docstrings
> > >    with TeX-like commands.  In my opinion, anything that full of
> > >    backslashes and braces will never fly in the Python community.
> >
> > I don't think people will start to write TeX in their docstrings...
> > after all not everyone can read plain TeX and will get pretty
> > confused about all those backslashes and curly brackets.
> 
> Ok, I think the syntax I proposed is quite bad ( from your comments),
> instead of \newcommand{\indexalfa}{\index{alfa}} and \indexalfa
> why not ?
> <@indexalfa,alfa>  and <#alfa>

This would probably make things a little less TeX-like.
 
> It's the SAME ! SantisimaInquisicion/TeEncontreX is NOT, I say,
> is NOT, TeX. It was TeX some billion years ago!

Well, it sure looks a lot like TeX. Believe me, I've written
LaTeX and TeX for many years -- I know that people don't like
it. Even I had my troubles with it at first. The syntax simply
isn't compatible with human reading habits and this is basically
what doc strings are all about: online help.
 
> > IMHO, a clean plain text approach goes much further; together
> > with some conventions on how to format this text and intelligent
> > tools to extract the information encoded by those conventions
> > will certainly make the writing docstrings much more popular.
> 
> Two big problems: tight conventions and intelligent tools.
> It seems to me hard stuff, for use and for programm.

The conventions need not be too tight. I've been using the
ones I mentioned for some time now and incorporated some of
it in my doc.py tool (which you can find on my Python Pages).
Works fine... for me at least.

> > BTW, in case someone cares, the format I use for docstrings and
> > function/method signature goes as follows:
> ...
> >         All tuples in the joinlist are turned into real strings.  The
> >         resulting list is a equivalent copy of the joinlist only
> >         consisting of strings.
> >
> >     """
> 
> My method can be used for USENET post, FAQ, .py, and *anything*
> in ASCII form. Yours seem just a signature-teller, that is fine BTW,
> but it's not the idea I'm proposing,

Right. The intention is to extract data from python scripts,
nothing more.
 
> I'm just proposing to focus in the Semantic in the Meaning, in the
> What ( a function, module, post, whatever...) does.
> 
> > > 3) Programmers in general, smart programmers especially, try to "think
> > >    out" all of the possible uses for something before they start to design
> > >    it.  That's why God Invented Managers and deadlines.  We need one or
> > >    the other.
> >
> > Right. And it's even worse in the Python community: they first try
> > to prove NP-completeness rather than think about good reasonable
> > approaches for the common case.
> 
> If you spent half an hour, just, attributing your own code or a
> FAQ with the \indexblabla stuff, you'd be ashtoundingly surprised
> of :
> - how fast is it
> - how powerful/flexible
> - how much can it help others understand what you've done.
> 
> It seems to me you don't want to even try to understand my proposal.
> It's damned simple and direct, but of course, if you don't make
> the try of thinking/understanding ... then ...!

Of course I have tried to get the idea... from what I understood
I can say, that I don't like the syntax you use. The system
itself may have its merrits, but the syntax is a bummer, IMHO.
 
Something about the general idea of automatic documentation:
I have tried to proceed in that direction a few years ago to
document my Python code. From that experience I can say that
automatic documentation -- for me at least -- only serves as
aid in finding APIs etc. fast during the programming phase.
It is not useable as final documentation. All my packages
include HTML documentation which is carefully crafted to include
all those things which I intend to publish and deliberately
leave parts undocumented or only partially documented. This
is not easily possible using automatic documentation or
other literate programming approaches. The written docs simply
are different because they focus on a different intent (and
sometimes even a different audience).

> > Looks fine, but there is one catch: not everyone is going to
> > write his docstrings in English...
> 
> My system, by default , can handle any kind of language...

Hmm, what language do "jiji" and "jaja" come from ? \newcommand
also sounds very English ;-)

How about making up some more programming compatible
tags to delimit code from docs, e.g. #doc and #/doc...

-- 
Marc-Andre Lemburg
______________________________________________________________________
Y2000:                                                    33 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/