[Doc-SIG] docstring grammar

[David Ascher]

On Tue, 30 Nov 1999, Robin Friedrich wrote:

> """
> Marking refs with [brackets], and at the end of the doc string place the
> annotations ala bibliography one per line. Key "brackets" is placed in the
> local namespace and used by other (lower) doc strings. In the gendoc
> implementation if the key doesn't match anything stored in the ref mapping
> no markup in done, so that things like [None]*5 are safe and no exception
> need be raised.
> 
> [brackets] -> http://www.howto.python.org/rtfm.html
> """

Nicely said.  I'd like to point out that the transformation I had in mind
is in fact, given the above and an HTML output:

[brackets] -> <a href="http://www.howto.python.org/rtfm.html">brackets</a>

In other words the keyword is kept until the rendering stage. I suppose
that it might be necessary to allow the reference to define a different
bit of text to render instead of the keyword.

So given:

  """
  ...
  References:

     PythonDotOrg: 
       Text: "Python's Main Website"
       Link: http://www.python.org
  """

we could have:

[PythonDotOrg] -> <a href="http://www.python.org">Python's main website</a>

Or not.  Luckily I think that issue can be left to the 'bibliography
engine', just like the bullet processing can be left to the 'list engine'.

--david

PS: I would suggest that the 'if no key exists, no markup is done'
    behavior be modifiable at runtime to 'a warning is emitted', as I
    think that this sort of silent behavior is problematic given the
    presence of typos in the world.