Guidelines for Rd files (original) (raw)

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 thanT 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 checkwill 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).