8. Editing R documentation files

ESS also provides support for editing R documentation ("Rd") files. R objects are documented in files written in Rd format, a simple markup language closely resembling (La)TeX, which can be processed into a variety of formats, including LaTeX, HTML, and plain text. Rd format is described in section "Rd format" of the "Writing R Extensions" manual in the R distribution.

Visiting an Rd file as characterized by its extension `Rd' will activate Rd Mode, which provides several facilities for making editing R documentation files more convenient, by helping with indentation, insertions, even doing some of the typing for you (with Abbrev Mode), and by showing Rd keywords, strings, etc. in different faces (with Font Lock Mode).

Note that R also accepts Rd files with extension `rd'; to activate ESS[Rd] support for this extension, you may need to add

(add-to-list 'auto-mode-alist '("\\.rd\\'" . Rd-mode))

to one of your Emacs startup files.

In Rd mode, the following special Emacs commands can be used in addition to the standard Emacs commands.

C-h m

Describe the features of Rd mode.

LFD

RET

Reindent the current line, insert a newline and indent the new line (reindent-then-newline-and-indent). An abbrev before point is expanded if abbrev-mode is non-nil.

TAB

Indent current line based on its contents and on previous lines (indent-according-to-mode).

C-c C-e

Insert a "skeleton" with Rd markup for at least all mandatory entries in Rd files (Rd-mode-insert-skeleton). Note that many users might prefer to use the R function prompt on an existing R object to generate a non-empty Rd "shell" documenting the object (which already has all information filled in which can be obtained from the object).

C-c C-f

Insert "font" specifiers for some of the Rd markup commands markup available for emphasizing or quoting text, including markup for URLs and email addresses (Rd-font). C-c C-f is only a prefix; see e.g. C-c C-f TAB for the available bindings. Note that currently, not all of the Rd text markup as described in section "Marking text" of "Writing R Extensions" can be accessed via C-c C-f.

C-c C-j

Insert a suitably indented `\item{' on the next line (Rd-mode-insert-item).

C-c C-p

Preview a plain text version ("help file", see section 9. Reading help files) generated from the Rd file (Rd-preview-help).

In addition, when editing Rd files one can interact with a running R process in a similar way as when editing R language files. E.g., C-c C-v provides access to on-line help, and C-c C-n sends the current line to the R process for evaluation. This interaction is particularly useful when editing the examples in the Rd file. See C-h m for all available commands.

Rd mode also provides access to abbreviations for most of the Rd markup commands. Type M-x list-abbrevs with Abbrev mode turned on to list all available abbrevs. Note that all Rd abbrevs start with a grave accent.

Rd mode can be customized via the following variables.

Rd-mode-hook

Hook to be run when Rd mode is entered.

Rd-indent-level

The indentation of Rd code with respect to containing blocks. Default is 2.

Rd-to-help-command

The shell command used for converting Rd source to help text. Default is `R CMD Rd2txt'.

To automatically turn on the abbrev and font-lock features of Rd mode, add the following lines to one of your Emacs startup files:

(add-hook 'Rd-mode-hook
          (lambda ()
           (abbrev-mode 1)
           (font-lock-mode 1)))