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 L^ATEX-output and Fman produces low quality ASCII-output for quick reference. The usage is

Lman T[.h] options
Fman T[.h] filter

   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, Lman list produces the manual page for the LEDA type list and 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.

• You don't have a current version of perl installed and accessible.
• You don't have a current version of latex installed and accessible.
• The environment variable LEDAROOT is not set to the root directory of the LEDA system.
• $LEDAROOT/Manual/cmd is not part of your PATH.
• $LEDAROOT/Manual/tex is not part of your TEXINPUTS.

    

The behavior of Lman and Fman can be fine-tuned by options. A call Lman without arguments gives a short survey of all available options. Options are specified in assignment syntax 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.

size={12, 11, 10}

Determines the font size.

constref={no, yes}

Determines how const-ref parameters are displayed. With the no-option a const-ref parameter const T& x is displayed as a value parameter T x and with the yes-option it is displayed in full.

partypes={no, yes}

Determines how parameters of unary and binary operators are displayed. Consider for example an operator + of a class number. With the no-option the operator operator+(number x, number y) is displayed as x + y and with the yes-option it is displayed as number x + number y.

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.

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.

verbosity={yes, no}

Determines whether Lman gives status information.

ack={no, yes}

Determines whether Lman asks for acknowledgments of warnings.

usesubscripts={yes, no}

Determines whether variables consisting of a single character followed by a number are displayed as subscripted variables.

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 Fman list insert shows the insert operation for lists and 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).

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.

latexruns={1, 0, 2}

Determines the number of L^ATEX runs used to produce the manual page. You need to run L^ATEX twice if the manual page contains cross references.

xdvi={yes, no}

Determines whether the manual page is displayed by xdvi.

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 Fman list signatures will display the signatures of all operations of the list data type.

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) C++-code suitably augmented by so-called manual comments. A manual comment is any comment of the form /*{\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.

The following part shows the enriched header file of data type stack:  

#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.}*/

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.}*/

\*{\Mimplementation
Stacks are implemented by singly linked linear lists. All operations take 
time $O(1)$.}*/ 
};
#endif

The section shows a header file augmented by manual comments and the stack manual page shows the manual page produced from it. The body of a manual comment is an ordinary L^ATEX-text augmented by the possiblity to quote code. Code is quoted by enclosing it either between vertical bars (|...|) or between double square brackets ([[...]]). Code quoted by double square brackets is typeset using typewriter font and code quoted by vertical bars is given a math-like appearance. So [[S.insert(E x)]] produces S.insert(E x) and |S.insert(E x)| produces S.insert(E x).

  

Figure 1.3: The Manual Production Process

Lman is based on the command lextract. See figure ldel and lextract.   

  lextract infile outfile [options]

reads infile, processes the manual commands in it, and writes the core of a TEX-file on outfile. All Lman options apply. Lman itself works in three phases. It first produces a tempory L^ATEX-file

\documentclass[a4paper,size pt]{article}  
\usepackage{Lweb}
\begin{document}
  output of lextract
\end{document}

and then applies latex and xdvi to it.

  

Figure 1.4: Manual relevant directories

Ldoc is the tool to produce full documentations consisting of manual page, implementation, and test routines. Ldoc is based on noweb [71], 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 noweb before proceeding. Ldoc is based on the commands lextract, ldel, and weave. We discussed lextract already.  

  ldel infile outfile

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., noweave for noweb, and lweave for Lweb. Ldoc works on 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.

Figure The LEDA directory tree shows the parts of the LEDAROOT directory that are relevant for manual production. Subdirectory Manual splits into cmd, noweb, tex, and MANUAL: cmd contains the commands Lman, Fman, ..., 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.

For more information about the LEDA tools for manual production and documentation we refer the reader to the corresponding chapter of [58].