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

[Gordon K Smyth]

With one expection, all warnings go away when I download the relevant 
Bioconductor packages as source code and re-build them (rcmd INSTALL 
--build) on my own machine.

The warnings re-appear if I install the Bioconductor packages in the 
normal way using biocLite("Biobase") etc.  I will follow this up with the 
Bioconductor people.

The one exception is the self-reference to limma:00Index.  This marked as 
a missing link, under Windows only, although it works fine.

Gordon

On Mon, 28 Sep 2009, Gordon K Smyth wrote:

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