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

[Chao-Jen Wong]

Hi, Gordon,

I don't think R CMD check is confused by the period in the file name.
The Biobase package has many Rd files with extra period, such as
class.ExpressionSet.Rd and class.AnnotatedDataFrame.Rd, and etc., and R
CMD check seems to recognize
\link[Biobase:class.ExpressionSet]{ExpressionSet}.  However, I did
confront the same problem that you have. I kind of suspect that might be
an "invisible" locale problem. What I did is to retype the link, and
then R CMD check worked just fine.  Nevertheless, I am not sure if that
would work for your case.

As for \link{qnorm}, since the packaged is not specified and the alias
'qnorm' is a function from the basic R packages (stats, base, util), R
CMD check is able to find the corresponding Rd that documents this
alias. On the other hand, if the package is given, R CMD check would
take 'qnorm' as the name of the Rd file and unfortunately not able to
find it. I agree with you that the syntax for the hyperlink is quiet
perverse. So, I always include the package name,  Rd file name, and
alias if and only if different from the Rd file name.

cheers,
chao-jen

Gordon K Smyth wrote:
> 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
>>
>
> _______________________________________________
> Bioc-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel


-- 
Chao-Jen Wong
Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Avenue N., M2-B876
PO Box 19024
Seattle, WA 98109
206.667.4485
cwon2 at fhcrc.org