\newcommand*{\RHOMEdir}[1]{\file{\$RHOME/#1}}
\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}}
\newcommand{\LB}{\texttt{{\char`\{}}}
\newcommand{\RB}{\texttt{{\char`\}}}}

\section{The Documentation Source Tree}

The help files containing detailed documentation for (potentially) all
\R{} functions are in the directories \RHOMEdir{src/library/$\ast$/man}
where `$\ast$' stands for \pkg{base} where all the standard functions
are and for ``proper'' libraries such as \pkg{mva} and \pkg{eda}.

This directory, \RHOMEdir{doc/manual}, 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 \RHOMEdir{etc/}.

The basic layout of a raw documentation file is as follows.  For a given
function \code{do.this}, use the \R{} command \code{prompt(do.this)} to
produce the file \file{do.this.Rd}.

%%-- Not anymore! (yes ?)
Note that each file should contain at least one
\CMD{alias\LB\var{name}\RB} line.

\begin{quote}
  \CMD{name}\LB\var{myfunction}\RB
  \COMMENT{1st argument of old TITLE(. @@ .)} \\
  \CMD{title}\LB\var{Description}\RB
  \COMMENT{2nd argument of old TITLE(. @@ .)}

  \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{alias}\LB\var{myfunction}\RB \\
  \CMD{alias}\LB\var{more\_aliases\_1}\RB
  \COMMENT{Need one \CMD{alias\LB\RB} for each topic explained} \\
  \CMD{alias}\LB\var{more\_aliases\_2}\RB
  \COMMENT{in this help page in addition to \var{myfunction}.} \\
  \strut\quad {etc.}

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

  \CMD{description}\LB\var{A precise description of what the function
    does.}\RB

  \CMD{value}\LB\var{A description of the value returned by the function.}

  \strut\quad If a list with  multiple values is returned, you can use \\
  \strut\quad\CMD{item}\LB\var{comp1}\RB\LB\var{Description of result
    component `comp1'}\RB \\
  \strut\quad\CMD{item}\LB\var{comp2}\RB\LB\var{Description of result
    component `comp2'}\RB \\
  \strut\qquad etc. \\
  \RB

  \CMD{references}\LB
  \EXPLAIN{References section.  Optional as well as all the following
    sections}
  \RB

  \CMD{section}\LB\var{name}\RB\LB\var{text \dots\dots}\RB

  \strut\qquad and maybe more \CMD{section\LB..\RB} environments

  \CMD{note}\LB\var{Some note you want to have pointed out \dots.}\RB

  \CMD{author}\LB\var{Whoever you are (if you are not one of R \& R)}\RB

  \CMD{seealso}\LB
  \EXPLAIN{Pointers to related \R{} functions, using \CMD{link\LB.\RB},
    usually in the form of \CMD{code\LB\CMD{link}\LB.\RB\RB}.}
  \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!}
  \RB

  \CMD{keyword}\LB\var{key\_1}\RB
  \COMMENT{Use at least one  keyword out of the list} \\
  \CMD{keyword}\LB\var{key\_2}\RB
  \COMMENT{in \RHOMEdir{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
\CMD{description\LB..\RB}, \CMD{value\LB..\RB}, etc.), you can
``define'' arbitrary ones by
\CMD{section\LB\var{section\_title}\RB\LB\ldots\RB}.  E.g.,
\begin{quote}
\begin{alltt}
\CMD{section}\LB{}Warning\RB\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 in the input they appear.

\section{Marking Text}

The following logical markup commands are available for indicating
specific kinds of text.
\begin{quote}
  \begin{tabular}{ll}
    \CMD{bold\LB\var{word}\RB}
    & set \emph{word} in \textbf{bold} font if possible. \\
    \CMD{emph\LB\var{word}\RB}
    & emphasize \emph{word} using \var{italic} font if possible
    \\
    \CMD{code\LB\var{word}\RB}
    & to indicate pieces of code, using \texttt{typewriter} font if
    possible \\
    \CMD{file\LB\var{word}\RB}
    & for file names. \\
    \CMD{email\LB\var{word}\RB}
    & for email addresses \\
    \CMD{url\LB\var{word}\RB}
    & 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, \CMD{link\LB{}foo\RB} (usually in the combination
\CMD{code\LB\CMD{link}\LB{}foo\RB\RB}) 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
\CMD{eqn\LB\var{latex}\RB\LB\var{ascii}\RB} and
\CMD{deqn\LB\var{latex}\RB\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{verbatim}
                   p(x) = lambda^x exp(-lambda)/x!

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

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 `\{\}' or `\bsl').
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.  If \texttt{\%} occurs
in \R{} code, you must ``escape'' it as `\%'.

\paragraph{Escaping Special Characters.}
You can produce a backslash (`\bsl') by escaping it by another
backslash.  (Note that \CMD{cr} is used for generating line breaks.)

The `comment' and `control' characters `\texttt{\%}' and `\bsl'
\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 `\%', `\{', and `\}', the four specials
\ \$, \ \&, \ \# and \ \_ \ are simply produced by preceding with a
`\bsl'.
Further, `` $\hat{}$ '' by \verb|\eqn{\hat{}}{^}|, and
       `` $\tilde{}$ '' by \verb|\eqn{\tilde{}}{~}|.
Also \ $<$\ , \ $>$ \  and \ $|$ \ \ must only be used in math mode, i.e. within \CMD{[d]eqn}.

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