Merge branch 'docs' (closes #81)

docs/dj.1

@@ -1,14 +1,13 @@
 .\" 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
+.TH DJ 1
-
 .SH NAME
-
 dj \(en disk jockey
-
+.\"
 .SH SYNOPSIS
 
 dj
@@ -43,118 +42,155 @@ dj
 .R [
 .B output offset
 .R ])
+.\"
+.SH DESCRIPTION
 
-.SH USAGE
+Perform precise read and write operations on files. This utility is useful for
+reading and writing binary data to and from disks, hence the name.
 
-The
+This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
-.B -i
+to a specified byte by index in the input and output of the program
-option takes a path as an argument to open and use in place of standard input.
+respectively. This language is inherited from the
-The
+.BR dd (1p)
-.B -o
+utility and is used here to decrease ambiguity.
-option does the same in place of standard output. Dj does not truncate output
+
-files and instead writes over the bytes in the existing file.
+When seeking or skipping to a byte, writing or reading starts at the byte
-.PP
+immediately subsequent to the specified byte.
-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, with 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
-option takes a numeric argument as the size in bytes of the input buffer and
+but for the output buffer.
-the
+.IP \fB-S\fP
-.B -B
+Seeks a number of bytes through the output before starting to write from
-option does the same for the output buffer, the default for both being 1024
+the input. If the output is a stream, null characters are printed.
-bytes, or one kibibyte (KiB).
+.IP \fB-a\fP
-.PP
+Accepts a single literal byte with which input buffer is padded in the event
-The
+of an incomplete read from the input file.
-.B -s
+.IP \fB-A\fP
-option takes a numeric argument as the number of bytes to skip into the input
+Specifying this option pads the input buffer with null bytes in the event of an
-before starting to read, and the
+incomplete read. Equivalent to specifying
-.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
-option takes one argument of one byte in length and pads the input buffer with
+with a null byte instead of a character.
-that byte in the event that a read doesn't fill the input buffer, and the
+.IP \fB-c\fP
-.B -A
+Specifies a number of reads to make. The default is zero, in which case the
-option takes no arguments and pads with nuls.
+input is read until a partial or empty read is made.
-The
+.IP \fB-d\fP
-.B -c
+Prints invocation information before program execution as described in the
-option specifies an amount of reads to make, and if 0 (the default) dj will
+DIAGNOSTICS section below. Each invocation increments the debug level of the
-continue reading until a partial or empty read.
+program.
-.PP
+.IP \fB-H\fP
-On a partial or empty read, dj prints a diagnostic message (unless the
+Prints diagnostics messages in a human-readable manner as described in the
-.B -q
+DIAGNOSTICS section below.
-option is specified) and exits (unless the
+.IP \fB-n\fP
-.B -n
+Retries failed reads once more before exiting.
-option is specified, in which case only two consecutive empty reads will cause
+.IP \fB-q\fP
-dj to exit).
+Suppresses error messages which print when a read or write is partial or
-At exit, usage statistics are printed unless the option
+empty. Each invocation decrements the debug level of the program.
-.B -q
+.\"
-is specified a second time. The
+.SH STANDARD INPUT
-.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 DIAGNOSTICS
 
-The
+On a partial or empty read, a diagnostic message is printed (unless the
-.B -d
+.B -q
-option prints all information, user-specified or otherwise, before program
+option is specified) and the program exits (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:
+
+.RS
 .R {records read} {ASCII unit separator} {partial records read}
 .R {ASCII record separator} {records written} {ASCII unit separator}
 .R {partial records written} {ASCII group separator} {bytes read}
 .R {ASCII record separator} {bytes written} {ASCII file separator}
-.PP
+.RE
-If the
+
+This format for diagnostic output is designed to be machine-parseable for
+convenience. For a more human-readable format, the
 .B -H
-option is specified dj instead uses this following format:
+option may be specified. In this event, the following format is used instead:
-.PP
+
+.RS
 .R {records read} '+' {partial records read} '>' {records written}
 .R '+' {partial records written} ';' {bytes read} '>' {bytes written}
 .R {ASCII line feed}
-.PP
+.RE
-The
-.B -q
-option suppresses error messages which print when a read or write is partial or
-empty and when used twice suppresses diagnostic output entirely.
-.PP
-In non-recoverable errors that don't pertain to dj's read-write cycle, a
-diagnostic message is printed and dj exits with the appropriate sysexits(3)
-status.
 
+If the
+.B -d
+option is specified, debug output will be printed at the beginning of
+execution. This debug information contains information regarding how the program
+was invoked. The following example is the result of running the program with
+.B -d
+as the only argument:
+
+.RS
+.R argv0=dj
+.R in=<stdin>      ibs=1024        skip=0  align=ff       count=0
+.R out=<stdout>    obs=1024        seek=0  debug= 3       noerror=0
+.RE
+
+In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
+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 a specified count, actual byte output may be lower than
+is specified along with the
-expected (the product of the count multiplied by the input block size). If the
+.B -c
+option and a count, actual byte output may be lower than expected (the product
+of the count and the input block size). If the
 .B -a
 or
 .B -A
-options are used this could make data written 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
 
-Dj was modeled after the dd utility specified in POSIX but adds additional
+This program was based on the
-features: typical option formatting, allowing seeks to be specified in bytes
+.BR dd (1p)
-rather than in blocks, allowing arbitrary bytes as padding, and printing in a
+utility as specified in POSIX. While character conversion may have been the
-format that's easy to parse for machines. It also neglects character
+original intent of
-conversion, which may be dd's original intent but is irrelevant to its modern
+.BR dd (1p),
-use.
+it is irrelevant to its modern use. Because of this, this program eschews
-
+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 (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright \(co 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 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023–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 FALSE 1
-
 .SH NAME
-
 false \(en do nothing, unsuccessfully
-
+.\"
 .SH DESCRIPTION
 
-False does nothing regardless of operands or standard input.
+Do nothing regardless of operands or standard input. An exit code of 1 will
-False will always return an exit code of 1.
+always be returned.
-
+.\"
 .SH RATIONALE
 
-False exists for the construction of control flow and loops based on a failure.
+In POSIX.1-2017,
-
+.BR false (1p)
-False functions as described in POSIX.1-2017.
+exists for the construction of control flow and loops based on a failure. This
-
+implementation functions as described in that standard.
+.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte <emma@tebibyte.media>.
+Written by Emma Tebibyte
-
+.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

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

docs/intcmp.1

@@ -1,78 +1,92 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023–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 intcmp 1
+.TH INTCMP 1
-
 .SH NAME
-
 intcmp \(en compare integers
-
+.\"
 .SH SYNOPSIS
 
 intcmp
-.RB ( -eghl )
+.RB ( -egl )
 .RB [ integer ]
 .RB [ integer... ]
-
 .SH DESCRIPTION
+Compare integers to each other.
+.\"
+.SH OPTIONS
 
-Intcmp compares integers.
+.IP \fB-e\fP
+Permits given integers to be equal to each other.
+.IP \fB-g\fP
+Permits a given integer to be greater than the following integer.
+.IP \fB-l\fP
+Permits a given integer to be less than the following integer.
+.\"
+.SH EXAMPLES
 
-.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
+infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq operators respectively, with
-putting its symbol between every given integer. For example,
+each option putting its symbol between every given integer. The following
+example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
+\"
+.RS
 .R intcmp -l 1 2 3
-is equivalent to evaluating "1 < 2 < 3".
+.RE
-
+.\"
 .SH DIAGNOSTICS
 
-Intcmp exits 0 for a valid expression and 1 for an invalid expression.
+The program will exit with a status code of 0 for a valid expression and with a
-.PP
+code of 1 for an invalid expression.
-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
 
-There are multiple ways to express compound comparisons; “less than or equal
+-egl, \(lqequal to or less than or greater than\(rq, exits 0 no matter what 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 -le or -el, for example.
+
+The inequality comparison is -gl or -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 test(1). This tool also handles string comparisons and file scrutiny.
+been
-These parts of its functionality have been broken out into multiple utilities.
+.BR test (1).
-
+This tool also handles string comparisons and file scrutiny. These parts of its
-Strcmp’s functionality may be performed on a POSIX-compliant system with
+functionality have been broken out into multiple utilities.
-test(1p).
 
+This program\(cqs functionality may be performed on a POSIX-compliant system
+with
+.BR test (1p).
+.\"
 .SH AUTHOR
 
-Written by DTB <trinity@trinity.moe>.
+Written by DTB
-
+.MT trinity@trinity.moe
+.ME .
+.\"
 .SH COPYRIGHT
-
+.\"
-Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-
+.\"
 .SH SEE ALSO
-
+.BR scrut (1),
-strcmp(1), scrut(1), str(1), test(1p)
+.BR strcmp (1),
+.BR str (1),
+.BR test (1p)

docs/mm.1

@@ -2,13 +2,11 @@
 .\"
 .\" 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
-
 .SH NAME
-
 mm \(en middleman
-
+.\"
 .SH SYNOPSIS
 
 mm