[Doc-SIG] docstring grammar

[David Ascher]

On Mon, 29 Nov 1999, Edward Welbourne wrote:

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

Agreed.  I am removing that bit about ignoring #'ed text from my proposal.

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

After a little thought, I'm tempted to remove the :: requirement as well.
In my proposal, I think that using the : after Example was a mistake in
style.  If it was a heading then it should just be text w/o a colon. If it
was supposed to be more of a sentence then it should have been spelled
out, as in:

   For example, we can have:

The *intent* was, however, to avoid the 'danger' you note above.  I'm
still open to go either way, "safe" or "comfortable".

I forgot two markups:  *this* is bold and _this_ is italic.  Bold and
italic markups must begin and end within a paragraph (I'd say 'within a
sentence' but I don't want to complicate the parser with a sentence type).
No space allowed between *'s and _'s and their contents.

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

By all means, we should borrow from gendoc if it's already solved those
issues.  I admit not to having looked deeply into gendoc.  I'll look into
this some more a bit later.

> Proposed by someone who knows how to write parsers ...

Uh?  Me?  No way.  You must be confusing me with someone else!

--david