RDoc

This is the start of some software that one can use to author documentation for functions, classes, data analyses, sessions, tutorials, etc. for the R programming language and environment. The aim is to treat documentation as objects in R and provide support for different formats. These facilities are intended to provide extensibility both for programming on the objects, and also for the tools for rendering the documentation in different formats. We want to encourage advances in documentation and how we display and interact with it. It is related to literate programming, literate data analysis, and interactive and dynamic documents and various projects covering these topics.

The functionality is intended to be a complementary alternative to the Rd format - not necessarily a replacement for it. We provide support for using XML to author documents. Also, we represent the document as an R object allowing it to be edited programmatically if one chooses. Additionally, one can move between the different supported formats relatively easily as the software develops.

There are many different aspects that become more feasible with extensible tools, both for creating and rendering documentation. This project was started many years ago. As the family of XML technologies have matured, the available tools for authoring and rendering XML have become more widely available. We can edit documents in Emacs, XMLSpy, Word, AbiWord, OpenOffice, etc. and operate on the results. The particular format is not important as long as we can access the information within the document at the content-level rather than the display level.

We have GUI tools (RGtk, Tcl/tk, and others) some of which can be used to develop rich browsers for displaying interactive, live documentation that is tightly integrated with R. Similarly, we have connected R and XSLT so that we can create documents using libraries of XSL transformations (e.g. Docbook) as well as in R. This hybrid approach makes for potentially rich documents and better transformation software.

Examples Sample function and class documents in xml transformed to HTML. Example vignette-style documents. These are files that I have written to describe some code, or functions or package using XML and many of the same tags that are shared with the XML documentation system described above. Overview A document that is taking shape to describe what we are trying to do, why and how. XSL files The directory containing the XSL files for the documentation. There are other dependent files located in the general Omegahat XSL area. Todo list The ever growing todo list for this project. This is currently quite small and we will add directions as we go.: Sample function and class documents in xml transformed to HTML.
Example vignette-style documents. These are files that I have written to describe some code, or functions or package using XML and many of the same tags that are shared with the XML documentation system described above. Overview A document that is taking shape to describe what we are trying to do, why and how. XSL files The directory containing the XSL files for the documentation. There are other dependent files located in the general Omegahat XSL area. Todo list The ever growing todo list for this project. This is currently quite small and we will add directions as we go.: These are files that I have written to describe some code, or functions or package using XML and many of the same tags that are shared with the XML documentation system described above.
Overview A document that is taking shape to describe what we are trying to do, why and how. XSL files The directory containing the XSL files for the documentation. There are other dependent files located in the general Omegahat XSL area. Todo list The ever growing todo list for this project. This is currently quite small and we will add directions as we go.: A document that is taking shape to describe what we are trying to do, why and how.
XSL files: The directory containing the XSL files for the documentation. There are other dependent files located in the general Omegahat XSL area.
Todo list The ever growing todo list for this project. This is currently quite small and we will add directions as we go.: The ever growing todo list for this project. This is currently quite small and we will add directions as we go.

The work was started by myself in 2000, I believe. Byron Ellis worked on it for a summer at Bell Labs. It got put aside for a long period as it wasn't clear people wanted to use XML, and the change to the R system to use objects for documentation was rather extensive. Additionally, we tried to hard to support the TeX/Rd format. This involved a Perl parser that made for additional complexity of installation, etc..

Duncan Temple Lang <duncan@wald.ucdavis.edu>

Last modified: Mon Sep 26 11:47:34 PDT 2005