From a6fd1108c606f782e707de31d24e5d84214809c6 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 18:26:51 -0600 Subject: [PATCH 01/48] docs: fixed formatting of many manpages --- docs/dj.1 | 156 ++++++++++++++++++++++++++++++-------------------- docs/intcmp.1 | 49 ++++++++++------ docs/npc.1 | 31 +++++----- docs/scrut.1 | 107 +++++++++++++++++++++------------- docs/str.1 | 8 +-- docs/strcmp.1 | 2 +- 6 files changed, 218 insertions(+), 135 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1e286f5..c94845e 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -1,4 +1,5 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -46,84 +47,117 @@ dj .SH USAGE -The -.B -i -option takes a path as an argument to open and use in place of standard input. -The -.B -o -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. -.PP -The -.B -b -option takes a numeric argument as the size in bytes of the input buffer and -the +.B -A +.RS +Takes no arguments and pads with nuls. +.RE + .B -B -option does the same for the output buffer, the default for both being 1024 -bytes, or one kibibyte (KiB). -.PP -The -.B -s -option takes a numeric argument as the number of bytes to skip into the input -before starting to read, and the +.RS +Does the same as +.B -b +but for the output buffer. +.RE + +.B -H +.RS +Prints diagnostics messages in an alternate manner as described in the +DIAGNOSTICS section below. +.RE + .B -S -option skips a number of bytes through the output before starting to write from +.RS +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 +.RE + .B -a -option takes one argument of one byte in length and pads the input buffer with -that byte in the event that a read doesn't fill the input buffer, and the -.B -A -option takes no arguments and pads with nuls. -The +.RS +Takes one argument of one byte in length and pads the input buffer with +that byte in the event that a read doesn’t fill the input buffer, and the +.RE + +.B -b +.RS +Takes a numeric argument as the size in bytes of the input buffer, with the +default being 1024 bytes or one kibibyte (KiB). +.RE + .B -c -option specifies an amount of reads to make, and if 0 (the default) dj will +.RS +Specifies an amount of reads to make, and if 0 (the default) dj will continue reading until a partial or empty read. -.PP +.RE + +.B -d +.RS +Prints all debug information, user-specified or otherwise, before program +execution. +.RE + +.B -i +.RS +Takes a path as an argument to open and use in place of standard input. +.RE + +.B -n +.RS +Causes dj to exit on two consecutive empty reads instead of one. +.RE + +.B -o +.RS +Does the same as +.B -i +but in place of standard output. Dj does not truncate output +files and instead writes over the bytes in the existing file. +.RE + +.B -s +.RS +Takes a numeric argument as the number of bytes to skip into the input +before starting to read. +.RE + +.B -q +.RS +Suppresses error messages which print when a read or write is partial or +empty. When +.B -q +is specified twice suppresses diagnostic output entirely. +.RE + +.SH DIAGNOSTICS + On a partial or empty read, dj prints a diagnostic message (unless the .B -q option is specified) and exits (unless the .B -n -option is specified, in which case only two consecutive empty reads will cause -dj to exit). -At exit, usage statistics are printed unless the option -.B -q -is specified a second time. The -.B -H -option will make these diagnostics human-readable. +option is specified. -.SH DIAGNOSTICS +By default statistics are printed for input and output to the standard error in +the following format: -The -.B -d -option prints all information, user-specified or otherwise, before program -execution. -.PP -When dj exits, by default statistics are printed for input and output to -standard error in the following format: -.PP +.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 .B -H -option is specified dj instead uses this following format: -.PP +option is specified, dj instead uses the following format: + +.RS .R {records read} '+' {partial records read} '>' {records written} .R '+' {partial records written} ';' {bytes read} '>' {bytes written} .R {ASCII line feed} -.PP -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) +.RE + +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.h(3) status. .SH BUGS @@ -136,7 +170,7 @@ expected (the product of the count multiplied by the input block size). If the or .B -A options are used this could make data written nonsensical. -.PP + 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. @@ -146,15 +180,15 @@ versions of lowercase options. Dj was modeled after the dd utility specified in POSIX but adds additional features: 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's easy to parse for machines. It also neglects character -conversion, which may be dd's original intent but is irrelevant to its modern +format that’s easy to parse for machines. It also neglects character +conversion, which may be dd’s original intent but is irrelevant to its modern use. .SH COPYRIGHT -Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . .SH SEE ALSO -dd(1) +dd(1p) diff --git a/docs/intcmp.1 b/docs/intcmp.1 index f370755..e3c0bcc 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -13,7 +13,7 @@ intcmp \(en compare integers .SH SYNOPSIS intcmp -.RB ( -eghl ) +.RB ( -egl ) .RB [ integer ] .RB [ integer... ] @@ -23,35 +23,52 @@ 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 +.B -e +.RS +Permits given integers to be equal to each other. If combined with +.B -g +or +.B -l +, only adjacent integers in the argument sequence can be equal. +.RE + +.B -g +.RS +Permits a given integer to be greater than the following integer. +.RE + +.B -l +.RS +Permits a given integer to be less than the following integer. +.RE + +.SH EXAMPLES + 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, +putting its symbol between every given integer. The following example is +equivalent to evaluating “1 < 2 < 3”: + +.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. -.PP -Intcmp prints a debug message and exits with the appropriate sysexits(3) error + +Intcmp prints a debug message and exits with the appropriate sysexits.h(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 + +-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. diff --git a/docs/npc.1 b/docs/npc.1 index 7f66c3d..e524f29 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -13,29 +13,31 @@ npc \(en show non-printing characters .SH SYNOPSIS npc -.RB ( -eht ) +.RB ( -et ) .SH DESCRIPTION Npc reads from standard input and writes to standard output, replacing non- printing characters with printable equivalents. Control characters print as a -carat ('^') followed by the character '@' through '_' corresponding to the -character replaced (e.g. control-X becomes "^X"). The delete character (0x7F) -becomes "^?". Characters with the high bit set (>127) are printed as "M-" +carat (“^”) followed by the character “@” through “_” corresponding to the +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 -The + .B -e -option prints a currency sign ('$') before each line ending. -.PP -The +.RS +Prints a currency sign (“$”) before each line ending. +.RE + .B -t -option prints tab characters as "^I" rather than a literal horizontal tab. +.RS +Prints tab characters as “^I” rather than a literal horizontal tab. +.RE .SH DIAGNOSTICS -Npc prints a debug message and exits with the appropriate sysexits(3) error +Npc prints a debug message and exits with the appropriate sysexits.h(3) error code in the event of an error, otherwise it exits successfully. .SH BUGS @@ -45,8 +47,9 @@ 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 cat(1p), the -v option, is the -bandage solution GNU and other software suites use. +using a standard tool. A popular extension to cat(1p), the +.B -v +option, is the bandage solution GNU and other software suites use. This functionality should be a separate tool because its usefulness extends beyond that of cat(1p). diff --git a/docs/scrut.1 b/docs/scrut.1 index 7a5107a..2f0955b 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -1,4 +1,5 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -21,47 +22,75 @@ Scrut determines if given files comply with the opted requirements. .SH OPTIONS -.B -b -requires the given files to exist and be block special files. -.PP -.B -c -requires the given files to exist and be character special files. -.PP -.B -d -requires the given files to exist and be directories. -.PP -.B -e -requires the given files to exist, and is redundant to any other option. -.PP -.B -e -requires the given files to exist and be regular files. -.PP -.B -g -requires the given files to exist and have their set group ID flags set. -.PP -.B -k -requires the given files to exist and have their sticky bit set. -.PP -.B -p -requires the given files to exist and be named pipes. -.PP -.B -r -requires the given files to exist and be readable. -.PP -.B -u -requires the given files to exist and have their set user ID flags set. -.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 +.RS +Requires the given files to exist and be symbolic links. +.RE + .B -S -requires the given files to exist and be sockets. +.RS +Requires the given files to exist and be sockets. +.RE + +.B -b +.RS +Requires the given files to exist and be block special files. +.RE + +.B -c +.RS +Requires the given files to exist and be character special files. +.RE + +.B -d +.RS +Requires the given files to exist and be directories. +.RE + +.B -e +.RS +Requires the given files to exist, and is redundant to any other option. +.RE + +.B -e +.RS +Requires the given files to exist and be regular files. +.RE + +.B -g +.RS +Requires the given files to exist and have their set group ID flags set. +.RE + +.B -k +.RS +Requires the given files to exist and have their sticky bit set. +.RE + +.B -p +.RS +Requires the given files to exist and be named pipes. +.RE + +.B -r +.RS +Requires the given files to exist and be readable. +.RE + +.B -u +.RS +Requires the given files to exist and have their set user ID flags set. +.RE + +.B -w +.RS +Requires the given files to exist and be writable. +.RE + +.B -x +.RS +Requires the given files to exist and be executable. +.RE .SH EXIT STATUS diff --git a/docs/str.1 b/docs/str.1 index ecf71ee..08137fb 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -24,10 +24,10 @@ the function of the same name within ctype(3). .SH DIAGNOSTICS Str exits successfully if all tests pass and unsuccessfully if a test failed. -.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. @@ -41,7 +41,7 @@ removed in favor of using strcmp(1) to compare strings against the empty string 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. .SH AUTHOR diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 14c0d0d..56e2ec9 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . From cf76fa94e6574ca5b7ab7ec456d98543171bb6cd Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 18:44:05 -0600 Subject: [PATCH 02/48] mm.1: updated man page --- docs/mm.1 | 61 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index 2244588..c8cc5dc 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -20,51 +20,60 @@ mm .SH DESCRIPTION -Mm catenates input files and writes them to the start of each output file. +Catenate input files and write them to the start of each output file or stream. .SH OPTIONS -Mm, upon receiving the .B -a -option, will open subsequent outputs for appending rather than updating. -.PP -The -.B -i -option opens a path as an input. Without any inputs specified mm will use -standard input. Standard input itself can be specified by giving the path '-'. -.PP -The -.B -o -option opens a path as an output. Without any outputs specified mm will use -standard output. Standard output itself can be specified by giving the -path '-'. Standard error itself can be specified with the +.RS +Opens subsequent outputs for appending rather than updating. +.RE + .B -e -option. -.PP -The +.RS +Set the output to the standard error. +.RE + +.B -i +.RS +Opens a path as an input. Without any inputs specified mm will use the +standard input. +.RE + +.B -o +.RS +Opens a path as an output. Without any outputs specified mm will use the +standard output. +.RE + .B -u -option ensures neither input or output will be buffered. -.PP -The +.RS +Ensures neither input or output will be buffered. +.RE + .B -n -option tells mm to ignore SIGINT signals. +.RS +Causes SIGINT signals to be ignored. +.RE .SH DIAGNOSTICS If an output can no longer be written mm prints a diagnostic message, ceases 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, diagnostic message is printed and the program +exits with the appropriate sysexits.h(3) status. .SH BUGS -Mm does not truncate existing files, which may lead to unexpected results. +Existing files are not truncated, which may lead to unexpected results. .SH RATIONALE -Mm was modeled after the cat and tee utilities specified in POSIX. +The cat(1p) and tee(1p) programs specified in POSIX provide equivalent +functionality. The separation of the two sets of functionality into separate +APIs seemed unncessary. .SH COPYRIGHT From 63a0c683f9803fe8b5023e07ceac1fc0bd922e51 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 19:22:30 -0600 Subject: [PATCH 03/48] docs: remove unnecessary references to the name of each program --- docs/dj.1 | 21 +++++++++++---------- docs/false.1 | 11 +++++------ docs/hru.1 | 22 ++++++++++++---------- docs/intcmp.1 | 11 ++++++----- docs/npc.1 | 20 ++++++++++++-------- docs/rpn.1 | 23 ++++++++++++++--------- docs/scrut.1 | 14 ++++++++------ docs/str.1 | 25 ++++++++++++++----------- docs/strcmp.1 | 25 +++++++++++++------------ docs/swab.1 | 52 ++++++++++++++++++++++++++++----------------------- docs/true.1 | 11 +++++------ 11 files changed, 129 insertions(+), 106 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index c94845e..3c57155 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -148,7 +148,7 @@ the following format: If the .B -H -option is specified, dj instead uses the following format: +option is specified, the following format is used instead: .RS .R {records read} '+' {partial records read} '>' {records written} @@ -156,9 +156,9 @@ option is specified, dj instead uses the following format: .R {ASCII line feed} .RE -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.h(3) -status. +In non-recoverable errors that don’t pertain to the read-write cycle, a +diagnostic message is printed and the program exits with the appropriate +sysexits.h(3) status. .SH BUGS @@ -177,12 +177,13 @@ versions of lowercase options. .SH RATIONALE -Dj was modeled after the dd utility specified in POSIX but adds additional -features: 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’s easy to parse for machines. It also neglects character -conversion, which may be dd’s original intent but is irrelevant to its modern -use. +The dd(1p) utility specified in POSIX was the basis of this program. + +It includes additional features: 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’s easy to parse for machines. It also neglects +character conversion. This may have been the original intent of dd(1p) but it is +irrelevant to its modern use as a disk utility. .SH COPYRIGHT diff --git a/docs/false.1 b/docs/false.1 index 6883802..b8463ae 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2022, 2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -12,14 +12,13 @@ false \(en do nothing, unsuccessfully .SH DESCRIPTION -False does nothing regardless of operands or standard input. -False will always return an exit code of 1. +Do nothing regardless of operands or standard input. +An exit code of 1 will always be returned. .SH RATIONALE -False exists for the construction of control flow and loops based on a failure. - -False functions as described in POSIX.1-2017. +In POSIX.1-2017, false(1p) exists for the construction of control flow and loops +based on a failure. This implementation functions as described in that standard. .SH AUTHOR diff --git a/docs/hru.1 b/docs/hru.1 index c75cb73..1ffc00e 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -3,7 +3,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . -.TH rpn 1 +.TH hru 1 .SH NAME @@ -15,18 +15,20 @@ hru .SH DESCRIPTION -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 -defined by the International System of Units. +Convert counts to higher 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 -the appropriate error code as defined by sysexits.h(3) and print an error -message. +If encountering non-integer characters in the standard input, the program will +exit with the appropriate error code as defined by sysexits.h(3) and print an +error message. .SH RATIONALE @@ -39,9 +41,9 @@ program. .SH STANDARDS -Hru follows the standard unit prefixes as specified by the Bureau International -des Poids et Mesures (BIPM) in the ninth edition of The International System of -Units (SI). +The standard unit prefixes as specified by the Bureau International des Poids +et Mesures (BIPM) in the ninth edition of The International System of Units +(SI) are utilized for the ouput of conversions. .SH AUTHOR diff --git a/docs/intcmp.1 b/docs/intcmp.1 index e3c0bcc..209b2d8 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -19,7 +19,7 @@ intcmp .SH DESCRIPTION -Intcmp compares integers. +Compare integers. .SH USAGE @@ -55,10 +55,11 @@ equivalent to evaluating “1 < 2 < 3”: .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 +code of 1 for an invalid expression. -Intcmp prints a debug message and exits with the appropriate sysexits.h(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 sysexits.h(3) error code. .SH BUGS @@ -78,7 +79,7 @@ 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 +This program’s functionality may be performed on a POSIX-compliant system with test(1p). .SH AUTHOR diff --git a/docs/npc.1 b/docs/npc.1 index e524f29..daad9f1 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -17,14 +17,18 @@ npc .SH DESCRIPTION -Npc reads from standard input and writes to standard output, replacing non- -printing characters with printable equivalents. Control characters print as a -carat (“^”) followed by the character “@” through “_” corresponding to the +Print normally non-printing characters. + +The program reads from standard input and writes to standard output, replacing +non-printing characters with printable equivalents. Control characters print as +a carat (“^”) followed by the character “@” through “_” corresponding to the 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. +.SH USAGE + .B -e .RS Prints a currency sign (“$”) before each line ending. @@ -37,12 +41,12 @@ Prints tab characters as “^I” rather than a literal horizontal tab. .SH DIAGNOSTICS -Npc prints a debug message and exits with the appropriate sysexits.h(3) error -code in the event of an error, otherwise it exits successfully. +In the event of an error, a debug message will be printed and the program will +exit with the appropriate sysexits.h(3) error code. .SH BUGS -Npc operates in single-byte chunks regardless of intended encoding. +The program operates in single-byte chunks regardless of intended encoding. .SH RATIONALE @@ -51,8 +55,8 @@ using a standard tool. A popular extension to cat(1p), the .B -v option, is the bandage solution GNU and other software suites use. -This functionality should be a separate tool because its usefulness extends -beyond that of cat(1p). +This functionality is a separate tool because its usefulness extends beyond that +of cat(1p). .SH AUTHOR diff --git a/docs/rpn.1 b/docs/rpn.1 index 2197fbe..0b6b264 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -17,10 +17,13 @@ rpn .SH DESCRIPTION -Rpn evaluates reverse polish notation expressions either read from the standard -input or parsed from provided arguments. See the STANDARD INPUT section. +Evaluate reverse polish notation. -Upon evaluation, rpn will print the resulting number on the stack to the +The program evaluates reverse polish notation expressions either read from the +standard input or parsed from provided arguments. See the STANDARD INPUT +section. + +Upon evaluation, the program will print the resulting number on the stack to the standard output. Any further specified numbers will be placed at the end of the stack. @@ -28,14 +31,16 @@ For information on for reverse polish notation syntax, see rpn(7). .SH STANDARD INPUT -If arguments are passed to rpn, it interprets them as an expression to be -evaluated. Otherwise, it reads whitespace-delimited numbers and operations from -the standard input. +If arguments are passed , they are interpreted as an expression to be evaluated. +Otherwise, it reads whitespace-delimited numbers and operations from the +standard input. .SH DIAGNOSTICS -If encountering a syntax error, rpn will exit with the appropriate error code -as defined by sysexits.h(3) and print an error message. +In the event of a syntax error, the program will print an + +In the event of an error, a debug message will be printed and the program will +exit with the appropriate sysexits.h(3) error code. .SH CAVEATS @@ -44,7 +49,7 @@ with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point arithmetic has rounding errors. This is somewhat curbed by using the machine epsilon as provided by the Rust standard library to which to round numbers. Because of this, variation is expected in the number of decimal places -rpn can handle based on the platform and hardware of any given machine. +the program can handle based on the platform and hardware of any given machine. .SH RATIONALE diff --git a/docs/scrut.1 b/docs/scrut.1 index 2f0955b..4c0b75b 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -18,7 +18,7 @@ scrut .SH DESCRIPTION -Scrut determines if given files comply with the opted requirements. +Determine if files comply with requirements. .SH OPTIONS @@ -94,14 +94,16 @@ Requires the given files to exist and be executable. .SH EXIT STATUS -Scrut prints a debug message and exits unsuccessfully with the appropriate -sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if -the given files comply with their requirements and unsuccessfully otherwise. +If the given files comply with the specified requirements, the program will exit +successfully. If not, it exits unsuccessfully. + +When invoked incorrectly, a debug message will be printed and the program will +exit with the appropriate sysexits.h(3) error code. .SH STANDARDS -Scrut is nearly compatible with POSIX's test utility though it is narrower in -scope. Notably, the +The test(1p) utility contains functionality that was broken out into separate +programs. Thus, the scope of this program is narrower than it. Notably, the .B -h option is now invalid and therefore shows usage information instead of being an alias to the modern diff --git a/docs/str.1 b/docs/str.1 index 08137fb..e671ecd 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -18,28 +18,31 @@ str .SH DESCRIPTION -Str tests each character in an arbitrary quantity of string arguments against -the function of the same name within ctype(3). +Test string arguments against each other. + +The tests in this program are equivalent to the functions with the same names in +ctype.h(0p) and are the methods by which string arguments are tested. .SH DIAGNOSTICS -Str exits successfully if all tests pass and unsuccessfully if a test failed. +If all tests pass, the program will exit with an exit code of 0. If any of the +tests fail, the program will exit unsuccessfully with an error code of 1. -Str will exit unsuccessfully if a string is empty, as none of its contents -passed the test. +An empty string will cause an unsuccessful exit as none of its contents pass any +tests. -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 +exit with the appropriate sysexits.h(3) error code. .SH DEPRECATED FEATURES -Str used to have an "isvalue" type as an extension to ctype(3). This was -removed in favor of using strcmp(1) to compare strings against the empty string -(''). +Originally, there was an isvalue type as an extension to ctype.h(3), but it +was removed in favor of using strcmp(1) to compare strings against the empty +string (''). .SH BUGS -There's no way of knowing which argument failed the test without re-testing +There’s no way of knowing which argument failed the test without re-testing arguments individually. If a character in a string isn't valid ASCII str will exit unsuccessfully. diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 56e2ec9..c2103dd 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -18,26 +18,27 @@ strcmp .SH DESCRIPTION -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. +Check whether string arguments are the same. + +.SH DIAGNOSTICS + +The program will exit successfully if the strings are identical. Otherwise, it +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 - -Strcmp will print an error message and exit unsuccessfully with a status -described in sysexits(3) if used incorrectly (given less than two operands). +When invoked incorrectly, a debug message will be printed and the program will +exit with the appropriate sysexits.h(3) error code. .SH UNICODE -Strcmp will exit unsuccessfully if the given strings are not identical; -Unicode strings may need to be normalized if the intent is to check visual -similarity and not byte similarity. +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 @@ -45,7 +46,7 @@ The traditional tool for string comparisons in POSIX and other Unix shells has been test(1). 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 +This program’s functionality may be performed on a POSIX-compliant system with test(1p). .SH AUTHOR diff --git a/docs/swab.1 b/docs/swab.1 index a0c1be3..f7e10b0 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -1,4 +1,5 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -20,46 +21,51 @@ swab .SH USAGE -Swab swaps the latter and former halves of a block of bytes. +Swap the latter and former halves of a block of bytes. + +.SH OPTIONS + +.B -f +.RS +Ignore system call interruptions. +.RE + +.B -w +.RS +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. +.RE .SH EXAMPLES The following sh(1p) line: +.RS .R printf 'hello world!\n' | swab +.RE Produces the following output: +.RS .R ehll oowlr!d - -.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. +.RE .SH DIAGNOSTICS -If an error is encountered in input, output, or invocation, a diagnostic -message will be written to standard error and swab will exit with the -appropriate status from sysexits.h(3). +In the event of an error, a debug message will be printed and the program will +exit with the appropriate sysexits.h(3) error code. .SH RATIONALE -Swab was modeled after the +This program was modeled and named after the .R conv=swab -functionality specified in the POSIX dd utility but additionally allows the -word size to be configured. -.PP -Swab is useful for fixing the endianness of binary files produced on other -machines. +functionality specified in the dd(1p) utility. It additionally allows the word +size to be configured. + +This functionality is useful for fixing the endianness of binary files produced +on other machines. .SH COPYRIGHT diff --git a/docs/true.1 b/docs/true.1 index 3c292d8..9b02fdd 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -1,5 +1,5 @@ .\" Copyright (c) 2022, 2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -12,14 +12,13 @@ true \(en do nothing, successfully .SH DESCRIPTION -True does nothing regardless of operands or standard input. -True will always return an exit code of 0. +Do nothing regardless of operands or standard input. +An exit code of 0 will always be returned. .SH RATIONALE -True exists for the construction of control flow and loops based on a success. - -True functions as described in POSIX.1-2017. +In POSIX.1-2017, true(1p) exists for the construction of control flow and loops +based on a success. This implementation functions as described in that standard. .SH AUTHOR From a1902df50351218bbad093cbdee9e27aa1054611 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 23:50:16 -0600 Subject: [PATCH 04/48] strcmp.1: Unicode is a proper noun --- docs/strcmp.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/strcmp.1 b/docs/strcmp.1 index c2103dd..48681c6 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -37,7 +37,7 @@ exit with the appropriate sysexits.h(3) error code. .SH UNICODE 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 +therefore, Unicode strings may need to be normalized if the intent is to check visual similarity and not byte similarity. .SH RATIONALE From f565f0530b041c45d82e27a5045349107a32d0b5 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 23:53:10 -0600 Subject: [PATCH 05/48] dj.1: dd(1p) is not a disk utility --- docs/dj.1 | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 3c57155..c1bb81d 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -177,13 +177,12 @@ versions of lowercase options. .SH RATIONALE -The dd(1p) utility specified in POSIX was the basis of this program. - -It includes additional features: 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’s easy to parse for machines. It also neglects -character conversion. This may have been the original intent of dd(1p) but it is -irrelevant to its modern use as a disk utility. +This program was based on the dd(1p) utility as specified in POSIX. While +character conversion may have been the original intent of dd(1p), it is +irrelevant to its modern use. Because of this, it 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’s easy to parse for machines. .SH COPYRIGHT From bb43533a374bd95dc844e1d9854777e0ccd99277 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 23:58:00 -0600 Subject: [PATCH 06/48] dj.1: -A and -a: fix descriptions --- docs/dj.1 | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index c1bb81d..a787544 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -45,11 +45,13 @@ dj .B output offset .R ]) -.SH USAGE +.SH OPTIONS .B -A .RS -Takes no arguments and pads with nuls. +If the output is a stream, nul bytes are printed. In other words, it does what +.B -a +does but with null bytes instead. .RE .B -B @@ -74,8 +76,8 @@ output is a stream, nul characters are printed. .B -a .RS -Takes one argument of one byte in length and pads the input buffer with -that byte in the event that a read doesn’t fill the input buffer, and the +Takes one argument of one byte in length and pads the input buffer with it in +the event of an incomplete read from the input file. .RE .B -b From 49e2022e521e7530bd4201a365f48d586ba037e9 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:08:43 -0600 Subject: [PATCH 07/48] dj.1: -d, -i, -o, fixed descriptions --- docs/dj.1 | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index a787544..41c4f3e 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -95,41 +95,42 @@ continue reading until a partial or empty read. .B -d .RS Prints all debug information, user-specified or otherwise, before program -execution. +execution. Each invocation increments the debug level of the program. .RE .B -i .RS -Takes a path as an argument to open and use in place of standard input. +Takes a file path as an argument to open and use as an input. .RE .B -n .RS -Causes dj to exit on two consecutive empty reads instead of one. +Retries failed reads once more before exiting. .RE .B -o .RS -Does the same as -.B -i -but in place of standard output. Dj does not truncate output -files and instead writes over the bytes in the existing file. +Takes a file path as an argument to open and use as an output. .RE .B -s .RS Takes a numeric argument as the number of bytes to skip into the input -before starting to read. +before starting to read. If the standard input is used, bytes read to this point +are discarded. .RE .B -q .RS Suppresses error messages which print when a read or write is partial or -empty. When -.B -q -is specified twice suppresses diagnostic output entirely. +empty. Each invocation decrements the debug level of the program. .RE +.SH STANDARD INPUT + +The standard input shall be used as an input if one or more of the input files +is “-”. + .SH DIAGNOSTICS On a partial or empty read, dj prints a diagnostic message (unless the @@ -177,6 +178,10 @@ 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 CAVEATS + +Output files are not truncated on ouput and are instead overwritten. + .SH RATIONALE This program was based on the dd(1p) utility as specified in POSIX. While From a2188dc674eb8d8b9801f6060dd31a44f9e378d6 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:09:17 -0600 Subject: [PATCH 08/48] dj.1: fix -H description --- docs/dj.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index 41c4f3e..c38a05d 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -63,7 +63,7 @@ but for the output buffer. .B -H .RS -Prints diagnostics messages in an alternate manner as described in the +Prints diagnostics messages in a human-readable manner as described in the DIAGNOSTICS section below. .RE From 6158a39a4ae58c195763777cd7a39d285248cb90 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:14:02 -0600 Subject: [PATCH 09/48] dj.1: consistency with mm.1 --- docs/dj.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index c38a05d..7e4b40b 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -180,7 +180,7 @@ versions of lowercase options. .SH CAVEATS -Output files are not truncated on ouput and are instead overwritten. +Existing files are not truncated on ouput and are instead overwritten. .SH RATIONALE From 3cb37d830a84710fc5493a953cc1a3b853e21f82 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:14:34 -0600 Subject: [PATCH 10/48] mm.1: wording, consistency with dj.1 --- docs/mm.1 | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index c8cc5dc..42a3e74 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -26,12 +26,12 @@ Catenate input files and write them to the start of each output file or stream. .B -a .RS -Opens subsequent outputs for appending rather than updating. +Opens outputs for appending rather than updating. .RE .B -e .RS -Set the output to the standard error. +Use the standard error as an output. .RE .B -i @@ -56,6 +56,11 @@ Ensures neither input or output will be buffered. Causes SIGINT signals to be ignored. .RE +.SH STANDARD INPUT + +The standard input shall be used as an input if one or more of the input files +is “-”. + .SH DIAGNOSTICS If an output can no longer be written mm prints a diagnostic message, ceases @@ -65,15 +70,15 @@ continues, eventually exiting unsuccessfully. When an error is encountered, diagnostic message is printed and the program exits with the appropriate sysexits.h(3) status. -.SH BUGS +.SH CAVEATS -Existing files are not truncated, which may lead to unexpected results. +Existing files are not truncated on ouput and are instead overwritten. .SH RATIONALE -The cat(1p) and tee(1p) programs specified in POSIX provide equivalent -functionality. The separation of the two sets of functionality into separate -APIs seemed unncessary. +The cat(1p) and tee(1p) programs specified in POSIX together provide nearly +equivalent functionality. The separation of the two sets of functionality into +separate APIs seemed unncessary. .SH COPYRIGHT From d3bfc7b1f540e1b131deb36e2343fda9281b7686 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:16:15 -0600 Subject: [PATCH 11/48] npc.1: ASCII bytes --- docs/npc.1 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/npc.1 b/docs/npc.1 index daad9f1..f3b7d0c 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -21,9 +21,9 @@ Print normally non-printing characters. The program reads from standard input and writes to standard output, replacing non-printing characters with printable equivalents. Control characters print as -a carat (“^”) followed by the character “@” through “_” corresponding to the -character replaced (e.g. control-X becomes “^X”). The delete character (0x7F) -becomes “^?”. Characters with the high bit set (>127) are printed as “M-” +a carat ('^') followed by the character '@' through '_' corresponding to the +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. @@ -31,12 +31,12 @@ high bit set. .B -e .RS -Prints a currency sign (“$”) before each line ending. +Prints a currency sign ('$') before each line ending. .RE .B -t .RS -Prints tab characters as “^I” rather than a literal horizontal tab. +Prints tab characters as '^I' rather than a literal horizontal tab. .RE .SH DIAGNOSTICS From cdd8e79b01092a307d381d52baa01b6826c8dae0 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:16:51 -0600 Subject: [PATCH 12/48] str.1: strings are not tested against each other --- docs/str.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/str.1 b/docs/str.1 index e671ecd..666f0b1 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -18,7 +18,7 @@ str .SH DESCRIPTION -Test string arguments against each other. +Test string arguments. The tests in this program are equivalent to the functions with the same names in ctype.h(0p) and are the methods by which string arguments are tested. From 603d8ee1d88a84c311ef6af19c7af14d0986eef4 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 27 Mar 2024 00:17:33 -0600 Subject: [PATCH 13/48] str.1: remove extraneous former implementation information --- docs/str.1 | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/str.1 b/docs/str.1 index 666f0b1..ef86861 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -34,12 +34,6 @@ tests. When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. -.SH DEPRECATED FEATURES - -Originally, there was an isvalue type as an extension to ctype.h(3), but it -was removed in favor of using strcmp(1) to compare strings against the empty -string (''). - .SH BUGS There’s no way of knowing which argument failed the test without re-testing From 70b0c2f9243385cb79d912aaf26372cbe4d88784 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:14:27 -0600 Subject: [PATCH 14/48] dj.1: fixed -d description --- docs/dj.1 | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 7e4b40b..631fa7b 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -94,8 +94,9 @@ continue reading until a partial or empty read. .B -d .RS -Prints all debug information, user-specified or otherwise, before program -execution. Each invocation increments the debug level of the program. +Prints invocation information before program execution as described in the +DIAGNOSTICS section below. Each invocation increments the debug level of the +program. .RE .B -i @@ -133,9 +134,9 @@ is “-”. .SH DIAGNOSTICS -On a partial or empty read, dj prints a diagnostic message (unless the +On a partial or empty read, a diagnostic message is printed (unless the .B -q -option is specified) and exits (unless the +option is specified) and the program exits (unless the .B -n option is specified. @@ -159,6 +160,20 @@ option is specified, the following format is used instead: .R {ASCII line feed} .RE +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= ibs=1024 skip=0 align=ff count=0 +.R out= obs=1024 seek=0 debug= 3 noerror=0 +.RE + In non-recoverable errors that don’t pertain to the read-write cycle, a diagnostic message is printed and the program exits with the appropriate sysexits.h(3) status. From 4e33f945ae632ff79090fe5be0c5a01583a4d7e0 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:17:48 -0600 Subject: [PATCH 15/48] dj.1: null bytes --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 631fa7b..d309678 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -49,7 +49,7 @@ dj .B -A .RS -If the output is a stream, nul bytes are printed. In other words, it does what +If the output is a stream, null bytes are printed. In other words, it does what .B -a does but with null bytes instead. .RE @@ -71,7 +71,7 @@ DIAGNOSTICS section below. .RS 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. +output is a stream, null characters are printed. .RE .B -a From 9ea57a27b7e68d49e01191324de7be724046cd2a Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:21:02 -0600 Subject: [PATCH 16/48] dj.1: stdin by default --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index d309678..0e882dd 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -129,8 +129,8 @@ empty. Each invocation decrements the debug level of the program. .SH STANDARD INPUT -The standard input shall be used as an input if one or more of the input files -is “-”. +The standard input shall be used as an input if no inputs are specified one or +more of the input files is “-”. .SH DIAGNOSTICS From 63c8ff8093564e3a88d1b4021790fb9afef36dd9 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:22:56 -0600 Subject: [PATCH 17/48] intcmp.1: compares integers to each other --- docs/intcmp.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 209b2d8..6087d0e 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -19,7 +19,7 @@ intcmp .SH DESCRIPTION -Compare integers. +Compare integers to each other. .SH USAGE From abc599148da8ab93e7eb41604dcc04bbfa342be1 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:26:41 -0600 Subject: [PATCH 18/48] mm.1: subsequent outputs are opened for appending --- docs/mm.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mm.1 b/docs/mm.1 index 42a3e74..01790fd 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -26,7 +26,7 @@ Catenate input files and write them to the start of each output file or stream. .B -a .RS -Opens outputs for appending rather than updating. +Opens subsequent outputs for appending rather than updating. .RE .B -e From ce5a4dc4bd043febdf02e33c22f309e3a77f0e19 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:29:27 -0600 Subject: [PATCH 19/48] mm.1: removed STANDARD INPUT section --- docs/mm.1 | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index 01790fd..6a1f664 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -37,13 +37,16 @@ Use the standard error as an output. .B -i .RS Opens a path as an input. Without any inputs specified mm will use the -standard input. +standard input. The standard input shall be used as an input if one or more of +the input files is “-”. .RE .B -o .RS Opens a path as an output. Without any outputs specified mm will use the -standard output. +standard output. The standard output shall be used as an output if one or more +of the output files is “-”. + .RE .B -u @@ -56,11 +59,6 @@ Ensures neither input or output will be buffered. Causes SIGINT signals to be ignored. .RE -.SH STANDARD INPUT - -The standard input shall be used as an input if one or more of the input files -is “-”. - .SH DIAGNOSTICS If an output can no longer be written mm prints a diagnostic message, ceases From 5db09a5ca19aca7b8d2e39b18bb5ac61927ff0fd Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:30:06 -0600 Subject: [PATCH 20/48] mm.1: cat(1p) and tee(1p) provide similar functionality --- docs/mm.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index 6a1f664..5315c8c 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -74,9 +74,9 @@ Existing files are not truncated on ouput and are instead overwritten. .SH RATIONALE -The cat(1p) and tee(1p) programs specified in POSIX together provide nearly -equivalent functionality. The separation of the two sets of functionality into -separate APIs seemed unncessary. +The cat(1p) and 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 From 13ee16173e46c09ba97fd35e6000a3455aaac174 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 29 Mar 2024 16:47:00 -0600 Subject: [PATCH 21/48] fop.1: initial commit --- docs/fop.1 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/fop.1 diff --git a/docs/fop.1 b/docs/fop.1 new file mode 100644 index 0000000..aa71b50 --- /dev/null +++ b/docs/fop.1 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte +.\" +.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, +.\" visit . + +.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 + +.B -d +.RS +Sets a delimiter by which the input data will be split into fields. The default +is an ASCII record separator (␞). +.RE + +.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 + +The idea for this utility originated in the fact that GNU ls(1) utility contains +a +.B -h +option which enables human-readable units in file size outputs. This +functionality was broken out into hru(1), but there was no easy way to modify +the field in the ouput of ls(1p) without a new tool. + +.SH COPYRIGHT + +Copyright © 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later +. + +.SH SEE ALSO + +sed(1p) From df16707b0e2c74217d7ea4aaaab0f45b6f0cff97 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:36:01 -0600 Subject: [PATCH 22/48] intcmp.1: -e permits adjacent integers to be equal to each other --- docs/intcmp.1 | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 6087d0e..b15f4c1 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -25,11 +25,7 @@ Compare integers to each other. .B -e .RS -Permits given integers to be equal to each other. If combined with -.B -g -or -.B -l -, only adjacent integers in the argument sequence can be equal. +Permits given integers to be equal to each other. .RE .B -g From 3cdade71e2019d754d85b53a680eef27b2fa2939 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:38:48 -0600 Subject: [PATCH 23/48] dj.1: -S whether or not the input is a stream is irrelevant --- docs/dj.1 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 0e882dd..e70c666 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -70,8 +70,7 @@ DIAGNOSTICS section below. .B -S .RS 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, null characters are printed. +the input. If the output is a stream, null characters are printed. .RE .B -a From ed284b9949eb9cc5a4fc2796e315d1c430fcce29 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:40:29 -0600 Subject: [PATCH 24/48] dj.1: -a: More specific wording --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index e70c666..41e3112 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -75,8 +75,8 @@ the input. If the output is a stream, null characters are printed. .B -a .RS -Takes one argument of one byte in length and pads the input buffer with it in -the event of an incomplete read from the input file. +Accepts a single literal byte with which input buffer is padded in the event +of an incomplete read from the input file. .RE .B -b From b41af1b578a912df0bd4484be2f2a7604e8e9312 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:41:55 -0600 Subject: [PATCH 25/48] dj.1: -c: grammar --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 41e3112..9bc2d82 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -87,8 +87,8 @@ default being 1024 bytes or one kibibyte (KiB). .B -c .RS -Specifies an amount of reads to make, and if 0 (the default) dj will -continue reading until a partial or empty read. +Specifies a number of reads to make. If set to zero (the default), reading will +continue until a partial or empty read is encountered. .RE .B -d From 187d9486b762006cbb1efb12a7d8a49ae54ed14a Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:44:44 -0600 Subject: [PATCH 26/48] dj.1: debug output clarification --- docs/dj.1 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 9bc2d82..175a32c 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -149,9 +149,10 @@ the following format: .R {ASCII record separator} {bytes written} {ASCII file separator} .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, the following format is used instead: +option may be specified. In this event, the following format is used instead: .RS .R {records read} '+' {partial records read} '>' {records written} From 432b19818ed625d6673c24e527a8502ffec5b689 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 28 Apr 2024 20:42:44 -0600 Subject: [PATCH 27/48] made dj options no longer alphabetized --- docs/dj.1 | 61 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 175a32c..429b7fc 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -47,11 +47,27 @@ dj .SH OPTIONS -.B -A +.B -i .RS -If the output is a stream, null bytes are printed. In other words, it does what -.B -a -does but with null bytes instead. +Takes a file path as an argument to open and use as an input. +.RE + +.B -b +.RS +Takes a numeric argument as the size in bytes of the input buffer, with the +default being 1024 bytes or one kibibyte (KiB). +.RE + +.B -s +.RS +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. +.RE + +.B -o +.RS +Takes a file path as an argument to open and use as an output. .RE .B -B @@ -61,12 +77,6 @@ Does the same as but for the output buffer. .RE -.B -H -.RS -Prints diagnostics messages in a human-readable manner as described in the -DIAGNOSTICS section below. -.RE - .B -S .RS Skips a number of bytes through the output before starting to write from @@ -79,18 +89,20 @@ Accepts a single literal byte with which input buffer is padded in the event of an incomplete read from the input file. .RE -.B -b -.RS -Takes a numeric argument as the size in bytes of the input buffer, with the -default being 1024 bytes or one kibibyte (KiB). -.RE - .B -c .RS Specifies a number of reads to make. If set to zero (the default), reading will continue until a partial or empty read is encountered. .RE +.B -A +.RS +If the output is a stream, null bytes are printed. This option is equivalent to +specifying +.B -a +with a null byte instead of a character. +.RE + .B -d .RS Prints invocation information before program execution as described in the @@ -98,9 +110,10 @@ DIAGNOSTICS section below. Each invocation increments the debug level of the program. .RE -.B -i +.B -H .RS -Takes a file path as an argument to open and use as an input. +Prints diagnostics messages in a human-readable manner as described in the +DIAGNOSTICS section below. .RE .B -n @@ -108,18 +121,6 @@ Takes a file path as an argument to open and use as an input. Retries failed reads once more before exiting. .RE -.B -o -.RS -Takes a file path as an argument to open and use as an output. -.RE - -.B -s -.RS -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. -.RE - .B -q .RS Suppresses error messages which print when a read or write is partial or From c53f3fa617d1bf628ac2b1874f043d769fdcc87a Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 09:53:54 -0600 Subject: [PATCH 28/48] dj.1: remove mention of KiB --- docs/dj.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index 429b7fc..1ebda2e 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -55,7 +55,7 @@ Takes a file path as an argument to open and use as an input. .B -b .RS Takes a numeric argument as the size in bytes of the input buffer, with the -default being 1024 bytes or one kibibyte (KiB). +default being 1024. .RE .B -s From d87f4b20a32f5b2ce49ce697b843eb749ca2d0bb Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 09:56:44 -0600 Subject: [PATCH 29/48] dj.1: -A: better description --- docs/dj.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1ebda2e..1473455 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -97,10 +97,10 @@ continue until a partial or empty read is encountered. .B -A .RS -If the output is a stream, null bytes are printed. This option is equivalent to -specifying +Specifying this option pads the input buffer with null bytes in the event of an +incomplete read. Equivalent to specifying .B -a -with a null byte instead of a character. +with a null byte instead of a character. .RE .B -d From 2137b0bf4342c5d63514f8946d15a395c08e29da Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:03:52 -0600 Subject: [PATCH 30/48] dj.1: -i: better description --- docs/dj.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1473455..1fd7a63 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -49,7 +49,7 @@ dj .B -i .RS -Takes a file path as an argument to open and use as an input. +Takes a file path as an argument and opens it for use as an input. .RE .B -b From b4173a23276ead1c1965a656c3bc06c58bd61f2c Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:06:15 -0600 Subject: [PATCH 31/48] dj.1: -o: better description --- docs/dj.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1fd7a63..49bf733 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -67,7 +67,7 @@ are discarded. .B -o .RS -Takes a file path as an argument to open and use as an output. +Takes a file path as an argument and opens it for use as an output. .RE .B -B From 0660db3d029ab12b58e77bba25e5be3cbfea7f42 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:13:17 -0600 Subject: [PATCH 32/48] dj.1: -c: better description --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 49bf733..e4399c3 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -91,8 +91,8 @@ of an incomplete read from the input file. .B -c .RS -Specifies a number of reads to make. If set to zero (the default), reading will -continue until a partial or empty read is encountered. +Specifies a number of reads to make. The default is zero, in which case the +input is read until a partial or empty read is made. .RE .B -A From 122a10257e472893389fd2678dda3134272d4782 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:13:59 -0600 Subject: [PATCH 33/48] dj.1: fixed option description locations --- docs/dj.1 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index e4399c3..2c2e634 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -89,12 +89,6 @@ Accepts a single literal byte with which input buffer is padded in the event of an incomplete read from the input file. .RE -.B -c -.RS -Specifies a number of reads to make. The default is zero, in which case the -input is read until a partial or empty read is made. -.RE - .B -A .RS Specifying this option pads the input buffer with null bytes in the event of an @@ -103,6 +97,12 @@ incomplete read. Equivalent to specifying with a null byte instead of a character. .RE +.B -c +.RS +Specifies a number of reads to make. The default is zero, in which case the +input is read until a partial or empty read is made. +.RE + .B -d .RS Prints invocation information before program execution as described in the From 922ee71283d0738b7c916f58eea45fb563c66aa5 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:14:53 -0600 Subject: [PATCH 34/48] dj.1: fixes standard input section grammar --- docs/dj.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 2c2e634..7534b6e 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -129,8 +129,8 @@ empty. Each invocation decrements the debug level of the program. .SH STANDARD INPUT -The standard input shall be used as an input if no inputs are specified one or -more of the input files is “-”. +The standard input shall be used as an input if no inputs are specified or if +one or more of the input files is “-”. .SH DIAGNOSTICS From b7f52902b6bde54876b5fd8efafa433e2cf0df9a Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 24 May 2024 10:21:06 -0600 Subject: [PATCH 35/48] dj.1: grammar & formatting --- docs/dj.1 | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 7534b6e..7af1c00 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -138,9 +138,9 @@ On a partial or empty read, a diagnostic message is printed (unless the .B -q option is specified) and the program exits (unless the .B -n -option is specified. +option is specified). -By default statistics are printed for input and output to the standard error in +By default, statistics are printed for input and output to the standard error in the following format: .RS @@ -163,9 +163,9 @@ option may be specified. In this event, the following format is used instead: 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 +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: @@ -183,29 +183,31 @@ sysexits.h(3) status. If .B -n -is specified along with a specified count, actual byte output may be lower than -expected (the product of the count multiplied by the input block size). If the +is specified along with 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. - -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. +options are used, this could make data written nonsensical. .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 dd(1p) utility as specified in POSIX. While character conversion may have been the original intent of dd(1p), it is -irrelevant to its modern use. Because of this, it 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’s easy to parse for machines. +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’s easy for machines to parse. .SH COPYRIGHT From 70cbc52c932e799b4b9e863d73adbdf95006184c Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 18:47:14 -0600 Subject: [PATCH 36/48] docs: updates to use man(7) macros to fix formatting --- docs/dj.1 | 119 ++++++++++++++++-------------------------------- docs/false.1 | 40 +++++++++-------- docs/fop.1 | 58 ++++++++++++------------ docs/hru.1 | 58 ++++++++++++------------ docs/intcmp.1 | 107 +++++++++++++++++++++---------------------- docs/mm.1 | 51 +++++++-------------- docs/npc.1 | 61 ++++++++++++------------- docs/rpn.1 | 85 +++++++++++++++++++---------------- docs/scrut.1 | 122 ++++++++++++++++++-------------------------------- docs/str.1 | 44 +++++++++--------- docs/strcmp.1 | 66 ++++++++++++++------------- docs/swab.1 | 54 +++++++++------------- docs/true.1 | 36 ++++++++------- 13 files changed, 406 insertions(+), 495 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 7af1c00..df660fa 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -3,15 +3,13 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH dj 1 - +.\" +.TH DJ 1 .SH NAME - dj \(en disk jockey - +.\" .SH SYNOPSIS - +.\" dj .RB ( -AdHnq ) .RB ( -a @@ -44,102 +42,63 @@ dj .R [ .B output offset .R ]) - +.\" .SH OPTIONS - -.B -i -.RS +.\" +.IP \fB-i\fP Takes a file path as an argument and opens it for use as an input. -.RE - -.B -b -.RS +.IP \fB-b\fP Takes a numeric argument as the size in bytes of the input buffer, with the default being 1024. -.RE - -.B -s -.RS +.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. -.RE - -.B -o -.RS +.IP \fB-o\fP Takes a file path as an argument and opens it for use as an output. -.RE - -.B -B -.RS +.IP \fB-B\fP Does the same as .B -b but for the output buffer. -.RE - -.B -S -.RS +.IP \fB-S\fP Skips a number of bytes through the output before starting to write from the input. If the output is a stream, null characters are printed. -.RE - -.B -a -.RS +.IP \fB-a\fP Accepts a single literal byte with which input buffer is padded in the event of an incomplete read from the input file. -.RE - -.B -A -.RS +.IP \fB-A\fP Specifying this option pads the input buffer with null bytes in the event of an incomplete read. Equivalent to specifying .B -a -with a null byte instead of a character. -.RE - -.B -c -.RS +with a null byte instead of a character. +.IP \fB-c\fP Specifies a number of reads to make. The default is zero, in which case the input is read until a partial or empty read is made. -.RE - -.B -d -.RS +.IP \fB-d\fP Prints invocation information before program execution as described in the DIAGNOSTICS section below. Each invocation increments the debug level of the program. -.RE - -.B -H -.RS +.IP \fB-H\fP Prints diagnostics messages in a human-readable manner as described in the DIAGNOSTICS section below. -.RE - -.B -n -.RS +.IP \fB-n\fP Retries failed reads once more before exiting. -.RE - -.B -q -.RS +.IP \fB-q\fP Suppresses error messages which print when a read or write is partial or empty. Each invocation decrements the debug level of the program. -.RE - .SH STANDARD INPUT - +.\" The standard input shall be used as an input if no inputs are specified or if -one or more of the input files is “-”. - +one or more of the input files is \(lq-\(rq. +.\" .SH DIAGNOSTICS - +.\" On a partial or empty read, a diagnostic message is printed (unless the .B -q option is specified) and the program exits (unless the .B -n option is specified). - +.\" By default, statistics are printed for input and output to the standard error in the following format: @@ -175,12 +134,12 @@ as the only argument: .R out= obs=1024 seek=0 debug= 3 noerror=0 .RE -In non-recoverable errors that don’t pertain to the read-write cycle, a +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 sysexits.h(3) status. - +.\" .SH BUGS - +.\" If .B -n is specified along with the @@ -191,29 +150,29 @@ of the count and the input block size). If the or .B -A options are used, this could make data written nonsensical. - +.\" .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 dd(1p) utility as specified in POSIX. While character conversion may have been the original intent of dd(1p), 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’s easy for machines to parse. - +printing in a format that\(cqs easy for machines to parse. +.\" .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 . - +.\" .SH SEE ALSO - -dd(1p) +.\" +.BR dd (1p) diff --git a/docs/false.1 b/docs/false.1 index b8463ae..5719899 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -3,32 +3,34 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .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 always be returned. - +.\" +Do nothing regardless of operands or standard input. An exit code of 1 will +always be returned. +.\" .SH RATIONALE - -In POSIX.1-2017, false(1p) exists for the construction of control flow and loops -based on a failure. This implementation functions as described in that standard. - +.\" +In POSIX.1-2017, +.BR false (1p) +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 . - +.\" +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 . - +.\" .SH SEE ALSO - -true(1p) +.\" +.BR true (1p) diff --git a/docs/fop.1 b/docs/fop.1 index aa71b50..75a956d 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -3,58 +3,58 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .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 - -.B -d -.RS +.\" +.IP \fB-d\fP Sets a delimiter by which the input data will be split into fields. The default is an ASCII record separator (␞). -.RE - .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 +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 GNU ls(1) utility contains -a +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 hru(1), but there was no easy way to modify -the field in the ouput of ls(1p) without a new tool. - +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 © 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later +.\" +Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -sed(1p) +.\" +.BR sed (1p) diff --git a/docs/hru.1 b/docs/hru.1 index 1ffc00e..f87be16 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -2,58 +2,60 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH hru 1 - +.\" +.TH HRU 1 .SH NAME - hru \(en human readable units - +.\" .SH SYNOPSIS - +.\" hru - +.\" .SH DESCRIPTION - +.\" Convert counts to higher 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 +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, the program will exit with the appropriate error code as defined by 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 ls(1) implementation contains a human-readable option (-h) that, when specified, makes the tool print size information in a format more immediately readable. This functionality is useful not only in the context of ls(1) so the decision was made to split it into a new tool. The original -functionality in GNU’s ls(1) can be emulated with fop(1) combined with this +functionality in GNU\(cqs ls(1) can be emulated with fop(1) combined with this program. - +.\" .SH STANDARDS - +.\" The standard unit prefixes as specified by the Bureau International des Poids et Mesures (BIPM) in the ninth edition of The International System of Units (SI) are utilized for the ouput of conversions. - +.\" .SH AUTHOR - -Written by Emma Tebibyte . - +.\" +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 . - +.\" .SH SEE ALSO - -GNU ls(1), The International System of Units (SI) 9th Edition +.\" +GNU +.BR ls (1), +The International System of Units (SI) 9th Edition diff --git a/docs/intcmp.1 b/docs/intcmp.1 index b15f4c1..79902b9 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -3,90 +3,87 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH intcmp 1 - +.\" +.TH INTCMP 1 .SH NAME - intcmp \(en compare integers - +.\" .SH SYNOPSIS - +.\" intcmp .RB ( -egl ) .RB [ integer ] .RB [ integer... ] - .SH DESCRIPTION - Compare integers to each other. - -.SH USAGE - -.B -e -.RS +.SH OPTIONS +.IP \fB-e\fP Permits given integers to be equal to each other. -.RE - -.B -g -.RS +.IP \fB-g\fP Permits a given integer to be greater than the following integer. -.RE - -.B -l -.RS +.IP \fB-l\fP Permits a given integer to be less than the following integer. -.RE - .SH EXAMPLES - +.\" 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. The following example is -equivalent to evaluating “1 < 2 < 3”: +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 .R intcmp -l 1 2 3 .RE - +.\" .SH DIAGNOSTICS - +.\" The program will exit with a status code of 0 for a valid expression and with a code of 1 for an invalid expression. In the event of an error, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. - +exit with the appropriate +.BR sysexits.h (3) +error code. +.\" .SH BUGS +.\" +-egl, \(lqequal to or less than or greater than\(rq, exits 0 no matter what for +valid program usage and may be abused to function as an integer validator. Use +.BR str (1) +instead. +.\" +.SH CAVEATS +.\" +There are multiple ways to express compound comparisons; \(lqless than or equal +to\(rq can be -le or -el, for example. -There are multiple ways to express compound comparisons; “less than or equal -to” can be -le or -el, for example. - -The inequality comparison is -gl or -lg for “less than or greater than”; this -is elegant but unintuitive. - --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. - +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. -These parts of its functionality have been broken out into multiple utilities. - -This program’s functionality may be performed on a POSIX-compliant system with -test(1p). +been +.BR test (1). +This tool also handles string comparisons and file scrutiny. These parts of its +functionality have been broken out into multiple utilities. +This program\(cqs functionality may be performed on a POSIX-compliant system +with +.BR test (1p). +.\" .SH AUTHOR - -Written by DTB . - +.\" +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 . - +.\" .SH SEE ALSO - -strcmp(1), scrut(1), str(1), test(1p) +.BR scrut (1), +.BR strcmp (1), +.BR str (1), +.BR test (1p) diff --git a/docs/mm.1 b/docs/mm.1 index 5315c8c..72ce9a1 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -2,62 +2,41 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .TH mm 1 - .SH NAME - mm \(en middleman - .SH SYNOPSIS - +.\" mm .RB ( -aenu ) .RB ( -i .RB [ input ]) .RB ( -o .RB [ output ]) - +.\" .SH DESCRIPTION - +.\" Catenate input files and write them to the start of each output file or stream. - +.\" .SH OPTIONS - -.B -a -.RS +.\" +.IP -a Opens subsequent outputs for appending rather than updating. -.RE - -.B -e -.RS +.IP -e Use the standard error as an output. -.RE - -.B -i -.RS +.IP -i Opens a path as an input. Without any inputs specified mm will use the standard input. The standard input shall be used as an input if one or more of the input files is “-”. -.RE - -.B -o -.RS +.IP -o Opens a path as an output. Without any outputs specified mm will use the standard output. The standard output shall be used as an output if one or more of the output files is “-”. - -.RE - -.B -u -.RS +.IP -u Ensures neither input or output will be buffered. -.RE - -.B -n -.RS +.IP -n Causes SIGINT signals to be ignored. -.RE .SH DIAGNOSTICS @@ -84,5 +63,7 @@ Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . .SH SEE ALSO - -cat(1p), dd(1), dj(1), tee(1p) +.BR cat (1p), +.BR dd (1), +.BR dj (1), +.BR tee (1p) diff --git a/docs/npc.1 b/docs/npc.1 index f3b7d0c..a75db5e 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -3,20 +3,18 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH npc 1 - +.\" +.TH NPC 1 .SH NAME - npc \(en show non-printing characters - +.\" .SH SYNOPSIS - +.\" npc .RB ( -et ) - +.\" .SH DESCRIPTION - +.\" Print normally non-printing characters. The program reads from standard input and writes to standard output, replacing @@ -26,41 +24,43 @@ 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. - +.\" .SH USAGE - -.B -e -.RS +.\" +.IP -e Prints a currency sign ('$') before each line ending. -.RE - -.B -t -.RS +.IP -t Prints tab characters as '^I' rather than a literal horizontal tab. -.RE - +.\" .SH DIAGNOSTICS - +.\" In the event of an error, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. - +exit with the appropriate +.BR sysexits.h (3) +error code. +.\" .SH BUGS - +.\" The program 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 cat(1p), the +using a standard tool. A popular extension to +.BR cat (1p), +the .B -v option, is the bandage solution GNU and other software suites use. - +.\" This functionality is a separate tool because its usefulness extends beyond that -of cat(1p). - +of +.BR cat (1p). +.\" .SH AUTHOR -Written by DTB . +Written by DTB +.MT trinity@trinity.moe +.ME . .SH COPYRIGHT @@ -69,7 +69,8 @@ Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later .SH SEE ALSO -cat(1p), cat-v(1) +.BR cat (1p), +.BR cat-v (1) .I UNIX Style, or cat -v Considered Harmful by Rob Pike diff --git a/docs/rpn.1 b/docs/rpn.1 index 0b6b264..53a8a9f 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -3,20 +3,19 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .TH rpn 1 - .SH NAME - rpn \(en reverse polish notation evaluation - +.\" .SH SYNOPSIS - +.\" rpn -.RB [numbers...]\ [operators...] - +.RB [ numbers... ] +.RB [ operators... ] +.\" .SH DESCRIPTION - +.\" Evaluate reverse polish notation. The program evaluates reverse polish notation expressions either read from the @@ -28,48 +27,58 @@ standard output. Any further specified numbers will be placed at the end of the stack. For information on for reverse polish notation syntax, see rpn(7). - +.\" .SH STANDARD INPUT - -If arguments are passed , they are interpreted as an expression to be evaluated. -Otherwise, it reads whitespace-delimited numbers and operations from the -standard input. - +.\" +If arguments are passed, they are interpreted as an expression to be +evaluated. Otherwise, it reads whitespace-delimited numbers and operations from +the standard input. +.\" .SH DIAGNOSTICS - +.\" In the event of a syntax error, the program will print an In the event of an error, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. - +exit with the appropriate +.BR sysexits.h(3) +error code. +.\" .SH CAVEATS - +.\" Due to precision constraints and the way floats are represented in accordance -with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point -arithmetic has rounding errors. This is somewhat curbed by using the -machine epsilon as provided by the Rust standard library to which to round +with the IEEE Standard for Floating Point Arithmetic (\fIIEEE 754\fP), +floating-point arithmetic has rounding errors. This is somewhat curbed by using +the machine epsilon as provided by the Rust standard library to which to round numbers. Because of this, variation is expected in 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, bc(1p), is included in the POSIX -standard, but does not accept expressions as arguments; in scripts, any -predefined, non-interactive input must be piped into the program. A dc(1) -pre-dates the standardized bc(1p), the latter originally being a preprocessor -for the former, and was included in UNIX v2 onward. While it implements reverse -polish notation, it still suffers from being unable to accept an expression as -an argument. - +.\" +An infix notation calculation utility, +.BR bc (1p), +is included in the POSIX standard, but does not accept expressions as arguments; +in scripts, any predefined, non-interactive input must be piped into the +program. A +.BR dc (1) +pre-dates the standardized +.BR bc (1p), +the latter originally being a preprocessor for the former, and was included in +UNIX v2 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 +.MT emma@tebibyte.media +.ME . +.\" .SH COPYRIGHT - +.\" Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -bc(1p), dc(1), rpn(7), IEEE 754 +.BR bc (1p), +.BR dc (1), +.BR rpn(7), +.I IEEE 754 diff --git a/docs/scrut.1 b/docs/scrut.1 index 4c0b75b..e6973ad 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -3,122 +3,86 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .TH scrut 1 - .SH NAME - scrut \(en scrutinize file properties - .SH SYNOPSIS - +.\" scrut .RB ( -bcdefgkprsuwxLS ) .RB [ file... ] - +.\" .SH DESCRIPTION - +.\" Determine if files comply with requirements. - +.\" .SH OPTIONS - -.B -L -.RS +.\" +.IP -L Requires the given files to exist and be symbolic links. -.RE - -.B -S -.RS +.IP -S Requires the given files to exist and be sockets. -.RE - -.B -b -.RS +.IP -b Requires the given files to exist and be block special files. -.RE - -.B -c -.RS +.IP -c Requires the given files to exist and be character special files. -.RE - -.B -d -.RS +.IP -d Requires the given files to exist and be directories. -.RE - -.B -e -.RS +.IP -e Requires the given files to exist, and is redundant to any other option. -.RE - -.B -e -.RS +.IP -e Requires the given files to exist and be regular files. -.RE - -.B -g -.RS +.IP -g Requires the given files to exist and have their set group ID flags set. -.RE - -.B -k -.RS +.IP -k Requires the given files to exist and have their sticky bit set. -.RE - -.B -p -.RS +.IP -p Requires the given files to exist and be named pipes. -.RE - -.B -r -.RS +.IP -r Requires the given files to exist and be readable. -.RE - -.B -u -.RS +.IP -u Requires the given files to exist and have their set user ID flags set. -.RE - -.B -w -.RS +.IP -w Requires the given files to exist and be writable. -.RE - -.B -x -.RS +.IP -x Requires the given files to exist and be executable. -.RE - -.SH EXIT STATUS - +.\" +.SH DIAGNOSTICS +.\" If the given files comply with the specified requirements, the program will exit successfully. If not, it exits unsuccessfully. When invoked incorrectly, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. - -.SH STANDARDS - -The test(1p) utility contains functionality that was broken out into separate -programs. Thus, the scope of this program is narrower than it. Notably, the +exit with the appropriate +.BR sysexits.h (3) +error code. +.\" +.SH RATIONALE +.\" +The +.BR test (1p) +utility contains functionality that was broken out into separate programs. Thus, +the scope of this program is narrower than it. 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 +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT -Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . .SH SEE ALSO -access(3p), lstat(3p), test(1p) +.BR access (3p), +.BR lstat (3p), +.BR test (1p) diff --git a/docs/str.1 b/docs/str.1 index ef86861..641a75f 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -3,28 +3,27 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .TH STR 1 - .SH NAME - str \(en test the character types of string arguments - +.\" .SH SYNOPSIS - +.\" str .RB [ type ] .RB [ string... ] - +.\" .SH DESCRIPTION - +.\" Test string arguments. The tests in this program are equivalent to the functions with the same names in -ctype.h(0p) and are the methods by which string arguments are tested. - +.BR ctype.h (0p) +and are the methods by which string arguments are tested. +.\" .SH DIAGNOSTICS - +.\" If all tests pass, the program will exit with an exit code of 0. If any of the tests fail, the program will exit unsuccessfully with an error code of 1. @@ -33,23 +32,26 @@ tests. When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. - -.SH BUGS - +.\" +.SH CAVEATS +.\" There’s no way of knowing which argument failed the test without re-testing arguments individually. If a character in a string isn't valid ASCII str will exit unsuccessfully. - +.\" .SH AUTHOR - -Written by DTB . - +.\" +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT - +.\" Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -ctype(3p), strcmp(1), ascii(7) +.BR ctype (3p), +.BR strcmp(1), +.BR ascii(7) diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 48681c6..1cc03dd 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -3,61 +3,63 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .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. - +.\" .SH DIAGNOSTICS - +.\" The program will exit successfully if the strings are identical. Otherwise, it 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 -). +later string (e.g. strcmp b a) and 255 if an earlier string has a lesser byte +value (e.g. strcmp a b). When invoked incorrectly, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. - -.SH UNICODE - +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 test(1). This tool also handles integer comparisons and file scrutiny. -These parts of its functionality have been broken out into multiple utilities. +been +.BR test (1). +This tool also handles integer comparisons and file scrutiny. These parts of its +functionality have been broken out into multiple utilities. This program’s functionality may be performed on a POSIX-compliant system with -test(1p). - +.BR test (1p). +.\" .SH AUTHOR - -Written by DTB . - +.\" +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT - +.\" Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -strcmp(3), intcmp(1), scrut(1), test(1p) +.BR strcmp (3), +.BR intcmp (1), +.BR scrut (1), +.BR test (1p) diff --git a/docs/swab.1 b/docs/swab.1 index f7e10b0..078dd54 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -3,43 +3,36 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH swab 1 - +.\" +.TH SWAB 1 .SH NAME - swab \(en swap bytes - +.\" .SH SYNOPSIS - +.\" swab .RB ( -f ) .RB ( -w .R [ .B word size .R ]) - +.\" .SH USAGE - +.\" Swap the latter and former halves of a block of bytes. - +.\" .SH OPTIONS - -.B -f -.RS +.\" +.IP -f Ignore system call interruptions. -.RE - -.B -w -.RS +.IP -w 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. -.RE - +.\" .SH EXAMPLES - +.\" The following sh(1p) line: .RS @@ -51,27 +44,24 @@ Produces the following output: .RS .R ehll oowlr!d .RE - +.\" .SH DIAGNOSTICS - +.\" In the event of an error, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. - +.\" .SH RATIONALE - -This program was modeled and named after the -.R conv=swab -functionality specified in the dd(1p) utility. It additionally allows the word -size to be configured. +.\" +This program was modeled and named after the conv=swab functionality specified +in the dd(1p) utility. It additionally allows the word size to be configured. This functionality is useful for fixing the endianness of binary files produced on other machines. - +.\" .SH COPYRIGHT - +.\" Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -dd(1p) +.BR dd (1p) diff --git a/docs/true.1 b/docs/true.1 index 9b02fdd..1025c21 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -3,32 +3,34 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .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 always be returned. - +.\" .SH RATIONALE - -In POSIX.1-2017, true(1p) exists for the construction of control flow and loops -based on a success. This implementation functions as described in that standard. - +.\" +In \fIPOSIX.1-2017\fP, +.BR true (1p) +exists for the construction of control flow and loops based on a success. This +implementation functions as described in that standard. +.\" .SH AUTHOR - -Written by Emma Tebibyte . - +.\" +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 . - +.\" .SH SEE ALSO - -false(1p) +.BR false (1p), +.BR true (1p) From c32c554e03f8f7fdd62bbf981bbf70e3fe318f71 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:07:19 -0600 Subject: [PATCH 37/48] docs: removed unnecessary comments --- docs/dj.1 | 19 +++++++++---------- docs/false.1 | 9 ++++----- docs/fop.1 | 15 +++++++-------- docs/hru.1 | 19 +++++++++---------- docs/intcmp.1 | 17 ++++++++++------- docs/mm.1 | 17 +++++++++-------- docs/npc.1 | 19 +++++++++---------- docs/rpn.1 | 16 ++++++++-------- docs/scrut.1 | 15 +++++++-------- docs/str.1 | 12 ++++++------ docs/strcmp.1 | 14 +++++++------- docs/swab.1 | 14 +++++++------- docs/true.1 | 8 ++++---- 13 files changed, 96 insertions(+), 98 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index df660fa..21f0e1d 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -9,7 +9,7 @@ dj \(en disk jockey .\" .SH SYNOPSIS -.\" + dj .RB ( -AdHnq ) .RB ( -a @@ -44,7 +44,7 @@ dj .R ]) .\" .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 @@ -87,18 +87,18 @@ Retries failed reads once more before exiting. Suppresses error messages which print when a read or write is partial or empty. Each invocation decrements the debug level of the program. .SH STANDARD INPUT -.\" + 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 -.\" + On a partial or empty read, a diagnostic message is printed (unless the .B -q option is specified) and the program exits (unless the .B -n option is specified). -.\" + By default, statistics are printed for input and output to the standard error in the following format: @@ -139,7 +139,7 @@ diagnostic message is printed and the program exits with the appropriate sysexits.h(3) status. .\" .SH BUGS -.\" + If .B -n is specified along with the @@ -152,7 +152,7 @@ or options are used, this could make data written nonsensical. .\" .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 @@ -160,7 +160,7 @@ confusing. Capitalized options tend to affect output or are more intense versions of lowercase options. .\" .SH RATIONALE -.\" + This program was based on the dd(1p) utility as specified in POSIX. While character conversion may have been the original intent of dd(1p), it is irrelevant to its modern use. Because of this, this program eschews character @@ -169,10 +169,9 @@ 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 . .\" .SH SEE ALSO -.\" .BR dd (1p) diff --git a/docs/false.1 b/docs/false.1 index 5719899..91bd286 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -9,28 +9,27 @@ false \(en do nothing, unsuccessfully .\" .SH DESCRIPTION -.\" + Do nothing regardless of operands or standard input. An exit code of 1 will always be returned. .\" .SH RATIONALE -.\" + In POSIX.1-2017, .BR false (1p) 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 .MT emma@tebibyte.media .ME . .\" .SH COPYRIGHT -.\" + This work is marked with CC0 1.0. To see a copy of this license, visit . .\" .SH SEE ALSO -.\" .BR true (1p) diff --git a/docs/fop.1 b/docs/fop.1 index 75a956d..29ba7ea 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -9,7 +9,7 @@ fop \(en field operator .\" .SH SYNOPSIS -.\" + fop .RB ( -d ) .RB [ delimiter ] @@ -17,24 +17,24 @@ fop .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. @@ -51,10 +51,9 @@ but there was no easy way to modify the field in the ouput of without creating a new tool. .\" .SH COPYRIGHT -.\" + Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later . .\" .SH SEE ALSO -.\" .BR sed (1p) diff --git a/docs/hru.1 b/docs/hru.1 index f87be16..984222a 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -8,28 +8,28 @@ hru \(en human readable units .\" .SH SYNOPSIS -.\" + hru .\" .SH DESCRIPTION -.\" + Convert counts to higher 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, the program will exit with the appropriate error code as defined by sysexits.h(3) and print an error message. .\" .SH RATIONALE -.\" + The GNU project\(cqs ls(1) implementation contains a human-readable option (-h) that, when specified, makes the tool print size information in a format more immediately readable. This functionality is useful not only in the context of @@ -38,24 +38,23 @@ functionality in GNU\(cqs ls(1) can be emulated with fop(1) combined with this program. .\" .SH STANDARDS -.\" + The standard unit prefixes as specified by the Bureau International des Poids et Mesures (BIPM) in the ninth edition of The International System of Units (SI) are utilized for the ouput of conversions. .\" .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 . .\" .SH SEE ALSO -.\" GNU .BR ls (1), The International System of Units (SI) 9th Edition diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 79902b9..ed88038 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -9,22 +9,25 @@ intcmp \(en compare integers .\" .SH SYNOPSIS -.\" + intcmp .RB ( -egl ) .RB [ integer ] .RB [ integer... ] .SH DESCRIPTION Compare integers to each other. +.\" .SH OPTIONS + .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 EXAMPLES + It may help to think of the -e, -g, and -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 @@ -35,7 +38,7 @@ example is equivalent to evaluating \(lq1 < 2 < 3\(rq: .RE .\" .SH DIAGNOSTICS -.\" + The program will exit with a status code of 0 for a valid expression and with a code of 1 for an invalid expression. @@ -45,14 +48,14 @@ exit with the appropriate error code. .\" .SH BUGS -.\" + -egl, \(lqequal to or less than or greater than\(rq, exits 0 no matter what for valid program usage and may be abused to function as an integer validator. Use .BR str (1) instead. .\" .SH CAVEATS -.\" + There are multiple ways to express compound comparisons; \(lqless than or equal to\(rq can be -le or -el, for example. @@ -60,7 +63,7 @@ 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 .BR test (1). @@ -72,7 +75,7 @@ with .BR test (1p). .\" .SH AUTHOR -.\" + Written by DTB .MT trinity@trinity.moe .ME . diff --git a/docs/mm.1 b/docs/mm.1 index 72ce9a1..c971c00 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -6,8 +6,9 @@ .TH mm 1 .SH NAME mm \(en middleman -.SH SYNOPSIS .\" +.SH SYNOPSIS + mm .RB ( -aenu ) .RB ( -i @@ -16,11 +17,11 @@ mm .RB [ output ]) .\" .SH DESCRIPTION -.\" + Catenate input files and write them to the start of each output file or stream. .\" .SH OPTIONS -.\" + .IP -a Opens subsequent outputs for appending rather than updating. .IP -e @@ -37,7 +38,7 @@ of the output files is “-”. Ensures neither input or output will be buffered. .IP -n Causes SIGINT signals to be ignored. - +.\" .SH DIAGNOSTICS If an output can no longer be written mm prints a diagnostic message, ceases @@ -46,22 +47,22 @@ continues, eventually exiting unsuccessfully. When an error is encountered, diagnostic message is printed and the program exits with the appropriate sysexits.h(3) status. - +.\" .SH CAVEATS Existing files are not truncated on ouput and are instead overwritten. - +.\" .SH RATIONALE The cat(1p) and 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 (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO .BR cat (1p), .BR dd (1), diff --git a/docs/npc.1 b/docs/npc.1 index a75db5e..64f3406 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -9,12 +9,12 @@ npc \(en show non-printing characters .\" .SH SYNOPSIS -.\" + npc .RB ( -et ) .\" .SH DESCRIPTION -.\" + Print normally non-printing characters. The program reads from standard input and writes to standard output, replacing @@ -26,32 +26,32 @@ followed by the graphical representation for the same character without the high bit set. .\" .SH USAGE -.\" + .IP -e Prints a currency sign ('$') before each line ending. .IP -t 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 exit with the appropriate .BR sysexits.h (3) error code. .\" .SH BUGS -.\" + The program 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 .BR cat (1p), the .B -v option, is the bandage solution GNU and other software suites use. -.\" + This functionality is a separate tool because its usefulness extends beyond that of .BR cat (1p). @@ -61,14 +61,13 @@ of Written by DTB .MT trinity@trinity.moe .ME . - +.\" .SH COPYRIGHT Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - .BR cat (1p), .BR cat-v (1) diff --git a/docs/rpn.1 b/docs/rpn.1 index 53a8a9f..c791613 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -9,13 +9,13 @@ rpn \(en reverse polish notation evaluation .\" .SH SYNOPSIS -.\" + rpn .RB [ numbers... ] .RB [ operators... ] .\" .SH DESCRIPTION -.\" + Evaluate reverse polish notation. The program evaluates reverse polish notation expressions either read from the @@ -29,13 +29,13 @@ stack. For information on for reverse polish notation syntax, see rpn(7). .\" .SH STANDARD INPUT -.\" + If arguments are passed, they are interpreted as an expression to be evaluated. Otherwise, it reads whitespace-delimited numbers and operations from the standard input. .\" .SH DIAGNOSTICS -.\" + In the event of a syntax error, the program will print an In the event of an error, a debug message will be printed and the program will @@ -44,7 +44,7 @@ exit with the appropriate error code. .\" .SH CAVEATS -.\" + Due to precision constraints and the way floats are represented in accordance with the IEEE Standard for Floating Point Arithmetic (\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is somewhat curbed by using @@ -53,7 +53,7 @@ numbers. Because of this, variation is expected in 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, .BR bc (1p), is included in the POSIX standard, but does not accept expressions as arguments; @@ -67,13 +67,13 @@ UNIX v2 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 .MT emma@tebibyte.media .ME . .\" .SH COPYRIGHT -.\" + Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later . .\" diff --git a/docs/scrut.1 b/docs/scrut.1 index e6973ad..52d96ed 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -8,17 +8,17 @@ .SH NAME scrut \(en scrutinize file properties .SH SYNOPSIS -.\" + scrut .RB ( -bcdefgkprsuwxLS ) .RB [ file... ] .\" .SH DESCRIPTION -.\" + Determine if files comply with requirements. .\" .SH OPTIONS -.\" + .IP -L Requires the given files to exist and be symbolic links. .IP -S @@ -49,7 +49,7 @@ Requires the given files to exist and be writable. Requires the given files to exist and be executable. .\" .SH DIAGNOSTICS -.\" + If the given files comply with the specified requirements, the program will exit successfully. If not, it exits unsuccessfully. @@ -59,7 +59,7 @@ exit with the appropriate error code. .\" .SH RATIONALE -.\" + The .BR test (1p) utility contains functionality that was broken out into separate programs. Thus, @@ -71,7 +71,7 @@ alias to the modern option. .\" .SH AUTHOR -.\" + Written by DTB .MT trinity@trinity.moe .ME . @@ -80,9 +80,8 @@ Written by DTB Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - .BR access (3p), .BR lstat (3p), .BR test (1p) diff --git a/docs/str.1 b/docs/str.1 index 641a75f..d40eafa 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -9,13 +9,13 @@ str \(en test the character types of string arguments .\" .SH SYNOPSIS -.\" + str .RB [ type ] .RB [ string... ] .\" .SH DESCRIPTION -.\" + Test string arguments. The tests in this program are equivalent to the functions with the same names in @@ -23,7 +23,7 @@ The tests in this program are equivalent to the functions with the same names in and are the methods by which string arguments are tested. .\" .SH DIAGNOSTICS -.\" + If all tests pass, the program will exit with an exit code of 0. If any of the tests fail, the program will exit unsuccessfully with an error code of 1. @@ -34,20 +34,20 @@ When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. .\" .SH CAVEATS -.\" + There’s no way of knowing which argument failed the test without re-testing arguments individually. If a character in a string isn't valid ASCII str will exit unsuccessfully. .\" .SH AUTHOR -.\" + Written by DTB .MT trinity@trinity.moe .ME . .\" .SH COPYRIGHT -.\" + Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . .\" diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 1cc03dd..768be0f 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -9,17 +9,17 @@ strcmp \(en compare strings .\" .SH SYNOPSIS -.\" + strcmp .RM [ string ] .RB [ strings... ] .\" .SH DESCRIPTION -.\" + Check whether string arguments are the same. .\" .SH DIAGNOSTICS -.\" + The program will exit successfully if the strings are identical. Otherwise, it exits with the value 1 if an earlier string has a greater byte value than a later string (e.g. strcmp b a) and 255 if an earlier string has a lesser byte @@ -31,13 +31,13 @@ exit with the appropriate 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 .BR test (1). @@ -48,13 +48,13 @@ This program’s functionality may be performed on a POSIX-compliant system with .BR test (1p). .\" .SH AUTHOR -.\" + Written by DTB .MT trinity@trinity.moe .ME . .\" .SH COPYRIGHT -.\" + Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . .\" diff --git a/docs/swab.1 b/docs/swab.1 index 078dd54..b1a0834 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -9,7 +9,7 @@ swab \(en swap bytes .\" .SH SYNOPSIS -.\" + swab .RB ( -f ) .RB ( -w @@ -18,11 +18,11 @@ swab .R ]) .\" .SH USAGE -.\" + Swap the latter and former halves of a block of bytes. .\" .SH OPTIONS -.\" + .IP -f Ignore system call interruptions. .IP -w @@ -32,7 +32,7 @@ cleanly divisible by 2, otherwise the block of bytes being processed can't be halved. .\" .SH EXAMPLES -.\" + The following sh(1p) line: .RS @@ -46,12 +46,12 @@ Produces the following output: .RE .\" .SH DIAGNOSTICS -.\" + In the event of an error, a debug message will be printed and the program will exit with the appropriate sysexits.h(3) error code. .\" .SH RATIONALE -.\" + This program was modeled and named after the conv=swab functionality specified in the dd(1p) utility. It additionally allows the word size to be configured. @@ -59,7 +59,7 @@ This functionality is useful for fixing the endianness of binary files produced on other machines. .\" .SH COPYRIGHT -.\" + Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . .\" diff --git a/docs/true.1 b/docs/true.1 index 1025c21..ac2e222 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -9,25 +9,25 @@ true \(en do nothing, successfully .\" .SH DESCRIPTION -.\" + Do nothing regardless of operands or standard input. An exit code of 0 will always be returned. .\" .SH RATIONALE -.\" + In \fIPOSIX.1-2017\fP, .BR true (1p) exists for the construction of control flow and loops based on a success. This implementation functions as described in that standard. .\" .SH AUTHOR -.\" + 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 . .\" From e7ba74013b9cbaed29334cc540a607e95ad618b3 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:21:00 -0600 Subject: [PATCH 38/48] dj.1: fixes man page reference formatting --- docs/dj.1 | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 21f0e1d..ea73a75 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -161,12 +161,15 @@ versions of lowercase options. .\" .SH RATIONALE -This program was based on the dd(1p) utility as specified in POSIX. While -character conversion may have been the original intent of dd(1p), 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. +This program was based on the +.BR dd (1p) +utility as specified in POSIX. While character conversion may have been the +original intent of +.BR dd (1p), +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 From beff2d98c672cf3696db6aff4b5a25d757cf7cdd Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:45:26 -0600 Subject: [PATCH 39/48] mm.1: fixed manpage reference formatting --- docs/mm.1 | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index c971c00..ef0336a 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -46,7 +46,9 @@ writing to that particular output, and if there are more outputs specified, continues, eventually exiting unsuccessfully. When an error is encountered, diagnostic message is printed and the program -exits with the appropriate sysexits.h(3) status. +exits with the appropriate +.BR sysexits.h (3) +status. .\" .SH CAVEATS @@ -54,9 +56,13 @@ Existing files are not truncated on ouput and are instead overwritten. .\" .SH RATIONALE -The cat(1p) and tee(1p) programs specified in POSIX together provide similar -functionality. The separation of the two sets of functionality into separate -APIs seemed unncessary. +The +.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 From fec61fee1b2009dd095d79be567a6a478a874519 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:47:14 -0600 Subject: [PATCH 40/48] swab.1: fixes formatting --- docs/swab.1 | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/swab.1 b/docs/swab.1 index b1a0834..90b50b0 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -23,9 +23,9 @@ Swap the latter and former halves of a block of bytes. .\" .SH OPTIONS -.IP -f +.IP \fB-f\fP Ignore system call interruptions. -.IP -w +.IP \fB-w\fP 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 @@ -33,7 +33,9 @@ halved. .\" .SH EXAMPLES -The following sh(1p) line: +The following +.Br sh (1p) +line: .RS .R printf 'hello world!\n' | swab @@ -48,12 +50,16 @@ Produces the following output: .SH DIAGNOSTICS In the event of an error, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. +exit with the appropriate +.BR sysexits.h (3) +error code. .\" .SH RATIONALE This program was modeled and named after the conv=swab functionality specified -in the dd(1p) utility. It additionally allows the word size to be configured. +in the +.BR dd (1p) +utility. It additionally allows the word size to be configured. This functionality is useful for fixing the endianness of binary files produced on other machines. From 896b251434bc544fc548bff69b63593d2b214018 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:52:28 -0600 Subject: [PATCH 41/48] hru.1: fixes formatting --- docs/hru.1 | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/hru.1 b/docs/hru.1 index 984222a..c3a5cdc 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -25,23 +25,30 @@ value is greater than one. .SH DIAGNOSTICS If encountering non-integer characters in the standard input, the program will -exit with the appropriate error code as defined by sysexits.h(3) and print an -error message. +exit with the appropriate error code as defined by +.BR sysexits.h (3) +and print an error message. .\" .SH RATIONALE -The GNU project\(cqs ls(1) implementation contains a human-readable option (-h) -that, when specified, makes the tool print size information in a format more -immediately readable. This functionality is useful not only in the context of -ls(1) so the decision was made to split it into a new tool. The original -functionality in GNU\(cqs ls(1) can be emulated with fop(1) combined with this -program. +The GNU project\(cqs +.BR ls (1) +implementation contains a human-readable option (\fB-h\fP) that, when specified, +makes the tool print size information in a format more immediately readable. +This functionality is useful not only in the context of +.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 The standard unit prefixes as specified by the Bureau International des Poids -et Mesures (BIPM) in the ninth edition of The International System of Units -(SI) are utilized for the ouput of conversions. +et Mesures (BIPM) in the ninth edition of The International System of Units (SI) +are utilized for the ouput of conversions. .\" .SH AUTHOR From f4cad598c467c07f2a7d3014e70093a85103eed6 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 4 Jun 2024 16:11:33 -0600 Subject: [PATCH 42/48] docs: formatting --- docs/intcmp.1 | 2 +- docs/mm.1 | 18 +++++++++--------- docs/npc.1 | 7 +++---- docs/rpn.1 | 7 ++++--- docs/scrut.1 | 30 +++++++++++++++--------------- docs/str.1 | 11 +++++++---- docs/strcmp.1 | 20 +++++++++++++++----- docs/swab.1 | 6 +++--- 8 files changed, 57 insertions(+), 44 deletions(-) diff --git a/docs/intcmp.1 b/docs/intcmp.1 index ed88038..905d31d 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -32,7 +32,7 @@ It may help to think of the -e, -g, and -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 .R intcmp -l 1 2 3 .RE diff --git a/docs/mm.1 b/docs/mm.1 index ef0336a..58bc26e 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -22,21 +22,21 @@ Catenate input files and write them to the start of each output file or stream. .\" .SH OPTIONS -.IP -a +.IP \fB-a\fP Opens subsequent outputs for appending rather than updating. -.IP -e +.IP \fB-e\fP Use the standard error as an output. -.IP -i +.IP \fB-i\fP Opens a path as an input. Without any inputs specified mm will use the standard input. The standard input shall be used as an input if one or more of -the input files is “-”. -.IP -o +the input files is \(lq-\(rq. +.IP \fB-o\fP Opens a path as an output. Without any outputs specified mm will use the standard output. The standard output shall be used as an output if one or more -of the output files is “-”. -.IP -u +of the output files is \(lq-\(rq. +.IP \fB-u\fP Ensures neither input or output will be buffered. -.IP -n +.IP \fB-n\fP Causes SIGINT signals to be ignored. .\" .SH DIAGNOSTICS @@ -66,7 +66,7 @@ unncessary. .\" .SH COPYRIGHT -Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . .\" .SH SEE ALSO diff --git a/docs/npc.1 b/docs/npc.1 index 64f3406..e18e4ff 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -27,9 +27,9 @@ high bit set. .\" .SH USAGE -.IP -e +.IP \fB-e\fP Prints a currency sign ('$') before each line ending. -.IP -t +.IP \fB-t\fP Prints tab characters as '^I' rather than a literal horizontal tab. .\" .SH DIAGNOSTICS @@ -69,7 +69,6 @@ Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later .\" .SH SEE ALSO .BR cat (1p), -.BR cat-v (1) - +.BR cat-v (1), .I UNIX Style, or cat -v Considered Harmful by Rob Pike diff --git a/docs/rpn.1 b/docs/rpn.1 index c791613..8e87802 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -26,7 +26,8 @@ Upon evaluation, the program will print the resulting number on the stack to the standard output. Any further specified numbers will be placed at the end of the stack. -For information on for reverse polish notation syntax, see rpn(7). +For information on for reverse polish notation syntax, see +.BR rpn (7). .\" .SH STANDARD INPUT @@ -40,7 +41,7 @@ In the event of a syntax error, the program will print an In the event of an error, a debug message will be printed and the program will exit with the appropriate -.BR sysexits.h(3) +.BR sysexits.h (3) error code. .\" .SH CAVEATS @@ -80,5 +81,5 @@ Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later .SH SEE ALSO .BR bc (1p), .BR dc (1), -.BR rpn(7), +.BR rpn (7), .I IEEE 754 diff --git a/docs/scrut.1 b/docs/scrut.1 index 52d96ed..22c77fb 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -10,7 +10,7 @@ scrut \(en scrutinize file properties .SH SYNOPSIS scrut -.RB ( -bcdefgkprsuwxLS ) +.RB ( -LSbcdefgkprsuwx ) .RB [ file... ] .\" .SH DESCRIPTION @@ -19,33 +19,33 @@ Determine if files comply with requirements. .\" .SH OPTIONS -.IP -L +.IP \fB-L\fB Requires the given files to exist and be symbolic links. -.IP -S +.IP \fB-S\fP Requires the given files to exist and be sockets. -.IP -b +.IP \fB-b\fP Requires the given files to exist and be block special files. -.IP -c +.IP \fB-c\fP Requires the given files to exist and be character special files. -.IP -d +.IP \fB-d\fP Requires the given files to exist and be directories. -.IP -e +.IP \fB-e\fP Requires the given files to exist, and is redundant to any other option. -.IP -e +.IP \fB-f\fP Requires the given files to exist and be regular files. -.IP -g +.IP \fB-g\fP Requires the given files to exist and have their set group ID flags set. -.IP -k +.IP \fB-k\fP Requires the given files to exist and have their sticky bit set. -.IP -p +.IP \fB-p\fP Requires the given files to exist and be named pipes. -.IP -r +.IP \fB-r\fP Requires the given files to exist and be readable. -.IP -u +.IP \fB-u\fP Requires the given files to exist and have their set user ID flags set. -.IP -w +.IP \fB-w\fP Requires the given files to exist and be writable. -.IP -x +.IP \fB-x\fP Requires the given files to exist and be executable. .\" .SH DIAGNOSTICS diff --git a/docs/str.1 b/docs/str.1 index d40eafa..87caabb 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -31,14 +31,17 @@ An empty string will cause an unsuccessful exit as none of its contents pass any tests. When invoked incorrectly, a debug message will be printed and the program will -exit with the appropriate sysexits.h(3) error code. +exit with the appropriate +.BR sysexits.h (3) +error code. .\" .SH CAVEATS -There’s no way of knowing which argument failed the test without re-testing +There\(cqs no way of knowing which argument failed the test without re-testing arguments individually. -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 @@ -48,7 +51,7 @@ Written by DTB .\" .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 . .\" .SH SEE ALSO diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 768be0f..84b661d 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -21,9 +21,19 @@ Check whether string arguments are the same. .SH DIAGNOSTICS The program will exit successfully if the strings are identical. Otherwise, it -exits with the value 1 if an earlier string has a greater byte value than a -later string (e.g. strcmp b a) and 255 if an earlier string has a lesser byte -value (e.g. strcmp a b). +will exit with an error code of 1 if a string passed has a lesser byte value +than one of the prior strings: + +.RS +.R strcmp b a +.RE + +and with an error code of 255 if it has a greater byte value than one of the +prior strings: + +.RS +.R strcmp a b +.RE When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate @@ -44,7 +54,7 @@ been This tool also handles integer comparisons and file scrutiny. These parts of its functionality have been broken out into multiple utilities. -This program’s functionality may be performed on a POSIX-compliant system with +This program\(cqs functionality may be performed on a POSIX-compliant system with .BR test (1p). .\" .SH AUTHOR @@ -55,7 +65,7 @@ Written by DTB .\" .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 . .\" .SH SEE ALSO diff --git a/docs/swab.1 b/docs/swab.1 index 90b50b0..7197a0a 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -17,7 +17,7 @@ swab .B word size .R ]) .\" -.SH USAGE +.SH DESCRIPTION Swap the latter and former halves of a block of bytes. .\" @@ -28,7 +28,7 @@ Ignore system call interruptions. .IP \fB-w\fP 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 +cleanly divisible by 2, otherwise the block of bytes being processed can\(cqt be halved. .\" .SH EXAMPLES @@ -66,7 +66,7 @@ on other machines. .\" .SH COPYRIGHT -Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . .\" .SH SEE ALSO From 3c0725f137a6089b549ae928dbd37c41eb336fbe Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 17:15:42 -0600 Subject: [PATCH 43/48] dj.1: adds DESCRIPTION and removes seek/skip confusion --- docs/dj.1 | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index ea73a75..d4c5053 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -43,6 +43,17 @@ dj .B output offset .R ]) .\" +.SH DESCRIPTION + +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. + +This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving +to a specified byte by index in the input and output of the program +respectively. This language is inherited from the +.BR dd (1p) +utility and is used here to decrease ambiguity. +.\" .SH OPTIONS .IP \fB-i\fP @@ -61,7 +72,7 @@ Does the same as .B -b but for the output buffer. .IP \fB-S\fP -Skips a number of bytes through the output before starting to write from +Seeks a number of bytes through the output before starting to write from the input. If the output is a stream, null characters are printed. .IP \fB-a\fP Accepts a single literal byte with which input buffer is padded in the event @@ -86,6 +97,7 @@ Retries failed reads once more before exiting. .IP \fB-q\fP Suppresses error messages which print when a read or write is partial or empty. Each invocation decrements the debug level of the program. +.\" .SH STANDARD INPUT The standard input shall be used as an input if no inputs are specified or if From 11b1b424a022d8a86abdc74e21720e98cb55d520 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 17:18:21 -0600 Subject: [PATCH 44/48] dj.1: more clarification --- docs/dj.1 | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/dj.1 b/docs/dj.1 index d4c5053..67d294d 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -53,6 +53,9 @@ to a specified byte by index in the input and output of the program respectively. This language is inherited from the .BR dd (1p) utility and is used here to decrease ambiguity. + +When seeking or skipping to a byte, writing or reading starts at the byte +immediately subsequent to the specified byte. .\" .SH OPTIONS From ad6f9d565baf1999675fcbfcfa9fd34a5cca1030 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 20:39:37 -0600 Subject: [PATCH 45/48] dj.1: formats sysexits.h(3) reference --- docs/dj.1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/dj.1 b/docs/dj.1 index 67d294d..f5dbe18 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -151,7 +151,8 @@ as the only argument: 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 -sysexits.h(3) status. +.BR sysexits.h (3) +status. .\" .SH BUGS From 526185c2c3e9900a03a1c591665fbb05f2664bc8 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 22:35:50 -0600 Subject: [PATCH 46/48] swab.1: typo --- docs/swab.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/swab.1 b/docs/swab.1 index 7197a0a..b1d27fc 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -34,7 +34,7 @@ halved. .SH EXAMPLES The following -.Br sh (1p) +.BR sh (1p) line: .RS From 8ce7890124307220a2ef9edd7057461c50ee5ad8 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 23:07:15 -0600 Subject: [PATCH 47/48] fop.1: removes Unicode representation of RS; hru.1: removes erroneous line break; mm.1: formatting & grammar; npc.1: dollar sign, not currency sign; rpn.1: syntax error; scrut.1: move description to DESCRIPTION; str.1: comma; swab.1: wording & escape codes; true.1: formatting --- docs/fop.1 | 3 ++- docs/hru.1 | 4 ++-- docs/mm.1 | 17 +++++++---------- docs/npc.1 | 2 +- docs/rpn.1 | 5 ++--- docs/scrut.1 | 7 +++---- docs/str.1 | 2 +- docs/swab.1 | 4 ++-- docs/true.1 | 4 ++-- 9 files changed, 22 insertions(+), 26 deletions(-) diff --git a/docs/fop.1 b/docs/fop.1 index 29ba7ea..295d9ff 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -24,7 +24,8 @@ Performs operations on specified fields in input data. .IP \fB-d\fP Sets a delimiter by which the input data will be split into fields. The default -is an ASCII record separator (␞). +is an ASCII record separator. +.\" .SH STANDARD INPUT Data will be read from the standard input. diff --git a/docs/hru.1 b/docs/hru.1 index c3a5cdc..8b898f8 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -34,8 +34,8 @@ and print an error message. The GNU project\(cqs .BR ls (1) implementation contains a human-readable option (\fB-h\fP) that, when specified, -makes the tool print size information in a format more immediately readable. -This functionality is useful not only in the context of +makes the tool print size information in a format more immediately +readable. This functionality is useful not only in the context of .BR ls (1) so the decision was made to split it into a new tool. The original functionality in GNU\(cqs diff --git a/docs/mm.1 b/docs/mm.1 index 58bc26e..812aef7 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -27,13 +27,11 @@ Opens subsequent outputs for appending rather than updating. .IP \fB-e\fP Use the standard error as an output. .IP \fB-i\fP -Opens a path as an input. Without any inputs specified mm will use the -standard input. The standard input shall be used as an input if one or more of -the input files is \(lq-\(rq. +Opens a path as an input. If one or more of the input files is \(lq-\(rq or if +no inputs are specified, the standard input shall be used. .IP \fB-o\fP -Opens a path as an output. Without any outputs specified mm will use the -standard output. The standard output shall be used as an output if one or more -of the output files is \(lq-\(rq. +Opens a path as an output. If one or more of the output files is \(lq-\(rq or if +no outputs are specified, the standard output shall be used. .IP \fB-u\fP Ensures neither input or output will be buffered. .IP \fB-n\fP @@ -41,11 +39,10 @@ Causes SIGINT signals to be ignored. .\" .SH DIAGNOSTICS -If an output can no longer be written mm prints a diagnostic message, ceases -writing to that particular output, and if there are more outputs specified, -continues, eventually exiting unsuccessfully. +If an output cannot be written to, an error occurs. Additional outputs are not +affected and writing to them continues. -When an error is encountered, diagnostic message is printed and the program +When an error is encountered, a diagnostic message is printed and the program exits with the appropriate .BR sysexits.h (3) status. diff --git a/docs/npc.1 b/docs/npc.1 index e18e4ff..27926ee 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -28,7 +28,7 @@ high bit set. .SH USAGE .IP \fB-e\fP -Prints a currency sign ('$') before each line ending. +Prints a dollar sign ('$') before each line ending. .IP \fB-t\fP Prints tab characters as '^I' rather than a literal horizontal tab. .\" diff --git a/docs/rpn.1 b/docs/rpn.1 index 8e87802..8a3b0fe 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -37,12 +37,11 @@ the standard input. .\" .SH DIAGNOSTICS -In the event of a syntax error, the program will print an - 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. +error code; however, in the event of a syntax error, the program will print an +error message and continue accepting input. .\" .SH CAVEATS diff --git a/docs/scrut.1 b/docs/scrut.1 index 22c77fb..2cb687c 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -15,7 +15,9 @@ scrut .\" .SH DESCRIPTION -Determine if files comply with requirements. +Determine if files comply with requirements. If the given files comply with the +specified requirements, the program will exit successfully. Otherwise, it exits +unsuccessfully. .\" .SH OPTIONS @@ -50,9 +52,6 @@ Requires the given files to exist and be executable. .\" .SH DIAGNOSTICS -If the given files comply with the specified requirements, the program will exit -successfully. If not, it exits unsuccessfully. - When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate .BR sysexits.h (3) diff --git a/docs/str.1 b/docs/str.1 index 87caabb..66565b9 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -40,7 +40,7 @@ error code. There\(cqs no way of knowing which argument failed the test without re-testing arguments individually. -If a character in a string isn\(cqt valid ASCII the program will exit +If a character in a string isn\(cqt valid ASCII, the program will exit unsuccessfully. .\" .SH AUTHOR diff --git a/docs/swab.1 b/docs/swab.1 index b1d27fc..64aed1a 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -27,7 +27,7 @@ Swap the latter and former halves of a block of bytes. Ignore system call interruptions. .IP \fB-w\fP 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 +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. .\" @@ -38,7 +38,7 @@ The following line: .RS -.R printf 'hello world!\n' | swab +.R printf 'hello world!\(rsn' | swab .RE Produces the following output: diff --git a/docs/true.1 b/docs/true.1 index ac2e222..ecf4c8e 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -10,8 +10,8 @@ true \(en do nothing, successfully .\" .SH DESCRIPTION -Do nothing regardless of operands or standard input. -An exit code of 0 will always be returned. +Do nothing regardless of operands or standard input. An exit code of 0 will +always be returned. .\" .SH RATIONALE From 4d27a4976c51126cd15058a415cfab3e62aff555 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 23:17:21 -0600 Subject: [PATCH 48/48] swab.1: -f Ignores the SIGINT signal --- docs/swab.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/swab.1 b/docs/swab.1 index 64aed1a..0ca19e8 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -24,7 +24,7 @@ Swap the latter and former halves of a block of bytes. .SH OPTIONS .IP \fB-f\fP -Ignore system call interruptions. +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