R devel - Jan 2009 - Missing links on Windows and \link[bar]{foo}; clarification

Dear List,

In one of my packages on R-Forge I have a custom panel function for
Lattice graphics. In the Rd file for this panel function I want to
provide links to some lattice functions (in package lattice). My first
instinct was to use:

\code{\link[lattice]{panel.xyplot}}

for example. However, I missed a few references to lattice functions and
just marked them up as \code{\link{panel.xyplot}}.

For the latter, I am getting warnings about missing links during package
check and installation *only* on Windows and *only* on R patched
(R-Forge version: R version 2.8.1 Patched (2009-01-12 r47554)).

With R Devel (R-Forge version: 2.9.0 Under development (unstable)
(2009-01-10 r47538)) under Windows no warnings are issued.

The R-exts manual mentions that the first style is rarely needed, yet
the warnings on R-patched suggest that [currently] it is, for CHM help
only, which is where I presume the warnings are being generated.

Is the change in R Devel intentional or a side-effect of other changes
that is yet to be fixed? (I appreciate that this version of R is still
under development and unstable.) Is this difference between versions
related to (from NEWS)?:

o	HTML links will be resolved first to the standard packages: this
	avoids other installed packages diverting help on e.g. qr()
	and plot() to themselves.

So can I proceed under the assumption that \code{\link{panel.xyplot}} is
the correct methodology for linking to a functions in
another /recommended/ package?

Is this different when referring to a function in another,
non-recommended package (i.e. that \code{\link{panel.xyplot}} is
preferred in most situations)?

Thanks in advance,

Gavin
-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL:
<https://stat.ethz.ch/pipermail/r-devel/attachments/20090113/c56ad350/attachment.bin>

You would expect to see issues on Windows whilst checking, as 
cross-library links do not work on Windows (unless fixed up, which 
install.packages() does for some standard packages, not including 
lattice which is 'recommended' not 'standard').  And, depending
where
you install, perhaps during installation.

Note that specifying \code{\link[lattice]{panel.xyplot}} just avoids 
the warnings: it still does not make a cross-library link work.

As for R-devel: very likely processing of help will have changed 
completely before release, so that is one area where we do not want 
to know about problems as yet, and anything in the NEWS file is 
provisional (some of the changes mentioned there may be reverted).

On Tue, 13 Jan 2009, Gavin Simpson wrote:
> Dear List,
>
> In one of my packages on R-Forge I have a custom panel function for
> Lattice graphics. In the Rd file for this panel function I want to
> provide links to some lattice functions (in package lattice). My first
> instinct was to use:
>
> \code{\link[lattice]{panel.xyplot}}
>
> for example. However, I missed a few references to lattice functions and
> just marked them up as \code{\link{panel.xyplot}}.
>
> For the latter, I am getting warnings about missing links during package
> check and installation *only* on Windows and *only* on R patched
> (R-Forge version: R version 2.8.1 Patched (2009-01-12 r47554)).
>
> With R Devel (R-Forge version: 2.9.0 Under development (unstable)
> (2009-01-10 r47538)) under Windows no warnings are issued.
>
> The R-exts manual mentions that the first style is rarely needed, yet
> the warnings on R-patched suggest that [currently] it is, for CHM help
> only, which is where I presume the warnings are being generated.
>
> Is the change in R Devel intentional or a side-effect of other changes
> that is yet to be fixed? (I appreciate that this version of R is still
> under development and unstable.) Is this difference between versions
> related to (from NEWS)?:
>
> o	HTML links will be resolved first to the standard packages: this
> 	avoids other installed packages diverting help on e.g. qr()
> 	and plot() to themselves.
No, as lattice is not a 'standard' package.
> So can I proceed under the assumption that \code{\link{panel.xyplot}} is
> the correct methodology for linking to a functions in
> another /recommended/ package?
>
> Is this different when referring to a function in another,
> non-recommended package (i.e. that \code{\link{panel.xyplot}} is
> preferred in most situations)?
>
> Thanks in advance,
>
> Gavin
> --
> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
> Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
> ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
> Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
> Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
> UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
>
>
-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595