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

[Martin Morgan]

Hi Gordon --

Gordon K Smyth wrote:
> 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?

An excellent question.

First, the links have always been broken, it is only now that they are 
being flagged as such.

Second, the 'Suspect' links work in HTML, but not in other documentation 
forms, in particular PDF I think, so they are still broken for some users.

Third, I really agree that the name of the Rd file in which an alias is 
documented is too private.

I don't know what the likelihood of further change is in this, but will 
try to find out.

My own strategy has been to update links as required to avoid the 
warning and to provide useful documentation, this has not proven too 
onerous. My recommendation would be to fix if that is your cup of tea, 
but to hold off on removing the links -- this sounds like it should 
really be a last resort.

Martin

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


-- 
Martin Morgan
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M1 B861
Phone: (206) 667-2793