Add @node lines and @menu lists.

diff --git a/doc/cln.texi b/doc/cln.texi
index f462676fb28089fe2643bbaecb62d8259a0aae09..fcbe9e60de35e91090da6229d1341d2bca83d21f 100644 (file)
--- a/doc/cln.texi
+++ b/doc/cln.texi
@@ -93,18 +93,146 @@ by the authors.
 
 
 @c Table of contents
-@contents
+@c @contents
 
 
-@node Top, Introduction, (dir), (dir)
+@node Top
+@top CLN
 
 @c @menu
 @c * Introduction::                Introduction
 @c @end menu
 
+@menu
+* Introduction::                
+* Installation::                
+* Ordinary number types::       
+* Functions on numbers::        
+* Input/Output::                
+* Rings::                       
+* Modular integers::            
+* Symbolic data types::         
+* Univariate polynomials::      
+* Internals::                   
+* Using the library::           
+* Customizing::                 
+* Index::
 
-@node Introduction, Top, Top, Top
-@comment node-name, next, previous, up
+ --- The Detailed Node Listing ---
+
+Installation
+
+* Prerequisites::               
+* Building the library::        
+* Installing the library::      
+* Cleaning up::                 
+
+Prerequisites
+
+* C++ compiler::                
+* Make utility::                
+* Sed utility::                 
+
+Building the library
+
+* Using the GNU MP Library::    
+
+Ordinary number types
+
+* Exact numbers::               
+* Floating-point numbers::      
+* Complex numbers::             
+* Conversions::                 
+
+Functions on numbers
+
+* Constructing numbers::        
+* Elementary functions::        
+* Elementary rational functions::  
+* Elementary complex functions::  
+* Comparisons::                 
+* Rounding functions::          
+* Roots::                       
+* Transcendental functions::    
+* Functions on integers::       
+* Functions on floating-point numbers::  
+* Conversion functions::        
+* Random number generators::    
+* Obfuscating operators::       
+
+Constructing numbers
+
+* Constructing integers::       
+* Constructing rational numbers::  
+* Constructing floating-point numbers::  
+* Constructing complex numbers::  
+
+Transcendental functions
+
+* Exponential and logarithmic functions::  
+* Trigonometric functions::     
+* Hyperbolic functions::        
+* Euler gamma::                 
+* Riemann zeta::                
+
+Functions on integers
+
+* Logical functions::           
+* Number theoretic functions::  
+* Combinatorial functions::     
+
+Conversion functions
+
+* Conversion to floating-point numbers::  
+* Conversion to rational numbers::  
+
+Input/Output
+
+* Internal and printed representation::  
+* Input functions::             
+* Output functions::            
+
+Modular integers
+
+* Modular integer rings::       
+* Functions on modular integers::  
+
+Symbolic data types
+
+* Strings::                     
+* Symbols::                     
+
+Univariate polynomials
+
+* Univariate polynomial rings::  
+* Functions on univariate polynomials::  
+* Special polynomials::         
+
+Internals
+
+* Why C++ ?::                   
+* Memory efficiency::           
+* Speed efficiency::            
+* Garbage collection::          
+
+Using the library
+
+* Compiler options::            
+* Include files::               
+* An Example::                  
+* Debugging support::           
+* Reporting Problems::          
+
+Customizing
+
+* Error handling::              
+* Floating-point underflow::    
+* Customizing I/O::             
+* Customizing the memory allocator::  
+
+@end menu
+
+@node Introduction
 @chapter Introduction
 
 @noindent
@@ -239,13 +367,29 @@ order to avoid name clashes.
 @end itemize
 
 
+@node Installation
 @chapter Installation
 
 This section describes how to install the CLN package on your system.
 
 
+@menu
+* Prerequisites::               
+* Building the library::        
+* Installing the library::      
+* Cleaning up::                 
+@end menu
+
+@node Prerequisites, Building the library, Installation, Installation
 @section Prerequisites
 
+@menu
+* C++ compiler::                
+* Make utility::                
+* Sed utility::                 
+@end menu
+
+@node C++ compiler
 @subsection C++ compiler
 
 To build CLN, you need a C++ compiler.
@@ -264,6 +408,7 @@ global variables, a feature which I could implement for GNU g++
 only. Also, it is not known whether this semi-automatic ordering works
 on all platforms when a non-GNU assembler is being used.
 
