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