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

[Duncan Murdoch]

On 23/09/2009 10:08 PM, Henrik Bengtsson wrote:
> 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.

No, \name{} is irrelevant for links.  It's the filename that matters in 
the 3rd form.

> 
> 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?

The first is what the 2nd form refers to.  "Name" there is what is 
displayed in the file making the link.

The second is new, as of 2.10.0, and is the fallback if a filename 
matching <topic> is not found.
> 
> 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?

They should work anywhere.  The difficulty arises if you link to 
something that a user doesn't have installed, or if the link is ambiguous.

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

I think good practice is to make sure that the base of the filename 
(less .Rd) is also an alias in the file, and also the \name{} of the 
file.  The system would probably be less confusing if this were forced, 
but there are lots of files out there where it's not true.

You want the filename to be an alias because links sometimes go to 
aliases and sometimes to filenames; you want the name to match because 
that's what is displayed at the top of the page, so people might 
remember "just go to the Foo man page".

> 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()?

If you follow the good practice above, then use \link[pkgA]{topic}.  If 
you don't follow that practice, you may be out of luck, because R will 
look for the filename topic.Rd in pkgA, not \alias{topic}.  However, as 
of 2.10.0, it will fall back to the latter.

> 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?

In 2.10.0, I believe this will be the case (but I'd have to check the 
code to be sure).  I'd recommend being explicit if you are worried about 
this possibility.


> 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?

I don't think there's really someone "in charge", but I've been closely 
involved with this, so I'll give some thoughts.

Generally speaking, we have releases on a regular schedule, we don't 
hold them up for particular features.  So I don't think it would be 
possible to figure out when development on Rd files will be done.  It 
depends on when people have the time to do what they think needs doing, 
and to a large extent, that depends on how things get used.

Some things that are not there now, but which might be there in the 
future (i.e. later than 2.10.0):

  - Better support for the \Sexpr macros (which let the content of man 
pages depend on R code, executed just before rendering).  Right now 
there's no special support for that R code; it would make sense to 
define some functions to make writing such stuff easier.  (This is 
something that could be done in a contributed package, it needn't be in 
base R.)

  - Improved prompt() and package.skeleton() functions to take advantage 
of the above.

  - Graphs in man pages.

  - Ways to link from man pages to vignettes.  The reverse would be 
nice, but it's not possible with the current design, so that would be 
far off.

  - Some general rationalization of the whole help system.

Duncan Murdoch

> 
> 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
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel