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

Mon Sep 28 08:22:56 CEST 2009

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