Initial revision

git-svn-id: https://svn.r-project.org/R/trunk@2 00db46b3-68df-0310-9c12-caf00c1e9a41

Attic/mansrc/ABOUT.tex

@@ -0,0 +1,238 @@
+\documentclass[a4paper,11pt]{article}
+\usepackage{alltt}
+
+\addtolength{\textheight}{12mm}%\
+\addtolength{\topmargin}{-9mm} %/ -- still fits on US paper
+\addtolength{\textwidth}{24mm}%/
+\addtolength{\oddsidemargin}{-12mm}
+
+\newenvironment{display}[0]%
+ {\begin{list}{}{\setlength{\leftmargin}{30pt}}\item}%
+ {\end{list}}
+\newcommand{\bold}[1]{\mbox{\boldmath $#1$}}
+\newcommand{\HTML}{\textsc{html}}
+\newcommand{\R}{\textsc{R}}
+
+
+\title{\textbf{Writing \R\ Documentation}}
+\author{\textit{Ross Ihaka \& Martin Maechler}}
+\date{July 7, 1997}
+
+\begin{document}
+\maketitle
+
+\section{The Documentation Source Tree}
+
+This directory contains detailed documentation for \R\ functions and code
+for translating them into \LaTeX\ and \emph{\HTML} help files.
+
+The help files actually \emph{used} are in the directories
+\texttt{\emph{\$RHOME}/src/library/*/man} where ``*'' stands for
+\texttt{base} where all the standard functions are and for ``proper''
+libraries such as \texttt{mva} and \texttt{eda}.
+
+The directories ``man.new'', ``man.defunct'' and ``man281'' (for Alan Lee
+functions) are not used anymore, currently.
+
+
+\section{Documentation Format}\label{sec:doc-format}
+
+The help files are written in a form which can be processed
+into a variety of formats.  The translation is carried out
+by a combination of \texttt{m4} and \texttt{sed} scripts.
+
+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.man}.
+Note that each file should contain at least one \texttt{ALIAS(name)} line.
+\begin{display}
+\begin{alltt}
+TITLE(\textit{name} @@ \textit{Description})
+USAGE(
+\textit{One or more lines showing the synopsis of the function.
+These are set verbatim in typewriter font.}
+)
+ALIAS(\textit{name})
+ALIAS(\textit{alias 1})
+ALIAS(\textit{alias 2})
+\textit{etc.}
+ARGUMENTS(
+ARG(\textit{arg1} @@ \textit{Description of arg1.})
+ARG(\textit{arg2} @@ \textit{Description of arg2.})
+\textit{etc.}
+)
+DESCRIPTION(
+\textit{A precise description of what the function does.}
+)
+VALUE(
+\textit{A description of the value returned by the function (if any).
+If multiple values are returned in a list use the \texttt{VALUES}
+macro described below instead.}
+)
+VALUES(
+{\textit{A description of the \textbf{list} of values returned by the function.
+For the list, use the same syntax as in ARGUMENTS}:
+@@\samepage}\pagebreak[3]
+ARG(\textit{comp1} @@ \textit{Description of list component `comp1'})
+ARG(\textit{comp2} @@ \textit{Description of list component `comp2'})
+\textit{etc.}
+)
+REFERENCES(
+\textit{References section.  Optional as well as all the following sections:}
+)
+NOTE( \textit{Some note you want to have pointed out\dots\dots.}
+)
+SECTION(Author @@ \dots\dots {\small(\textit{if you are not one of R\&R})}
+)
+SECTION(Warning @@ \textit{\dots\dots}
+)
+\textit{ and maybe more \texttt{SECTION(..)}  environments}
+
+SEEALSO(
+\textit{Pointers to related \R\ functions, using \texttt{LINK(.)}.}
+)
+EXAMPLES(
+\textit{Examples of how to use the function.
+These are set verbatim in typewriter font.}
+
+\fbox{Use examples which are \emph{directly} executable!}
+\textit{To this end, define data, use random number generators (e.g.,
+  \texttt{x <- rnorm(100)}), or use a standard dataset, \texttt{data(\dots)}
+  (Use \texttt{help(data=index)} for info).}
+
+)
+\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{center}
+\begin{tabular}{ll}
+\texttt{BOLD(\textit{word})}   & set \emph{word} in \textbf{bold} font. \\
+\texttt{ITALIC(\textit{word})} & set \emph{word} in \textit{italic} font. \\
+\texttt{LANG(\textit{word})}   & set \emph{word} in \texttt{typewriter} font. \\
+\end{tabular}
+\end{center}
+You should use \texttt{BOLD} and \texttt{ITALIC} in plain text for emphasis
+and \texttt{LANG} to make sure that language fragments stand out from the
+text.
+
+\section{Sectioning}
+To begin a new paragraph insert \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{DESCRIPTION(..)}, \texttt{VALUE\textit{[S]}(..)},
+\texttt{REFERENCES(.)} and \texttt{NOTE(.)} sections, you can use further
+by, e.g.,
+\begin{display}
+\begin{alltt}
+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{LINK(foo)} (usually in the combination \texttt{LANG(LINK(foo))})
+produces a hyperlink to the help page for function
+\texttt{`foo'}.
+One main usage of  `\texttt{LINK}' is in the \texttt{SEEALSO} section of
+the help page, see~\ref{sec:doc-format}, above.
+
+
+
+\section{Miscellaneous}
+Use \texttt{DOTS} for the dots in function argument list ``\texttt{...}'',
+and \texttt{LDOTS} for $\ldots$ (ellipsis dots)
+
+With \texttt{COMMENT}(\dots)\ 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.
+
+\bigskip
+
+\section{Mathematics}
+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
+
+\noindent The following example is from the \texttt{Poisson} help page:
+%\samepage
+\begin{display}
+\begin{verbatim}
+DEQN(p(x) = OVER(SUP(greeklambda@@x) SUP(e@@-greeklambda) @@ x!)
+  @@ p(x) = lambda^x exp(-lambda)/x!)
+for EQN(x = 0, 1, 2, LDOTS).
+\end{verbatim}
+\end{display}
+which, for the \LaTeX\ manual, becomes
+\begin{quote}
+\[ p(x) = {{{{\lambda}^{x}} {{e}^{-\lambda}}} \over {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}
+
+\end{document}

Attic/mansrc/Attic/html/Makefile

@@ -0,0 +1,15 @@
+HTMLDIR= ../../html
+HTMLfun= $(HTMLDIR)/funs
+
+all:
+	@echo Making html documentation
+	-(mkdir -p $(HTMLfun); cd $(HTMLfun); rm -f `echo * | sed /CVS/d`)
+	-(mkdir -p src; cd src; rm -f `ls | sed '/CVS/d'`)
+	cd src; ln -s `ls -d ../../man/* | sed '/CVS/d; /~/d'` .
+	html.format
+	html.aliases
+	html.index > $(HTMLfun)/index.html
+
+clean:
+	@echo cleaning in manual/html
+	@-cd src; rm -f `ls | sed '/CVS/d'`

Attic/mansrc/Attic/html/doc2html

@@ -0,0 +1,123 @@
+#!/bin/sh
+
+(cat << 'END'
+undefine(`eval')
+undefine(`index')
+undefine(`format')
+undefine(`include')
+undefine(`substr')
+undefine(`paste')
+define(COMMENT,`')
+define(TITLE,`
+<HEAD><title>$2</title></HEAD><BODY>
+<A NAME=HEADING1></A>
+[ <A HREF="../index.html">top</A> | <A HREF="index.html"> up</A> ]
+<CENTER><H2><I>$2</I></H2></CENTER>')
+define(USAGE,`
+<H3><I>Syntax</I></H3>
+<PRE>$1</PRE>
+')
+define(ALIAS,`dnl')
+define(BEGIN_ARGUMENTS,`<H3><I>`Arguments'</I></H3>
+<TABLE>')
+define(END_ARGUMENTS,`</TABLE>')
+define(ARGUMENTS,`
+<H3><I>`Arguments'</I></H3>
+<TABLE>
+$1
+</TABLE>
+')
+define(ARG,``<TR VALIGN=TOP><TD><CODE>$1</CODE>
+<TD>
+$2'')
+define(ITEM,`<TR VALIGN=TOP><TD><CODE>$1</CODE>
+<TD>
+$2>')
+define(DESCRIPTION,`<H3><I>`Description'</I></H3>
+$1
+')
+define(NOTE,`<H3><I>`Note'</I></H3>
+$1
+')
+define(VALUE,`<H3><I>`Value'</I></H3>
+$1
+')
+define(SECTION,`<H3><I>$1</I></H3>$2')
+define(VALUES,`<H3><I>`Values'</I></H3>
+$1
+<DL>
+$2
+</DL>
+')
+define(REFERENCES,`<H3><I>`References'</I></H3>
+$1
+')
+define(SEEALSO,`<H3><I>See Also</I></H3>
+$1
+')
+define(LINK,`<A HREF = "$1.html">$1</A>')
+define(EXAMPLES,`<H3><I>`Examples'</I></H3>
+<XMP>$1</XMP>
+')
+
+define(CTRL,`^$1')
+define(LANG,`<CODE>$1</CODE>')dnl
+define(ITALIC,`<I>$1</I>')dnl
+define(BOLD,`<B>$1</B>')dnl
+define(PARA,`<P>')dnl
+define(LDOTS,`...')
+define(EQUALS,`=')
+define(LT,``&#60;'')
+define(GT,``&#62;'')
+define(LE,``&#60;='')
+define(GE,``&#62;='')
+define(OVER,`$1 / $2')
+define(SUP,`{$1}^{$2}^')
+define(SUB,`{{$1}_{$2}_}')
+define(CHOOSE,`{\left(\begin{array}{c} $1 \\ $2 \end{array} \right)}')
+define(PAREN,`{\left( $1 \right)}')
+define(SP,`')
+define(greekAlpha,`&Alpha;')
+define(greekGamma,`&Gamma;')
+define(greekalpha,`&alpha;')
+define(greekpi,`&pi;')
+define(greekmu,`&mu;')
+define(greeksigma,`&sigma;')
+define(greeklambda,`&lambda;')
+define(boldgreekbeta,`\bold{&beta;}')
+define(boldgreekepsilon,`\bold{&epsilon;}')
+define(LOG,`\log')
+define(SQRT,`\sqrt{$1}')
+define(EQBOLD,`\bold{$1}')
+define(EQN,`<i>$1</i>')
+define(DEQN,`<P align=center>
+<I>Equations will come with HTML3</I>
+<P>')
+END
+# Fix up the input to protect things that m4 is sensitive about.
+sed '
+s/unix/M4_unix/g
+s/#/M4_HASH/g
+s/\\(/M4_LP/g
+s/\\(/M4_LP/g
+s/\\)/M4_RP/g
+s/`/M4_LQ/g
+s/'\''/M4_RQ/g
+s/,/M4_COMMA/g
+s/ @@ /,/g
+s/@@/,/g
+s/ifelse/M4_IFELSE/g
+' $*) |m4 |sed '
+/^$/d
+s/^BLANK$//
+s/DOTS/\.\.\./g
+s/M4_unix/unix/g
+s/M4_HASH/#/g
+s/M4_LP/(/g
+s/M4_RP/)/g
+s/M4_LQ/`/g
+s/M4_RQ/'\''/g
+s/M4_COMMA/,/g
+s/M4_IFELSE/ifelse/g
+'
+echo '</BODY>'

Attic/mansrc/Attic/html/html.aliases

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+HTMLDIR=../../html
+
+(cd src ; grep 'ALIAS([A-Za-z.]' `ls | sed '/CVS/d'`) | sed '
+s/:ALIAS(/.html /
+s/)$//
+s/^/ln /
+s/$/.html/
+' | (cd $HTMLDIR/funs ; sh)
+
+(cd src ; grep 'ALIAS([A-Za-z.]' `ls | sed '/CVS/d'`) | sed '
+s/:ALIAS(/ /
+s/)$//
+s/^/ln /
+' | (cd src ; sh)