@@@ much mess, mostly manpages

[mLib] / struct / sym.3.in

diff --git a/struct/sym.3 b/struct/sym.3.in
similarity index 79%
rename from struct/sym.3
rename to struct/sym.3.in
index a683e20..5961464 100644 (file)
--- a/struct/sym.3
+++ b/struct/sym.3.in
@@ -1,41 +1,52 @@
 .\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.ie t \{\
-.  de VP
-.    sp .4v
-..
-\}
-.el \{\
-.  de VP
-.    sp
-..
-\}
-.TH sym 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-sym \- symbol table manager
+.\"
+.\" Manual for symbol table
+.\"
+.\" (c) 1999, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the mLib utilities library.
+.\"
+.\" mLib is free software: you can redistribute it and/or modify it under
+.\" the terms of the GNU Library General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or (at
+.\" your option) any later version.
+.\"
+.\" mLib is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+.\" License for more details.
+.\"
+.\" You should have received a copy of the GNU Library General Public
+.\" License along with mLib.  If not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
+.\" USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH sym 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
 .\" @sym_create
 .\" @sym_destroy
 .\" @sym_find
 .\" @sym_remove
 .\" @sym_mkiter
 .\" @sym_next
-.\"
+.
 .\" @SYM_NAME
 .\" @SYM_LEN
 .\" @SYM_HASH
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+sym \- symbol table manager
+.
+.\"--------------------------------------------------------------------------
 .SH SYNOPSIS
+.
 .nf
 .B "#include <mLib/sym.h>"
 .PP
@@ -59,7 +70,10 @@ sym \- symbol table manager
 .BI "void sym_mkiter(sym_iter *" i ", sym_table *" t );
 .BI "void *sym_next(sym_iter *" i );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH "DESCRIPTION"
+.
 The
 .B sym
 functions implement a data structure often described as a dictionary, a
@@ -95,6 +109,7 @@ All of the above data structures should be considered
 .IR opaque :
 don't try looking inside.  Representations have changed in the past, and
 they may change again in the future.
+.
 .SS "Creation and destruction"
 The
 .B sym_table
@@ -113,6 +128,7 @@ values and other maintenance structures can be reclaimed by calling
 .BR sym_destroy .
 Any bits of user data attached to values should previously have been
 destroyed.
+.
 .SS "Adding, searching and removing"
 Most of the actual work is done by the function
 .BR sym_find .
@@ -160,6 +176,7 @@ A symbol can be removed from the table by calling
 .BR sym_remove ,
 passing the symbol table itself, and the value block that needs
 removing.
+.
 .SS "Enquiries about symbols"
 Three macros are provided to enable simple enquiries about a symbol.
 Given a pointer
@@ -172,6 +189,7 @@ byte);
 returns a pointer to the symbol's name; and
 .BI SYM_HASH( s )
 returns the symbol's hash value.
+.
 .SS "Enumerating symbols"
 Enumerating the values in a symbol table is fairly simple.  Allocate a
 .B sym_iter
@@ -191,6 +209,7 @@ However, it's not safe to remove any other symbol.  So don't do that.
 .PP
 When you've finished with an iterator, it's safe to just throw it away.
 You don't need to call any functions beforehand.
+.
 .SS "Use in practice"
 In normal use, the keys are simple strings (usually identifiers from
 some language), and the values are nontrivial structures providing
@@ -242,6 +261,7 @@ for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; ) {
 }
 .VE
 That ought to be enough examples to be getting on with.
+.
 .SS Implementation
 The symbol table is an extensible hashtable, using the universal hash
 function described in
@@ -250,8 +270,16 @@ and the global hashing key.  The hash chains are kept very short
 (probably too short, actually).  Every time a symbol is found, its block
 is promoted to the front of its bin chain so it gets found faster next
 time.
+.
+.\"--------------------------------------------------------------------------
 .SH SEE ALSO
+.
 .BR hash (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH AUTHOR
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------