+@node Make utility
 @subsection Make utility
 @cindex @code{make}
 
@@ -271,6 +416,7 @@ To build CLN, you also need to have GNU @code{make} installed.
 
 Only GNU @code{make} 3.77 is unusable for CLN; other versions work fine.
 
+@node Sed utility
 @subsection Sed utility
 @cindex @code{sed}
 
@@ -280,6 +426,7 @@ on @code{sed}, and the vendor's @code{sed} utility on these systems is too
 limited.
 
 
+@node Building the library
 @section Building the library
 
 As with any autoconfiguring GNU software, installation is as easy as this:
@@ -384,6 +531,11 @@ problems.  Also, they are generally slightly slower than static
 libraries so runtime-critical applications should be linked statically.
 
 
+@menu
+* Using the GNU MP Library::    
+@end menu
+
+@node Using the GNU MP Library
 @subsection Using the GNU MP Library
 @cindex GMP
 
@@ -408,6 +560,7 @@ library, then you can explicitly specify so by calling
 @code{configure} with the option @samp{--without-gmp}.
 
 
+@node Installing the library
 @section Installing the library
 @cindex installation
 
@@ -428,6 +581,7 @@ specify @code{--prefix=@dots{}} at configure time, just re-run
 the @code{--prefix=@dots{}} option.
 
 
+@node Cleaning up
 @section Cleaning up
 
 You can remove system-dependent files generated by @code{make} through
@@ -444,6 +598,7 @@ $ make distclean
 @end example
 
 
+@node Ordinary number types
 @chapter Ordinary number types
 
 CLN implements the following class hierarchy:
@@ -507,6 +662,14 @@ The class @code{cl_F} implements floating-point approximations to real numbers.
 It is an abstract class.
 
 
+@menu
+* Exact numbers::               
+* Floating-point numbers::      
+* Complex numbers::             
+* Conversions::                 
+@end menu
+
+@node Exact numbers
 @section Exact numbers
 @cindex exact number
 
@@ -538,6 +701,7 @@ allocation. Otherwise the distinction between these immediate integers
 is completely transparent.
 
 
+@node Floating-point numbers
 @section Floating-point numbers
 @cindex floating-point number
 
@@ -621,6 +785,7 @@ but such declarations are missing for the types @code{cl_SF}, @code{cl_FF},
 the floating point contagion rule happened to change in the future.)
 
 
+@node Complex numbers
 @section Complex numbers
 @cindex complex number
 
@@ -633,6 +798,7 @@ Complex numbers can arise from real numbers alone, for example
 through application of @code{sqrt} or transcendental functions.
 
 
+@node Conversions
 @section Conversions
 @cindex conversion
 
@@ -745,6 +911,7 @@ Example:
 @end example
 
 
+@node Functions on numbers
 @chapter Functions on numbers
 
 Each of the number classes declares its mathematical operations in the
@@ -752,17 +919,43 @@ corresponding include file. For example, if your code operates with
 objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
 
 
+@menu
+* Constructing numbers::        
+* Elementary functions::        
+* Elementary rational functions::  
+* Elementary complex functions::  
+* Comparisons::                 
+* Rounding functions::          
+* Roots::                       
+* Transcendental functions::    
+* Functions on integers::       
+* Functions on floating-point numbers::  
+* Conversion functions::        
+* Random number generators::    
+* Obfuscating operators::       
+@end menu
+
+@node Constructing numbers
 @section Constructing numbers
 
 Here is how to create number objects ``from nothing''.
 
 
+@menu
+* Constructing integers::       
+* Constructing rational numbers::  
+* Constructing floating-point numbers::  
+* Constructing complex numbers::  
+@end menu
+
+@node Constructing integers
 @subsection Constructing integers
 
 @code{cl_I} objects are most easily constructed from C integers and from
 strings. See @ref{Conversions}.
 
 
+@node Constructing rational numbers
 @subsection Constructing rational numbers
 
 @code{cl_RA} objects can be constructed from strings. The syntax
@@ -771,6 +964,7 @@ Another standard way to produce a rational number is through application
 of @samp{operator /} or @samp{recip} on integers.
 
 
+@node Constructing floating-point numbers
 @subsection Constructing floating-point numbers
 
 @code{cl_F} objects with low precision are most easily constructed from
@@ -796,6 +990,7 @@ and then apply the exponential function:
 @end example
 
 
