@@@ much mess, mostly manpages

[mLib] / utils / exc.3.in

diff --git a/utils/exc.3 b/utils/exc.3.in
similarity index 77%
rename from utils/exc.3
rename to utils/exc.3.in
index 92b65c3..c37c1d6 100644 (file)
--- a/utils/exc.3
+++ b/utils/exc.3.in
@@ -1,51 +1,70 @@
 .\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.TH exc 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-exc \- exception handling for C programs
+.\"
+.\" Manual for exception handling
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 exc 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
 .\" @TRY
 .\" @CATCH
 .\" @END_TRY
 .\" @THROW
 .\" @RETHROW
-.\"
+.
 .\" @exc_uncaught
-.\"
+.
 .\" @EXC_PAIR
 .\" @EXC_ALLOC
 .\" @EXC_ALLOCN
 .\" @EXC_ALLOCI
 .\" @EXC_ALLOCP
 .\" @EXC_ALLOCS
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+exc \- exception handling for C programs
+.
+.\"--------------------------------------------------------------------------
 .SH SYNOPSIS
+.
+.nf
 .B "#include <mLib/exc.h>"
-.sp 1
+.PP
+.ta 2n
 .B TRY
-.I statement
+.I "   statement"
 .B CATCH
-.I statement
+.I "   statement"
 .B END_TRY;
-.br
 .B EXIT_TRY;
-.sp 1
-.BI "THROW(exc_extype " type
-.RB [ ,
-.IR data ]\fB);
-.br
+.PP
+.BI "THROW(exc_extype " type " " "" \fR[ "" ", "data \fR] "" );
 .B RETHROW;
-.sp 1
+.PP
 .nf
 .B "typedef void (*exc__uncaught)(exc_extype, exc_exval);"
 .BI "exc__uncaught exc_uncaught(exc__uncaught " proc );
@@ -57,7 +76,10 @@ exc \- exception handling for C programs
 .BI "exc_extype EXC_ALLOCP(exc_extype " owner ", exc_extype " type );
 .BI "exc_extype EXC_ALLOCS(exc_extype " owner ", exc_extype " type );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH DESCRIPTION
+.
 The header file
 .B <mLib/exc.h>
 introduces some new syntax and definitions to support exception handling
@@ -75,6 +97,7 @@ and
 It's unfortunately important to remember that the syntax is provided
 using macro expansion and standard C facilities; some of the
 restrictions of these features show through.
+.
 .SS "The TRY statement"
 The
 .B TRY
@@ -115,6 +138,7 @@ and
 which refer to members of
 .B exc_val
 directly.
+.
 .SS "The EXIT_TRY statement"
 It is not safe to leave the dynamic scope of an exception handler early
 (e.g., by a
@@ -126,6 +150,7 @@ statement from within the
 scope of the
 .B TRY
 statement.
+.
 .SS "The THROW and RETHROW statements"
 The
 .B THROW
@@ -147,6 +172,7 @@ Neither
 nor
 .B RETHROW
 yields any value.
+.
 .SS "Exception type allocation"
 Exception types are 32-bit values.  The top 16 bits are an
 .IR "owner identifier" .
@@ -229,6 +255,7 @@ macros take two arguments: the owner code (usually allocated with
 .B EXC_PAIR
 as described above), and the type code.  The data type is encoded into
 the exception type by the allocation macro.
+.
 .SS "Predefined exceptions"
 The following exceptions are predefined:
 .TP
@@ -261,7 +288,15 @@ Therefore all the caveats about
 and automatic data apply.  Also, note that status such as the signal
 mask is not reset, so you might have to do that manually in order to
 recover from a signal.
+.
+.\"--------------------------------------------------------------------------
 .SH "SEE ALSO"
+.
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH AUTHOR
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------