[Doc-SIG] On David Ascher's Rant

[Manuel Gutierrez Algaba]

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

It's the SAME ! SantisimaInquisicion/TeEncontreX is NOT, I say,
is NOT, TeX. It was TeX some billion years ago!

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

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

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

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

Pity that you don't make the try of understanding it. In 10 minutes
you'd get the whole functioning of it all!

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
 /SantisimaInquisicion/index.html 

  Disease can be cured; fate is incurable. -- Chinese proverb