[Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long)

[Manuel Gutierrez Algaba]

On Fri, 4 Feb 2000, Tony J Ibbs (Tibs) wrote:

> (Apologies to Moshe, to whom I inadvertently sent a separate copy of this -
> the perils of hitting "Reply" instead of "Reply All" in Outlook <fx:spit>)
> 
> 
> Either I'm terminally confused (I hope that's it), or else several people
> must have been murdered at IPC8...

Since the beginning, I knew that the "official" line will succeed and
any other "lines" ( some of them with a lot of common sense) will
be easily erased:

- eval docstrings 
- hyperreferences
- indexes 

I proposed or I contributed an approach:
http://www.ctv.es/USERS/irmina/mandoc/mandoc.py

but I didn't finish it, partly because I got bored, partly because
I knew the official line had XML in mind. 

> 
> If I'm understanding things, Moshe is proposing (officially) a
> text-intensive form of markup for use within doc strings. This is designed
> to be easily mapped to (for instance) XML, and is nearly as verbose. If I
> have understood that correctly, then I have two immediate comments:
> 
> 1. Why don't we just use XML? - the proposed format is almost as verbose,
> and has the disadvantage that it is a new format "for the sake of it" [1].

The question is which are the benefits of a XML-ish doc string system?
Certainly, the casual programmer is not going to write doc in 
a grammar that is far more complex than the language ( python) itself.

So I think, this so complex doc strings aims other objectives,
it's intended to be robust, and to be used by "proffesional" people.

When I mean "professional" I mean what people thinks professional is.
Professional usually means little complex but clearly defined and
massively used. Most people would consider Java more professional
than python, because it's more used and less complex ( or its 
complexity is biased towards "professional things"). Visual Basic
and Windows are very "professional" too.

"Professional" always involves two words: "fashionable",
 "stupid-enough".

XML is both: fashionable and "stupid-enough".

Even admitting that XML is very useful, I think it's completely
stupid to use XML whenever there's an exchange of data between 
programs or whenever we have to declare a structure. I think XML
is the glue that unites "Black boxes", each program should be
a black box, but inside that Black box I can live without XML. 

Now, documenting can be considered a black box, we can always
support a XML layer in the most external step of documentation,
and use an internal mini-language or tags or whatever suits our
needs better. 

But all this is against "professional" stuff because:
- It gives an unnecessary flexibility ( professionals want stiff
systems)
- It gives more than one way to do it (professionals want only one
solution)
- It uses academic rubish : black boxes, modularity. Any professional
want to hard-wire and write the less code as possible. Any professional
will tell you that the less interfaces the better. The TRUTH is 
that the more interfaces you use , the more freedom degrees are
available for you, and better maintainance. But "professional" like
the hard way, rewrite code and such. 

Of course, being "professional" is the logical step for python,
it will lose most of its charm but it'll make more money.
Linux is suffering the same evolution, btw.

> 
> 2. What happened to all the people who were going to refuse to use such a
> format if it were more verbose than the proposal being circulated pre-IPC8
> (which I thouhgt was generally agreed on)? There's been no explanation of
> why they've suddenly reversed position, if they indeed have.

I can't fight against the world. I must add that few people is 
interested in the problem itself. The problem is as simple as this:
 - A rich, flexible and used by many people, way of doc

This implies more than a solution, but generating XML in the 
last step. Used by many people implies extremely simple and encouraging,
I think my "mandoc" is simple, and I must add that there should
be more than one way of simple documentation.

> 
> As a smaller note, Moshe seems to be leaving out "cross references" as

Cross references are extremely useful but they're never as impressive
as a set of magic words. Many people suggest their own recipe
of magic words for the problem , of course, professional like 
magic words. But they're not magic at all, but just a tool for 
describing things, the interesting thing is expression capability.
Crossreferences express the inner structure and as many relationships
as we want to, unfortunately they're not magic.

> 
> [1] If we're going to have our own format, it has to give *significant*
> benefits to readability/typability/etc, because having to translate into
> something else to determine if it is legitimate (in the "valid XML" sense)
> already makes it that much harder to correlate errors back to the original
> text. I don't see those benefits here.

I can't agree with this, pure XML would be always more buggy.


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

  I have an existential map. It has "You are here" written all over it. -- Steven Wright