com_err.texinfo: Add appropriate @node and @menu lines so that

	the a valid .info file can be made.  Use @deftypefun to
	define functions.  Change the e-mail address where bug
	reports to be sent to be is the e2fsprogs maintainer.

diff --git a/lib/et/ChangeLog b/lib/et/ChangeLog
index 28d6650..c1104a3 100644 (file)
--- a/lib/et/ChangeLog
+++ b/lib/et/ChangeLog
@@ -1,3 +1,10 @@
+2001-09-10  Theodore Tso  <tytso@valinux.com>
+
+       * com_err.texinfo: Add appropriate @node and @menu lines so that
+               the a valid .info file can be made.  Use @deftypefun to
+               define functions.  Change the e-mail address where bug
+               reports to be sent to be is the e2fsprogs maintainer.
+
 2001-09-02  Theodore Tso  <tytso@thunk.org>
 
        * Release of E2fsprogs 1.24a

diff --git a/lib/et/com_err.texinfo b/lib/et/com_err.texinfo
index 2f4b266..3914b09 100644 (file)
--- a/lib/et/com_err.texinfo
+++ b/lib/et/com_err.texinfo
@@ -51,8 +51,6 @@ Note that the file texinfo.tex, provided with this distribution, is from
 the Free Software Foundation, and is under different copyright restrictions
 from the remainder of this package.
 
-@end ifinfo
-
 @ignore
 Permission is granted to process this file through Tex and print the
 results, provided the printed document carries copying permission
@@ -113,12 +111,30 @@ from the remainder of this package.
 
 @end titlepage
 
-@ifinfo
-@c should put a menu here someday....
+
+@node Top, Why com_err?, (dir), (dir)
+
+@top A Common Error Description Library for UNIX
+
+This manual documents the com_err library.
+
+@menu
+* Why com_err?::                
+* Error codes::                 
+* Error table source file::     
+* The error-table compiler::    
+* Run-time support routines::   
+* Coding Conventions::          
+* Building and Installation::   
+* Bug Reports::                 
+* Acknowledgements::            
+@end menu
+
 @end ifinfo
 
 @page
 
+@node Why com_err?, Error codes, Top, Top
 @section Why com_err?
 
 In building application software packages, a programmer often has to
@@ -154,6 +170,7 @@ error codes accidentally returned before making the table known, which is
 of the form @samp{unknown code foo 32}, where @samp{foo} would be the name
 of the table.
 
+@node Error codes, Error table source file, Why com_err?, Top
 @section Error codes
 
 Error codes themselves are 32 bit (signed) integers, of which the high
@@ -182,6 +199,7 @@ not support 32-bit @t{long} values cannot make use of this package (nor
 much other software that assumes an ANSI-C environment base) without
 significant effort.
 
+@node Error table source file, The error-table compiler, Error codes, Top
 @section Error table source file
 
 The error table source file begins with the declaration of the table name,
@@ -219,6 +237,7 @@ error table might be:
 
 @end example
 
+@node The error-table compiler, Run-time support routines, Error table source file, Top
 @section The error-table compiler
 
 The error table compiler is named @code{compile_et}.  It takes one
@@ -240,6 +259,7 @@ be extended to include some support for C++.  The default is currently
 @kbd{K&R-C}, though the generated sources will have ANSI-C code
 conditionalized on the symbol @t{__STDC__}.
 
+@node Run-time support routines, Coding Conventions, The error-table compiler, Top
 @section Run-time support routines
 
 Any source file which uses the routines supplied with or produced by the
@@ -276,9 +296,7 @@ specified table.
 This rarely needs be used by the
 programmer.
 
-@example
-const char *error_message (long code);
-@end example
+@deftypefun const char *error_message (long @var{code});
 
 This routine returns the character string error message associated
 with @code{code}; if this is associated with an unknown error table, or
@@ -291,56 +309,48 @@ by that error code, and @var{nn} is the offset from that base value.
 Although this routine is available for use when needed, its use should be
 left to circumstances which render @code{com_err} (below) unusable.
 
