[Doc-SIG] docstring grammar

[Edward Welbourne]

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