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

Tue, Jan 13, 2009 1:35 AM #

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>

Brian Ripley

Tue, Jan 13, 2009 3:12 AM #

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:

No, as lattice is not a 'standard' package.

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

Gavin Simpson

Tue, Jan 13, 2009 4:30 AM #

On Tue, 2009-01-13 at 11:12 +0000, Prof Brian Ripley wrote:

Thank you for your reply Prof. Ripley.

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

Tue, Jan 13, 2009 4:40 AM #

On Tue, 13 Jan 2009, Gavin Simpson wrote:

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