-@example
-void com_err (const char *whoami,  /* module reporting error */
-              long code,           /* error code */
-              const char *format,  /* format for additional detail */
-              ...);                /*  (extra parameters) */
-@end example
+@end deftypefun
+
+@deftypefun
+void com_err (const char *@var{whoami}, long @var{error_code},
+              const char *@var{format}, ...);             
 
 This routine provides an alternate way to print error messages to
 standard error; it allows the error message to be passed in as a
 parameter, rather than in an external variable.  @emph{Provide grammatical
 context for ``message.''}
 
+The module reporting the error should be passed in via @var{whoami}.
 If @var{format} is @code{(char *)NULL}, the formatted message will not be
 printed.  @var{format} may not be omitted.
 
-@example
-#include <stdarg.h>
+@end deftypefun
 
-void com_err_va (const char *whoami,
-                 long code,
-                 const char *format,
-                 va_list args);
-@end example
+@deftypefun
+void com_err_va (const char *@var{whoami}, long @var{error_code}, const char *@var{format}, va_list @var{args});
 
 This routine provides an interface, equivalent to @code{com_err} above,
 which may be used by higher-level variadic functions (functions which
 accept variable numbers of arguments).
 
-@example
-#include <stdarg.h>
+@end deftypefun
 
-void (*set_com_err_hook (void (*proc) ())) ();
+@deftypefun void (*set_com_err_hook (void (*@var{proc}) (const char *@var{whoami}, long @var{error_code}, va_list @var{args}))) (const char *@var{whoami}, long @var{error_code}, va_list @var{args});
 
-void (*@var{proc}) (const char *whoami, long code, va_list args);
-
-void reset_com_err_hook ();
-@end example
+@deftypefunx void reset_com_err_hook ();
 
 These two routines allow a routine to be dynamically substituted for
 @samp{com_err}.  After @samp{set_com_err_hook} has been called,
 calls to @samp{com_err} will turn into calls to the new hook routine.
 @samp{reset_com_err_hook} turns off this hook.  This may intended to
-be used in daemons (to use a routine which calls @var{syslog(3)}), or
+be used in daemons (to use a routine which calls @cite{syslog(3)}), or
 in a window system application (which could pop up a dialogue box).
 
 If a program is to be used in an environment in which simply printing
 messages to the @code{stderr} stream would be inappropriate (such as in a
 daemon program which runs without a terminal attached),
 @code{set_com_err_hook} may be used to redirect output from @code{com_err}.
-The following is an example of an error handler which uses @var{syslog(3)}
+The following is an example of an error handler which uses @cite{syslog(3)}
 as supplied in BSD 4.3:
 
 @example
@@ -382,6 +392,9 @@ consistency, @code{printf}-style interpretation is suggested, via
 @code{vsprintf} (or @code{_doprnt} on BSD systems without full support for
 the ANSI C library).
 
+@end deftypefun
+
+@node Coding Conventions, Building and Installation, Run-time support routines, Top
 @section Coding Conventions
 
 The following conventions are just some general stylistic conventions
@@ -492,6 +505,7 @@ error:
 @}
 @end example
 
+@node Building and Installation, Bug Reports, Coding Conventions, Top
 @section Building and Installation
 
 The distribution of this package will probably be done as a compressed
@@ -523,7 +537,7 @@ be used.
 
 @item If your linker rejects symbols that are simultaneously defined in two
 library files, edit @samp{Makefile} to remove @samp{perror.c} from the
-library.  This file contains a version of @var{perror(3)} which calls
+library.  This file contains a version of @cite{perror(3)} which calls
 @code{com_err} instead of calling @code{write} directly.
 
 @end itemize
@@ -533,11 +547,17 @@ bugs present that may interfere with building or using this package on
 other systems.  If they are reported to me, they can probably be fixed for
 the next version.
 
+@node Bug Reports, Acknowledgements, Building and Installation, Top
 @section Bug Reports
 
-Please send any comments or bug reports to the principal author: Ken
-Raeburn, @t{Raeburn@@Athena.MIT.EDU}.
+The principal author of this library is: Ken
+Raeburn, @t{raeburn@@MIT.EDU}.  
+
+This version of the com_err library is being maintained by Theodore
+Ts'o, and so bugs and comments should be sent to @t{tytso@@thunk.org}.
+
 
+@node Acknowledgements,  , Bug Reports, Top
 @section Acknowledgements
 
 I would like to thank: Bill Sommerfeld, for his help with some of this