[Bioc-devel] BioC 2.5: "suspect" interpackage links

[Gordon K Smyth]

Dear Seth, Patrick, Martin and others,

I'd like some advice on the issue of interpackage links.

The R 2.10.0 NEWS file says:

 	- The HTML help can now locate cross-references of the form
           \link[pkg]{foo} and \link[pkg:foo]{bar} where 'foo' is an
           alias in the package, rather than the documented (basename
           of a) filename (since the documnetation has been much
           ignored).

I agree that links of this type are highly desirable and should be 
encouraged.  Yet any link of this type causes a WARNING message in R 
2.10.0 cmd check as a "Suspect" link.  Hence links of this sort can't be 
used if one wants to pass R cmd check without warnings, which a package 
needs to do to be included in a Bioconductor release.

I understand that I could fix the problem with \link[pkg:rdfilename]{bar}, 
but I believe that the specific naming of files in a developer's package 
directory is up to them.  I think it is unreasonable to be expected to 
keep track of what everyone else chooses to name their files, considering 
that the file name is completely arbitrary and doesn't have to bear any 
relation to the function name or help alias.  I'd prefer to remove the 
links than have to do that.

Should I remove all links of this sort from my Bioconductor packages, or
wait for a better resolution?

Regards
Gordon

---------- original message ----------------
[Bioc-devel] BioC 2.5: Broken interpackage man page links
Seth Falcon seth at userprimary.net
Fri Sep 4 20:46:56 CEST 2009

* On 2009-09-04 at 09:37 -0700 Patrick Aboyoun wrote:

> R-devel has recently begun surfacing long-time broken man interpackage 
> man page links such as \link[base]{mget} (corrected link: 
> \link[base:get]{mget} since mget is described in base's get.Rd file). Up 
> until this point, broken interpackage man page links were not discovered 
> through R CMD check. Now these broken links are assigned WARNINGs.

There is some discussion in the r-core group about this warning and
the behavior of \link[foo]{bar}.  The discussion has not concluded,
but there is a reasonable chance that the behavior of \link will at
least be enhanced to support the commonly used form of
\link[package]{topic} (rather than {filename} and that the warning
will not appear for these cases.

+ seth

-- 
Seth Falcon | @sfalcon | http://userprimary.net/user