[Doc-SIG] docstring grammar

[Robin Friedrich]

From: David Ascher <da@ski.org>
> 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>

grumble grumble...see below.
>
> 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.

Why? keywords are arbitrary strings. (may include spaces, etc.)
>
> 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'.

Yes. However I really don't like the idea of HTML finding its way into the
doc string. The BiblioEngine would be told the information of the reference
and, along with what rendering mode she is in, emit the appropriate output
format, be it HTML, XML, PDF, etc.
>
> --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.

Agreed.