[DOC-SIG] Xrefs

[Mark Hammond]

[Fred wrote]

>  It sounds like we're in reasonable agreement on this.
>  Comments from anyone else?

Of course :-)  Sorry about their delay tho...

Before I start, I should state my "position".  IMO, if we do a good enough
job with gendoc, people will _generally_ use the documentation generated,
rather than attempting to browse the sources directly.
Therefore, I would prefer to sacrifice readability for functionality - ie,
if we need to make _small_ parts of the docstring scan not so well for a
human, but it significantly enhances the gendoc output, then I am all for
it.
Just MO of course - I am sure others do not agree.

OK:

The proposal is:
> .. [name] in <namespace-type>[:] <namespace-name>
eg: """
  see also foo in function mymodule
"""

My main problem with it is that it only allows you to insert a hyperling to
object "foo" by using the word "foo".  What if I wanted the documentation to
have a hyperlink to an object, but I want the hyperlink text to be something
other than the object name - say a phrase or complete sentence.

And I also cant see what "namespace-type" gives us?  The name itself
determines
the object and if we use Python's normal scoping rules, then a given name
can mean exactly one object.  If you get a different object than you expect,
I would consider it a "documentation bug" in the same way it would be a bug
in code.  Rudimentary testing of the generated documentation would find it.
Id find it ironic if the Python documentation was more type-safe than Python
itself :-)

However, I _could_ see the <namespace-type> being useful for other reasons.
[Brainstorm]
If ommitted, it means "Python".

You could use it to reference source files themselves - eg, .  Eg, a
namespace could be "sourcefile", and the formatting tools could make the
appropriate hyperlink

You could allow "plug-in" namespaces.  Eg, if may be possible to allow me to
develop a "win32api" namespace, so I could insert cross-references into the
Microsoft API documentation.  With this moving to HTML itself, it may be
quite feasable.

You could provide a namespace called "html" and replace the existing
hyperlink stuff with this.
[/Brainstorm]

As a poor starting point, I would consider:
<reference text|object name|namespace>

It does not screw human scanning completely, and infact may help with the
highlighting that a link exists, even if you can't click to see it.

Here is an example of some docstrings that I could forsee myself writing
with this functionality :-)

""" ... this example makes use of the <win32com client
support|win32com.client>
  It is very similar to the <other sample in
othersample.py|win32com.demos.othersample.py|sourcefile>.

  It makes very heavy use of the bizarre <Python feature
spam|www.python.org|html>,
  and the bizarre feature <eggs that the win32 API provides|eggs|win32api>
"""

Or am I way off track?

Here is another curly one for you all - if we support cross-references,
should we also support generating and reading "map" files?  If we did, it
would be possible for a whole suite of seperately generated gendoc code to
be completely cross-referenced and  indexed.  Something like this will be a
necessity (ok - very handy :-) if we are ever to allow someone to press the
"help" key in a
Python IDE, and have it find the correct keyword, or have people reference
each others packages.  Eeek!!  But worth at least thinking about for a few
seconds :-)

FWIW, I would be happy to contribute in this general xref area if we can nut
out general agreement...

[Im also going to want to be able to plug in my own "parser", "scanner",
"importer" or whatever you call the thing that "collects" the documentation
info into the Python structures.  I have lots of C++ code in a "special"
format that I could then use, and drop my winhelp files alltogether...  If
you have seen my Windows stuff, all the winhelp files are generated purely
from C++ sources!
But that is a different issue. :-)]

Mark.



_______________
DOC-SIG  - SIG for the Python Documentation Project

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