reduce-historical/r38/doc/help/help.tex

\documentstyle{article}

\title{The REDUCE reference format}


\begin{document}

%\maketitle
The REDUCE reference format is used to create material for help systems on
various platforms.  In particular, it is designed to allow formatting in
\LaTeX{} as well as automatic translation into a format suitable for
help systems like MS-Windows help or GNU info.

The structure of the text is specified by suitable \verb|section|,
\verb|\subsection|, and \verb|subsubsection| commands.

Every entry in the reference text is given by a special environment.
The following environments of one argument are defined:
\begin{verbatim}
  \begin{Declaration}{id}     ...     \end{Declaration}
  \begin{Operator}{id}        ...     \end{Operator}
  \begin{Switch}{id}          ...     \end{Switch}
  \begin{Variable}{id}        ...     \end{Variable}
\end{verbatim}
The argument denotes the object to be explained. The side effects of
these environments are
\begin{enumerate}
  \item An appropriate node is defined in the info output.
  \item An index entry is generated.
  \item A cross reference is generated. This can be used in the
        \verb|\ref|, \verb|\pageref|, \verb|\nameref|, and \verb|\see|
        commands.
\end{enumerate}
Additional index entries or cross reference keys can be generated as usual,
with the \verb|\index| and \verb|\label| commands.

Within each of these environments the following special environments
may be used:
\begin{itemize}
  \item
    \begin{verbatim}
      \begin{Syntax}          ...     \end{Syntax}
\end{verbatim}
    This is for the syntax description. (add description here)
  \item
    \begin{verbatim}
      \begin{Comments}        ...     \end{Comments}
\end{verbatim}
    This is for the explanation.
  \item 
    \begin{verbatim}
      \begin{Examples}        ...     \end{Examples}
\end{verbatim}
    This is similar to a two-column tabular environment and is to show
    REDUCE input and output on the same line.
  \item
    \begin{verbatim}
      \begin{Related}         ...     \end{Related}
\end{verbatim}
    This is similar to an \verb|itemize| environment. Every entry
    starts with a \verb|\item[|{\it name\/}\verb|]| command and refers
    to related entries in the reference guide.
\end{itemize}

The following new commands are defined:
\begin{itemize}
  \item \verb|\name{|{\it id\/}\verb|}| for identifiers of all sorts.
  \item \verb|\nameref{|{\it id\/}\verb|}| is an abbreviation for
        \verb|name| followed by \verb|\ref|.
  \item \verb|\see{|{\it id\/}\verb|}| is an abbreviation for ``see
        also'' followed by the reference.
\end{itemize}


Since the input is to be translated automatically into some simple
format, many of the normal \LaTeX{} commands are not allowed in the
text. There is, however, the possibility to include certain text only
in the printed version, or in the info version of the document. To
this end there is one new command,
\begin{quotation}
  \verb|\IFTEX{|\TeX{} text\verb|}{|info text\verb|}|
\end{quotation}
and two new environments,
\begin{verbatim}
  \begin{TEX}  ... \end{TEX}
  \begin{INFO} ... \end{INFO}
\end{verbatim}
For example, a mathematical formula like $\exp(x)$ must be written as
follows:
\begin{verbatim}
  \IFTEX{$\exp(x)$}{exp(x)}
\end{verbatim}
The following commands and environments are only allowed in the first
argument to the \verb|\IFTEX| command or in the body of a
\verb|TEX| environment:
\begin{itemize}
  \item All math mode commands and environments (\verb|$|, \verb|\(|,
        \verb|\)|, \verb|\[|, \verb|\]|, and the \verb|displaymath|,
        \verb|equation|, \verb|eqnarray|, and \verb|array|
        environments).
  \item All size changing commands like \verb|\normalsize|,
        \verb|\large|, etc., or their environment forms.
  \item All typeface changing commands like \verb|\it|, \verb|\sf|,
        except \verb|\em| to emphasize a given portion of text. The
        same applies to the corresponding environment forms.
  \item The \verb|*|-variants of the \verb|\verb| command and the 
        \verb|verbatim| environment.
  \item The \verb|picture|, \verb|tabbing|, and \verb|tabular|
        environments.
  \item All float environments, like \verb|table| and \verb|figure|.
  \item (what's missing here?)
\end{itemize}

\end{document}