
\newcommand{\ign}[1]{}

\section{The LEDA Tools for Manual Production and Documentation}


The Lman and Fman utilities give online access to the manual pages of the LEDA system.
Lman produces \LaTeX-output and Fman produces
low quality ASCII-output for quick reference. The usage is

\medskip

\noindent
\verb-Lman T[.h] options-\\
\verb-Fman T[.h] filter-
\medskip


\noindent
where T is the name of a LEDA type, e.g., list, sortseq, or
point. Without options Lman produces manual pages as contained in the LEDA 
manual. Thus, \verb-Lman list- produces
the manual page for the LEDA type list and \verb-Fman list- produces a
low quality version of it. 
Please try out Lman and Fman before proceeding.
If they do not work the error is very likely to be one of the following (if not, you should refer to the LEDA installation guide):

\begin{itemize}
\item The environment variable LEDAROOT is not set to the root directory of the LEDA system. 
\item \$LEDAROOT/Manual/cmd is not part of your PATH.
\item \$LEDAROOT/Manual/tex is not part of your TEXINPUTS.
\end{itemize}
The behavior of Lman and Fman can be fine-tuned
by options. A call \verb-Lman- without arguments gives a 
short survey of all available options. Options are specified in assignment 
syntax \verb-variable=value-. There must be no
blank on either side of the equality sign. In the list of options to follow we list the default value of each option first.

\paragraph*{size=\{12, 11, 10\}:} Determines the font size.

\paragraph*{constref=\{no, yes\}:} Determines how const-ref parameters are
displayed. With the no-option a const-ref parameter 
\verb-const T& x- is displayed as a value parameter \verb-T x- and
with the yes-option it is displayed in full.

\paragraph*{partypes=\{no, yes\}:} Determines how parameters of unary and binary operators are displayed. Consider for example an operator \verb|+| of a class
number. With the no-option the operator \verb|operator+(number x, number y)|
is displayed as \verb|x + y|  and with the yes-option it is displayed as
\verb|number x + number y|.

\paragraph*{numbered=\{no, yes\}:} Determines whether the headerline of the
manual page is numbered. You probably want it numbered when the manual page
becomes part of a larger document.

\paragraph*{warnings=\{yes, no\}:} Determines whether Lman gives warnings. We recommend to use the option warnings=yes and to deal with individual warnings as later in the chapter.

\paragraph*{ack=\{no, yes\}:} Determines whether Lman asks for acknowledgments of warnings.

\paragraph*{usesubscripts=\{yes, no\}:} Determines whether variables consisting 
of a single character followed by a number are displayed as subscripted variables. 

\paragraph*{filter=\{all, signatures, definition, creation, operations,
implementation, example, opname\}:} Determines which part of the manual page is shown. The all-option shows the complete manual page, the signature-options shows the signatures of all operations of the data type, the next five options
show only the corresponding section of the manual page, and the opname-option
shows only the operation with the same name. Thus \verb-Fman list insert-
shows the insert operation for lists and \verb-Lman point filter=operator+- extracts the + operator of the point
type (write arrop to inquire about the array operator and funop to inquire
about the function operator). 

