CONDUCT

@@ -1,83 +0,0 @@
-Code of Conduct
-
-This Code of Conduct is derived from the 10 Pāramitās of Theravadin Buddhism.
-You can read more about them in Ṭhānissaro Bhikkhu’s Ten Perfections: A Study
-Guide [0].
-
-1. Generosity (Dāna)
-
-Give contributions freely and willingly under the terms of the GNU Affero
-General Public License, version 3 or later, or a compatible license.
-
-2. Ethics (Sīla)
-
-Do not use nonfree code or uncredited code in contributions. Do not contribute
-code of dubious origins, such as code generated by large language models or
-unlicensed snippets found online [1]. Do not take credit for others’
-contributions. Make sure to utilize the copyright header and license notice on
-source files to credit yourself and others for their work.
-
-3. Renunciation (Nekkhamma)
-
-Stay committed to the principles of simplicity and interoperability embodied by
-the project. Keep your personal will and desire out of the project, for it can
-only prove harmful to its success.
-
-4. Wisdom (Pañña)
-
-Look to established sources for standards, best practices, and important
-implementation details when setting new precedence. Follow the existing
-precedence where it applies.
-
-5. Energy (Viriya)
-
-Focus on the currently-open, currently-assigned, and currently-in-progress
-issues, pull requests, and other endeavors in order to keep yourself and others
-from being overwhelmed with responsibility, either from your zeal or your
-negligence.
-
-If you notice an issue, open an issue as soon as you can. If you see a neglected
-branch, open a pull request or comment on an existing one, if applicable. Be
-diligent in your commitment to making this project work.
-
-6. Patience (Khanti)
-
-Be patient with maintainers and other contributors. We all have our own lives
-going on and may need significant time to get to things.
-
-7. Truthfulness (Sacca)
-
-Communicate honestly and openly. Do not embellish facts to get your way. Make
-sure to let maintainers know about any issues along the way and keep ample
-communication channels open.
-
-8. Determination (Adhiṭṭhāna)
-
-Stay focused on long-term objectives and cultivate attainment to that
-achievement by utilizing to the fullest extent possible the tools available to
-you for managing the workload.
-
-9. Loving-Kindness (Mettā)
-
-Treat everyone with respect, even if they treat you poorly. This does not mean
-you have to put up with abuse, but make sure to respond with kindness and with
-love in your heart. Support and uplift maintainers and other contributors with
-your words and actions.
-
-Do not use angry or hateful language toward contributors, such as demeaning
-phrases and slurs. Make sure that if you do not know the pronouns of a
-contributor to ask for them and, in the meantime, use gender-neutral they/them
-or equivalent pronouns.
-
-10. Equanimity (Upekkhā)
-
-Keep a balanced perspective on all suggestions and contributions and make
-judgements not from a place of ego and personal preference but on their
-usefulness and suitability to the project. Make sure to keep an eye on the
-bigger picture as implementing individual features may seem intuitive at first
-but scale poorly in practical use. Keep a level head about your own work: it is
-not shameful to make a mistake in this vein, and fixing it usually leads to
-more insight.
-
-[0] <https://www.dhammatalks.org/books/#/books/TenPerfections/Section0001.html>
-[1] <https://www.fsf.org/news/publication-of-the-fsf-funded-white-papers-on-questions-around-copilot>

CONTRIBUTING

@@ -1,5 +1,3 @@
-Make sure to read our code of conduct in the CONDUCT file.
-
 When contributing a pull request to the main branch, please sign your commits
 with a PGP key and add your name and the year to the bottom of the list of
 copyright holders for the file. For example, an existing copyright header might

Makefile

@@ -8,16 +8,15 @@
 # permitted in any medium without royalty provided the copyright notice and this
 # notice are preserved.  This file is offered as-is, without any warranty.
 
-# The octal escape \043 is utilized twice in this file as make(1p) will
-# interpret a hash in a rule as an inline comment.
-
 .POSIX:
 
+# if using BSD make(1), remove these pragmas because they break it
+.PRAGMA: posix_202x # future POSIX standard support à la pdpmake(1)
+.PRAGMA: command_comment # breaks without this?
+
 DESTDIR ?= dist
 PREFIX ?= /usr/local
 
-MANDIR != [ $(PREFIX) = / ] && printf '/usr/share/man\n' \
-	|| printf '/share/man\n'
 SYSEXITS != printf '\043include <sysexits.h>\n' | cpp -M - | sed 's/ /\n/g' \
 	| sed -n 's/sysexits\.h//p' || printf 'include\n'
 
@@ -31,9 +30,9 @@ CFLAGS += -I$(SYSEXITS)
 .PHONY: all
 all: dj eep false fop hru intcmp mm npc rpn scrut str strcmp swab true
 
+build:
 	# keep build/include until bindgen(1) has stdin support
 	# https://github.com/rust-lang/rust-bindgen/issues/2703
-build:
 	mkdir -p build/bin build/include build/lib build/o build/test
 
 .PHONY: clean
