[Rd] R v2.10.0: Doc clarification for cross references and where are we heading?

[Henrik Bengtsson]

Hi,

in 'Writing R Extensions" of R v2.10.0, under Section
'Cross-references' (2009-09-07) it says:

1. "The markup \link{foo} (usually in the combination
\code{\link{foo}}) produces a hyperlink to the help for foo. Here foo
is a topic, that is the argument of \alias markup in another Rd file
(possibly in another package)."

2. "You can specify a link to a different topic than its name by
\link[=dest]{name} which links to topic dest with name name. This can
be used to refer to the documentation for S3/4 classes, for example
\code{"\link[=abc-class]{abc}"} would be a way to refer to the
documentation of an S4 class "abc" defined in your package, and
\code{"\link[=terms.object]{terms}"} to the S3 "terms" class (in
package stats). To make these easy to read, \code{"\linkS4class{abc}"}
expands to the form given above."

3. "There are two other forms of optional argument specified as
\link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to
files foo.html and bar.html respectively. These are rarely needed,
perhaps to refer to not-yet-installed packages (but there the HTML
help system will resolve the link at run time) or in the normally
undesirable event that more than one package offers help on a topic20
(in which case the present package has precedence so this is only
needed to refer to other packages). They are only in used in HTML help
(and ignored for hyperlinks in LaTeX conversions of help pages), and
link to the file rather than the topic (since there is no way to know
which topics are in which files in an uninstalled package). The *only*
reason to use these forms for base and recommended packages is to
force a reference to a package that might be further down the search
path. Because they have been frequently misused, as from R 2.10.0 the
HTML help system will look for topic foo in package pkg if it does not
find file foo.html."


Trying to summarize the above, do we have the following markups/rules?

A. \link{<topic>} - where <topic> must occur as an \alias{<topic>},
but not necessarily as an \name{<topic>}.  The link will be display as
the string <topic>.
B. \link[=<topic>]{<name>} - where <topic> must occur as an
\alias{<topic>} with a \name{<name>}.  The link will be display as the
string <name>.
C. \link{<packageName>]{<name>} - where <name> must be a \name{<name>}
in a package named <packageName>.  The link will be display as the
string <name>.
D. \link{<packageName>:<name>]{<label>} - where <name> must be a
\name{<name>} in a package named <packageName>.  The link will be
display as the string <label>.  There are no restrictions on <label>.
E. \linkS4class{<className>} expands to
\link[=<className>-class]{<className>}.  From (B) it then follows that
there must be an \alias{<className>-class} and a \name{<className>}.


Q1. Is that correct?  To me it look a bit inconsistent.

Q2. Are there more?

Q3. Will there be more?

Q4. What about

\link[=<topic>]{<label>}
\link{<packageName>:<topic>]{<label>}

where <label> can be (almost) any string?

Q4. Are (A) and (B) only supposed to be used for linking within a
package, or can it be used to link to "wherever" <topic> exist?

Q5. It sounds that (C) and (D) should be avoided.  Is that correct?

Q6. What if <topic> exist in two packages 'pkgA' and 'pkgB' and I want
to specify that I mean topic <topic> of package 'pkgA', cf namespaces
and pkgA::foo()?

Q7. I the 1st paragraph above it says "(possibly in another package)"
and in the 3rd paragraph above it is mentioned at "The only reason to
use these forms [...] is to force a reference to a package that might
be further down the search path" - is that the answer to Q4?  Will
\link{<topic>} be *dynamically* linked to whatever comes first on the
search() path - to reflect the running environment rather than the
intention of the document?

Reading between the lines, the development of Rd looks exiting.
Instead of 2nd guessing where we are heading, could someone in charge
please give some thoughts on what the plans are and an estimate on how
long it will take before we are there - what R version?


MISC:
I understand that \link[=<className>-class]{<className>} is part of
standard Rd conventions, but to the best of my knowledge
\link[=<className>.class]{<className>} is not, correct?  I would like
to suggest to write a separate paragraph for S4 classes without
mentioning S3 classes.  The following also adds to the confusion -
there exists one Rd page with \name{terms} and one with
\name{terms.object}, so it is not really clear what
\link[=terms.object]{terms} is strictly supposed to do - is it of form
\link[=<topic>]{<name>} or \link[=<topic>]{<label>}.  Maybe it is
helpful to clarify what the static/dynamic link will be and what will
be display.

Thanks

Henrik

PS. This is related to today's (Sept 23, 2009) BioConductor posts by
Gordon Smyth - "[Bioc-devel] BioC 2.5: "suspect" interpackage links";
https://stat.ethz.ch/pipermail/bioc-devel/2009-September/001975.html