Flat documentation?

"mark" == Mark Bravington <Mark.Bravington@csiro.au> writes:

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

what about "prompt"?  A bit more work, maybe a few widgets (ala
Bioconductor's widgets for adding MIAME information to chips; that is,
free-text fields/paragraphs) could result in "easy" generation of
documentation.  

Or is that not simple enough?

I think with the few extra widgets that would be fine for putting
together Rd files.  But there is still an overhead to Rd files in two
respects:

  - There is a lot of structure to an Rd file.  There are conventions
for how they're organized that need to be learned.  Sometimes it's
nice just to be able to associate some hastily written text with a
function.  

  - There is some amount (I'm honestly not sure exactly how much)
"infrastructure" needed before they work at all.  Most Windows users
won't have that.  I think you need  the "Source Package Installation
Files" plus a number of tools (including Perl) installed before you
can do anything with them.  I could make the installation files a
default install item, but they won't work without the tools.

I don't know how much these flat files should participate in the
overall R help system.  The more they show up like regular help topics
the better, but that's going to impose constraints on what goes in
them.  For example, cross-references or entries in the contents or
index listings would be nice, but would need markup of some sort.  

Duncan Murdoch