Clean up terminology and clarify a few things. Add a simple example.

crypto/dist/heimdal/lib/com_err/compile_et.1

@@ -1,4 +1,4 @@
-.\"     $NetBSD: compile_et.1,v 1.2 2001/11/10 08:16:45 wiz Exp $
+.\"     $NetBSD: compile_et.1,v 1.3 2001/11/21 05:36:33 gmcgarry Exp $
 .\"
 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -59,10 +59,12 @@ must end with a suffix of
 .Dq .et
 and
 .Nm
-writes the tables to the files
+writes a C header file
+.Pa file.h
+which contains definitions of the numerical values of the error codes
+defined in the error table and a C source file
 .Pa file.c
-and
-.Pa file.h .
+which should be compiled and linked with the executable.
 .Pp
 The source file is a plain ASCII text file.  A
 .Dq \&#
@@ -79,16 +81,16 @@ first declaration in the source file.
 Specifies the name of the error table to be
 .Em name .
 It is mandatory and must be declared after the id declaration and
-before all other declarations.  The optional argument
+before all other declarations.  The name of table is limited to four
+ASCII characters.  The optional argument
 .Em base
-specifies the base of the error table.
+specifies the base value of error codes the table.
 .Pp
 The name of the table is used to construct the name of a function
 .Fn initialize_<name>_error_table
-which must be called in order for the
+which must be called to register the error table the the
 .Xr com_err 3
-library to recognize the error table.  A re-entrant (thread-safe)
-version called
+library.  A re-entrant (thread-safe) version called
 .Fn initialize_<name>_error_table_r
 is also defined.
 .It prefix Op Em string
@@ -108,9 +110,42 @@ and its associated error message
 .Em msg .
 The error codes are assigned sequentially increasing numbers.  The
 name is placed into the C header file as an enumerated type.
+.It end
+Indicates the end of the error table.
 .El
 .Pp
 To maintain compatibility, new codes should be added to the end of an
 existing table, and codes should not be removed from tables.
+.Sh EXAMPLE
+A short sample error table might be
+.Pa test_err.et :
+.Pp
+.Bd -literal
+	# example error table source file
+	id	"\\$Id\\$"
+	et	test
+	prefix	TEST
+	ec	PERM,		"Operation not permitted"
+	ec	IO,		"I/O error"
+	ec	NOMEM,		"Out of memory"
+	ec	INVAL,		"Invalid argument"
+	end
+.Ed
+.Pp
+Compilation the source file
+.Pa test_err.et
+with
+.Nm
+will create a C header file
+.Pa test_err.h
+containing the enumerated type
+.Va test_error_number
+with values TEST_PERM, TEST_IO, TEST_NOMEM and
+TEST_INVAL, and a C source file
+.Pa test_err.c
+containing the
+.Xr com_err 3
+initialisation function
+.Fn initialize_test_error_table .
 .Sh SEE ALSO
 .Xr com_err 3