With one expection, all warnings 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 if I install the Bioconductor packages in the
normal way using biocLite("Biobase") etc. I will follow this up with the
Bioconductor people.
The one exception is the self-reference to limma:00Index. This marked as
a missing link, under Windows only, although it works fine.
Gordon
On Mon, 28 Sep 2009, Gordon K Smyth wrote:
Rcmd check under R 2.10.0dev for Windows seems to be issuing a number of
spurious warning messages about Rd cross-references.
The following warning messages appear when checking the latest (non-public)
version of the Bioconductor package limma. They appear only under Windows,
not Unix or Mac. All the flagged links appear to be ok, in that they
specific a genuine html file, and should therefore not be marked as suspect
or missing.
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 Wed, 23 Sep 2009, Duncan Murdoch wrote:
On 23/09/2009 10:08 PM, Henrik Bengtsson wrote:
Hi,
in 'Writing R Extensions" of R v2.10.0, under Section
'Cross-references' (2009-09-07) it says:
1. "The markup \link{foo} (usually in the combination
\code{\link{foo}}) produces a hyperlink to the help for foo. Here foo
is a topic, that is the argument of \alias markup in another Rd file
(possibly in another package)."
2. "You can specify a link to a different topic than its name by
\link[=dest]{name} which links to topic dest with name name. This can
be used to refer to the documentation for S3/4 classes, for example
\code{"\link[=abc-class]{abc}"} would be a way to refer to the
documentation of an S4 class "abc" defined in your package, and
\code{"\link[=terms.object]{terms}"} to the S3 "terms" class (in
package stats). To make these easy to read, \code{"\linkS4class{abc}"}
expands to the form given above."
3. "There are two other forms of optional argument specified as
\link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to
files foo.html and bar.html respectively. These are rarely needed,
perhaps to refer to not-yet-installed packages (but there the HTML
help system will resolve the link at run time) or in the normally
undesirable event that more than one package offers help on a topic20
(in which case the present package has precedence so this is only
needed to refer to other packages). They are only in used in HTML help
(and ignored for hyperlinks in LaTeX conversions of help pages), and
link to the file rather than the topic (since there is no way to know
which topics are in which files in an uninstalled package). The *only*
reason to use these forms for base and recommended packages is to
force a reference to a package that might be further down the search
path. Because they have been frequently misused, as from R 2.10.0 the
HTML help system will look for topic foo in package pkg if it does not
find file foo.html."
Trying to summarize the above, do we have the following markups/rules?
A. \link{<topic>} - where <topic> must occur as an \alias{<topic>},
but not necessarily as an \name{<topic>}. The link will be display as
the string <topic>.
B. \link[=<topic>]{<name>} - where <topic> must occur as an
\alias{<topic>} with a \name{<name>}. The link will be display as the
string <name>.
C. \link{<packageName>]{<name>} - where <name> must be a \name{<name>}
in a package named <packageName>. The link will be display as the
string <name>.
D. \link{<packageName>:<name>]{<label>} - where <name> must be a
\name{<name>} in a package named <packageName>. The link will be
display as the string <label>. There are no restrictions on <label>.
E. \linkS4class{<className>} expands to
\link[=<className>-class]{<className>}. From (B) it then follows that
there must be an \alias{<className>-class} and a \name{<className>}.
Q1. Is that correct? To me it look a bit inconsistent.
No, \name{} is irrelevant for links. It's the filename that matters in the
3rd form.
Q2. Are there more?
Q3. Will there be more?
Q4. What about
\link[=<topic>]{<label>}
\link{<packageName>:<topic>]{<label>}
where <label> can be (almost) any string?
The first is what the 2nd form refers to. "Name" there is what is
displayed in the file making the link.
The second is new, as of 2.10.0, and is the fallback if a filename matching
<topic> is not found.
Q4. Are (A) and (B) only supposed to be used for linking within a
package, or can it be used to link to "wherever" <topic> exist?
They should work anywhere. The difficulty arises if you link to something
that a user doesn't have installed, or if the link is ambiguous.
Q5. It sounds that (C) and (D) should be avoided. Is that correct?
I think good practice is to make sure that the base of the filename (less
.Rd) is also an alias in the file, and also the \name{} of the file. The
system would probably be less confusing if this were forced, but there are
lots of files out there where it's not true.
You want the filename to be an alias because links sometimes go to aliases
and sometimes to filenames; you want the name to match because that's what
is displayed at the top of the page, so people might remember "just go to
the Foo man page".
Q6. What if <topic> exist in two packages 'pkgA' and 'pkgB' and I want
to specify that I mean topic <topic> of package 'pkgA', cf namespaces
and pkgA::foo()?
If you follow the good practice above, then use \link[pkgA]{topic}. If you
don't follow that practice, you may be out of luck, because R will look for
the filename topic.Rd in pkgA, not \alias{topic}. However, as of 2.10.0,
it will fall back to the latter.
Q7. I the 1st paragraph above it says "(possibly in another package)"
and in the 3rd paragraph above it is mentioned at "The only reason to
use these forms [...] is to force a reference to a package that might
be further down the search path" - is that the answer to Q4? Will
\link{<topic>} be *dynamically* linked to whatever comes first on the
search() path - to reflect the running environment rather than the
intention of the document?
In 2.10.0, I believe this will be the case (but I'd have to check the code
to be sure). I'd recommend being explicit if you are worried about this
possibility.
Reading between the lines, the development of Rd looks exiting.
Instead of 2nd guessing where we are heading, could someone in charge
please give some thoughts on what the plans are and an estimate on how
long it will take before we are there - what R version?
I don't think there's really someone "in charge", but I've been closely
involved with this, so I'll give some thoughts.
Generally speaking, we have releases on a regular schedule, we don't hold
them up for particular features. So I don't think it would be possible to
figure out when development on Rd files will be done. It depends on when
people have the time to do what they think needs doing, and to a large
extent, that depends on how things get used.
Some things that are not there now, but which might be there in the future
(i.e. later than 2.10.0):
- Better support for the \Sexpr macros (which let the content of man pages
depend on R code, executed just before rendering). Right now there's no
special support for that R code; it would make sense to define some
functions to make writing such stuff easier. (This is something that could
be done in a contributed package, it needn't be in base R.)
- Improved prompt() and package.skeleton() functions to take advantage of
the above.
- Graphs in man pages.
- Ways to link from man pages to vignettes. The reverse would be nice, but
it's not possible with the current design, so that would be far off.
- Some general rationalization of the whole help system.
Duncan Murdoch
MISC:
I understand that \link[=<className>-class]{<className>} is part of
standard Rd conventions, but to the best of my knowledge
\link[=<className>.class]{<className>} is not, correct? I would like
to suggest to write a separate paragraph for S4 classes without
mentioning S3 classes. The following also adds to the confusion -
there exists one Rd page with \name{terms} and one with
\name{terms.object}, so it is not really clear what
\link[=terms.object]{terms} is strictly supposed to do - is it of form
\link[=<topic>]{<name>} or \link[=<topic>]{<label>}. Maybe it is
helpful to clarify what the static/dynamic link will be and what will
be display.
Thanks
Henrik
PS. This is related to today's (Sept 23, 2009) BioConductor posts by
Gordon Smyth - "[Bioc-devel] BioC 2.5: "suspect" interpackage links";
https://stat.ethz.ch/pipermail/bioc-devel/2009-September/001975.html
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
