[Doc-SIG] docstring grammar

[Edward Welbourne]

Manuel: if David includes `Keyword::' in his bits and pieces, would

Keyword::
     indexing
     keyword
     data retrieval
     searching

(within a doc-string) contain the information you've been wanting to
take out of your

\indexaboutindexing
\indexaboutkeyword
\indexretrieval
\indexsearching

etc. (with apologies for not having followed your system well enough to
mimic the names you'd actually use) ?  What I've understood of your
scheme appears to tell me the answer Yes.  If so, I guess you could just
slurp the Keyword slice out of a namespace-tree generated from
doc-strings and, I suspect, happiness would abound and confusion abate.

I know you have bits that define an indexing command that expands to
several indexing commands, which this lacks: but could the same effect
be arrived at by turning your set of indexing command definitions into
an `expert system' that expands some keywords ?

And ... to folk who know about the state of the craft of indexing: is
there a better way to go with this ?  After all, I'm pretty much just
borrowing from one of HTML's META tags here ...

Now, back to the spec itself:

> For compatibility with Guido, IDLE ... 
>        len(object) -> integer

i.e.
docstring-startline: archetypical-call [ '->' return ] ['--' summary ]

Quite apart from compatibility - this is a *good* approach.
I guess that could be why Guido does it ...

>  Each paragraph is either 'text' or a 'keyword-tagged block'.  
Sounds good.  Flesh and skeleton.

I'm with Tibs on the #-comment stuff - particularly the liberty to
simply embed a piece of python code in a doc string.

>   A 'keyword-tagged block' is nested much like Python code.
Yes, thank you very much, beautiful - this will give us scope for nested
sub-structures in the keyword-tagged data: in particular, get rid of
that Date_of_release ... use

Author:: David Ascher
Release::
    Date:: 1999/11/28
    Name:: post-gendoc-0.1
    Stability:: draft
etc.

I was initially confused about : or :: because your examples began with
the first keyword I'd thought of, namely Example, and only used one :
with that one, going on to :: for the rest - then I noticed that you
weren't offering it as an example keyword but using it to introduce your
list of examples.  While I would far sooner have only one :, those of us
advocating this need to watch for the danger that the parser will get
similarly confused between the author's use of `Example:' in the manner
of English idiom and in its keyword sense (and, of course, it isn't the
only word to worry about).  (The flip-side is: I can see myself getting
irritated by the need to say Example:: as a keyword immediately after
I've ended a paragraph with the word example ...)

Note: this keyword representation is isomorphic to XML via `the usual'
equivalences between (pythonic) indentation-structuring and the
begin-end style of structuring that C and XML use.

keyword: single-liner
->
<keyword>single-liner</keyword>

keyword: indent block dedent
->
<keyword>
block (possibly transformed down a bit itself)
</keyword>

>     Some keywords can have special parsing rules, 
coo, context-sensitive parsing ;^)
Good idea.  Lets some things only be keywords where they need to be ...

>   The above was (quickly) written with parsing in mind.  Is it really
>   easily parseable?  If not, what needs to be changed so that it is
>   parseable?
Well, the bulleting (and descriptive list stuff) has been explored
already in pythondoc / gendoc, so clearly it's all `within scope'.
Heh.  And between David and Tibs, surely we have the parsing technology ...

On the subject of vertical space ... I'd guess the parser won't need a
blank line between 
    * the end of a paragraph and

    * the start of its first indented subordinate ?

Though, indeed, I do want to take out the other blank line here, and I
thought gendoc managed that ...

>   Is there value in having string interpolation?
Yes.  Definitely.
I hadn't realised it was possible until you mentioned it, now I'm sure
it's Needed.

> Hopefully constructively, 
having had some time to think on it, I'd say Thoroughly so.

Hierarchical namespaces,
Context-sensitive parsing,
Mappable to XML but written like python,
Scope for indexing, and for arbitrary extension within sub-namespaces,
Conformance to the only important standard (Guido's de facto habits ;^)
Proposed by someone who knows how to write parsers ...
No need for the run-time system to bother with any of it
	(all hidden inside the doc string)

Thank you David,

	Eddy.
--
PS - David: you do realise, though, that the committee won't keep up the
momentum on this unless you ruthlessly play Gdo until he joins in ...