@@ -43,7 +42,7 @@ clean:
 dist: all
 	mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1
 	cp build/bin/* $(DESTDIR)/$(PREFIX)/bin
-	cp docs/*.1 $(DESTDIR)/$(PREFIX)/$(MANDIR)/man1
+	cp docs/*.1 $(DESTDIR)/$(PREFIX)/share/man/man1
 
 .PHONY: install
 install: dist
@@ -66,9 +65,9 @@ build/o/libstrerror.rlib: build src/strerror.rs
 	$(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \
 		src/strerror.rs
 
-# bandage solution until bindgen(1) gets stdin support
 build/o/libsysexits.rlib: build $(SYSEXITS)sysexits.h
-	printf '\043define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
+	# bandage solution until bindgen(1) gets stdin support
+	printf '#define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
 		> build/include/sysexits.h 
 	bindgen --default-macro-constant-type signed --use-core --formatter=none \
 		build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ -
@@ -103,6 +102,7 @@ mm: build/bin/mm
 build/bin/mm: src/mm.c build
 	$(CC) $(CFLAGS) -o $@ src/mm.c
 
+
 .PHONY: npc
 npc: build/bin/npc
 build/bin/npc: src/npc.c build

README

@@ -1,11 +1,9 @@
 “Seek not to walk the path of the masters; seek what they sought.”
 – Matsuo Basho
 
-The Bonsai core utilities are a replacement for standard POSIX utilities which
+The Bonsai core utilities are the result of the careful examination of the
-aim to fill its niche while expanding on their capabilities. These new tools are
+current state of POSIX and Unix utilies. The Unix Philosophy, “do one thing and
-the result of the careful examination of the current state of POSIX and Unix
+do it well” is its core but these tools do not cling to the names of the past.
-utilies. The Unix Philosophy of “do one thing and do it well” are their core but
-they avoid clinging to the past.
 
 The era of the original Unix tools has been long and fruitful, but they have
 their flaws. The new, non-POSIX era of this project started with frustration
@@ -22,9 +20,9 @@ See docs/ for more on the specific utilities currently implemented.
 Building
 
 The coreutils require a POSIX-compliant environment to compile, including a C
-compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust
+compiler and preprocessor (cc(1) and cpp(1) by default) with the -idirafter
-compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant make(1)
+flag, a Rust compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant
-utility.
+make(1) utility.
 
 To build and install:
 
@@ -40,7 +38,7 @@ To test the utilities:
 
 $ make test
 
-To remove all build and distributable files:
+To remove all untracked files:
 
 $ make clean
 

docs/dj.1

@@ -1,13 +1,14 @@
 .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 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 DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH dj 1
+
 .SH NAME
+
 dj \(en disk jockey
-.\"
+
 .SH SYNOPSIS
 
 dj
@@ -18,172 +19,142 @@ dj
 .RB [ count ])
 
 .RB ( -i
-[\fBinput file\fP])
+.R [
+.B input file
+.R ])
 .RB ( -b
-[\fBinput block size\fP])
+.R [
+.B input block size
+.R ])
 .RB ( -s
-[\fBinput offset\fP])
+.R [
+.B input offset
+.R ])
 
 .RB ( -o
-[\fBoutput file\fP])
+.R [
+.B output file
+.R ])
 .RB ( -B
-[\fBoutput block size\fP])
+.R [
+.B output block size
+.R ])
 .RB ( -S
-[\fBoutput offset\fP])
+.R [
-.\"
+.B output offset
-.SH DESCRIPTION
+.R ])
 
-Perform precise read and write operations on files. This utility is useful for
+.SH USAGE
-reading and writing binary data to and from disks.
 
-This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
+The
-to a specified byte by index in the input and output of the program
+.B -i
-respectively. This language is inherited from the
+option takes a path as an argument to open and use in place of standard input.
-.BR dd (1p)
+The
-utility and used here to decrease ambiguity.
+.B -o
-
+option does the same in place of standard output. Dj does not truncate output
-When seeking or skipping to a byte, writing or reading starts at the byte
+files and instead writes over the bytes in the existing file.
-immediately subsequent to the specified byte.
+.PP
-.\"
+The
-.SH OPTIONS
-
-.IP \fB-i\fP
-Takes a file path as an argument and opens it for use as an input.
-.IP \fB-b\fP
-Takes a numeric argument as the size in bytes of the input buffer, the default
-being 1024.
-.IP \fB-s\fP
-Takes a numeric argument as the number of bytes to skip into the input
-before starting to read. If the standard input is used, bytes read to this point
-are discarded.
-.IP \fB-o\fP
-Takes a file path as an argument and opens it for use as an output.
-.IP \fB-B\fP
-Does the same as
 .B -b
-but for the output buffer.
+option takes a numeric argument as the size in bytes of the input buffer and
-.IP \fB-S\fP
+the
-Seeks a number of bytes through the output before starting to write from
+.B -B
-the input. If the output is a stream, null characters are printed.
+option does the same for the output buffer, the default for both being 1024
-.IP \fB-a\fP
+bytes, or one kibibyte (KiB).
-Accepts a single literal byte with which the input buffer is padded in the event
+.PP
-of an incomplete read from the input file.
+The
-.IP \fB-A\fP
+.B -s
-Specifying this option pads the input buffer with null bytes in the event of an
+option takes a numeric argument as the number of bytes to skip into the input
-incomplete read. This is equivalent to specifying
+before starting to read, and the
+.B -S
+option skips a number of bytes through the output before starting to write from
+the input. If the input is a stream the bytes are read and discarded. If the
+output is a stream, nul characters are printed.
+.PP
+The
 .B -a
-with a null byte instead of a character.
+option takes one argument of one byte in length and pads the input buffer with
-.IP \fB-c\fP
+that byte in the event that a read doesn't fill the input buffer, and the
-Specifies a number of reads to make. The default is 0, in which case the
+.B -A
-input is read until a partial or empty read is made.
+option takes no arguments and pads with nuls.
-.IP \fB-d\fP
+The
-Prints invocation information before program execution as described in the
+.B -c
-DIAGNOSTICS section. Each invocation increments the debug level of the
+option specifies an amount of reads to make, and if 0 (the default) dj will
-program.
+continue reading until a partial or empty read.
-.IP \fB-H\fP
+.PP
-Prints diagnostics messages in a human-readable manner as described in the
+On a partial or empty read, dj prints a diagnostic message (unless the
-DIAGNOSTICS section.
+.B -q
-.IP \fB-n\fP
+option is specified) and exits (unless the
-Retries failed reads once before exiting.
+.B -n
-.IP \fB-q\fP
+option is specified, in which case only two consecutive empty reads will cause
-Suppresses error messages which print when a read or write is partial or
+dj to exit).
-empty. Each invocation decrements the debug level of the program.
+At exit, usage statistics are printed unless the option
-.\"
+.B -q
-.SH STANDARD INPUT
+is specified a second time. The
+.B -H
+option will make these diagnostics human-readable.
 
-The standard input shall be used as an input if no inputs are specified or if
-one or more of the input files is \(lq-\(rq.
-.\"
-.SH STANDARD OUTPUT
-The standard output shall be used as an output if no inputs are specified or if
-one or more of the input files is \(lq-\(rq.
-.\"
 .SH DIAGNOSTICS
 
-On a partial or empty read, unless the
+The
-.B -q
+.B -d
-option is specified, a diagnostic message is printed. Then, the program exits
+option prints all information, user-specified or otherwise, before program
-unless the
+execution.
-.B -n
+.PP
-option is specified.
+When dj exits, by default statistics are printed for input and output to
-
+standard error in the following format:
-By default, statistics are printed for input and output to the standard error in
+.PP
-the following format:
+.R {records read} {ASCII unit separator} {partial records read}
-
+.R {ASCII record separator} {records written} {ASCII unit separator}
-.RS
+.R {partial records written} {ASCII group separator} {bytes read}
-{records read} {ASCII unit separator} {partial records read}
+.R {ASCII record separator} {bytes written} {ASCII file separator}
-{ASCII record separator} {records written} {ASCII unit separator}
+.PP
-{partial records written} {ASCII group separator} {bytes read}
-{ASCII record separator} {bytes written} {ASCII file separator}
-.RE
-
-This format for diagnostic output is designed to be machine-parseable for
-convenience. For a more human-readable format, the
-.B -H
-option may be specified. In this event, the following format is used instead:
-
-.RS
-{records read} '+' {partial records read} '>' {records written}
-'+' {partial records written} ';' {bytes read} '>' {bytes written}
-{ASCII line feed}
-.RE
-
 If the
-.B -d
+.B -H
-option is specified, debug information will be printed at the beginning of
+option is specified dj instead uses this following format:
-execution. This output contains information regarding how the program was
+.PP
-invoked. The following example is the result of running the program with
+.R {records read} '+' {partial records read} '>' {records written}
-.B -d
+.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
-as the only argument:
+.R {ASCII line feed}
-
+.PP
-.RS
+The
-argv0=dj
+.B -q
-in=<stdin>      ibs=1024        skip=0  align=ff       count=0
+option suppresses error messages which print when a read or write is partial or
-out=<stdout>    obs=1024        seek=0  debug= 3       noerror=0
+empty and when used twice suppresses diagnostic output entirely.
-.RE
+.PP
-
+In non-recoverable errors that don't pertain to dj's read-write cycle, a
-In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
+diagnostic message is printed and dj exits with the appropriate sysexits(3)
-diagnostic message is printed and the program exits with the appropriate
-.BR sysexits.h (3)
 status.
-.\"
+
 .SH BUGS
 
 If
 .B -n
-is specified along with the
+is specified along with a specified count, actual byte output may be lower than
-.B -c
+expected (the product of the count multiplied by the input block size). If the
-option and a count, actual byte output is the product of the count and the input
-block size and therefore may be lower than expected. If the
 .B -a
 or
 .B -A
-options are specified, this could make written data nonsensical.
+options are used this could make data written nonsensical.
-.\"
+.PP
-.SH CAVEATS
-
-Existing files are not truncated on ouput and are instead overwritten.
-
 Many lowercase options have capitalized variants and vice-versa which can be
 confusing. Capitalized options tend to affect output or are more intense
 versions of lowercase options.
-.\"
+
 .SH RATIONALE
 
-This program was based on the
+Dj was modeled after the dd utility specified in POSIX but adds additional
-.BR dd (1p)
+features: typical option formatting, allowing seeks to be specified in bytes
-utility as specified in POSIX. While character conversion may have been the
+rather than in blocks, allowing arbitrary bytes as padding, and printing in a
-original intent of
+format that's easy to parse for machines. It also neglects character
-.BR dd (1p),
+conversion, which may be dd's original intent but is irrelevant to its modern
-it is irrelevant to its modern use. Because of this, this program eschews
+use.
-character conversion and adds typical option formatting, allowing seeks to be
+
-specified in bytes rather than in blocks, allowing arbitrary bytes as padding,
-and printing in a format that\(cqs easy for machines to parse.
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR dd (1p)
+
+dd(1)

docs/false.1

@@ -1,35 +1,35 @@
 .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
+.TH FALSE 1
+
 .SH NAME
+
 false \(en do nothing, unsuccessfully
-.\"
+
 .SH DESCRIPTION
 
-Do nothing regardless of operands or standard input. An exit code of 1 will
+False does nothing regardless of operands or standard input.
-always be returned.
+False will always return an exit code of 1.
-.\"
+
 .SH RATIONALE
 
-In POSIX.1-2017,
+False exists for the construction of control flow and loops based on a failure.
-.BR false (1p)
+
-exists for the construction of control flow and loops based on a failure. This
+False functions as described in POSIX.1-2017.
-implementation functions as described in that standard.
+
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 This work is marked with CC0 1.0. To see a copy of this license, visit
 <http://creativecommons.org/publicdomain/zero/1.0>.
-.\"
+
 .SH SEE ALSO
-.BR true (1p)
+
+true(1p)

docs/fop.1

@@ -1,62 +0,0 @@
-.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 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 FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
-.SH NAME
-fop \(en field operator
-.\"
-.SH SYNOPSIS
-
-fop
-.RB ( -d )
-.RB [ delimiter ]
-.RB index 
-.RB program...
-.\"
-.SH DESCRIPTION
-
-Performs operations on specified fields in data read from the standard input.
-.\"
-.SH OPTIONS
-
-.IP \fB-d\fP
-Sets a delimiter by which the input data will be split into fields. The default
-is an ASCII record separator.
-.\"
-.SH CAVEATS
-
-Field indices are zero-indexed, which may be unexpected behavior for some users.
-.\"
-.SH RATIONALE
-
-With the assumption that tools will output data separated with ASCII field
-separators, there is a need for the ability to modify select fields in this data
-easily and quickly.
-
-The idea for this utility originated in the fact that the GNU
-.BR ls (1)
-utility contains a
-.B -h
-option which enables human-readable units in file size outputs. This
-functionality was broken out into
-.BR hru (1),
-but there was no easy way to modify the field in the ouput of
-.BR ls (1p)
-without creating a new tool.
-.\"
-.SH AUTHOR
-
-Written by Emma Tebibyte
-.MT emma@tebibyte.media
-.ME .
-.\"
-.SH COPYRIGHT
-
-Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
-<https://gnu.org/licenses/agpl.html>.
-.\"
-.SH SEE ALSO
-.BR sed (1p)

docs/hru.1

@@ -2,68 +2,56 @@
 .\"
 .\" 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 HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH rpn 1
+
 .SH NAME
+
 hru \(en human readable units
-.\"
+
 .SH SYNOPSIS
 
 hru
-.\"
+
 .SH DESCRIPTION
 
-Convert counts to higher units.
+Hru reads byte counts in the form of whole numbers from the standard input and
-
+writes to the standard output the same number converted one of the units of data
-Byte counts will be read in the form of whole numbers from the standard input
+defined by the International System of Units.
-and be written to the standard output the same number converted to a higher unit
-of data as defined by the \fIInternational System of Units\fP.
 
 The program will convert the byte count to the highest unit possible where the
 value is greater than one.
-.\"
+
 .SH DIAGNOSTICS
 
-If encountering non-integer characters in the standard input, the program will
+If encountering non-integer characters in the standard input, hru will exit with
-exit with the appropriate error code as defined by
+the appropriate error code as defined by sysexits.h(3) and print an error
-.BR sysexits.h (3)
+message.
-and print an error message.
+
-.\"
 .SH RATIONALE
 
-The GNU project\(cqs
+The GNU project’s ls(1) implementation contains a human-readable option (-h)
-.BR ls (1)
+that, when specified, makes the tool print size information in a format more
-implementation contains a human-readable option (\fB-h\fP) that, when specified,
+immediately readable. This functionality is useful not only in the context of
-makes the tool print size information in a format more immediately
+ls(1) so the decision was made to split it into a new tool. The original
-readable. This functionality is useful not only in this context, so the decision
+functionality in GNU’s ls(1) can be emulated with fop(1) combined with this
-was made to split it into a new tool. The original functionality from GNU\(cqs
+program.
-.BR ls (1)
+
-can be emulated with
-.BR fop (1)
-combined with this program.
-.\"
 .SH STANDARDS
 
-The standard unit prefixes as specified by the
+Hru follows the standard unit prefixes as specified by the Bureau International
-.I Bureau International des Poids et Mesures
+des Poids et Mesures (BIPM) in the ninth edition of The International System of
-.RI ( BIPM )
+Units (SI).
-in the ninth edition of
+
-.I The International System of Units
-.RI ( SI )
-are utilized for the ouput of conversions.
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-GNU
+
-.BR ls (1),
+GNU ls(1), The International System of Units (SI) 9th Edition
-.I The International System of Units (SI) 9th Edition

docs/intcmp.1

@@ -1,105 +1,78 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 2024-06-06 "Bonsai Core Utilites 0.13.11"
+.TH intcmp 1
+
 .SH NAME
+
 intcmp \(en compare integers
-.\"
+
 .SH SYNOPSIS
 
 intcmp
-.RB ( -egl )
+.RB ( -eghl )
 .RB [ integer ]
 .RB [ integer... ]
+
 .SH DESCRIPTION
-Compare integers to each other.
-.\"
-.SH OPTIONS
 
-.IP \fB-e\fP
+Intcmp compares integers.
-Permits given integers to be equal to each other.
+
-.IP \fB-g\fP
+.SH USAGE
-Permits a given integer to be greater than the following integer.
+
-.IP \fB-l\fP
+The -e option permits given integers to be equal to each other. If combined
-Permits a given integer to be less than the following integer.
+with -g or -l, only adjacent integers in the argument sequence can be equal.
-.\"
+.PP
-.SH EXAMPLES
+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".
 
-It may help to think of the
-.BR -e ,
-.BR -g ,
-and
-.B -l
-options as equivalent to the infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq
-operators respectively, with each option putting its symbol between every given
-integer. The following example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
-\"
-.RS
-intcmp -l 1 2 3
-.RE
-.\"
 .SH DIAGNOSTICS
 
-The program will exit with a successfully for a valid expression and with an
+Intcmp exits 0 for a valid expression and 1 for an invalid expression.
-error code of 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.
 
-In the event of an error, a debug message will be printed and the program will
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
 .SH BUGS
 
-.BR -egl ,
+There are multiple ways to express compound comparisons; “less than or equal
-\(lqequal to or less than or greater than\(rq, always exits successfully for
+to” can be -le or -el, for example.
-valid program usage and may be abused to function as an integer validator. Use
+.PP
-.BR str (1)
+The inequality comparison is -gl or -lg for “less than or greater than”; this
-instead.
+is elegant but unintuitive.
-.\"
+.PP
-.SH CAVEATS
+-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.
 
-There are multiple ways to express compound comparisons; \(lqless than or equal
-to\(rq can be
-.B -le
-or
-.BR -el ,
-for example.
-
-The inequality comparison is
-.B -gl
-.B or
-.B -lg
-for \(lqless than or greater than\(rq;
-this is elegant but unintuitive.
-.\"
 .SH RATIONALE
 
 The traditional tool for integer comparisons in POSIX and other Unix shells has
-been
+been test(1). This tool also handles string comparisons and file scrutiny.
-.BR test (1).
+These parts of its functionality have been broken out into multiple utilities.
-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).
 
-This program\(cqs functionality may be performed on a POSIX-compliant system
-with
-.BR test (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
-.\"
+
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR scrut (1),
+
-.BR strcmp (1),
+strcmp(1), scrut(1), str(1), test(1p)
-.BR str (1),
-.BR test (1p)

docs/mm.1

@@ -2,11 +2,13 @@
 .\"
 .\" 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 MM 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH mm 1
+
 .SH NAME
+
 mm \(en middleman
-.\"
+
 .SH SYNOPSIS
 
 mm
@@ -15,59 +17,60 @@ mm
 .RB [ input ])
 .RB ( -o
 .RB [ output ])
-.\"
+
 .SH DESCRIPTION
 
-Catenate input files and write them to the start of each output file or stream.
+Mm catenates input files and writes them to the start of each output file.
-.\"
+
 .SH OPTIONS
 
-.IP \fB-a\fP
+Mm, upon receiving the
-Opens subsequent outputs for appending rather than updating.
+.B -a
-.IP \fB-e\fP
+option, will open subsequent outputs for appending rather than updating.
-Use the standard error as an output.
+.PP
-.IP \fB-i\fP
+The
-Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
+.B -i
-no inputs are specified, the standard input shall be used.
+option opens a path as an input. Without any inputs specified mm will use
-.IP \fB-o\fP
+standard input. Standard input itself can be specified by giving the path '-'.
-Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
+.PP
-no outputs are specified, the standard output shall be used.
+The
-.IP \fB-u\fP
+.B -o
-Ensures neither input or output will be buffered.
+option opens a path as an output. Without any outputs specified mm will use
-.IP \fB-n\fP
+standard output. Standard output itself can be specified by giving the
-Causes SIGINT signals to be ignored.
+path '-'. Standard error itself can be specified with the
-.\"
+.B -e
+option.
+.PP
+The
+.B -u
+option ensures neither input or output will be buffered.
+.PP
+The
+.B -n
+option tells mm to ignore SIGINT signals.
+
 .SH DIAGNOSTICS
 
-If an output cannot be written to, an error occurs; however, exiting will be 
+If an output can no longer be written mm prints a diagnostic message, ceases
-deferred until writing to any other specified outputs completes.
+writing to that particular output, and if there are more outputs specified,
+continues, eventually exiting unsuccessfully.
+.PP
+On error mm prints a diagnostic message and exits with the appropriate
+sysexits.h(3) status.
 
-When an error is encountered, a diagnostic message is printed and the program
+.SH BUGS
-exits with the appropriate
+
-.BR sysexits.h (3)
+Mm does not truncate existing files, which may lead to unexpected results.
-status.
-.\"
-.SH CAVEATS
 
-Existing files are not truncated on ouput and are instead overwritten.
-.\"
 .SH RATIONALE
 
-The
+Mm was modeled after the cat and tee utilities specified in POSIX.
-.BR cat (1p)
+
-and
-.BR tee (1p)
-programs specified in POSIX together provide similar functionality. The
-separation of the two sets of functionality into separate APIs seemed
-unncessary.
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR cat (1p),
+
-.BR dd (1),
+cat(1p), dd(1), dj(1), tee(1p)
-.BR dj (1),
-.BR tee (1p)

docs/npc.1

@@ -1,74 +1,68 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH npc 1
+
 .SH NAME
+
 npc \(en show non-printing characters
-.\"
+
 .SH SYNOPSIS
 
 npc
-.RB ( -et )
+.RB ( -eht )
-.\"
+
 .SH DESCRIPTION
 
-Print normally non-printing characters.
+Npc reads from standard input and writes to standard output, replacing non-
-
+printing characters with printable equivalents. Control characters print as a
-The program reads from standard input and writes to standard output, replacing
+carat ('^') followed by the character '@' through '_' corresponding to the
-non-printing characters with printable equivalents. Control characters print as
+character replaced (e.g. control-X becomes "^X"). The delete character (0x7F)
-a carat ('^') followed by the character '@' through '_' corresponding to the
+becomes "^?". Characters with the high bit set (>127) are printed as "M-"
-character replaced (e.g. control-X becomes '^X'). The delete character (0x7F)
-becomes '^?'. Characters with the high bit set (>127) are printed as 'M-'
 followed by the graphical representation for the same character without the
 high bit set.
-.\"
+.PP
-.SH OPTIONS
+The
+.B -e
+option prints a currency sign ('$') before each line ending.
+.PP
+The
+.B -t
+option prints tab characters as "^I" rather than a literal horizontal tab.
 
-.IP \fB-e\fP
-Prints a dollar sign ('$') before each newline.
-.IP \fB-t\fP
-Prints tab characters as '^I' rather than a literal horizontal tab.
-.\"
 .SH DIAGNOSTICS
 
-In the event of an error, a debug message will be printed and the program will
+Npc prints a debug message and exits with the appropriate sysexits(3) error
-exit with the appropriate
+code in the event of an error, otherwise it exits successfully.
-.BR sysexits.h (3)
+
-error code.
-.\"
 .SH BUGS
 
-The program operates in single-byte chunks regardless of intended encoding.
+Npc operates in single-byte chunks regardless of intended encoding.
-.\"
+
 .SH RATIONALE
 
 POSIX currently lacks a way to display non-printing characters in the terminal
-using a standard tool. A popular extension to
+using a standard tool. A popular extension to cat(1p), the -v option, is the
-.BR cat (1p),
+bandage solution GNU and other software suites use.
-the
+
-.B -v
+This functionality should be a separate tool because its usefulness extends
-option, is the bandage solution GNU and other software suites use.
+beyond that of cat(1p).
 
-This functionality is included in a separate tool because its usefulness extends
-beyond that of
-.BR cat (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR cat (1p),
+
-.BR cat-v (1),
+cat(1p), cat-v(1)
+
 .I UNIX Style, or cat -v Considered Harmful
 by Rob Pike

docs/rpn.1

@@ -3,84 +3,68 @@
 .\"
 .\" 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 RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH rpn 1
+
 .SH NAME
+
 rpn \(en reverse polish notation evaluation
-.\"
+
 .SH SYNOPSIS
 
 rpn
-.RB [ numbers... ]
+.RB [numbers...]\ [operators...]
-.RB [ operators... ]
+
-.\"
 .SH DESCRIPTION
 
-Evaluate reverse polish notation.
+Rpn evaluates reverse polish notation expressions either read from the standard
+input or parsed from provided arguments. See the STANDARD INPUT section.
 
-The program evaluates reverse polish notation expressions read either from the
+Upon evaluation, rpn will print the resulting number on the stack to the
-standard input or parsed from provided arguments. See the STANDARD INPUT
+standard output. Any further specified numbers will be placed at the end of the
-section.
-
-Upon evaluation, the resulting number on the stack will be printed to the
-standard output. Any further numbers specified will be placed at the end of the
 stack.
 
-For information on for reverse polish notation syntax, see
+For information on for reverse polish notation syntax, see rpn(7).
-.BR rpn (7).
+
-.\"
 .SH STANDARD INPUT
 
-If arguments are specified, they are interpreted as an expression to be
+If arguments are passed to rpn, it interprets them as an expression to be
-evaluated. Otherwise, whitespace-delimited numbers and operations are read from
+evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
 the standard input.
-.\"
+
 .SH DIAGNOSTICS
 
-In the event of an error, a debug message will be printed and the program will
+If encountering a syntax error, rpn will exit with the appropriate error code
-exit with the appropriate
+as defined by sysexits.h(3) and print an error message.
-.BR sysexits.h (3)
+
-error code; however, in the event of a syntax error, the program will print an
-error message and continue accepting input.
-.\"
 .SH CAVEATS
 
 Due to precision constraints and the way floats are represented in accordance
-with the
+with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point
-.I IEEE Standard for Floating Point Arithmetic
+arithmetic has rounding errors. This is somewhat curbed by using the
-(\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is
+machine epsilon as provided by the Rust standard library to which to round
-somewhat curbed by using the machine epsilon as provided by the Rust standard
+numbers. Because of this, variation is expected in the number of decimal places 
-library to which numbers are rounded. Because of this, variation is expected in
+rpn can handle based on the platform and hardware of any given machine.
-the number of decimal places the program can handle based on the platform and
+
-hardware of any given machine.
-.\"
 .SH RATIONALE
 
-An infix notation calculation utility,
+An infix notation calculation utility, bc(1p), is included in the POSIX
-.BR bc (1p),
+standard, but does not accept expressions as arguments; in scripts, any
-is included in the POSIX standard, but does not accept expressions as arguments;
+predefined, non-interactive input must be piped into the program. A dc(1)
-in scripts, any predefined, non-interactive input must be piped into the
+pre-dates the standardized bc(1p), the latter originally being a preprocessor
-program. A
+for the former, and was included in UNIX v2 onward. While it implements reverse
-.BR dc (1)
+polish notation, it still suffers from being unable to accept an expression as
-pre-dates the standardized
+an argument.
-.BR bc (1p),
+
-the latter originally being a preprocessor for the former, and was included in
-Second Edition UNIX and onward. While it implements reverse polish notation, it
-still suffers from being unable to accept an expression as an argument.
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR bc (1p),
+
-.BR dc (1),
+bc(1p), dc(1), rpn(7), IEEE 754
-.BR rpn (7),
-.I IEEE 754

docs/scrut.1

@@ -1,86 +1,93 @@
 .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 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 SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
+.TH scrut 1
+
 .SH NAME
+
 scrut \(en scrutinize file properties
+
 .SH SYNOPSIS
 
 scrut
-.RB ( -LSbcdefgkprsuwx )
+.RB ( -bcdefgkprsuwxLS )
 .RB [ file... ]
-.\"
+
 .SH DESCRIPTION
 
-Determine if files comply with requirements. If the given files comply with the
+Scrut determines if given files comply with the opted requirements.
-specified requirements, the program will exit successfully. Otherwise, it exits
+
-unsuccessfully.
-.\"
 .SH OPTIONS
 
-.IP \fB-L\fB
+.B -b
-Requires the given files to exist and be symbolic links.
+requires the given files to exist and be block special files.
-.IP \fB-S\fP
+.PP
-Requires the given files to exist and be sockets.
+.B -c
-.IP \fB-b\fP
+requires the given files to exist and be character special files.
-Requires the given files to exist and be block special files.
+.PP
-.IP \fB-c\fP
+.B -d
-Requires the given files to exist and be character special files.
+requires the given files to exist and be directories.
-.IP \fB-d\fP
+.PP
-Requires the given files to exist and be directories.
+.B -e
-.IP \fB-e\fP
+requires the given files to exist, and is redundant to any other option.
-Requires the given files to exist, and is redundant to any other option.
+.PP
-.IP \fB-f\fP
+.B -e
-Requires the given files to exist and be regular files.
+requires the given files to exist and be regular files.
-.IP \fB-g\fP
+.PP
-Requires the given files to exist and have their set group ID flags set.
+.B -g
-.IP \fB-k\fP
+requires the given files to exist and have their set group ID flags set.
-Requires the given files to exist and have their sticky bit set.
+.PP
-.IP \fB-p\fP
+.B -k
-Requires the given files to exist and be named pipes.
+requires the given files to exist and have their sticky bit set.
-.IP \fB-r\fP
+.PP
-Requires the given files to exist and be readable.
+.B -p
-.IP \fB-u\fP
+requires the given files to exist and be named pipes.
-Requires the given files to exist and have their set user ID flags set.
+.PP
-.IP \fB-w\fP
+.B -r
-Requires the given files to exist and be writable.
+requires the given files to exist and be readable.
-.IP \fB-x\fP
+.PP
-Requires the given files to exist and be executable.
+.B -u
-.\"
+requires the given files to exist and have their set user ID flags set.
-.SH DIAGNOSTICS
+.PP
+.B -w
+requires the given files to exist and be writable.
+.PP
+.B -x
+requires the given files to exist and be executable.
+.PP
+.B -L
+requires the given files to exist and be symbolic links.
+.PP
+.B -S
+requires the given files to exist and be sockets.
 
-When invoked incorrectly, a debug message will be printed and the program will
+.SH EXIT STATUS
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH RATIONALE 
 
-The 
+Scrut prints a debug message and exits unsuccessfully with the appropriate
-.BR test (1p)
+sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if
-utility contains functionality that was broken out into separate programs. Thus,
+the given files comply with their requirements and unsuccessfully otherwise.
-the scope of this program is narrower than it. Notably, the
+
+.SH STANDARDS
+
+Scrut is nearly compatible with POSIX's test utility though it is narrower in
+scope. Notably, the
 .B -h
 option is now invalid and therefore shows usage information instead of being an
 alias to the modern
 .B -L
 option.
-.\"
+
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR access (3p),
+
-.BR lstat (3p),
+access(3p), lstat(3p), test(1p)
-.BR test (1p)

docs/str.1

@@ -1,60 +1,58 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 STR 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH STR 1
+
 .SH NAME
-str \(en test string arguments
+
-.\"
+str \(en test the character types of string arguments
+
 .SH SYNOPSIS
 
 str
 .RB [ type ]
 .RB [ string... ]
-.\"
+
 .SH DESCRIPTION
 
-Test the character types of string arguments.
+Str tests each character in an arbitrary quantity of string arguments against
+the function of the same name within ctype(3).
 
-The tests in this program are equivalent to the functions with the same names in
-.BR ctype.h (0p)
-and are the methods by which string arguments are tested.
-.\"
 .SH DIAGNOSTICS
 
-If all tests pass, the program will exit successfully. If any of the tests fail,
+Str exits successfully if all tests pass and unsuccessfully if a test failed.
-the program will exit unsuccessfully with an error code of 1.
+.PP
+Str will exit unsuccessfully if a string is empty, as none of its contents
+passed the test.
+.PP
+Str will print a message to standard error and exit unsuccessfully if used
+improperly.
 
-When invoked incorrectly, a debug message will be printed and the program will
+.SH DEPRECATED FEATURES
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH CAVEATS
 
-None of an empty string\(cqs contents pass any of the tests, so the program will
+Str used to have an "isvalue" type as an extension to ctype(3). This was
-exit unsuccessfully if one is specified.
+removed in favor of using strcmp(1) to compare strings against the empty string
+('').
 
-There\(cqs no way of knowing which argument failed the test without re-testing
+.SH BUGS
+
+There's no way of knowing which argument failed the test without re-testing
 arguments individually.
+.PP
+If a character in a string isn't valid ASCII str will exit unsuccessfully.
 
-If a character in a string isn\(cqt valid ASCII, the program will exit
-unsuccessfully.
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR ctype (3p),
+
-.BR strcmp(1),
+ctype(3p), strcmp(1), ascii(7)
-.BR ascii(7)

docs/strcmp.1

@@ -1,76 +1,62 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH STRCMP 1
+
 .SH NAME
+
 strcmp \(en compare strings
-.\"
+
 .SH SYNOPSIS
 
 strcmp
 .RM [ string ]
 .RB [ strings... ]
-.\"
+
 .SH DESCRIPTION
 
-Check whether string arguments are the same.
+Strcmp checks whether the given strings are the same.
-.\"
+Strcmp exits successfully if the strings are identical. Otherwise, strcmp exits
+with the value 1 if an earlier string has a greater byte value than a later
+string (e.g.
+.R strcmp b a
+)
+and 255 if an earlier string has a lesser byte value (e.g.
+.R strcmp a b
+).
+
 .SH DIAGNOSTICS
 
-The program will exit successfully if the strings are identical. Otherwise, it
+Strcmp will print an error message and exit unsuccessfully with a status
-will exit with an error code of 1 if a string passed has a lesser byte value
+described in sysexits(3) if used incorrectly (given less than two operands).
-than one of the prior strings:
 
-.RS
+.SH UNICODE
-strcmp b a
-.RE
 
-or with an error code of 255 if it has a greater byte value than one of the
+Strcmp will exit unsuccessfully if the given strings are not identical;
-prior strings:
+Unicode strings may need to be normalized if the intent is to check visual
+similarity and not byte similarity.
 
-.RS
-strcmp a b
-.RE
-
-When invoked incorrectly, a debug message will be printed and the program will
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH CAVEATS
-
-The program will exit unsuccessfully if the given strings are not identical;
-therefore, Unicode strings may need to be normalized if the intent is to check
-visual similarity and not byte similarity.
-.\"
 .SH RATIONALE
 
 The traditional tool for string comparisons in POSIX and other Unix shells has
-been
+been test(1). This tool also handles integer comparisons and file scrutiny.
-.BR test (1).
+These parts of its functionality have been broken out into multiple utilities.
-This tool also handles integer 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).
 
-This program\(cqs functionality may be performed on a POSIX-compliant system
-with
-.BR test (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB 
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR strcmp (3),
+
-.BR intcmp (1),
+strcmp(3), intcmp(1), scrut(1), test(1p)
-.BR scrut (1),
-.BR test (1p)

docs/swab.1

@@ -1,13 +1,14 @@
 .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 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 SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
+.TH swab 1
+
 .SH NAME
+
 swab \(en swap bytes
-.\"
+
 .SH SYNOPSIS
 
 swab
@@ -16,66 +17,55 @@ swab
 .R [
 .B word size
 .R ])
-.\"
-.SH DESCRIPTION
 
-Swap the latter and former halves of a block of bytes.
+.SH USAGE
-.\"
+
-.SH OPTIONS
+Swab swaps the latter and former halves of a block of bytes.
 
-.IP \fB-f\fP
-Ignore SIGINT signal.
-.IP \fB-w\fP
-Configures the word size; that is, the size in bytes of the block size
-on which to operate. The default word size is 2. The word size must be
-cleanly divisible by 2, otherwise the block of bytes being processed can\(cqt be
-halved.
-.\"
 .SH EXAMPLES
 
-The following
+The following sh(1p) line:
-.BR sh (1p)
-line:
 
-.RS
+.R printf 'hello world!\n' | swab
-printf 'hello world!\(rsn' | swab
-.RE
 
 Produces the following output:
 
-.RS
+.R ehll oowlr!d
-ehll oowlr!d
+
-.RE
+.SH OPTIONS
-.\"
+
+The
+.B -f
+option ignores system call interruptions.
+.PP
+The
+.B -w
+option configures the word size; that is, the size in bytes of the block size
+on which to operate. By default the word size is 2. The word size must be
+cleanly divisible by 2, otherwise the block of bytes being processed can't be
+halved.
+
 .SH DIAGNOSTICS
 
-In the event of an error, a debug message will be printed and the program will
+If an error is encountered in input, output, or invocation, a diagnostic
-exit with the appropriate
+message will be written to standard error and swab will exit with the
-.BR sysexits.h (3)
+appropriate status from sysexits.h(3).
-error code.
+
-.\"
 .SH RATIONALE
 
-This program was modeled and named after the
+Swab was modeled after the
-.B conv=swab
+.R conv=swab
-functionality specified
+functionality specified in the POSIX dd utility but additionally allows the
-in the
+word size to be configured.
-.BR dd (1p)
+.PP
-utility. It additionally allows the word size to be configured.
+Swab is useful for fixing the endianness of binary files produced on other
+machines.
 
-This functionality is useful for fixing the endianness of binary files produced
-on other machines.
-.\"
-.SH AUTHOR
-
-Written by DTB
-.MT trinity@trinity.moe
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR dd (1p)
+
+dd(1p)

docs/true.1

@@ -1,36 +1,35 @@
 .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" 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 TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
+.TH TRUE 1
+
 .SH NAME
+
 true \(en do nothing, successfully
-.\"
+
 .SH DESCRIPTION
 
-Do nothing regardless of operands or standard input. An exit code of 0 will
+True does nothing regardless of operands or standard input.
-always be returned.
+True will always return an exit code of 0.
-.\"
+
 .SH RATIONALE
 
-In \fIPOSIX.1-2017\fP,
+True exists for the construction of control flow and loops based on a success.
-.BR true (1p)
+
-exists for the construction of control flow and loops based on a success. This
+True functions as described in POSIX.1-2017.
-implementation functions as described in that standard.
+
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 This work is marked with CC0 1.0. To see a copy of this license, visit
 <http://creativecommons.org/publicdomain/zero/1.0>.
-.\"
+
 .SH SEE ALSO
-.BR false (1p),
+
-.BR true (1p)
+false(1p)

src/fop.rs

@@ -32,12 +32,18 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };
 
 fn main() {
 	let argv = args().collect::<Vec<String>>();
-	let mut d = '\u{1E}'.to_string();
+	let mut d = '␞';
 	let mut arg_parser = Parser::new(&argv, "d:");
 
 	while let Some(opt) = arg_parser.next() {
 		match opt {
-			Ok(Opt('d', Some(arg))) => d = arg,
+			Ok(Opt('d', Some(arg))) => {
+				let arg_char = arg.chars().collect::<Vec<char>>();
+				if arg_char.len() > 1 {
+					eprintln!("{}: {}: Not a character.", argv[0], arg);
+					exit(EX_USAGE);
+				} else { d = arg_char[0]; }
+			},
 			_ => {},
 		};
 	}
@@ -57,7 +63,7 @@ fn main() {
 
 	let mut buf = String::new();
 	let _ = stdin().read_to_string(&mut buf);
-	let mut fields = buf.split(&d).collect::<Vec<&str>>();
+	let mut fields = buf.split(d).collect::<Vec<&str>>();
 
 	let opts = argv
 		.iter()

src/test.rs

@@ -0,0 +1,10 @@
+extern crate strerror;
+
+use strerror::raw_message;
+
+fn main() {
+	stdout.write_all(b"meow\n").unwrap_or_else(|e| {
+		eprintln!("{}", raw_message(e));
+		std::process::exit(1);
+	});
+}