Guidelines for Rd files
These are suggested guidelines for the system help files (in
.Rd format) that are intended for core developers but
may also be useful for package writers.
-
The page \title and the \section titles
should be capitalized and not end in a period.
It is best to avoid all markup in titles, which need to be
automatically processed for various hypertext search systems.
-
Argument lists need to cover all the arguments in all the functions
covered, including '...'.
This is also checked by tools::checkDocFiles()
,
run as part of R CMD check.
-
Do provide text alternatives for all but the very simplest
\eqn and \deqn commands.
-
In \source and \references sections
-
Use separate paragraphs (separated by a blank line) for each
reference.
-
Write authors' names in the form Author, A. B. and
separate them by a comma or and (but not both).
- Give a date immediately after the author(s), and do not put a
period after the date.
- Enclose titles of books and journals (but not articles)
in \emph{...}.
- Enclose volume numbers for journals in \bold{...}
and follow them by a comma.
- Use -- for page ranges.
- If you give an address for a publisher (probably unnecessary)
use the form New York: Springer-Verlag.
-
In \usage and \examples sections
- Watch the line length: 65 characters is a reasonable limit.
- Use TRUE and FALSE rather than
T and F.
- Readability is greatly enhanced by adding spaces around binary
operators and after commas in argument lists. In particular,
<- needs spaces around it.
- Always use <- rather than = for
assignments.
- Follow the 'R core' indentation guidelines for example code
(which basically means an indentation level of 4 spaces and aligning
continuation lines suitably — but copy the code into a
.R Emacs buffer and reformat it there).
-
Ensure that the \usage section exactly matches the
function definition.
tools::codoc()
run as part of R CMD check
will complain if it doesn't.
-
Not only make sure that examples are directly executable, also make
sure that they are system-independent (do not use system)
and do not require special facilities (for example Internet access or
write permission to specific directories).
-
Use quotation marks sparingly: quotation marks are used for R objects
in text rendition. If you must use them, make them double
(\dQuote{a quotation}), and use \sQuote and
\dQuote
-
Do not use tabs to indent (as these do not render correctly on all
possible pagers).
-
Please put two spaces after the end of a sentence in sections with
running text (\description, \details, ...).
-
For consistency, aim to use British (rather than American)
spelling. (NB: British spelling often uses -ize as in
'capitalize'. The view of spell -b of British spelling is
a flawed American one. There are English/Scottish differences too.)
-
Do not use & except where quoting (for example, the
publisher that has been called Chapman & Hall fairly
recently).