Re: [Rd] link to an alias in another package
In summary
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}. ...
\code(\link[stats:varimax]{promax}}
works but will probably break if promax is ever moved to its own Rd
file. (From the discussion there is probably not a better general solution.)
\code(\link{promax}}
works because stats is always installed, but is not a general solution
because I have other cases where the package may not be installed.
\code(\link[stats:promax]{varimax}}
which might be another (but presumably mistaken) interpretation of the
Writing R Extensions documentation
\link[pkg:bar]{foo} to link to the package pkg with topic (file?)
foo and bar respectively.
does not work and also displays varimax in the text (which is not what
I want).
Paul Gilbert
__
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] link to an alias in another package
On Tue, 8 Feb 2005 07:18:28 + (GMT), Prof Brian Ripley
[EMAIL PROTECTED] 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:
- 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.
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
Re: [Rd] link to an alias in another package
On Tue, 8 Feb 2005, Duncan Murdoch wrote:
On Tue, 8 Feb 2005 07:18:28 + (GMT), Prof Brian Ripley
[EMAIL PROTECTED] 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, [EMAIL PROTECTED]
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, UKFax: +44 1865 272595
__
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] link to an alias in another package
On Tue, 8 Feb 2005 12:21:05 + (GMT), Prof Brian Ripley
[EMAIL PROTECTED] wrote :
On Tue, 8 Feb 2005, Duncan Murdoch wrote:
On Tue, 8 Feb 2005 07:18:28 + (GMT), Prof Brian Ripley
[EMAIL PROTECTED] 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.
I only see two differences between the current scheme and the last
case:
- now no warning is printed, which does seem reasonable, given that
there exist mutual cross-references.
- my scheme would require that a topic name be repeated as an alias
if both the first and last type of lookups were possible.
Alternatively, we could allow lookups by topic name as well as alias
for back-compatibility.
Other than these, I don't see how the current scheme is better. In
the current system:
- If I use an unadorned \link{promax}, I run the risk of having it go
to the wrong place if someone defines a promax alias in some other
package that is installed before mine.
- If I use \link[stats:varimax]{promax}, then I run the risk of
having it go to the wrong place if someone splits promax.Rd out of
varimax.Rd in the stats package.
- If I have a spelling error in the link (e.g.
\link[stats:varmax]{promax}), then neither INSTALL nor CHECK will tell
me about it.
None of these would be a problem if I used \link[stats]{promax} under
my proposal, unless my package were being installed before stats was,
in which case the link would fail.
But if that's a possibility (e.g. we're talking about a core package,
or a package with mutual dependencies with the referenced one so that
we can't be sure which will be installed first), then we could simply
document that references to aliases might fail. Two packages with
mutual dependencies are presumably being maintained together, so the
second problem above wouldn't be an issue.
Have I missed some advantages of the current scheme over the one I
proposed? There's the obvious one of the fact that it exists, whereas
mine will take a bit of work to do, but if I don't hear of some fatal
flaw, I'll volunteer to do the work. I don't think it will be hard.
Duncan Murdoch
[Rd] link to an alias in another package
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?
Thanks,
Paul
__
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] link to an alias in another package
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.
You only need the [] to disambiguate crossreferences, or to refer to
packages that might not yet be installed, which does not apply to [stats].
--
Brian D. Ripley, [EMAIL PROTECTED]
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, UKFax: +44 1865 272595
__
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
