[Rd] link to an alias in another package

[Prof Brian Ripley]

On Tue, 8 Feb 2005, Duncan Murdoch wrote:

> On Tue, 8 Feb 2005 07:18:28 +0000 (GMT), Prof Brian Ripley
> <ripley at stats.ox.ac.uk> wrote :
>
>> On Mon, 7 Feb 2005, Paul Gilbert wrote:
>>
>>> In some documentation for a package I am working on I have
>>>
>>>>    \code{\link[stats]{varimax}}
>>>>    \code{\link[stats]{promax}}
>>>
>>> The link to varimax works, but not the one to promax. Promax is an alias
>>> under \name{varimax}. This kind of link works within a package, but I'm not
>>> sure if it is suppose to work when it is a link to another package. Is this a
>>> known limitation or bug, or something I should explore more carefully?
>>
>> Definitely the latter!  Don't include [stats] (why are you including it?),
>> or do read the documentation in R-exts:
>>
>>   There are optional arguments specified as \link[pkg]{foo} and
>>   \link[pkg:bar]{foo} to link to the package pkg with topic (file?)
>>   foo and bar respectively.
>>
>> so you need \code{\link[stats:varimax]{promax}}. Note the difference
>> between `topic' and `alias' here.
>
> This is not a bug, but is it a design flaw?  The problem is that Paul
> wants to refer to the documentation for promax.  Currently that's in

Not a design flaw, just a rather more carefully researched design that 
actually works.

Unless the package is present, you have no idea in what file the help for 
promax is, and you need to know to generate hyperlinks (or you don't need 
to use this notation).

Now, hyperlinks to other packages are no real use in current PDF (unless 
you merge PDF files), and HTML help will if java/javascript is enabled 
resolve the references at run time, BUT neither HTML without the search 
engine nor CHTML can do that.

Since two packages can cross-reference each other, you cannot assume that 
the one you want to reference is currently installed without a potential 
deadlock.

> the varimax topic, but if someone were to split the topics, that
> wouldn't be true any more: and then Paul's link would point to the
> wrong place.
>
> It is inconsistent that \link{foo} looks for the alias foo, but
> \link[pkg]{foo} and \link[pkg:foo]{bar} look for the topic foo.

Not in my understanding.  That's the whole (and documented) point of the 
notation, to tell Rdconv where to look when aliases are not 
known/available.

> It is probably impossible to implement links to aliases perfectly
> (e.g. if pkg is unavailable at the time the .html file for Paul's
> topic is being built, it's not clear what the link should be), but

However, that is the only common reason to use this form of link.

> doing at least as well as \link{foo} does would take very little work.
> The algorithm could be:
>
> - attempt to look up the alias foo in pkg.  If that succeeds, use the
> resulting topic in the link.
> - if pkg exists but the lookup fails, that's an error.
> - if the lookup fails because pkg does not exist, print a warning,
> and create a link as though the alias is a topic.

The last is the only time you really need this, and what is done now is 
better than your suggestion.  We set up a mechanism for precisely this 
case, and to break it would be a design flaw.

The only other known circumstance can be seen in links like

\link[stats]{logLik}
\link[stats4:logLik-methods]{logLik},

since two packages have such a topic/alias and they need to refer to each 
other.  That's most likely for S4 methods.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595