\newcommand*{\BS}{\textbackslash}
\newcommand*{\RHOMEdir}[1]{\texttt{\emph{\$RHOME}/#1}}
\newcommand*{\QQUAD}{\hspace*{1em}}

\section{The Documentation Source Tree}

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

%%%----- FOLLOWING SHOULD BE ADAPTED TO NEW DIRECTORY STRUCTURE
This directory, \texttt{mansrc}, contains code for translating them into
\LaTeX{} and further documents pertaining to \R.

The sub-directories ``man.new'', ``man.defunct'' and ``man281'' (for
Alan Lee functions) are not used anymore, currently.
%%%----- end adaption


\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 \texttt{Rdconv} in \RHOMEdir{etc/}.

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

%%-- Not anymore! (yes ?)
Note that each file should contain at least one
\verb|\alias{|\emph{name}\texttt{\}} line.  

\begin{display}
\begin{alltt}
\BS{}name\{\textit{myfunction}\}        \% first argument of old TITLE(. @@ .)
\BS{}title\{\textit{Description}\}      \% 2nd   argument of old TITLE(. @@ .)
\BS{}usage\{
myfunction(\dots)
\textit{One or more lines showing the synopsis of the function(s) and variables
documented in the file.  These are set verbatim in typewriter font.}
\}
\BS{}alias\{\textit{alias 1}\}     \%-- \textit{need one \texttt{\BS{}alias\{obj\}}  for each object `\texttt{obj}'}
\BS{}alias\{\textit{alias 2}\}     \%-- \textit{defined here in addition to `\texttt{myfunction}'.}
   \textit{etc.}
\BS{}arguments\{
 \textit{Some optional text \emph{before} the optional list}
 \BS{}item\{\textit{arg1}\}\{\textit{Description of arg1.}\}
 \BS{}item\{\textit{arg2}\}\{\textit{Description of arg2.}\}
    \textit{etc.}
 \textit{Some optional text \emph{after} the list.}
\}
\BS{}description\{\textit{A precise description of what the function does.}\}
\BS{}value\{
 \textit{A description of the value returned by the function (if any).
 If a list with  multiple values is returned, you can use} 
 \samepage\pagebreak[3]
 \BS{}item\{\textit{comp1}\}\{\textit{Description of result component `comp1'}\}
 \BS{}item\{\textit{comp2}\}\{\textit{Description of result component `comp2'}\}
    \textit{etc.}
 \}
\BS{}references\{
 \textit{References section.  Optional as well as all the following sections:}\}
\BS{}note\{ \textit{Some note you want to have pointed out\dots\dots.}\}
\BS{}author\{\dots\dots {\small(\textit{if you are not one of R \& R})}\}
\BS{}section\{Warning\}\{\textit{\dots\dots}\}

   \textit{and maybe more \texttt{\BS{}section\{..\}}  environments}

\BS{}seealso\{
 \textit{Pointers to related \R{} functions, using \texttt{\BS{}link\{.\}},
 usually in the form of \texttt{\BS{}code\{\BS{}link\{.\}\}}.} \}
\BS{}examples\{
 \textit{Examples of how to use the function.
 These are set verbatim in typewriter font.}

 \QQUAD\fbox{Use examples which are \emph{directly} executable!}
 \QQUAD\textit{To this end, define data, use random number generators (e.g.,
 \QQUAD  \texttt{x <- rnorm(100)}), or use a standard dataset, \texttt{data(\dots)}
 \QQUAD  (Use \texttt{data()} for info).}
\}
\BS{}keyword\{key1\}       \% \textit{use at least one  keyword out of the list}
\BS{}keyword\{key2\}       \% \textit{in } \RHOMEdir{doc/KEYWORDS}.
\end{alltt}
\end{display}

\bigskip
\pagebreak[3]
%%- \pagebreak[4]%-- at the moment, given the content....

\section{Emphasis}
Within the text of the document it is possible to set words in phrases
in different styles as follows.
\begin{quote}
  \begin{tabular}{ll}
    \texttt{\BS{}bold\{\textit{word}\}}
    & set \emph{word} in \textbf{bold} font. \\
    \texttt{\BS{}emph\{\textit{word}\}}
    & emphasize \emph{word} (often setting \textit{italic} font.)  \\
    \texttt{\BS{}code\{\textit{word}\}}
    & set \emph{word} in \texttt{typewriter} font. \\
  \end{tabular}
\end{quote}
You should use \texttt{\BS{}bold} and \texttt{\BS{}emph} in plain text
for emphasis and \texttt{\BS{}code} to make sure that language fragments
stand out from the text.

\section{Sectioning}
To begin a new paragraph or leave a blank in an example, just insert an
empty line (as in \TeX).
%%-  \texttt{PARA} on a line by itself 
%%- and to leave a blank line in an example place \texttt{BLANK}
%%- on a line by itself.
%%- \textbf{Note:} Do \underline{\emph{not}} use
%%- \texttt{PARA} in the \textsc{EXAMPLES} section, but rather \texttt{BLANK}
%%- ({\footnotesize The reason is an \texttt{nroff} problem: The \emph{nofill}
%%-   command (\texttt{.nf}) is invalidated by a paragraph break}).
%%-
Besides the \texttt{\BS{}description\{..\}}, \texttt{\BS{}value\{..\}},
\texttt{\BS{}references\{.\}} and \texttt{\BS{}note\{.\}} sections, you can
``define'' arbitrary ones by
\texttt{\BS{}section\{\emph{section\_title}\}\{\ldots\}}, e.g., 
\begin{display}
\begin{alltt}
\BS{}section\{Warning\}\{ You must not call this function unless \ldots\ldots\}
\end{alltt}
\end{display}

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


\section{Miscellaneous}
Use \texttt{\BS{}dots} for the dots in function argument list
``\texttt{...}'', and \texttt{\BS{}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 ``\verb|\%|''.

\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
\texttt{\BS{}eqn\{\textit{latex}\}\{\textit{ascii}\}} and
\texttt{\BS{}deqn\{\textit{latex}\}\{\textit{ascii}\}} are used. 
Where \texttt{\BS{}eqn} is used for ``inline'' formula (corresponding to
(La)\TeX's \$\ldots\$),
 \texttt{\BS{}deqn} gives ``displayed equations'' ({\`a} la \LaTeX's
 \texttt{equation} environment, or \TeX's \$\$\ldots\ldots\$\$).

\noindent The following example is from the \texttt{Poisson} help page:
%\samepage
\begin{display}
\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{display}
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}
        
%%- 
%%- These are constructs that you can use for writing formulae:
%%- %
%%- \begin{center}
%%- \begin{tabular}{l@{\ \ $\to$\ \ }p{12em}@{\ \ $\longrightarrow$\ \ }l}
%%- \hline
%%- Help-File & \LaTeX-code & \LaTeX ``result'' \\
%%- \hline\hline
%%- 
%%-   %%--- the following lines are original straight from  latex/doc2latex 
%%-   %%- 1)  (query-replace-regexp "define(\\([A-z_]+\\),\\(.*\\))"
%%-   %%                      "\\1  & \\\\verb#\\2#         & $ \\2 $ \\\\\\\\" nil)
%%-   %%- 2)  (query-replace "$1" "a1" nil)
%%-   %%-     (query-replace "$2" "a2" nil)
%%-   %%- 3)  (query-replace-regexp "\\$ `\\(.*\\)' \\$" "$ \\1 $" nil)
%%- EQUALS          & \verb#`='#    & $ = $ \\
%%- LT              & \verb#`<'#    & $ < $ \\
%%- LE              & \verb#`\le'#  & $ \le $ \\
%%- GE              & \verb#`\ge'#  & $ \ge $ \\
%%- GT              & \verb#`>'#    & $ > $ \\
%%- LOG             & \verb#`\log'#         & $ \log $ \\
%%- EXP             & \verb#`\exp'#         & $ \exp $ \\
%%- SQRT            & \verb#`\sqrt{a1}'#    & $ \sqrt{a1} $ \\
%%- DISPLAYSTYLE    & \verb#`{\displaystyle a1}'#   & $ {\displaystyle a1} $ \\
%%- OVER            & \verb#{{a1} \over {a2}}#      & $ {{a1} \over {a2}} $ \\
%%- SUP             & \verb#`{{a1}^{a2}}'#  & $ {{a1}^{a2}} $ \\
%%- SUB             & \verb#`{{a1}_{a2}}'#  & $ {{a1}_{a2}} $ \\
%%- CHOOSE          & \verb#`{ a1 \choose a2 }'#    & $ { a1 \choose a2 } $ \\
%%- PAREN           & \verb#`{\left( a1 \right)}'#  & $ {\left( a1 \right)} $ \\
%%- SP              & \verb#`'#     & $  $ \\
%%- \hline
%%- greekGamma      & \verb#`\Gamma'#       & $ \Gamma $ \\
%%- greekalpha      & \verb#`\alpha'#       & $ \alpha $ \\
%%- greekpi         & \verb#`\pi'#  & $ \pi $ \\
%%- greekmu         & \verb#`\mu'#  & $ \mu $ \\
%%- greeksigma      & \verb#`\sigma'#       & $ \sigma $ \\
%%- greeklambda     & \verb#`\lambda'#      & $ \lambda $ \\
%%- boldgreekbeta   & \verb#`\bold{\beta}'#         & $ \bold{\beta} $ \\
%%- boldgreekepsilon& \verb#`\bold{\varepsilon}'#   & $ \bold{\varepsilon} $ \\
%%- \hline\hline
%%- EQBOLD          & \verb#`\bold{a1}'#    & $ \bold{a1} $ \\
%%- EQN             & \verb#`$ a1 $'#       & $  a1  $ \\
%%- DEQN\{\textsc{tex}\}\{ascii\} & \verb#`\[ #\textsc{tex}\verb# \]'#
%%-                                         &  $\displaystyle \textsc{tex} $  \\
%%- DEQTEX          & \verb#\[ a1 \]#       &  $\displaystyle a1 $  \\
%%- DEQHTML         & \verb#`'#     & $  $ \\ \hline
%%- \end{tabular}
%%- \end{center}
%%- 
%%- \bigskip


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