intcmp(1): new tool; npc(1): new tool; scrut(1): new tool; str(1): new tool; strcmp(1): new tool; tests: added POSIX compatibility test and C compiler compatibility test; Makefile: converted to GNUmakefile; README: added README; docs: added docs

docs/intcmp.1

@@ -0,0 +1,78 @@
+.\" Copyright (c) 2023 DTB <trinity@trinity.moe>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+.\"
+.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
+.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
+
+.TH intcmp 1
+
+.SH NAME
+
+intcmp \(en compare integers
+
+.SH SYNOPSIS
+
+intcmp
+.RB ( -eghl )
+.RB [ integer ]
+.RB [ integer... ]
+
+.SH DESCRIPTION
+
+Intcmp compares integers.
+
+.SH USAGE
+
+The -e option permits given integers to be equal to each other. If combined
+with -g or -l, only adjacent integers in the argument sequence can be equal.
+.PP
+The -g option permits a given integer to be greater than the following integer.
+.PP
+The -l option permits a given integer to be less than the following integer.
+.PP
+It may help to think of the -e, -g, and -l options as equivalent to the
+infix algebraic “=”, “>”, and “<” operators respectively, with each option
+putting its symbol between every given integer. For example,
+.R intcmp -l 1 2 3
+is equivalent to evaluating "1 < 2 < 3".
+
+.SH DIAGNOSTICS
+
+Intcmp exits 0 for a valid expression and 1 for an invalid expression.
+.PP
+Intcmp prints a debug message and exits with the appropriate sysexits(3) error
+code in the event of an error.
+
+.SH BUGS
+
+There are multiple ways to express compound comparisons; “less than or equal
+to” can be -le or -el, for example.
+.PP
+The inequality comparison is -gl or -lg for “less than or greater than”; this
+is elegant but unintuitive.
+.PP
+-egl, "equal to or less than or greater than", exits 0 no matter what for valid
+program usage and may be abused to function as an integer validator.
+Use str(1) instead.
+
+.SH RATIONALE
+
+The traditional tool for integer comparisons in POSIX and other Unix shells has
+been test(1). This tool also handles string comparisons and file scrutiny.
+These parts of its functionality have been broken out into multiple utilities.
+
+Strcmp’s functionality may be performed on a POSIX-compliant system with
+test(1p).
+
+.SH AUTHOR
+
+Written by DTB <trinity@trinity.moe>.
+
+.SH COPYRIGHT
+
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/gpl.html>.
+
+.SH SEE ALSO
+
+strcmp(1), scrut(1), str(1), test(1)