[DOC-SIG] Xrefs (was)Status of documentation effort?

[Fred L. Drake]

Friedrich, Robin K writes:
...
 > .. [Party] in module: Disco
 > """
 > In this case gendoc would look for documented object 'Party' in module
 > Disco. We'd have to have other context indicators like package and then
 > maybe bore down to the containing namespace by slash separated names,
 > e.g. 
 > .. [method] in package: Dance/Disco/Party
 > 
 > to completely specify the Party.method cross reference. A problem crops
 > up if you want to reference two objects of the same name in different
 > namespaces. Ideas?

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).
  Using slashes instead of dots is adding new & unnecessary syntax;
dots work well in Python, and these are references to Python objects.
Tools can use whatever internal representations are needed easily
enough.
  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
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.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________