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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
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 _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
Friedrich Thanks for the clarifications and update.>I'm currently starting (the long announced, but now it's real) >re-write of Rdconv by making it module-oriented and using Text::Delim >as extraction engine (as suggested by Doug quite some time ago).So I guess I should wait to do my conversion. PG> - Must there be separate .Rd files for each function or can they be combined PG> into one large file?>Yes, currently the idea is to have one Rd file per html/help file. I >never thought about it though ... do many people want to be able to >have all documentation in one big file?I don't really care too much about this, I just wanted to make sure I understand it. However, it may not be too difficult allow a large .Rd file and have the build decompose it using the /name{..}. I currently keep many functions in one file along with their documentation separated by /* */. I separate this into the .R and .Rd files with an awk script. So the question for me is whether I have to separate the .Rd file further or is the R build going to do it. I guess I would prefer that the R build do it, as I think others may use it this way too, but I think I can do it fairly easily. 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 _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
> From: Paul Gilbert <pgilbert@bank-banque-canada.ca> > > From Fritz Leisch> >Yes, currently the idea is to have one Rd file per html/help file. I > >never thought about it though ... do many people want to be able to > >have all documentation in one big file? > > I don't really care too much about this, I just wanted to make sure Iunderstand> it. However, it may not be too difficult allow a large .Rd file and have the > build decompose it using the /name{..}. I currently keep many functions in one > file along with their documentation separated by /* */. I separate this into > the .R and .Rd files with an awk script. So the question for me is whether I > have to separate the .Rd file further or is the R build going to do it. Iguess> I would prefer that the R build do it, as I think others may use it this way > too, but I think I can do it fairly easily.It's legal with S's files, and it is a great way to avoid file name problems: just have one file with a simple name (and some of those in lme and locfit cause problems to several tools: file names with "<" in are somewhat unexpected!) However, S has an end of section marker, and it think that is needed for safety. (In S format, help for one object is between .BG and .WR.) -- 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 _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
> From: Friedrich Leisch <Friedrich.Leisch@ci.tuwien.ac.at> > > BDR> It's legal with S's files, and it is a great way to avoid file > BDR> name problems: just have one file with a simple name (and some > BDR> of those in lme and locfit cause problems to several tools: > BDR> file names with "<" in are somewhat unexpected!) However, S > BDR> has an end of section marker, and it think that is needed for > BDR> safety. (In S format, help for one object is between .BG and > BDR> .WR.) > > DB> The .Rd file name in lme that always gives me trouble is [.pdMat.Rd. > DB> I hadn't realized that the others with "<" in them, like matrix<-.Rd, > DB> also gave problems. > > Does S also store the complete output in one file or is the output > split into different files?In the cases where you want to do this, one. You can convert to Windows help (one file per library) or to process to postscript (pipe to stdout). Standard S files are processed at display time, so there is no output file per se, just a screen or printer.> In the second case we'd simply move the problem from problematic input > names to problematic output names ...Yes, but it does not occur in my experience. -- 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 _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._