+@node Constructing complex numbers
 @subsection Constructing complex numbers
 
 Non-real @code{cl_N} objects are normally constructed through the function
@@ -805,6 +1000,7 @@ Non-real @code{cl_N} objects are normally constructed through the function
 See @ref{Elementary complex functions}.
 
 
+@node Elementary functions
 @section Elementary functions
 
 Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
@@ -913,6 +1109,7 @@ This is defined as @code{x / abs(x)} if @code{x} is non-zero, and
 @end table
 
 
+@node Elementary rational functions
 @section Elementary rational functions
 
 Each of the classes @code{cl_RA}, @code{cl_I} defines the following operations:
@@ -931,6 +1128,7 @@ The numerator and denominator of a rational number are normalized in such
 a way that they have no factor in common and the denominator is positive.
 
 
+@node Elementary complex functions
 @section Elementary complex functions
 
 The class @code{cl_N} defines the following operation:
@@ -968,6 +1166,7 @@ We have the relations
 @end itemize
 
 
+@node Comparisons
 @section Comparisons
 @cindex comparison
 
@@ -1038,6 +1237,7 @@ For example, @code{(cl_F)(cl_R)"1/3" == (cl_R)"1/3"} returns false because
 there is no floating point number whose value is exactly @code{1/3}.
 
 
+@node Rounding functions
 @section Rounding functions
 @cindex rounding
 
@@ -1257,6 +1457,7 @@ The classes @code{cl_R}, @code{cl_I} define the following operations:
 @end table
 
 
+@node Roots
 @section Roots
 
 Each of the classes @code{cl_R},
@@ -1319,6 +1520,7 @@ The result is an exact number only if @code{z} is an exact number.
 @end table
 
 
+@node Transcendental functions
 @section Transcendental functions
 @cindex transcendental functions
 
@@ -1328,6 +1530,15 @@ inexact numbers even if the argument is exact.
 For example, @code{cos(0) = 1} returns the rational number @code{1}.
 
 
+@menu
+* Exponential and logarithmic functions::  
+* Trigonometric functions::     
+* Hyperbolic functions::        
+* Euler gamma::                 
+* Riemann zeta::                
+@end menu
+
+@node Exponential and logarithmic functions
 @subsection Exponential and logarithmic functions
 
 @table @code
@@ -1388,6 +1599,7 @@ Returns e as a float of format @code{default_float_format}.
 @end table
 
 
+@node Trigonometric functions
 @subsection Trigonometric functions
 
 @table @code
@@ -1504,6 +1716,7 @@ Returns pi as a float of format @code{default_float_format}.
 @end table
 
 
+@node Hyperbolic functions
 @subsection Hyperbolic functions
 
 @table @code
@@ -1645,6 +1858,7 @@ Proof: Write z = x+iy. Examine
 @end table
 
 
+@node Euler gamma
 @subsection Euler gamma
 @cindex Euler's constant
 
@@ -1678,6 +1892,7 @@ Returns Catalan's constant as a float of format @code{default_float_format}.
 @end table
 
 
+@node Riemann zeta
 @subsection Riemann zeta
 @cindex Riemann's zeta
 
@@ -1698,8 +1913,16 @@ Returns Riemann's zeta function at @code{s} as a float of format
 @end table
 
 
+@node Functions on integers
 @section Functions on integers
 
+@menu
+* Logical functions::           
+* Number theoretic functions::  
+* Combinatorial functions::     
+@end menu
+
+@node Logical functions
 @subsection Logical functions
 
 Integers, when viewed as in two's complement notation, can be thought as
@@ -1920,6 +2143,7 @@ If @code{x} = 2^(n-1), it returns n. Else it returns 0.
 @end table
 
 
+@node Number theoretic functions
 @subsection Number theoretic functions
 
 @table @code
@@ -1977,6 +2201,7 @@ Returns the smallest probable prime >=@code{x}.
 @end table
 
 
+@node Combinatorial functions
 @subsection Combinatorial functions
 
 @table @code
@@ -2005,6 +2230,7 @@ for 0 <= k <= n, 0 else.
 @end table
 
 
+@node Functions on floating-point numbers
 @section Functions on floating-point numbers
 
 Recall that a floating-point number consists of a sign @code{s}, an
@@ -2111,9 +2337,16 @@ zero, it is treated as positive. Same for @code{y}.
 @end table
 
 
