[Rd] documentation cross references under R 2.10.0dev for Windows

[Gordon K Smyth]

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