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

Tue Sep 29 03:22:00 CEST 2009

Checking yet further, all warnings (except for the self-reference to 
limma:00Index) 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 (under Windows only) if I install the Bioconductor 
packages in the normal way using biocLite("Biobase") etc.

Gordon

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

> Hi Chao-Jen and Martin,
>
> On further checking, it turns out that most of the "missing" and "suspect" 
> messages I'm getting from R 2.10.0dev CMD CHECK are Windows-specific. This 
> supports your guess that the problem may be a locale or character set issue.
>
> All warnings which appear in Unix/Mac we have been able to fix.  The 
> following warning messages appear only under Windows, not Unix or Mac.
>
> 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 Thu, 24 Sep 2009, Chao-Jen Wong wrote:
>
>> 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
>> 
>> 
>