[Doc-SIG] docstring grammar

[Robin Friedrich]

Ed is correct.

Gendoc solved the HREF problem with:
"...An addition was made to support hypertext references. Hypertext
references are marked with double quotes in the body of the doc string. At
the end of the doc string will be a matching line starting with two dots '..
' and a space followed by the same quoted text and then followed by the
mapping (URL). This is patterned after the footnote notion in setext but is
easier on the eyes. For example, "Pythonland" will be marked as a
hyper-references to Python.org. If no matching trailing reference is found
then nothing is done. "

Which might be modified with current thinking to yield:
"""
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
"""
-Robin

----- Original Message -----
From: Edward Welbourne <eddyw@lsl.co.uk>
To: M.-A. Lemburg <mal@lemburg.com>
Cc: <mhammond@skippinet.com.au>; 'David Ascher' <da@ski.org>;
<doc-sig@python.org>
Sent: Tuesday, November 30, 1999 11:34 AM
Subject: Re: [Doc-SIG] docstring grammar


> > Since [] is only used for lists in Python, we could
> > define the RE '\[[a-zA-Z0-9_.]+\]' for our purposes and
> > raise an exception in case the enclosed reference cannot
> > be mapped to a symbol in the global namespace (note: no
> > whitespace, no commas) which either evaluates to a function,
> > method, module or reference object.
>
> umm ... hang on, two things seem stirred up here.  The proposal I
> remember from ages ago and tried to echo has [token] and the token
> doesn't have to be intelligible to the python engine: elsewhere in the
> doc string, we'll have
>
> References:
>    [token] reference text
>
> which the parsed docstring uses to decode each use of [token] that
> appeared in the docstring.  Here, reference would normally be something
> recognised by the python engine (and would be the thing I understand you
> to be putting in [brackets]), but the Reference-handler might also cope
> with it being, e.g., an URL.  The text that ends the reference becomes
> the text of the `anchor' generated:
>
> -> ... and tried to echo has <a href="reference">text</a> and the token
...
>
> note non-appeareance of [token] in the digested form: but if `text' had
> been omitted from the Reference spec, [token] is the default text
> (e.g. when what you're doing really is a citation and that's just how
> you want it to appear).  Then any uses of [None] that appear in your doc
> string, meaning `the list with one entry, None', it suffices that your
> References section doesn't have an entry for [None] - the parsed
> docstring will then just say [None] (and not even attempt to wrap an
> anchor round it).
>
> The only real relevance to forbidding [spaces within] the citation token
> is to ensure that where authors use [square brackets] for parenthetical
> remarks or as list denotations, the parser hasn't got to do the piece of
> jiggery-pokery that marks it as `maybe a xref' and obliges it to come
> back later to settle the maybe once it knows.  This cost will remain for
> [None], but it'll be well-defined that the parser marks it as a maybe,
> discovers that it isn't and settles on it being just text, not a
reference.
>
> Now, it seems to me that what you were describing was slightly different
...
> am I merely confused ?
>
> Eddy.
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG@python.org
> http://www.python.org/mailman/listinfo/doc-sig