@@@ much mess, mostly manpages

[mLib] / ui / mdwopt.3.in

diff --git a/ui/mdwopt.3 b/ui/mdwopt.3.in
similarity index 87%
rename from ui/mdwopt.3
rename to ui/mdwopt.3.in
index 9b87323..8f01f8f 100644 (file)
--- a/ui/mdwopt.3
+++ b/ui/mdwopt.3.in
@@ -1,9 +1,43 @@
 .\" -*-nroff-*-
-.TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for option parsing
+.\"
+.\" (c) 1999, 2001, 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 mdwopt 3mLib "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @mdwopt
+.
+.\"--------------------------------------------------------------------------
 .SH "NAME"
 mdwopt \- command-line option parser
-.\" @mdwopt
+.
+.\"--------------------------------------------------------------------------
 .SH "SYNOPSIS"
+.
 .nf
 .B "#include <mLib/mdwopt.h>"
 .PP
@@ -59,7 +93,10 @@ mdwopt \- command-line option parser
 .BI "  const char * "shortopt ,
 .BI "  const struct option *" longopt ", int *" longind );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH "OVERVIEW"
+.
 The
 .B mdwopt
 function is a command line options parser which is (mostly) compatible
@@ -68,7 +105,10 @@ with the standard POSIX and GNU
 functions, although provides more features than either.  It's not the
 most featureful options parser around, but it's good enough for my
 purposes at the moment.
+.
+.\"--------------------------------------------------------------------------
 .SH "OPTION SYNTAX"
+.
 A command line consists of a number of
 .I words
 (which may contain spaces, according to various shell quoting
@@ -102,6 +142,7 @@ and
 .IR long .
 Traditional Unix (and POSIX) only uses short options.  The long options
 are a GNU convention.
+.
 .SS "Short option syntax"
 Short options are the sort which Unix has known for ages: an option is a
 single letter, preceded by a
@@ -128,6 +169,7 @@ instead of a
 .RB ` \- '
 to introduce the option.  (Some programs use upper-case option letters
 to indicate this instead.)
+.
 .SS "Long option syntax"
 Long options, as popularized by the GNU utilities, are given long-ish
 memorable names, preceded by a double-dash
@@ -158,12 +200,16 @@ single
 character, and negated by a
 .RB ` + '
 character.
+.
 .SS "Numerical options"
 Finally, some (older) programs accept arguments of the form
 .RB ` \- \c
 .IR number ',
 to set some numerical parameter, typically a line count of some kind.
+.
+.\"--------------------------------------------------------------------------
 .SH "PARSING OPTIONS WITH \fBmdwopt\fP"
+.
 An application parses its options by calling
 .B mdwopt
 repeatedly.  Each time it is called,
@@ -220,6 +266,7 @@ describe the command-line argument array which is to be parsed.  These
 will usually be exactly the arguments passed to the program's
 .B main
 function.
+.
 .SS "Short option parsing"
 Short options are described by a string,
 .IR shortopt ,
@@ -289,6 +336,7 @@ argument.  If a negated option was found, the option character is
 returned ORed with
 .B OPTF_NEGATED
 (bit 8 set).
+.
 .SS "Long option parsing"
 Long options are described in a table.  Each entry in the
 table is of type
@@ -368,6 +416,7 @@ negated.
 Arguments from long options are stored in the
 .B arg
 member of the data block.
+.
 .SS "Other optional features"
 The
 .I flags
@@ -423,6 +472,7 @@ rather than a
 .RB ` \- '.
 The return value is
 .RB ` # ' " | OPTF_NEGATED" .
+.
 .SS "Compatibility features"
 The macros
 .BR getopt ,
@@ -463,8 +513,16 @@ These names aren't considered deprecated: they help make the code easier
 to read by people used to the traditional
 .B getopt
 function.
+.
+.\"--------------------------------------------------------------------------
 .SH "SEE ALSO"
+.
 .BR getopt (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH "AUTHOR"
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------