[Doc-SIG] docstring grammar

[David Ascher]

On Tue, 30 Nov 1999, Robin Friedrich wrote:

> Hmmm.  Gosh we need a glossary quick! Yup, we had different notions of
> "keyword".

  A keyword is a case-sensitive string which:
      - starts a paragraph
      - matches  '^ *[a-zA-Z_]+[\-a-zA-Z_0-9]*: +' 
        (Python identifiers with the addition of hyphens and which end
        with a : and one or more spaces)

As (I think it was) Tibs mentioned, it's syntactic sugar for XML
notation, with the same aim of making a 'labeled' hierarchy.  Maybe the
word 'Label' is better.

  Foo:
    this is the body of foo
    which spans multiple lines

is isomorphic to

  <Foo>
  this is the body of foo
  which spans multiple lines
  </Foo>

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

No.  I intend only the DAKeywords listed in a special "References:"
section to be available as the targets of references (see below).

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

This is, I would assume, harder to parse -- you must have some implicit
rules in there regarding which [Starship Python] is a 'mention of
something else' and which is a 'this is the thing I mentioned'.  Is it the
sequential order, the 0-indent?

My vision for the same semantics as above was:

 """.....
      For further information visit:
         [PythonLanguageWebSite] is the main source for Python itself.
         [StarshipPython] houses a number of Python user resources.

      References:
         PythonLanguageWebSite:  http://www.python.org
         StarshipPython: http://starship.python.net
 """

Which leaves open the question of how we can have 'space-enabled' labels
for references which can't have spaces in them.  

One idea is to tag the [] markup with a ="stringlabel":

         [PythonLanguageWebSite="The Python.org website"] is the main
          source for Python itself.

Another possibility hinted at previously is to enrich the References
section:

     References:
        PythonLanguageWebSite:
          Label: The Python.org website
          Link: http://www.python.org

either of which, when rendered, would 'do the right thing.  I only expect
this to be an issue when referring to URLs.  Python modules, classes and
functions already have perfectly good names.  For things which are more
like *real* bibliographic references, I'd be just as happy with the
conventional [keyword] notation seen in many CS papers.

     See [ascher29] for the source of the algorithm.

     References:
       ascher29: My famous Ph.D. Dissertation, Foo University, 2029.

which would get rendered just the way it looks on your screen even in a
printed format.

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

I don't understand the above paragraph.  The word 'visit' isn't a
DAKeyword because it wasn't starting a paragraph.

--david

PS: I'm working on updating the proposal, but I have other pressing
    deadlines (such as getting the JPython tutorial ready for IPC8!), so
    it may not be ready for a couple of days.