[Doc-SIG] docstring grammar
Edward Welbourne <email@example.com>
Tue, 30 Nov 1999 17:34:28 +0000
> 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
[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 ?