documentation cross references under R 2.10.0dev for Windows

Rcmd check under R 2.10.0dev for Windows seems to be issuing a number of 
spurious warning messages about Rd cross-references.

The following warning messages appear when checking the latest (non-public) 
version of the Bioconductor package limma.  They appear only under Windows, 
not Unix or Mac.  All the flagged links appear to be ok, in that they 
specific a genuine html file, and should therefore not be marked as suspect 
or missing.

Regards
Gordon

* using R version 2.10.0 Under development (unstable) (2009-09-27 r49846)
* using session charset: ISO8859-1
* checking Rd cross-references ... WARNING
Missing link(s) in documentation object './man/01Introduction.Rd':
 '[limma:00Index]{LIMMA contents page}'

Suspect link(s) in documentation object './man/asmalist.Rd':
 '[marray:marrayNorm-class]{marrayNorm}'

Suspect link(s) in documentation object './man/asmatrix.Rd':
 '[Biobase]{exprs}'

Suspect link(s) in documentation object './man/dupcor.Rd':
 '[statmod]{mixedModel2Fit}'

Suspect link(s) in documentation object './man/EList.Rd':
 '[Biobase]{ExpressionSet-class}'

Suspect link(s) in documentation object './man/imageplot.Rd':
 '[marray]{maImage}'

Suspect link(s) in documentation object './man/intraspotCorrelation.Rd':
 '[statmod]{remlscore}'

Suspect link(s) in documentation object './man/limmaUsersGuide.Rd':
 '[Biobase]{openPDF}' '[Biobase]{openVignette}' '[base]{Sys.putenv}'

Suspect link(s) in documentation object './man/malist.Rd':
 '[marray:marrayNorm-class]{marrayNorm}'

Suspect link(s) in documentation object './man/normalizebetweenarrays.Rd':
 '[marray:maNormScale]{maNormScale}' '[affy:normalize]{normalize}'

Suspect link(s) in documentation object './man/normalizeWithinArrays.Rd':
 '[marray:maNorm]{maNorm}'

Suspect link(s) in documentation object './man/normexpfit.Rd':
 '[affy:bg.adjust]{bg.parameters}'

Suspect link(s) in documentation object './man/readgal.Rd':
 '[marray:read.Galfile]{read.Galfile}'

Suspect link(s) in documentation object './man/rglist.Rd':
 '[marray:marrayRaw-class]{marrayRaw}'



On Wed, 23 Sep 2009, Duncan Murdoch wrote:

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