The R Project SVN R

\newcommand{\pkg}[1]{{\textbf{#1}}}
\newcommand{\var}[1]{{{\normalfont\textit{#1}}}}
\newcommand{\COMMENT}[1]{%
  \hfill\makebox[.5\textwidth][l]{{\normalfont{\% #1}}}}
\newcommand{\EXPLAIN}[1]{\par\relax\qquad\parbox{0.8\textwidth}{#1}\\}
\newcommand{\CMD}[1]{\texttt{{\char`\\}#1}}% prepend "\"
\newcommand{\LB}{\texttt{{\char`\{}}}% left  bracket "{"
\newcommand{\RB}{\texttt{{\char`\}}}}% right bracket "}"
\newcommand{\CMDb}[2]{\texttt{{\char`\\}#1}{\LB{#2}\RB}}% ``\cmd{xx}''
\newcommand{\CMDv}[2]{\texttt{{\char`\\}#1}{\LB\var{#2}\RB}}% ``\cmd{xx}''
%
\newcommand{\Ind}{\strut\quad}% indent at beginning of line
\newcommand{\nlInd}{\\\Ind}% newline + indent
\newcommand{\nlIInd}{\\\strut\qquad}% newline + more indent

\section{The Documentation Source Tree}

The help files containing detailed documentation for (potentially) all
\R{} objects are in the \file{src/library/$\ast$/man} subdirectories of
the R source tree, where `$\ast$' stands for \pkg{base} where all the
standard objects are, and for ``proper'' libraries such as \pkg{eda} and
\pkg{mva}.  The \file{doc/manual} subdirectory contains code for running
the translated help files through \LaTeX{} and further documents
pertaining to \R.

\section{Documentation Format}\label{sec:doc-format}

The help files are written in a form and syntax---closely resembling
\TeX{} and \LaTeX{}---which can be processed into a variety of formats,
including \LaTeX, [TN]roff, and \HTML.  The translation is carried out
by the \textsc{perl} script \file{Rdconv} in \file{\$R\_HOME/bin}.

For a given R function \code{myfunction}, use the \R{} command
\code{prompt(myfunction)} to produce the file \file{myfunction.Rd}.  The
basic layout of a raw documentation file is as follows (note that each
file should contain at least one \CMDv{alias}{name} line).

\begin{quote}
  \CMDv{name}{myfunction}
  \COMMENT{\var{myfunction} is the basename of the file.}

  \CMDv{alias}{myfunction}
  \COMMENT{Need one \CMDb{alias}{}\ for each topic explained} \\  
  \CMDv{alias}{more\_aliases\_1}
  \COMMENT{in this help page.} \\
  \CMDv{alias}{more\_aliases\_2} \nlInd
  {etc.}

  \CMDv{title}{Description}

  \CMD{description}\LB
  \EXPLAIN{A short description of what the function(s) do(es)
    (one paragraph, a few lines only).}\RB

  \CMD{usage}\LB \\
  \var{myfunction}(\dots)
  \EXPLAIN{One or more lines showing the synopsis of the function(s) and
    variables documented in the file.  These are set verbatim in
    typewriter font.}
  \RB

  \CMD{arguments}\LB \nlInd
        \var{Some optional text \emph{before} the optional list.} \nlInd
        \CMDv{item}{arg1}\LB\var{Description of arg1.}\RB \nlInd
        \CMDv{item}{arg2}\LB\var{Description of arg2.}\RB \nlIInd
                \textrm{etc.} \nlInd
        \var{Some optional text \emph{after} the list.} \\
  \RB

  \CMD{details}\LB
  \EXPLAIN{A detailed if possible precise description of
    the functionality provided.  Sometimes, precise \CMDb{references}{}
    can be given instead.}\RB

  \CMD{value}\LB\var{A description of the value returned by the
    function.}
  \EXPLAIN{If a list with  multiple values is returned, you can use
    \\*[2mm]\strut\quad
    \CMDv{item}{comp1}\LB\var{Description of result component `comp1'}\RB
    \nlInd
    \CMDv{item}{comp2}\LB\var{Description of result component `comp2'}\RB
    \\*[2mm]
    etc.}
  \RB

  \CMD{references}\LB
  \EXPLAIN{Section of references to the literature; use \CMDb{url}{}
    for web pointers. \ \
    Optional as well as all the following sections.}
  \RB

  \CMDv{section}{name}\LB\var{text}\RB

  \Ind and maybe more \CMD{section\LB~\RB} environments

  \CMDv{note}{Some note you want to have pointed out.}
  
  \CMD{author}\LB \EXPLAIN{Who you are.  Use \CMDb{email}{}{} without
    extra delimiters (`\texttt{(~)}' or `\texttt{<~>}') or
    \CMDb{url}{}.}\RB

  \CMD{seealso}\LB
  \EXPLAIN{Pointers to related \R{} functions, using \CMDb{link}{},
    usually in the form of \CMDb{code}{\CMDb{link}{}}}
  \RB

  \CMD{examples}\LB
    \EXPLAIN{Examples of how to use the function.  These are set verbatim
      in typewriter font.
      \begin{center}
        \textbf{Use examples which are \emph{directly} executable!}
      \end{center}
      Use random number generators (e.g., \code{x <- rnorm(100)}), or a
      standard dataset loadable via \code{data(\dots)} (see
      \code{data()} for info) to define data!
      
      \medskip {\CMDv{dontrun}{commands that should only be shown, but
          not run through \R}.}
      
      \medskip {\CMD{testonly}\LB\var{for extra commands \emph{testing}
          \R{} functionality. These will be run (by ``\texttt{make
            check}'') but not shown in the help outputs}\RB.}}
    \RB

  \CMDv{keyword}{key\_1}
  \COMMENT{Use at least one  keyword out of the list} \\
  \CMDv{keyword}{key\_2}
  \COMMENT{in \file{\$R\_HOME/doc/KEYWORDS}}
\end{quote}

\section{Sectioning}

To begin a new paragraph or leave a blank in an example, just insert an
empty line (as in (La)\TeX).  To break a line, use \CMD{cr}.

In addition to the predefined sections (such as \CMDb{description}{},
\CMDb{value}{}, etc.), you can ``define'' arbitrary ones by
\CMDv{section}{section\_title}\LB\ldots\RB.  E.g.,
\begin{quote}
\begin{alltt}
\CMDb{section}{Warning}\LB{}You must not call this function unless ...\RB
\end{alltt}
\end{quote}
Note that the additonal named sections are always inserted at fixed
positions in the output (before \CMD{note}, \CMD{seealso} and the
examples), no matter where they appear in the input.

\section{Marking Text}

The following logical markup commands are available for indicating
specific kinds of text.
\begin{quote}
  \begin{tabular}{@{}ll}
    \CMDv{bold}{word} & set \emph{word} in \textbf{bold} font if
    possible \\
    \CMDv{emph}{word} & emphasize \emph{word} using \var{italic} font if
    possible \\
    \CMDv{code}{word} & for pieces of code, using \texttt{typewriter}
    font if possible \\
    \CMDv{file}{word} & for file names \\
    \CMDv{email}{word} & for email addresses \\
    \CMDv{url}{word} & for URLs
  \end{tabular}
\end{quote}
The first two, \CMD{bold} and \CMD{emph}, should be used in plain text
for emphasis.

Fragments of \R{} code, including the names of \R{} objects, should be
marked using \CMD{code}.  Only backslashes and percent signs need to be
escaped inside \CMD{code}.

Finally, \CMDb{link}{foo} (usually in the combination
\CMDb{code}{\CMDb{link}{foo}}) produces a hyperlink to the help page for
function \texttt{foo}.  One main usage of \CMD{link} is in the
\CMD{seealso} section of the help page, see~\ref{sec:doc-format}, above.
(Currently, this only affects the creation of the \HTML{} pages used,
e.g., by \code{help.start()}.)

\section{Mathematics}

Mathematical formula are something we want ``perfectly'' for printed
documentation (i.e., for the conversion to \LaTeX{} and PostScript
subsequently) and still want something useful for ASCII and \HTML{}
online help.

To this end, the two commands \CMDv{eqn}{latex}\LB\var{ascii}\RB{} and
\CMDv{deqn}{latex}\LB\var{ascii}\RB{} are used.  Where \CMD{eqn} is used
for ``inline'' formula (corresponding to (La)\TeX's
\texttt{\$\ldots\$}), \CMD{deqn} gives ``displayed equations'' ({\`a} la
\LaTeX's \texttt{displaymath} environment, or \TeX's
\texttt{\$\$\ldots\$\$}).

Both commands can also be used as \CMD{eqn\LB\var{latexascii}\RB} (only
\emph{one} arg.) which then is used for both \var{latex} and
\var{ascii}.

The following example is from the \texttt{Poisson} help page:
\begin{quote}
\begin{verbatim}
\deqn{p(x) = {\lambda^x\ \frac{e^{-\lambda}}{x!}}
     {p(x) = lambda^x exp(-lambda)/x!}
for \eqn{x = 0, 1, 2, ...}.
\end{verbatim}
\end{quote}
which, for the \LaTeX{} manual, becomes
\begin{quote}
  \[ p(x) = \lambda^x\ \frac{e^{-\lambda}}{x!}  \]
  for $ x = 0, 1, 2, \ldots $.
\end{quote}
where, for the \HTML{} and the ``direct'' (man-like) on-line help
becomes
\begin{quote}
\begin{verbatim}
  p(x) = lambda^x exp(-lambda)/x!

for x = 0, 1, 2, ....
\end{verbatim}
\end{quote}

For historic reasons mostly, the \TeX/\LaTeX{} commands \CMD{alpha},
\CMD{Alpha}, \CMD{beta}, \CMD{Gamma}, \CMD{epsilon}, \CMD{lambda},
\CMD{mu}, \CMD{pi}, \CMD{sigma}, \CMD{left(} and \CMD{right)} exist.
These can be used directly, without using the \CMD{eqn} diversion.

\section{Miscellaneous}

Use \CMD{R} for the \R{} system itself (you don't need extra `\verb+{}+'
or `\verb+\+').  Use \CMD{dots} for the dots in function argument list
`\texttt{...}', and \CMD{ldots} for `$\ldots$' (ellipsis dots).

After a `\texttt{\%}', you can put your own comments regarding the help
text. This will be completely disregarded, normally. Therefore, you can
also use it to make part of the ``help'' invisible.

\paragraph{Escaping Special Characters.}

You can produce a backslash (`\verb+\+') by escaping it by another
backslash.  (Note that \CMD{cr} is used for generating line breaks.)

The ``comment'' and ``control'' characters `\texttt{\%}' and `\verb+\+'
\emph{always} need to be escaped.  Inside the verbatim-like commands
(\CMD{code} and \CMD{examples}), no other characters are special.

In ``regular'' text (no verbatim, no \CMD{eqn}, \ldots), you currently
must escape all \LaTeX{} special characters, i.e., besides
`\texttt{\%}', `\verb+{+', and `\verb+}+', the four specials
`\texttt{\$}', `\texttt{\&}', `\texttt{\#}', and `\texttt{\_}' are
simply produced by preceding with a `\verb+\+'.  Further, `\verb+^+' by
\verb|\eqn{\hat{}}{^}|, and `\verb|~|' by \verb|\eqn{\tilde{}}{~}|.
Also, `\verb|<|', `\verb|>|', and `\verb+|+' must only be used in math
mode, i.e., within \CMD{eqn} or \CMD{deqn}.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ABOUT"
%%% TeX--master: "Man"
%%% End: