[Doc-SIG] docstring grammar

[David Ascher]

On Tue, 30 Nov 1999, Robin Friedrich wrote:

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

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

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

I don't recall putting HTML in the docstring.  Just a URL.