[DOC-SIG] Xrefs

[Friedrich, Robin K]

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