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

[Prof Brian Ripley]

On Tue, 13 Jan 2009, Gavin Simpson wrote:

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

Yes, the simpler form works on OSes where we can assume symbolic 
links (and before someone tells me Windows has them -- not in Windows 
2000, our minimum requirement still).

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

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