R-alpha: Re: suggestions for R help system

Kurt Hornik (Kurt.Hornik@ci.tuwien.ac.at)
Wed, 20 Nov 1996 16:10:08 +0100


Date: Wed, 20 Nov 1996 16:10:08 +0100
Message-Id: <199611201510.QAA30167@aragorn.ci.tuwien.ac.at>
From: Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at>
To: r-testers@stat.math.ethz.ch
Subject: R-alpha: Re: suggestions for R help system

I thought I'd wait a week or so for feedback to my original posting.

Thomas Lumley <thomas@biostat.washington.edu> wrote,

> If you also copy the help source files to the appropriate place in
> mansrc/the help system will also be properly rebuilt when R is remade
> (a relatively frequent occurence in some places).

This is definitely what I was trying to avoid in the long run.  For
right now, this is certainly not a problem.  But if we decide to
officially distribute R packages (e.g., packages for the various Linux
distributions---I am not sure about packaging systems for other Unices)
there must be a way to install add-ons WITHOUT needing all sources.

Ross wrote,

> I'm not happy with the way we have done the manual entries.  I would
> rather do the formatting for on-line help directly from the manual
> source files, rather than processing them all with nroff as part of
> the setup step (this is not a good solution for the Mac or Windows).

> This might mean changing the format of the files, but I don't see this
> as a problem.  The present format (designed to be processed by m4) was
> chosen to make it easy to switch to another format.

> If anyone would like to take on the task of designing a
> manual/documentation system for R we'd welcome it.

Now ... I definitely don't volunteer for that.  But ...

If the idea is to have one source for producing help files, dvi/ps, and
HTML (and perhaps also RTF), the obvious idea would be to use SGML.  Not
that I am a real fan of it, but it seems to be the only system that
supports enough math AND converts nicely to the relevant formats (quite
unfortunately, texinfo does not).  Most likely, changing the current
format to SGML (e.g., Linuxdoc-SGML or a similar DTD) would not be too
hard.

The problem which we then run into is that many systems will not have
the necessary tools to turn the sources into the various formats.  Also,
if we like to use S add-on packages, we'd need to convert the man
sources to SGML ... but perhaps the scripts Thomas mentioned could be
modified into doing this.

There seems to be no optimal solution.  For the time being, I still
think it would be nice to introduce an extra `package' hierarchy into
the documentation system, such as

	RHOME/help/base/...
	RHOME/html/base/...

etc, have FIXED indexes for each of the packages, and simple scripts for
updating the general index if one of the packages changes.

For the help files, this would mostly require changing the help.index
from producing
	entry <TAB> file
to
	entry <TAB> $package/file
entries, and output that to .../AnIndex.$package.

(I could perhaps do that ...)

Btw, could the scripts Thomas wrote for converting S help to R help
files be included in the distribution?

Thanks,
-k

PS.  We use a variant of the cmd/help script which allows us to have a
help hierarchy in ~/lib/R along with the site-wide one.  Perhaps some
one wants something similar ...

************************************************************************
#!/bin/sh
pager=${PAGER-"more -s"}
for d in $HOME/lib/R/help $RHOME/help; do
    if [ -f "$d/AnIndex" ]; then
	file=`grep "^$1	" $d/AnIndex`
	echo "HMM: $d $file"
	if [ -n "$file" ]; then
	    file=$d/`echo $file | awk '{print $2}'`
	    break
	fi
    fi
done
if [ -z $file ]; then
    echo "sorry, no help for \"$1\"."
else    
    $pager $file
fi
***********************************************************************





=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
r-testers mailing list -- For info or help, send "info" or "help",
To [un]subscribe, send "[un]subscribe"
(in the "body", not the subject !)  To: r-testers-request@stat.math.ethz.ch
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-