@@@ much mess, mostly manpages

[mLib] / buf / pkbuf.3.in

diff --git a/buf/pkbuf.3 b/buf/pkbuf.3.in
similarity index 79%
rename from buf/pkbuf.3
rename to buf/pkbuf.3.in
index dd48a33..c50bb39 100644 (file)
--- a/buf/pkbuf.3
+++ b/buf/pkbuf.3.in
@@ -1,7 +1,34 @@
 .\" -*-nroff-*-
-.TH pkbuf 3 "16 July 2000" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-pkbuf \- split packets out of asynchronously received blocks
+.\"
+.\" Manual for packet splitting
+.\"
+.\" (c) 1999--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 pkbuf 3mLib "16 July 2000" "Straylight/Edgeware" "mLib utilities library"
 .\" @pkbuf_flush
 .\" @pkbuf_close
 .\" @pkbuf_free
@@ -9,7 +36,14 @@ pkbuf \- split packets out of asynchronously received blocks
 .\" @pkbuf_want
 .\" @pkbuf_init
 .\" @pkbuf_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+pkbuf \- split packets out of asynchronously received blocks
+.
+.\"--------------------------------------------------------------------------
 .SH "SYNOPSIS"
+.
 .nf
 .ta 2n
 .B "#include <mLib/pkbuf.h>"
@@ -35,7 +69,10 @@ pkbuf \- split packets out of asynchronously received blocks
 .BI "void pkbuf_init(pkbuf *" pk ", pkbuf_func *" func ", void *" p );
 .BI "void pkbuf_destroy(pkbuf *" pk );
 .fi
-.SH "DESCRIPTION"
+.
+.\"--------------------------------------------------------------------------
+SH "DESCRIPTION"
+.
 The declarations in
 .B <mLib/pkbuf.h>
 implement a
@@ -50,6 +87,7 @@ This is a structure which must be allocated by the caller.  The
 structure should normally be considered opaque (see the section on
 .B Disablement
 for an exception to this).
+.
 .SS "Initialization and finalization"
 The function
 .B pkbuf_init
@@ -82,6 +120,7 @@ unallocated.
 A packet buffer must be destroyed after use by calling
 .BR pkbuf_destroy ,
 passing it the address of the buffer block.
+.
 .SS "Inserting data into the buffer"
 There are two interfaces for inserting data into the buffer.  One's much
 simpler than the other, although it's less expressive.
@@ -144,6 +183,7 @@ The
 function is trivially implemented in terms of the more complex
 .BR pkbuf_free / pkbuf_flush
 interface.
+.
 .SS "Packet breaking and the handler function"
 The function
 .B pkbuf_want
@@ -178,6 +218,7 @@ move them into the right place.
 The pointer which was set up in the call to
 .BR pkbuf_init .
 .PP
+.
 .SS "Flushing the remaining data"
 When the client program knows that there's no more data arriving (for
 example, an end-of-file condition exists on its data source) it should
@@ -185,6 +226,7 @@ call the function
 .BR pkbuf_close .
 This will call the handler one final time with a null pointer to inform
 it of the end-of-file.
+.
 .SS "Disablement"
 The packet buffer is intended to be used in higher-level program
 objects, such as the packet selector described in
@@ -224,9 +266,17 @@ function does not handle disablement at all, because it would complicate
 the interface so much that it wouldn't have any advantage over the more
 general
 .BR pkbuf_free / pkbuf_flush .
+.
+.\"--------------------------------------------------------------------------
 .SH "SEE ALSO"
+.
 .BR lbuf (3),
 .BR selpk (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH "AUTHOR"
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------