Rd files

[Prof Brian D Ripley]

Paul,

I am replying about the differences in Windows vs Unix, as I modified the
help conversion for Windows.

On Wed, 20 Jan 1999, Paul Gilbert wrote:

> I've just been looking at the possibility of converting my html help to Rd
> files. Could you please remind me of a few things (or point me to where they are
> documented):
 
> - Is the name{..} field used or is the name field picked up from the file name?
> (Looking at the html result of a few tests it seems to be picked up from the
> file name, but then what does name{..} do?

This is used on Windows, and I am urging that it be used on Unix. It is not
currently used on Unix, and this has meant that several files had incorrect
or mis-formated name fields (especially in packages). Most but not all help
files have the name also in an alias field, and that does no harm.  There
are some quirks here: there are a few help files with phrases in the name
field (qraux.Rd, lm.summaries.Rd, ...) and a few that reply on the file
name to give an alias (?Random).  On the other hand, `Alias' appears as a
help entry because it is a file name and seems rather confusing (it
refers to .Alias but not alias).

> - Does this work in file systems with more restrictive (e.g.. 8.3) file names?
> If so, how do I specify the function names?

No such systems are in current use, BUT on Windows the file system may be
case-insensitive, and the programs certainly are. Thus having alias.Rd and
Alias.Rd (as in base) will not work; programs will use the one they find
first. For Windows I have changed these by renaming one of them to start
with z. The current Windows system can cope with arbitrary names for the
.Rd files, and it can generate re-mapped 8:3 names for the help, html and
R-ex files, but we do not use that remapping at present.

> - R INSTALL  does not seem to report errors in Rd files that I know have syntax
> problems. Is there a way to get error reports?

It will report some, but the conversion scripts are very tolerant and some
things are just mis-converted (item fields outside argument and value
fields, for one).  I find I do have to look at the output. Looking at the
help conversion to nroff (temporarily remove the /dev/null in line 108 of
build-help, in RHOME/lib/R/bin if you installed) will show a lot of
warnings/errors, many of which can be ignored, but many are also revealing.
As I cannot suppress these on Windows I get to see them, and have found
a lot of .Rd problems that way.

Brian

-- 
Brian D. Ripley,                  ripley@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 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._