[Bioc-devel] BioC 2.5: "suspect" interpackage links
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