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

[Gavin Simpson]

On Tue, 2009-01-13 at 11:12 +0000, Prof Brian Ripley wrote:
> 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.

Thank you for your reply Prof. Ripley.

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

That covers Windows and I'm happy to leave those warnings in place. Is
the simpler form sufficient to make the required links on Linux (and
MacOSX...?); that seems the intention of R-exts.pdf, to me at least.

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

Yes, I realised that R-devel was changing considerably in this regard;
one of the reasons I was going through my Rd files was to fix-up some
problems with the mark-up that the new parser identified. Some changes I
made (not related to the parser version 2 warnings) triggered these
warnings on R-Forge.

All the best,

Gavin

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