[Doc-SIG] Re: Links between documents?

[Fred L. Drake]

  Skip Montanaro wrote, in mail to python-docs, that inter-document
linking and/or a combined index would be very useful, especially since 
may people use the HTML version of the documentation.
  I agree; I've been trying to improve the level of hyperlinking in
the manuals[1], but don't have anything for inter-document linking yet.
I've looked into LaTeX approaches to this, and some things do exist.
None of them seem to be quite right, but I don't expect it to be too
difficult to create something that is close enough and has the right
level of support.
  I think the primitive should be something like \doclink{tag}{label}, 
where tag is an ID for the target document (something like api, ext,
lib, mac, etc.), and label is a name defined by \label in the other
document.  There should be something similar, like
\modlink[key]{tag}{modulename}, for use with module.  (Modules have
the nasty property that their names may include underscores, which
break all things TeXish in the Python documentation, and also numbers, 
which break my experimental platform dependence annotation; "key" is
used to provide an alternate identifier to use in constructing the
parameter to \label.)
  A combined index will be a bit easier, and has crossed my mind
before.  The scripts that process index information probably won't
need to much augmentation.  (Patches welcome.)
  Any ideas?  Suggestions?


  -Fred

[1] Note the addition of \refmodule to the set of macros; this creates 
    a hyperlink to a module section within the same document, with the 
    link text being the module name.  This is essentially a linking
    version of \module.  As I've had to do things to sections, I've
    been looking for opportunities to convert \module to \refmodule.

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191