+@node Conversion functions
 @section Conversion functions
 @cindex conversion
 
+@menu
+* Conversion to floating-point numbers::  
+* Conversion to rational numbers::  
+@end menu
+
+@node Conversion to floating-point numbers
 @subsection Conversion to floating-point numbers
 
 The type @code{float_format_t} describes a floating-point format.
@@ -2183,6 +2416,7 @@ Returns the smallest floating point number e > 0 such that @code{1-e != 1}.
 @end table
 
 
+@node Conversion to rational numbers
 @subsection Conversion to rational numbers
 
 Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_F}
@@ -2219,6 +2453,7 @@ If @code{x} is any float, one has
 @end itemize
 
 
+@node Random number generators
 @section Random number generators
 
 
@@ -2267,6 +2502,7 @@ if @code{n} is a float.
 @end table
 
 
+@node Obfuscating operators
 @section Obfuscating operators
 @cindex modifying operators
 
@@ -2339,9 +2575,17 @@ In CLN @samp{x += y;} is exactly the same as  @samp{x = x+y;}, not more
 efficient.
 
 
+@node Input/Output
 @chapter Input/Output
 @cindex Input/Output
 
+@menu
+* Internal and printed representation::  
+* Input functions::             
+* Output functions::            
+@end menu
+
+@node Internal and printed representation
 @section Internal and printed representation
 @cindex representation
 
@@ -2416,6 +2660,7 @@ In Common Lisp notation: @code{#C(@var{realpart} @var{imagpart})}.
 @end table
 
 
+@node Input functions
 @section Input functions
 
 Including @code{<cln/io.h>} defines a number of simple input functions
@@ -2512,6 +2757,7 @@ precision corresponding to their number of significant digits.
 @end table
 
 
+@node Output functions
 @section Output functions
 
 Including @code{<cln/io.h>} defines a number of simple output functions
@@ -2603,6 +2849,7 @@ The global variable @code{default_print_flags} contains the default values,
 used by the function @code{fprint}.
 
 
+@node Rings
 @chapter Rings
 
 CLN has a class of abstract rings.
@@ -2679,9 +2926,16 @@ Tests whether the given number is an element of the number ring R.
 @end table
 
 
+@node Modular integers
 @chapter Modular integers
 @cindex modular integer
 
+@menu
+* Modular integer rings::       
+* Functions on modular integers::  
+@end menu
+
+@node Modular integer rings
 @section Modular integer rings
 @cindex ring
 
@@ -2741,6 +2995,7 @@ to @code{find_modint_ring} with the same argument necessarily return the
 same ring because it is memoized in the cache table.
 @end table
 
+@node Functions on modular integers
 @section Functions on modular integers
 
 Given a modular integer ring @code{R}, the following members can be used.
@@ -2855,11 +3110,18 @@ on the global printer settings in the variable @code{default_print_flags}.
 @end table
 
 
+@node Symbolic data types
 @chapter Symbolic data types
 @cindex symbolic type
 
 CLN implements two symbolic (non-numeric) data types: strings and symbols.
 
+@menu
+* Strings::                     
+* Symbols::                     
+@end menu
+
+@node Strings
 @section Strings
 @cindex string
 @cindex @code{cl_string}
@@ -2908,6 +3170,7 @@ Compares two strings for equality. One of the arguments may also be a
 plain @code{const char *}.
 @end table
 
+@node Symbols
 @section Symbols
 @cindex symbol
 @cindex @code{cl_symbol}
@@ -2939,10 +3202,18 @@ Compares two symbols for equality. This is very fast.
 @end table
 
 
+@node Univariate polynomials
 @chapter Univariate polynomials
 @cindex polynomial
 @cindex univariate polynomial
 
+@menu
+* Univariate polynomial rings::  
+* Functions on univariate polynomials::  
+* Special polynomials::         
+@end menu
+
+@node Univariate polynomial rings
 @section Univariate polynomial rings
 
 CLN implements univariate polynomials (polynomials in one variable) over an
@@ -3051,6 +3322,7 @@ These functions are equivalent to the general @code{find_univpoly_ring},
 only the return type is more specific, according to the base ring's type.
 @end table
 
+@node Functions on univariate polynomials
 @section Functions on univariate polynomials
 
 Given a univariate polynomial ring @code{R}, the following members can be used.
@@ -3182,6 +3454,7 @@ depend on the global printer settings in the variable
 @code{default_print_flags}.
 @end table
 
+@node Special polynomials
 @section Special polynomials
 
 The following functions return special polynomials.
@@ -3213,8 +3486,17 @@ of these polynomials from their definition can be found in the
 @code{doc/polynomial/} directory.
 
 
+@node Internals
 @chapter Internals
 
+@menu
+* Why C++ ?::                   
+* Memory efficiency::           
+* Speed efficiency::            
+* Garbage collection::          
+@end menu
+
+@node Why C++ ?
 @section Why C++ ?
 @cindex advocacy
 
@@ -3252,6 +3534,7 @@ debugged. No need to rewrite it in a low-level language after having prototyped
 in a high-level language.
 
 
+@node Memory efficiency
 @section Memory efficiency
 
 In order to save memory allocations, CLN implements:
@@ -3275,6 +3558,7 @@ on the heap.
 @end itemize
 
 
+@node Speed efficiency
 @section Speed efficiency
 
 Speed efficiency is obtained by the combination of the following tricks
@@ -3320,6 +3604,7 @@ of division and radix conversion.
 @end itemize
 
 
+@node Garbage collection
 @section Garbage collection
 @cindex garbage collection
 
@@ -3337,6 +3622,7 @@ resized. The effect of this strategy is that recently used rings remain
 cached, whereas undue memory consumption through cached rings is avoided.
 
 
+@node Using the library
 @chapter Using the library
 
 For the following discussion, we will assume that you have installed
@@ -3346,6 +3632,15 @@ For example, for me it's @code{CLN_DIR="$HOME/cln"} and
 environment variables, or directly substitute the appropriate values.
 
 
+@menu
+* Compiler options::            
+* Include files::               
+* An Example::                  
+* Debugging support::           
+* Reporting Problems::          
+@end menu
+
+@node Compiler options
 @section Compiler options
 @cindex compiler options
 
@@ -3398,6 +3693,7 @@ PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}], [],
 @end example
 
 
