[Rd] Flat documentation?

Wed Dec 11 02:17:06 2002

#-----Original Message-----
#From: Duncan Murdoch [mailto:dmurdoch@pair.com]
#Subject: [Rd] Flat documentation?
#
#
#Putting together documentation in Rd format is a bit of a pain.  In
#fact, one of my colleagues has chosen to use S-PLUS instead of R
#partly because it's easier to document the stuff he's written.  (In
#S-PLUS plain text files can be used to document your code.  At least
#they could in fairly recent versions; I don't have the current one
#installed.)
#

(1) Yes, I'd agree with that, speaking as an occasional package developer.
After all, the Windows binary (a fair proportion of the market) doesn't even
include Rd files. I've distributed a quite a bit of material to colleagues,
but the documentation issue has put me off releasing stuff more widely,
because of lack of time; it's very slow, and not much fun, to have to write
in Rd. 

#I think it's reasonable to require Rd format documents for stuff on
#CRAN, but it should be easier to document things that are for personal
#use or limited distribution.
#

(2) NB what are the alternatives for distribution, apart from CRAN? CRAN
currently has an "outside of CRAN" section, which mentions just 2 other
websites; could this be systematically expanded, to include references to
"informal packages" on other websites? [I've wondered about this, because
when I eventually do post to CRAN or somewhere, I will need to distribute
DLLs as my source code isn't in C. CRAN itself won't host DLLs, for security
reasons.]

#Are there existing schemes that help in this?  If not, would it be
#worth putting one together?

(3) It might well encourage the free exchange of useful programs, I think.

Eventually, writers will need to put things into Rd format, though. One
thing that might make this easier, is tools that can produce Rd from other
structured document formats for which there are already easy editing tools;
LaTex springs to mind, or HTML. Tools for converting *from* Rd already
exist, according to R-exts.pdf. (There was a recent exchange indicating that
something like this used to exist for SGML, but is now broken.)

For example, I use Scientific Word as a front-end to LaTeX (and very good it
is too, BTW; no \ and $ and { to worry about, it's all taken care of
automatically). I think it might be possible to produce a LaTeX package /
SciWord "shell" which makes it easy to bang out something very close to Rd
format; maybe just a short Perl function away. I posted yesterday to
Scientific Word, asking if anyone had done this; no reply yet, and I'm not
hopeful. But I'd love to hear otherwise!

cheers
Mark

*******************************

Mark Bravington
CSIRO (CMIS)
PO Box 1538
Castray Esplanade
Hobart
TAS 7001

phone (61) 3 6232 5118
fax (61) 3 6232 5012
Mark.Bravington@csiro.au 

#
#______________________________________________
#R-devel@stat.math.ethz.ch mailing list
#http://www.stat.math.ethz.ch/mailman/listinfo/r-devel
#