[Doc-SIG] Re: Ease of use is #1

[Peter Funk]

Hi!

[ping]:
> > [there follow some 450 lines of description]

[Moshe]:
> No, 10 lines of description and 450 lines of a module done up in the way I
> propose.
> 
> Ping, it seems you didn't even read my message.

I don't want to be pernickety, but this is plain wrong!  
Moshe's syntax makes no sense at all without the list of 
tags (attributes) which is longer than 10 lines:

> List of tags, and where they are valid:
>         code (both as long and short) -- anywhere
>         example (long, no attributes) -- anywhere
>         arg, return (attributes: name, type, default (optional) ) -- 
>                 function docstring, never inside another long tag.
>         rest-arg, kw-arg (long, no attributes) -- 
>                 function docstring, never inside another long tag.
>         data (attributes: name, type) -- 
>                 class/module doc-string, never inside another long tag.
>         exception (attributes: name) -- 
>                 class/module doc-string, never inside another long tag.
>         member (attributes: name, type) -- 
>                 class doc-string, never inside another long tag.
>         function, module, class, exception, var, method, keyword, member,
>         pytype, file, url, arg (short tag) -- anywhere
> 
>         (these are for general markup syntax, so I've probably forgotten
>         some):
>                 list (long tag) -- anywhere
>                 item (long tag) -- anywhere
>                 emph (short tag) -- anywhere 

This list is on one hand too complex (as we have seen in this discussion,
the average Python programmer will hardly bother with such a beast) and on 
the other hand still incomplete.

As ping pointed out before, the vast majority of the tags listed by
moshe above can be discovered from context of the python modules.

[Moshe]:
> While I admire the way you markup by "guessing", I must admit I have my
> qualms about this approach: too little control for the documenter.
> Possibly, a mix of the two approaches is in order.

I think, it would be very valuable, if we could come up with a more
formal description (grammar?) of how this "guessing" markup engine works
or should work.  

As long as this wonderful artificial intelligence code build into
the guessing engine works well, no one has to bother with it.  But
if it fails, the documenter shouldn't be forced into a deep swamp
regexp (that is the situation right now, if you are unsatisfied by
the results of gendoc or pythondoc).  That is the point, where 
in IMHO the "docstring grammar" comes into play: Giving the documenter
who cares about the output the chance to correct misinterpretations
of guessing engine.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60