+@node Include files
 @section Include files
 @cindex include files
 @cindex header files
@@ -3528,6 +3824,7 @@ Includes all of the above.
 @end table
 
 
+@node An Example
 @section An Example
 
 A function which computes the nth Fibonacci number can be written as follows.
@@ -3598,6 +3895,7 @@ gets passed to the caller.
 The file @code{fibonacci.cc} in the subdirectory @code{examples}
 contains this implementation together with an even faster algorithm.
 
+@node Debugging support
 @section Debugging support
 @cindex debugging
 
@@ -3668,6 +3966,7 @@ $7 = @{<cl_gcpointer> = @{ = @{pointer = 0x8055b60, heappointer = 0x8055b60,
 Unfortunately, this feature does not seem to work under all circumstances.
 @end itemize
 
+@node Reporting Problems
 @section Reporting Problems
 @cindex bugreports
 @cindex mailing list
@@ -3682,9 +3981,18 @@ expect will help us to reproduce it quickly. Finally, do not forget to
 report the version number of CLN.
 
 
+@node Customizing
 @chapter Customizing
 @cindex customizing
 
+@menu
+* Error handling::              
+* Floating-point underflow::    
+* Customizing I/O::             
+* Customizing the memory allocator::  
+@end menu
+
+@node Error handling
 @section Error handling
 @cindex exception
 @cindex error handling
@@ -3719,6 +4027,7 @@ declared in the public header files and they are all subclasses of the
 above exceptions, so catching those you are always on the safe side.
 
 
+@node Floating-point underflow
 @section Floating-point underflow
 @cindex underflow
 
@@ -3737,6 +4046,7 @@ zero will be generated instead.  The default value of
 @code{cl_inhibit_floating_point_underflow} is @code{false}.
 
 
+@node Customizing I/O
 @section Customizing I/O
 
 The output of the function @code{fprint} may be customized by changing the
@@ -3744,6 +4054,7 @@ value of the global variable @code{default_print_flags}.
 @cindex @code{default_print_flags}
 
 
+@node Customizing the memory allocator
 @section Customizing the memory allocator
 
 Every memory allocation of CLN is done through the function pointer
@@ -3774,6 +4085,7 @@ global variables.
 
 @c Indices
 
+@node Index,  , Customizing, Top
 @unnumbered Index
 
 @printindex my