library path in Rd link - R-devel

Wed, Nov 14, 2007 3:21 PM #

On Thu, 15 Nov 2007, Adrian Dusa wrote:

Dear Prof. Ripley,

On Wednesday 14 November 2007, Prof Brian Ripley wrote:

On Wed, 14 Nov 2007, Adrian Dusa wrote:

Dear all,

When creating new functions in a package, there is a "See also" component
in the Rd file.
Usually one uses \link{otherfun}, if the other function is from the same
package, or \link[otherpackage]{otherfun} otherwise.

I think you have misread the manual here:

   There are two other forms of optional argument specified as
   \link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to
   files foo.html and bar.html respectively. These are rarely needed,
   perhaps to refer to not-yet-installed packages (but there the HTML
   help system will resolve the link at run time) or in the normally
   undesirable event that more than one package offers help on a topic
   (in which case the present package has precedence so this is only
   needed to refer to other packages)

Note: 'rarely needed'.

Ah-haa, thanks for the clarification. I could have directly used
\code{\link{anova}}
to refer to the anova() from package stats which is also installed by default
in the same installation folder as the base package.

The trouble is that I install new packages not in the default R library
folder, but into some other subfolder in my home, so the link searches
for "otherpackage" in my home subfolder.

Is there a method to create links to functions from the base package, for
example (which is installed by default in the normal library folder)?

What OS is this?  (As I recall you used Linux last time you posted.)

Linux it is, I only thought the question should be platform independent.

In any case, on all OSes you will be able to do cross-library links to the
base package without having to do anything further (and CRAN packages are
full of them).  On Unix-alikes the help files are all linked into a single
virtual library, and on Windows links to the base package (and a few
others) from other libraries are fixed up on installation by
link.html.help (see its help).

Indeed, link.html.help() resolves all the links under Windows (where I
suspected the biggest trouble would be). It is strangely under Linux that I
am not able to resolve the links (most surely I do something wrong).

Using as above:
\code{\link{anova}}

the html help file directs to
file:///home/adi/myRlibrary/stats/html/anova.html

I hope it is actually ../../stats/html/anova.html and the browser is 
interpreting that as a full URL.

But at run time help.start() creates links into a subdirectory of 
tempdir().  As in

Making links in per-session dir ...
If '/home/ripley/bin/firefox' is already running, it is *not*
     restarted, and you must switch to its window.
Otherwise, be patient ...

and without that

Help for 'anova' is shown in browser /home/ripley/bin/firefox ...
Use
         help("anova", htmlhelp = FALSE)
or
         options(htmlhelp = FALSE)
to revert.
Warning message:
In .show_help_on_topic_as_HTML(file, topic) :
   Using non-linked HTML file: style sheet and hyperlinks may be incorrect

and note the last line.

(In case anyone wonders about the browser path: I am running 32-bit 
Firefox on x86_64 Linux.)

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

Adrian Dusa

Wed, Nov 14, 2007 3:44 PM #

On Thursday 15 November 2007, Prof Brian Ripley wrote:

I got it.
Perhaps it would be useful to have another startup option, something like:
options(htmlLinksResolve=TRUE)

that one could use in the .First() function from .Rprofile

I tried using help.start() in .Rprofile, but it throws a (probably obvious) 
error:
Error: could not find function "help.start"


For my personal purposes, all questions have been answered though.
Thank you very much,
Adrian

Adrian Dusa
Romanian Social Data Archive
1, Schitu Magureanu Bd
050025 Bucharest sector 5
Romania
Tel./Fax: +40 21 3126618 \
          +40 21 3120210 / int.101

Duncan Murdoch

Wed, Nov 14, 2007 3:54 PM #

On 14/11/2007 6:44 PM, Adrian Dusa wrote:

That's just because .Rprofile is run before most packages are attached; 
you should be able to say utils::help.start() to get it to run.

Adrian Dusa

Wed, Nov 14, 2007 4:11 PM #

On Thursday 15 November 2007, Duncan Murdoch wrote:

Smooth :o)

Adrian Dusa
Romanian Social Data Archive
1, Schitu Magureanu Bd
050025 Bucharest sector 5
Romania
Tel./Fax: +40 21 3126618 \
          +40 21 3120210 / int.101

Brian Ripley

Wed, Nov 14, 2007 11:22 PM #

On Thu, 15 Nov 2007, Adrian Dusa wrote:

You could have a function to run there, essentially (from help.start())

     .Script("sh", "help-links.sh",
             paste(tempdir(), paste(.libPaths(), collapse = " ")))

and perhaps (it is a lot slower)

     utils::make.packages.html()

The problem is that even the first can be slow on a network-mounted file 
system with a lot of packages installed, do we don't want to do it by 
default.

Duncan has answered that.

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

Brian Ripley

Thu, Nov 15, 2007 1:13 AM #

On Thu, 15 Nov 2007, Prof Brian Ripley wrote:

It transpires that currently you do need both: although the script is 
passed the library locations it does not make use of them, leaving the 
linking to make.packages.html.  (That used not to be the case.)

So speed is the problem: I am seeing about 4 secs on a system with 1450 
packages on the local disc, and 33 secs on a slower system with a 
network-mounted FS.

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

Adrian Dusa

Thu, Nov 15, 2007 2:51 AM #

On Thursday 15 November 2007, Prof Brian Ripley wrote:

Completely understandable, it's not going to be automatic. Users who don't 
suffer from these restrictions could manually make use of the script.

Thank you very much,
Adrian

Adrian Dusa
Romanian Social Data Archive
1, Schitu Magureanu Bd
050025 Bucharest sector 5
Romania
Tel./Fax: +40 21 3126618 \
          +40 21 3120210 / int.101