[Rd] Missing links on Windows and \link[bar]{foo}; clarification

[Prof Brian Ripley]

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