From ripley at stats.ox.ac.uk  Thu Nov 15 00:21:39 2007
From: ripley at stats.ox.ac.uk (Prof Brian Ripley)
Date: Wed, 14 Nov 2007 23:21:39 +0000 (GMT)
Subject: [Rd] library path in Rd link
In-Reply-To: <200711150109.02826.dusa.adrian@gmail.com>
References: <200711141549.54176.dusa.adrian@gmail.com>
	<Pine.LNX.4.64.0711142132320.1433@gannet.stats.ox.ac.uk>
	<200711150109.02826.dusa.adrian@gmail.com>
Message-ID: <Pine.LNX.4.64.0711142309470.1433@gannet.stats.ox.ac.uk>

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.

> instead of
> file:///usr/lib/R/library/stats/html/anova.html

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

> help.start()
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("anova", htmlhelp=TRUE)
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



[Rd] library path in Rd link
Prof Brian Ripley