@@@ much mess, mostly manpages

[mLib] / struct / assoc.3.in

diff --git a/struct/assoc.3 b/struct/assoc.3.in
similarity index 70%
rename from struct/assoc.3
rename to struct/assoc.3.in
index 9f65b8e..fb65ced 100644 (file)
--- a/struct/assoc.3
+++ b/struct/assoc.3.in
@@ -1,29 +1,50 @@
 .\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH assoc 3 "23 January 2001" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-assoc \- tables indexed by atoms
+.\"
+.\" Manual for association tables based on atoms
+.\"
+.\" (c) 2001, 2005, 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 assoc 3mLib "23 January 2001" "Straylight/Edgeware" "mLib utilities library"
 .\" @assoc_create
 .\" @assoc_destroy
 .\" @assoc_find
 .\" @assoc_remove
 .\" @assoc_mkiter
 .\" @assoc_next
-.\"
+.
 .\" @ASSOC_ATOM
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+assoc \- tables indexed by atoms
+.
+.\"--------------------------------------------------------------------------
 .SH SYNOPSIS
+.
 .nf
 .B "#include <mLib/assoc.h>"
 .PP
@@ -41,7 +62,10 @@ assoc \- tables indexed by atoms
 .BI "void assoc_mkiter(assoc_iter *" i ", assoc_table *" t );
 .BI "void *assoc_next(assoc_iter *" i );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH DESCRIPTION
+.
 An
 .I "association table"
 is a data structure which maps atoms (see
@@ -74,6 +98,7 @@ in the table
 All of the above structures should be considered
 .IR opaque :
 don't try looking inside.
+.
 .SS "Creation and destruction"
 The
 .B assoc_table
@@ -92,6 +117,7 @@ the values and other maintenance structures can be reclaimed by calling
 .BR assoc_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 assoc_find .
@@ -123,12 +149,14 @@ A symbol can be removed from the table by calling
 .BR assoc_remove ,
 passing the association table itself, and the value block that needs
 removing.
+.
 .SS "Enquiries about associations"
 Given a pointer
 .I a
 to an association, the expression
 .BI ASSOC_ATOM( a )
 has as its value a poinetr to the atom which is that association's key.
+.
 .SS "Enumerating associations"
 Enumerating the values in an association table is fairly simple.
 Allocate an
@@ -149,10 +177,18 @@ 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.
+.
+.\"--------------------------------------------------------------------------
 .SH SEE ALSO
+.
 .BR atom (3),
 .BR hash (3),
 .BR sym (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH AUTHOR
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------