[Doc-SIG] docstring grammar
Tue, 30 Nov 1999 12:56:10 -0800 (Pacific Standard Time)
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.