Re: [Rd] link to an alias in another package

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Tue 08 Feb 2005 - 21:05:56 EST

On Tue, 8 Feb 2005 07:18:28 +0000 (GMT), Prof Brian Ripley <ripley@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 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.

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 doing at least as well as \link{foo} does would take very little work. The algorithm could be:

This would mean \link[stats]{promax} would be fine, and would survive the addition of a promax topic to another package, or the splitting of promax out of the varimax topic.

>You only need the [] to disambiguate crossreferences, or to refer to
>packages that might not yet be installed, which does not apply to [stats].

Duncan Murdoch



R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Tue Feb 08 20:11:49 2005

This archive was generated by hypermail 2.1.8 : Fri 18 Mar 2005 - 09:02:45 EST