[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Rd format

R objects are documented in files written in "R documentation" (Rd) format, a simple markup language much of which closely resembles (La)TeX, which can be processed into a variety of formats, including LaTeX, HTML and plain text. The translation is carried out by functions in the tools package called by the script Rdconv in `R_HOME/bin' and by the installation scripts for packages.

The R distribution contains more than 1300 such files which can be found in the `src/library/pkg/man' directories of the R source tree, where pkg stands for one of the standard packages which are included in the R distribution.

As an example, let us look at a simplified version of `src/library/base/man/load.Rd' which documents the R function load.

 
% File src/library/base/man/load.Rd
\name{load}
\alias{load}
\title{Reload Saved Datasets}
\description{
  Reload the datasets written to a file with the function
  \code{save}.
}
\usage{
load(file, envir = parent.frame())
}
\arguments{
  \item{file}{a connection or a character string giving the
    name of the file to load.}
  \item{envir}{the environment where the data should be
    loaded.}
}
\seealso{
  \code{\link{save}}.
}
\examples{
## save all data
save(list = ls(), file= "all.RData")

## restore the saved values to the current environment
load("all.RData")

## restore the saved values to the workspace
load("all.RData", .GlobalEnv)
}
\keyword{file}

An `Rd' file consists of three parts. The header gives basic information about the name of the file, the topics documented, a title, a short textual description and R usage information for the objects documented. The body gives further information (for example, on the function's arguments and return value, as in the above example). Finally, there is an optional footer with keyword information. The header is mandatory.

Information is given within a series of sections with standard names (and user-defined sections are also allowed). Unless otherwise specified(50) these should occur only once in an `Rd' file (in any order), and the processing software will retain only the first occurrence of a standard section in the file, with a warning.

See "Guidelines for Rd files" for guidelines for writing documentation in `Rd' format which should be useful for package writers. The R generic function prompt is used to construct a bare-bones `Rd' file ready for manual editing. Methods are defined for documenting functions (which fill in the proper function and argument names) and data frames. There are also functions promptData, promptPackage, promptClass, and promptMethods for other types of `Rd' file.

The general syntax of `Rd' files is summarized below. For a detailed technical discussion of current `Rd' syntax, see "Parsing Rd files". Note that there have been a number of changes to the `Rd' format over the years, which can be important if a package is intended to be used with earlier versions of R: see earlier versions of this manual if a package is intended to be used with R before 2.10.0.

`Rd' files consists of three types of text input. The most common is LaTeX-like, with the backslash used as a prefix on markup (e.g. \alias), and braces used to indicate arguments (e.g. {load}). The least common type of text is verbatim text, where no markup is processed. The third type is R-like, intended for R code, but allowing some embedded macros. Quoted strings within R-like text are handled specially: regular character escapes such as \n may be entered as-is. Only markup starting with \l (e.g. \link) or \v (e.g. \var) will be recognized within quoted strings. The rarely used vertical tab \v must be entered as \\v.

Each macro defines the input type for its argument. For example, the file initially uses LaTeX-like syntax, and this is also used in the \description section, but the \usage section uses R-like syntax, and the \alias macro uses verbatim syntax. Comments run from a percent symbol % to the end of the line in all types of text (as on the first line of the load example).

Because backslashes, braces and percent symbols have special meaning, to enter them into text sometimes requires escapes using a backslash. In general balanced braces do not need to be escaped, but percent symbols always do. For the complete list of macros and rules for escapes, see "Parsing Rd files".


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by root on April, 26 2012 using texi2html 1.76.