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

[Gordon K Smyth]

Hi Martin,

Thanks for the superquick response.

I'll hold off for a short time on removing cross-links, but there are two 
reasons which disuade me from adding file names.  Firstly, even a fully 
correct link with complete file name may still be flagged as "Suspect", 
for example

   \link[marray:read.Galfile]{read.Galfile}

As far as I can see, "read.Galfile.Rd" is the correct file name, yet this 
is flagged as suspect.  Perhaps R cmd check is confused by the extra 
period in the file name?

Secondly, I'd be happy to add names once, but not to keep updating them on 
an ongoing basis as people reorganise their file names.

As an aside, it's ironical that the some links are flagged by the only 
version of R in which they actually work, and not by the versions of R in 
which they don't work.  I also find it perverse that links like 
\link{qnorm}, which give no guidance as to the package, are fine but 
\link[stats]{qnorm}, which correctly narrows down the package, is 
"Suspect".

Regards
Gordon

On Wed, 23 Sep 2009, Martin Morgan wrote:

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