Skip to content

Rd files

2 messages · Paul Gilbert, Brian Ripley

Original
Paul Gilbert
# 
Friedrich

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

- Must there be separate .Rd files for each function or can they be combined
into one large file?

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

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

- Is there a fixed set of legitimate headings or can I add things easily?

- Is there a fixed set of legitimate keywords or can I add anything?

- What was once called "details" in the S documentation appears to be called
"description" in the Rd files and what was called description (but was often
just about the same as the title) is gone in the Rd files. Is that right?

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

Thanks,
Paul


-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
Brian 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:

            

      
      
      
    

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

            

      
      
      
    

        
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.

            

      
      
      
    

        
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