\paragraph*{outfile=\{`',string\}:} Determines whether the \TeX-file generated
is written on a temporary file (the default option) or on the file with 
name string. Only available for Lman.

\paragraph*{latexruns=\{1, 0, 2\}:} Determines the number of \LaTeX\  runs used to produce the manual page. You need to run  \LaTeX\  twice if the manual page
contains cross references.

\paragraph*{xdvi=\{yes, no\}:} Determines whether the manual page is displayed by xdvi.
\bigskip

Lman can be customized by putting options in a file Lman.cfg in either 
the home directory or the working directory. Command line options take 
precedence over options in the working directory which in turn take precedence 
over options in the home directory.

Fman is the utility for quick reference. It takes two arguments, a typename
and one of the filters, and directly displays its output. For example, the call
\verb-Fman list signatures- will display the signatures of all operations of
the list data type.
\begin{figure}[t!]
{\footnotesize
\begin{verbatim}
#ifndef LEDA_STACK_H
#define LEDA_STACK_H

#include <LEDA/basic.h>
#include <LEDA/impl/slist.h>

/*{\Manpage {stack} {E} {Stacks} {S}}*/

template<class E> class _CLASSTYPE stack : private SLIST
{
/*{\Mdefinition
An instance |S| of the parameterized data type |\Mname| is a sequence of 
elements of data type |E|, called the element type of |S|. Insertions or
deletions of elements take place only at one end of the sequence, called 
the top of |S|. The size of |S| is the length of the sequence, a stack
of size zero is called the empty stack.}*/

  void copy_el(GenPtr& x)  const { x=Copy(ACCESS(E,x)); }
  void clear_el(GenPtr& x) const { Clear(ACCESS(E,x)); }
public:

/*{\Mcreation}*/

  stack() {}
/*{\Mcreate creates an instance |\Mvar| of type |\Mname| and initializes 
it to the empty stack.}*/

  stack(const stack<E>& S) : SLIST(S) {}
 ~stack() { clear(); }
  stack<E>& operator=(const stack<E>& S) { return (stack<E>&)SLIST::operator=(S); }

/*{\Moperations 2.5 4}*/

E top()   const { return ACCESS(E,SLIST::head());}
/*{\Mop      returns the top element of |\Mvar|.\\ \precond $S$ is not empty.}*/

void push(E x)  { SLIST::push(Copy(x)); }
/*{\Mop      adds $x$ as new top element to |\Mvar|.}*/

E pop()         { E x=top(); SLIST::pop(); return x; }
/*{\Mop      deletes and returns the top element of |\Mvar|.\\ \precond $S$ is not empty.}*/

int  empty() { return SLIST::empty(); }
/*{\Mop      returns true if |\Mvar| is empty, false otherwise.}*/

\*{\Mimplementation
Stacks are implemented by singly linked linear lists. All operations take time $O(1)$.}*/ 
#endif
\end{verbatim}
}
\caption{The header file for the stack data type.}
\label{an h-file}
\end{figure}

Lman and Fman are not only applicable to the header files of the LEDA system, they can be applied to any file containing (possibly among other things) \CCC-code suitably augmented by so-called manual comments. A manual comment
is any comment of the form \verb|/*{\Mcommand ...}*/| where Mcommand is one
of so-called manual commands. We discuss manual commands in detail below. 
Every manual comment produces part of the manual page. Figures \ref{an h-file}
and \ref{a man page} show a header file augmented by manual comments and the
manual page produced from it. The body of a manual comment is an ordinary \LaTeX-text augmented by the possiblity to \emph{quote code}. Code is quoted by enclosing it either between vertical bars ($\Lvert\ldots\Lvert$) or between
double square brackets (\DLK\ldots\DRK). Code quoted by double square brackets
is typeset using typewriter font and code quoted by vertical bars is given a math-like appearance. So \DLK S.insert(E x)\DRK\ produces {\tt S.insert(E x)}
and $\Lvert$S.insert(E x)$\Lvert$ produces $\mathit{S}\nspacedot.\mathit{insert}(E\ x)$.


\begin{figure}[t!]
\begin{manual}

\large{\bf Stacks (stack)}\medskip

\definition

An instance $S$ of the parameterized data type \mbox{$\mathit{stack\<E\>}$} is 
a sequence of 
elements of
data type $E$, called the element type of $S$. Insertions or deletions of 
elements 
take place only at one end of the sequence, called the top of $S$. The size of 
$S$ 
is the length of the sequence, a stack of size zero is called the empty stack. 


\creation

\create {\mbox{$\mathit{stack\<E\>}$}}
{\mbox{$\mathit{S}$}} 
{} 
{creates an instance \mbox{$\mathit{S}$} of type 
\mbox{$\mathit{stack\<E\>}$} and initializes it to the empty stack. 
}

\setlength{\typewidth}{2.5cm}
\setlength{\callwidth}{4cm}
\computewidths
\operations

\function {\mbox{$\mathit{E}$}}
{\mbox{$\mathit{S.}$}top} 
{} 
{returns the top element of \mbox{$\mathit{S}$}.\\ \precond $S$ is not empty. 
}

\function {\mbox{$\mathit{void}$}}
{\mbox{$\mathit{S.}$}push} 
{\mbox{$\mathit{E\ x}$}} 
{adds $x$ as new top element to \mbox{$\mathit{S}$}. 
}

\function {\mbox{$\mathit{E}$}}
{\mbox{$\mathit{S.}$}pop} 
{} 
{deletes and returns the top element of \mbox{$\mathit{S}$}.\\ \precond $S$ is 
not empty. 
}

\function {\mbox{$\mathit{int}$}}
{\mbox{$\mathit{S.}$}empty} 
{} 
{returns true if \mbox{$\mathit{S}$} is empty, false otherwise. 
}

\end{manual}
% Dieses File ist wie folgt produziert. Take the body of the previous figure and
% put into stack.h. Run Lman to obtain stack.tex. Then edit stack.tex. Remove
% everything before \begin{manual} and after \end{manual}
\caption{The manual page for the stack data type}
\label{a man page}
\end{figure}

Lman is based on the command lextract.
\medskip

\noindent
\verb|lextract infile outfile options|
\medskip

\noindent
reads infile, processes the manual commands in it, and writes the core of a \TeX-file on outfile. All Lman options apply.

Lman works in three phases. It first produces a tempory \TeX-file

\begin{verbatim}
\documentclass[a4paper,size pt]{article}  % the size of the size-option
\usepackage{Lweb}
\begin{document}
  output of lextract
\end{document}
\end{verbatim}
and then applies latex and xdvi to it. 
%The outfile-option allows to write 
%the generated \TeX-file on a user-specified file.

Ldoc is the tool to produce full documentations consisting of manual page, implementation, and test routines. Ldoc works together with the literate programming systems CWEB \cite{Knuth-Levy}, noweb \cite{Ramsey:noweb}, and Lweb. Lweb is a dialect of noweb which we developed for the production of the LEDA book and the documentation of the LEDA system. You should have a working knowledge of either CWEB or noweb before proceeding (we discuss noweb and Lweb in more detail later in the chapter).

Ldoc is based on the commands \emph{lextract}, \emph{ldel}, and \emph{weave}.
We discussed lextract already.
\medskip

\noindent
\verb|ldel infile outfile|
\medskip

\noindent reads infile, deletes all manual comments from it, and writes the
result on outfile. Weave is the weave-command of the literate programming tool  
in use, i.e., cweave for CWEB, noweave for noweb, and lweave for Lweb. Ldoc
works on Cweb-, noweb-, and Lweb-files. It first uses lextract to extract the manual and 
ldel to extract a file pure of manual comments, it then applies the appropriate weave command to the output of ldel, and it finally applies latex and xdvi to the resulting file. All Lman options apply. In order to try out Ldoc copy sortseq.lw from \$LEDAROOT/Lweb to a directory where you have write-permission and then call Ldoc sortseq. If noweb is not available at your installation copy all files sortseq.* and call latex sortseq.tex.


\newpage
\begin{verbatim}
foo.[lw|nw|w] -- ldel -- foo-del.[lw|nw|w] -- XXXweave -- foo.tex -- latex 
  |                                                         |
  lextract                                                  | \input
  |                                                         |
foo.man ----------------------------------------------------
\end{verbatim}


Figure \ref{manual directory} shows the parts of the LEDAROOT directory that are 
relevant for manual production. Subdirectories Cweb, Noweb, and Lweb contain 
examples of full documentations written with the literate programming systems of the
same name. Subdirectory Manual splits into cmd, noweb, tex, and MANUAL: cmd 
contains the commands Lman, Fman, \ldots, noweb contains the full documentation 
(written in noweb) of all commands, tex contains the style-files for manual 
production, and MANUAL contains the actual LEDA manual.
\begin{figure}
\begin{verbatim}
                           LEDAROOT
         _____________________|______________________                      
        |              |               |             |
       Cweb          Noweb            Lweb         Manual
                                                 ____|_______________
                                                |    |        |      |
                                              cmd  noweb     tex  MANUAL 
\end{verbatim}
\caption{The parts of the LEDAROOT directory relevant for manual production.}
\label{manual directory}
\end{figure}


\ign{LEDA offers tools for manual production and documentation.

\begin{verbatim}
       __________  weave ______   LaTeX source
      |
      |   ------- Lman --------   LaTeX source for manual page
    foo
      |   ------- Ldoc --------   LaTeX source for full documentation
      |
      |   ------- Fman --------   ASCII version of manual page
      |
      |__________ tangle ______   program

    
    foo's ------- Mkman -------   LaTeX source of manual

\end{verbatim}

Lman produces manual pages from header files suitably
augmented by so-called manual comments. Many examples can be found in the LEDA include directory (LEDAROOT/incl/LEDA). A manual comment starts with \verb-\*{\M- 
and ends with \verb-}*/-. Try \verb-Lman list- to see Lman in action.
If it does not work the error is very likely to be one of the following (if not, you should refer to the LEDA installation guide):

\begin{itemize}
\item The environment variable LEDAROOT is not set to the root directory of the LEDA system. 
\item \$LEDAROOT/Manual/cmd is not part of your PATH.
\item \$LEDAROOT/Manual/tex is not part of your TEXINPUTS.
\end{itemize}
\begin{verbatim}
                      LEDAROOT
    _____________________|______________________                      
   |       |      |               |             |
 incl   Cweb   Noweb            Lweb          Manual
   |                                        _____|_______________
 LEDA                                      |     |        |      |
                                          cmd   noweb    tex  Manual
                                                              
                                                             
\end{verbatim}
shows the parts of the LEDAROOT directory relevant for manual production
and documentation. The include directory contains all header files of the 
LEDA system, the directories CWEB, noweb, and Lweb contains examples
of full documentation written with various literate programming tools,
and Manual contains all the relevant commands and tex files.

The Lman utility can be applied to LEDA data types and user-defined 
data types.
Write \\ 
\verb-Lman T[.h] options -
to apply it to the LEDA data type T and
write\\
\verb-Lman T[.ext] options - to apply it to file T.ext in the working directory. The extensions lw (Lweb file), nw (noweb file), w (a CWEB-file), and h (h-file) are possible. The extensions are tried in this order and the working directory is searched before the LEDA include directory. The following options are available:
\smallskip\\
size={12,11,10}\\
constref={no,yes}\\
partypes={no,yes}\\
usesubscripts={no,yes}\\
numbered={no,yes}\\
xdvi={yes,no}\\
warnings={no,yes}\\
ack={no,yes}\\
latexruns={2,1}\\
filter={all,signatures,definition,creation,operations,implementation,example,opname}\\
pid={"",string}

Options are given in assignment syntax. There must be no blank on either side of the equality sign.

The size-option selects the
font-size. The option constref determines whether const-ref pairs are shown, 
the option partypes determines whether the type of a value parameter of
an operator is suppressed if equal to the currently defined type, and
the option usesubscripts determines whether indexed variables are typeset 
using subscripts.  

A manual page can be numbered or not and the call of xdvi can be suppressed.
Lman may be asked to issue warnings and warnings may require a user action or
not. We recommend to run Lman with \verb-warnings=yes- and \verb-ack=yes-
in the early stages of designing a manual page.
Lman usually runs \LaTeX\ twice in order to get cross-references correct.
You may settle for a single run of \LaTeX. Lman makes use of a preprocessor
called ext. The preprocessor writes its output on file /tmp/pid-ext.tex
where pid is either the process identification of the preprocessor run or
specified by the pid-option. Mkman makes use of the pid-option. You will probably never have to use it. 

There are four ways to specify options for Lman. You may either put them 
into the file itself by means of the Moptions command, or you can put them
onto the command line, or you can put them into a configuration file
Lman.cfg in either the working directory or the home directory.

The Lman-utility can also be told to extract only part of a manual page by
the filter-option. The options definition, 
creation, operations, implementation, and example cause extraction of the 
corresponding section of the manual, and the option signatures
extracts the signatures of all operations but suppresses the descriptions.
One can also extract a single operation by using its name, e.g., \verb-Lman stack filter=push- extracts the push operation of the
stack type 
and \verb-Lman point filter=operator+- extracts the + operator of the point
type (write arrop to inquire about the array operator and funop to inquire
about the function operator). 

Fman is an alternative to Lman. It gives low quality ASCII output but works faster.

Mkman is the tool to produce manuals like the LEDA manual. 

Ldoc is the utility that supports the production of full documentations. All remarks above apply equally well to Ldoc. Ldoc applies to Lweb, noweb, and CWEB files. For use with noweb and Lweb, the LEDA dialect of noweb, you must have installed noweb and for use with CWEB you must have installed CWEB. The subdirectories CWEB, noweb, and Lweb contain full documentations of parts of the LEDA system. Copy a file from one of these directories to your working directory and run Lman on it to see it in action. If it does not work check whether you have installed the proper literate programming system. 
 
Lweave is the weave tool for Lweb.}


For more information about the LEDA tools for manual production and documentation we refer the reader to the corresponding chapter of \cite{LEDAbook}.


