[Doc-SIG] docstring grammar

[Robin Friedrich]

My bad.
----- Original Message -----
From: David Ascher <da@ski.org>
> > > [brackets] -> <a
href="http://www.howto.python.org/rtfm.html">brackets</a>

I was interpreting the above as a doc string rewrite of my
[brackets] -> http://www.howto.python.org/rtfm.html
*in* the doc string.  Sorry.

> > Why? keywords are arbitrary strings. (may include spaces, etc.)
>
> We should watch our language =).  Keywords in my proposal are things
> before :'s which lead a paragraph and cannot contain whitespaces. Maybe we
> don't need that restrictions on things in []'s.
>
> > >   References:
> > >
> > >      PythonDotOrg:
> > >        Text: "Python's Main Website"
> > >        Link: http://www.python.org

Hmmm.  Gosh we need a glossary quick! Yup, we had different notions of
"keyword".
Do you really want arbitrary DAkeywords (stuff before colons) usable for
internal/external references?  Since this confused me, I might conclude that
it would confuse others as well.
I would have placed the following in my doc string and been satisfied...
""".....
    For further information visit:
        [Python Language Web Site] is the main source for Python itself.
        [Starship Python] houses a number of Python user resources.

[Python Language Web Site] -> http://www.python.org
[Starship Python] -> http://starship.python.net
"""
Intuitively I don't think of the word "visit" as a keyword that can be
referenced, while anything in brackets seems fair game. What other features
did you have in mind?
Dejavu'ly yours,
Robin