[Doc-SIG] docstring grammar

Robin Friedrich friedrich@pythonpros.com
Tue, 30 Nov 1999 14:38:45 -0600

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
> > local namespace and used by other (lower) doc strings. In the gendoc
> > implementation if the key doesn't match anything stored in the ref
> > no markup in done, so that things like [None]*5 are safe and no
> > 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
> 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.