@@@ much mess, mostly manpages

[mLib] / buf / lbuf.3.in

diff --git a/buf/lbuf.3 b/buf/lbuf.3.in
similarity index 82%
rename from buf/lbuf.3
rename to buf/lbuf.3.in
index 001dc9a152417507d16f9ab4c86078ed57d11acf..ac445d13e4ea6105ba9458b65a1c7c38c8caa52b 100644 (file)
--- a/buf/lbuf.3
+++ b/buf/lbuf.3.in
@@ -1,15 +1,48 @@
 .\" -*-nroff-*-
-.TH lbuf 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-lbuf \- split lines out of asynchronously received blocks
-.\" @lbuf_flush
+.\"
+.\" Manual for line buffering
+.\"
+.\" (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 lbuf 3mLib "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
 .\" @lbuf_close
 .\" @lbuf_free
 .\" @lbuf_snarf
 .\" @lbuf_setsize
 .\" @lbuf_init
 .\" @lbuf_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+lbuf \- split lines out of asynchronously received blocks
+.
+.\"--------------------------------------------------------------------------
 .SH "SYNOPSIS"
+.
 .nf
 .ta 2n
 .B "#include <mLib/lbuf.h>"
@@ -29,6 +62,7 @@ lbuf \- split lines out of asynchronously received blocks
 .B "typedef void lbuf_func(char *" s ", size_t " len ", void *" p );
 .PP
 .BI "void lbuf_flush(lbuf *" b ", char *" p ", size_t " len );
+.\" @lbuf_flush
 .BI "void lbuf_close(lbuf *" b );
 .BI "size_t lbuf_free(lbuf *" b ", char **" p );
 .BI "void lbuf_snarf(lbuf *" b ", const void *" p ", size_t " sz );
@@ -36,7 +70,10 @@ lbuf \- split lines out of asynchronously received blocks
 .BI "void lbuf_init(lbuf *" b ", lbuf_func *" func ", void *" p );
 .BI "void lbuf_destroy(lbuf *" b );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH "DESCRIPTION"
+.
 The declarations in
 .B <mLib/lbuf.h>
 implement a handy object called a
@@ -54,6 +91,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 lbuf_init
@@ -91,6 +129,7 @@ unallocated.
 A line buffer must be destroyed after use by calling
 .BR lbuf_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.
@@ -153,6 +192,7 @@ The
 function is trivially implemented in terms of the more complex
 .BR lbuf_free / lbuf_flush
 interface.
+.
 .SS "Line breaking"
 By default, the line buffer considers a line to end with either a simple
 linefeed character (the normal Unix convention) or a
@@ -174,6 +214,7 @@ stream of data containing no newline markers, wasting the server's
 memory.  Instead, the buffer will truncate overly long lines (silently)
 and return only the initial portion.  It will ignore the rest of the
 line completely.
+.
 .SS "Line-handler functions"
 Completed lines, as already said, are passed to the caller's
 line-handler function.  It is given three arguments: the address
@@ -194,6 +235,7 @@ The line pointer argument
 may be null to signify end-of-file; in this case, the length
 .I len
 will be zero.  See the next section.
+.
 .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
@@ -204,6 +246,7 @@ terminated) line.  This will pass the remaining text to the line
 handler, if there is any, and then call the handler one final time with
 a null pointer rather than the address of a text line to inform it of
 the end-of-file.
+.
 .SS "Disablement"
 The line buffer is intended to be used in higher-level program objects,
 such as the buffer selector described in
@@ -243,8 +286,16 @@ 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 lbuf_free / lbuf_flush .
+.
+.\"--------------------------------------------------------------------------
 .SH "SEE ALSO"
+.
 .BR selbuf (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH "AUTHOR"
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------