From: Fred L. Drake[SMTP:fdrake@cnri.reston.va.us] Robin, Why not:

.. [Party] in module: Dance.Disco.Party

for module attributes, and require that the module name be fully qualified? Or that using just one name is searched for in "current package, global package" order (meaning the "current package" needs to be known, which is not unreasonable).

On second thought, requiring full qualification is probably the best since it requires the least new understanding on the part of the user. And when reading the code this will be the most helpful as relying on the tool's searching rules won't help the reader of the source. And yes the . separator is more appropriate.

We can generalize this a little by using the form:

.. [name] in <namespace-type>[:] <namespace-name>

The colon should be omitable (new word?!); some people may like it for presentation, but it carries no content. Identifying the footer line

I do like it for presentation and to help disambiguate the namespace type from the namespace name itself. Just because it carries no information content doesn't mean it's not mentally useful. And in general I don't like optional tokens.

should be done only on the leading ".." and brackets around the name. <namespace-type> should allow checking the reference to be sure it matches what's found at the target; I expect "class", "module", and "package" might be usable. Perhaps allow "namespace" to signify an namespace of arbitrary type. Overall, this seems like a very reasonable notation.

Agreed. Robin

_______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________