From a6fd1108c606f782e707de31d24e5d84214809c6 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 18:26:51 -0600 Subject: [PATCH 01/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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/81] 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 61382c34d924ab3b42fb6a666dae43bf441ce30b Mon Sep 17 00:00:00 2001 From: DTB Date: Sun, 31 Mar 2024 22:54:03 -0600 Subject: [PATCH 22/81] mm(1): error out when given positional arguments --- src/mm.c | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/mm.c b/src/mm.c index ff62148..dc337b7 100644 --- a/src/mm.c +++ b/src/mm.c @@ -106,6 +106,15 @@ oserr(char *s, char *r){ } \ return retval +/* Prints a usage text, in which s is the program being run (i.e. argv[0]), and + * returns an exit status appropriate for a usage error. */ +int usage(char *s){ + + fprintf(stderr, "Usage: %s (-aenu) (-i [input])... (-o [output])...\n", s); + + return EX_USAGE; +} + int main(int argc, char *argv[]){ int c; struct Files files[2]; /* {read, write} */ @@ -178,12 +187,15 @@ int main(int argc, char *argv[]){ k = 1; break; default: - fprintf(stderr, "Usage: %s (-aenu) (-i [input])..." - " (-o [output])...\n", argv[0]); - retval = EX_USAGE; + retval = usage(argv[0]); terminate; } + if(optind != argc){ + retval = usage(argv[0]); + terminate; + } + files[0].s += files[0].s == 0; files[1].s += files[1].s == 0; From df16707b0e2c74217d7ea4aaaab0f45b6f0cff97 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 18 Apr 2024 08:36:01 -0600 Subject: [PATCH 23/81] 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 24/81] 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 25/81] 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 26/81] 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 27/81] 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 f6aac60aee89eafcb088337d7f820766a657d5c1 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 25 Apr 2024 12:40:20 -0600 Subject: [PATCH 28/81] Makefile: fixed manpage install location --- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 68efd20..e0068dc 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,8 @@ DESTDIR ?= dist PREFIX ?= /usr/local +MANDIR != [ $(PREFIX) = / ] && printf '/usr/share/man\n' \ + || printf '/share/man\n' SYSEXITS != printf '\043include \n' | cpp -M - | sed 's/ /\n/g' \ | sed -n 's/sysexits\.h//p' || printf 'include\n' @@ -42,7 +44,7 @@ clean: dist: all mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1 cp build/bin/* $(DESTDIR)/$(PREFIX)/bin - cp docs/*.1 $(DESTDIR)/$(PREFIX)/share/man/man1 + cp docs/*.1 $(DESTDIR)/$(PREFIX)/$(MANDIR)/man1 .PHONY: install install: dist From d8b54fdbf5b1e19810c28a341c59d0ec4fec01ec Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 25 Apr 2024 12:43:31 -0600 Subject: [PATCH 29/81] Makefile: fixes erroneous whitespace --- Makefile | 1 - 1 file changed, 1 deletion(-) diff --git a/Makefile b/Makefile index e0068dc..1952a25 100644 --- a/Makefile +++ b/Makefile @@ -104,7 +104,6 @@ mm: build/bin/mm build/bin/mm: src/mm.c build $(CC) $(CFLAGS) -o $@ src/mm.c - .PHONY: npc npc: build/bin/npc build/bin/npc: src/npc.c build From 488351da39384f7ef510a19bcfa1af65feccc4f4 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 25 Apr 2024 16:46:05 -0600 Subject: [PATCH 30/81] scrut(1): changed return status 0 to EXIT_SUCCESS --- src/scrut.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/scrut.c b/src/scrut.c index e2494d3..8d0d393 100644 --- a/src/scrut.c +++ b/src/scrut.c @@ -100,5 +100,5 @@ usage: fprintf(stderr, "Usage: %s (-%s) [file...]\n", return 1; }while(*++argv != NULL); - return 0; + return EXIT_SUCCESS; } From adc9dbded5401bb05538d1b2dec8b20b3c2200f3 Mon Sep 17 00:00:00 2001 From: DTB Date: Fri, 26 Apr 2024 19:30:33 -0600 Subject: [PATCH 31/81] scrut(1): changed return status 1 to EXIT_FAILURE --- src/scrut.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/scrut.c b/src/scrut.c index 8d0d393..025b743 100644 --- a/src/scrut.c +++ b/src/scrut.c @@ -17,7 +17,7 @@ */ #include /* fprintf(3), stderr, NULL */ -#include /* EXIT_FAILURE */ +#include /* EXIT_FAILURE, EXIT_SUCCESS */ #include /* memset(3), strchr(3) */ #include /* access(3), getopt(3), F_OK, R_OK, W_OK, X_OK */ #include /* lstat(3), stat struct, S_ISBLK, S_ISCHR, S_ISDIR, @@ -57,7 +57,7 @@ int main(int argc, char *argv[]){ argv += optind; do{ if(access(*argv, F_OK) != 0 || lstat(*argv, &buf) == -1) - return 1; /* doesn't exist or isn't stattable */ + return EXIT_FAILURE; /* doesn't exist or isn't stattable */ for(i = 0; ops[i] != '\0'; ++i) if(ops[i] == 'e') @@ -97,7 +97,7 @@ usage: fprintf(stderr, "Usage: %s (-%s) [file...]\n", && !S_ISLNK(buf.st_mode)) || (ops[i] == 'S' && !S_ISSOCK(buf.st_mode))) - return 1; + return EXIT_FAILURE; }while(*++argv != NULL); return EXIT_SUCCESS; From 8e38db92c761286d9a4f9e09c111bba94c9a213c Mon Sep 17 00:00:00 2001 From: DTB Date: Fri, 26 Apr 2024 19:33:45 -0600 Subject: [PATCH 32/81] scrut(1): update copyright header --- src/scrut.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/scrut.c b/src/scrut.c index 025b743..acc05ff 100644 --- a/src/scrut.c +++ b/src/scrut.c @@ -1,5 +1,6 @@ /* - * Copyright (c) 2023 DTB + * Copyright (c) 2023–2024 DTB + * Copyright (c) 2024 Emma Tebibyte * SPDX-License-Identifier: AGPL-3.0-or-later * * This program is free software: you can redistribute it and/or modify it under From 919b17140098b01bc2d12e1054a35681b871e549 Mon Sep 17 00:00:00 2001 From: DTB Date: Fri, 26 Apr 2024 19:35:33 -0600 Subject: [PATCH 33/81] scrut(1): conditionally include non-POSIX sysexits.h --- src/scrut.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/scrut.c b/src/scrut.c index acc05ff..c5b675f 100644 --- a/src/scrut.c +++ b/src/scrut.c @@ -20,11 +20,13 @@ #include /* fprintf(3), stderr, NULL */ #include /* EXIT_FAILURE, EXIT_SUCCESS */ #include /* memset(3), strchr(3) */ +#ifndef EX_USAGE +# include +#endif #include /* access(3), getopt(3), F_OK, R_OK, W_OK, X_OK */ #include /* lstat(3), stat struct, S_ISBLK, S_ISCHR, S_ISDIR, * S_ISFIFO, S_ISGID, S_ISREG, S_ISLNK, S_ISSOCK, * S_ISUID, S_ISVTX */ -#include static char args[] = "bcdefghkprsuwxLS"; static char ops[(sizeof args) / (sizeof *args)]; From 432b19818ed625d6673c24e527a8502ffec5b689 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 28 Apr 2024 20:42:44 -0600 Subject: [PATCH 34/81] 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 35/81] 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 36/81] 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 37/81] 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 38/81] 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 39/81] 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 40/81] 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 41/81] 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 42/81] 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 43/81] 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 2dd6c0ded7a65fee58a8fbff5f62891d5484b778 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 19:05:30 -0600 Subject: [PATCH 44/81] fop(1): adds the ability to use any string as a delimiter --- src/fop.rs | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/src/fop.rs b/src/fop.rs index b829602..d28a7b0 100644 --- a/src/fop.rs +++ b/src/fop.rs @@ -32,18 +32,12 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; fn main() { let argv = args().collect::>(); - let mut d = '␞'; + let mut d = "␞".to_owned(); let mut arg_parser = Parser::new(&argv, "d:"); while let Some(opt) = arg_parser.next() { match opt { - Ok(Opt('d', Some(arg))) => { - let arg_char = arg.chars().collect::>(); - if arg_char.len() > 1 { - eprintln!("{}: {}: Not a character.", argv[0], arg); - exit(EX_USAGE); - } else { d = arg_char[0]; } - }, + Ok(Opt('d', Some(arg))) => d = arg, _ => {}, }; } @@ -63,7 +57,7 @@ fn main() { let mut buf = String::new(); let _ = stdin().read_to_string(&mut buf); - let mut fields = buf.split(d).collect::>(); + let mut fields = buf.split(&d).collect::>(); let opts = argv .iter() From 24b235e7c1737a5e01c5390dcac3052e3c64d760 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 19:15:23 -0600 Subject: [PATCH 45/81] README: updated to make current --- README | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README b/README index accfc7e..d7a79f6 100644 --- a/README +++ b/README @@ -20,9 +20,9 @@ See docs/ for more on the specific utilities currently implemented. Building The coreutils require a POSIX-compliant environment to compile, including a C -compiler and preprocessor (cc(1) and cpp(1) by default) with the -idirafter -flag, a Rust compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant -make(1) utility. +compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust +compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant make(1) +utility. To build and install: From 642774bccf76b7025005c0d34f1f6b0b2d22b275 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 19:21:56 -0600 Subject: [PATCH 46/81] src: removed erroneous file --- src/test.rs | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 src/test.rs diff --git a/src/test.rs b/src/test.rs deleted file mode 100644 index 4a602b1..0000000 --- a/src/test.rs +++ /dev/null @@ -1,10 +0,0 @@ -extern crate strerror; - -use strerror::raw_message; - -fn main() { - stdout.write_all(b"meow\n").unwrap_or_else(|e| { - eprintln!("{}", raw_message(e)); - std::process::exit(1); - }); -} From d6fb08019eb4a1d80b6160f02678afd67567ebc2 Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 23:14:40 -0600 Subject: [PATCH 47/81] CONDUCT: initial commit --- CONDUCT | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING | 2 ++ 2 files changed, 82 insertions(+) create mode 100644 CONDUCT diff --git a/CONDUCT b/CONDUCT new file mode 100644 index 0000000..0585d15 --- /dev/null +++ b/CONDUCT @@ -0,0 +1,80 @@ +Code of Conduct + +This Code of Conduct is derived from the 10 Pāramitās of Theravadin Buddhism. +You can read more about them in Ṭhānissaro Bhikkhu’s Ten Perfections: A Study +Guide [0]. + +1. Generosity (Dāna) + +Give contributions freely and willingly under the terms of the GNU Affero +General Public License, version 3 or later, or a compatible license. + +2. Ethics (Sīla) + +Do not use nonfree code or uncredited code in contributions. Do not take credit +for others’ contributions. Make sure to utilize the copyright header and license +notice on source files to credit yourself and others for their work. + +3. Renunciation (Nekkhamma) + +Stay committed to the principles of simplicity and interoperability embodied by +the project. Keep your personal will and desire out of the project, for it can +only prove harmful to its success. + +4. Wisdom (Pañña) + +Look to established sources for standards, best practices, and important +implementation details when setting new precedence. Follow the existing +precedence where it applies. + +5. Energy (Viriya) + +Focus on the currently-open, currently-assigned, and currently-in-progress +issues, pull requests, and other endeavors in order to keep yourself and others +from being overwhelmed with responsibility, either from your zeal or your +negligence. + +If you notice an issue, open an issue as soon as you can. If you see a neglected +branch, open a pull request or comment on an existing one, if applicable. Be +diligent in your commitment to making this project work. + +6. Patience (Khanti) + +Be patient with maintainers and other contributors. We all have our own lives +going on and may need significant time to get to things. + +7. Truthfulness (Sacca) + +Communicate honestly and openly. Do not embellish facts to get your way. Make +sure to let maintainers know about any issues along the way and keep ample +communication channels open. + +8. Determination (Adhiṭṭhāna) + +Stay focused on long-term objectives and cultivate attainment to that +achievement by utilizing to the fullest extent possible the tools available to +you for managing the workload. + +9. Loving-Kindness (Mettā) + +Treat everyone with respect, even if they treat you poorly. This does not mean +you have to put up with abuse, but make sure to respond with kindness and with +love in your heart. Support and uplift maintainers and other contributors with +your words and actions. + +Do not use angry or hateful language toward contributors, such as demeaning +phrases and slurs. Make sure that if you do not know the pronouns of a +contributor to ask for them and, in the meantime, use gender-neutral they/them +or equivalent pronouns. + +10. Equanimity (Upekkhā) + +Keep a balanced perspective on all suggestions and contributions and make +judgements not from a place of ego and personal preference but on their +usefulness and suitability to the project. Make sure to keep an eye on the +bigger picture as implementing individual features may seem intuitive at first +but scale poorly in practical use. Keep a level head about your own work: it is +not shameful to make a mistake in this vein, and fixing it usually leads to +more insight. + +[0] diff --git a/CONTRIBUTING b/CONTRIBUTING index d7fdc8e..74e821e 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -1,3 +1,5 @@ +Make sure to read our code of conduct in the CONDUCT file. + When contributing a pull request to the main branch, please sign your commits with a PGP key and add your name and the year to the bottom of the list of copyright holders for the file. For example, an existing copyright header might From c32c554e03f8f7fdd62bbf981bbf70e3fe318f71 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:07:19 -0600 Subject: [PATCH 48/81] 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 49/81] 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 50/81] 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 51/81] 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 52/81] 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 53/81] 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 46c4be5c591f189598bbaaa23d8fc73947e4befd Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 4 Jun 2024 16:21:25 -0600 Subject: [PATCH 54/81] CONDUCT: no llm contributions --- CONDUCT | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONDUCT b/CONDUCT index 0585d15..4a26e37 100644 --- a/CONDUCT +++ b/CONDUCT @@ -11,9 +11,11 @@ General Public License, version 3 or later, or a compatible license. 2. Ethics (Sīla) -Do not use nonfree code or uncredited code in contributions. Do not take credit -for others’ contributions. Make sure to utilize the copyright header and license -notice on source files to credit yourself and others for their work. +Do not use nonfree code or uncredited code in contributions. Do not contribute +code of dubious origins, such as code generated in large part by large language +models [1]. Do not take credit for others’ contributions. Make sure to utilize +the copyright header and license notice on source files to credit yourself and +others for their work. 3. Renunciation (Nekkhamma) @@ -78,3 +80,4 @@ not shameful to make a mistake in this vein, and fixing it usually leads to more insight. [0] +[1] From 3c0725f137a6089b549ae928dbd37c41eb336fbe Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 17:15:42 -0600 Subject: [PATCH 55/81] 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 56/81] 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 3392d64e440b8911a51bfead6c73fb5c4fe3f452 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 17:25:22 -0600 Subject: [PATCH 57/81] fop(1): literal record separator --- src/fop.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fop.rs b/src/fop.rs index d28a7b0..1cc8152 100644 --- a/src/fop.rs +++ b/src/fop.rs @@ -32,7 +32,7 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; fn main() { let argv = args().collect::>(); - let mut d = "␞".to_owned(); + let mut d = 0x1E.to_string(); let mut arg_parser = Parser::new(&argv, "d:"); while let Some(opt) = arg_parser.next() { From 516d10e21d37bc94f63e67c0ec930fd374d61e22 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 17:27:13 -0600 Subject: [PATCH 58/81] CONDUCT: wording --- CONDUCT | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONDUCT b/CONDUCT index 4a26e37..4dd97a9 100644 --- a/CONDUCT +++ b/CONDUCT @@ -12,10 +12,10 @@ General Public License, version 3 or later, or a compatible license. 2. Ethics (Sīla) Do not use nonfree code or uncredited code in contributions. Do not contribute -code of dubious origins, such as code generated in large part by large language -models [1]. Do not take credit for others’ contributions. Make sure to utilize -the copyright header and license notice on source files to credit yourself and -others for their work. +code of dubious origins, such as code generated by large language models or +unlicensed snippets found online [1]. Do not take credit for others’ +contributions. Make sure to utilize the copyright header and license notice on +source files to credit yourself and others for their work. 3. Renunciation (Nekkhamma) From ad6f9d565baf1999675fcbfcfa9fd34a5cca1030 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 5 Jun 2024 20:39:37 -0600 Subject: [PATCH 59/81] 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 60/81] 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 61/81] 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 62/81] 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 From 51421b2128ba93502dec3ccb19b01772ac7c2226 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 6 Jun 2024 00:14:55 -0600 Subject: [PATCH 63/81] dj.1, strcmp.1, swab.1: remove nonexistent roff macros --- docs/dj.1 | 44 ++++++++++++++++---------------------------- docs/strcmp.1 | 4 ++-- docs/swab.1 | 4 ++-- 3 files changed, 20 insertions(+), 32 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index f5dbe18..f2570ae 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -18,30 +18,18 @@ dj .RB [ count ]) .RB ( -i -.R [ -.B input file -.R ]) +[\fBinput file\fP]) .RB ( -b -.R [ -.B input block size -.R ]) +[\fBinput block size\fP]) .RB ( -s -.R [ -.B input offset -.R ]) +[\fBinput offset\fP]) .RB ( -o -.R [ -.B output file -.R ]) +[\fBoutput file\fP]) .RB ( -B -.R [ -.B output block size -.R ]) +[\fBoutput block size\fP]) .RB ( -S -.R [ -.B output offset -.R ]) +[\fBoutput offset\fP]) .\" .SH DESCRIPTION @@ -118,10 +106,10 @@ By default, statistics are printed for input and output to the standard error in the following format: .RS -.R {records read} {ASCII unit separator} {partial records read} -.R {ASCII record separator} {records written} {ASCII unit separator} -.R {partial records written} {ASCII group separator} {bytes read} -.R {ASCII record separator} {bytes written} {ASCII file separator} +{records read} {ASCII unit separator} {partial records read} +{ASCII record separator} {records written} {ASCII unit separator} +{partial records written} {ASCII group separator} {bytes read} +{ASCII record separator} {bytes written} {ASCII file separator} .RE This format for diagnostic output is designed to be machine-parseable for @@ -130,9 +118,9 @@ convenience. For a more human-readable format, the option may be specified. In this event, the following format is used instead: .RS -.R {records read} '+' {partial records read} '>' {records written} -.R '+' {partial records written} ';' {bytes read} '>' {bytes written} -.R {ASCII line feed} +{records read} '+' {partial records read} '>' {records written} +'+' {partial records written} ';' {bytes read} '>' {bytes written} +{ASCII line feed} .RE If the @@ -144,9 +132,9 @@ was invoked. The following example is the result of running the program with 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 +argv0=dj +in= ibs=1024 skip=0 align=ff count=0 +out= obs=1024 seek=0 debug= 3 noerror=0 .RE In non-recoverable errors that don\(cqt pertain to the read-write cycle, a diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 84b661d..46eccdf 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -25,14 +25,14 @@ 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 +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 +strcmp a b .RE When invoked incorrectly, a debug message will be printed and the program will diff --git a/docs/swab.1 b/docs/swab.1 index 0ca19e8..526b057 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -38,13 +38,13 @@ The following line: .RS -.R printf 'hello world!\(rsn' | swab +printf 'hello world!\(rsn' | swab .RE Produces the following output: .RS -.R ehll oowlr!d +ehll oowlr!d .RE .\" .SH DIAGNOSTICS From 314254b32f2cd508724f55a2310ff076e26493ba Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 6 Jun 2024 13:32:54 -0600 Subject: [PATCH 64/81] docs: hotfix --- docs/dj.1 | 2 +- docs/false.1 | 2 +- docs/fop.1 | 2 +- docs/hru.1 | 2 +- docs/intcmp.1 | 2 +- docs/mm.1 | 2 +- docs/npc.1 | 2 +- docs/rpn.1 | 2 +- docs/scrut.1 | 2 +- docs/str.1 | 2 +- docs/strcmp.1 | 2 +- docs/swab.1 | 2 +- docs/true.1 | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index f2570ae..1572991 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH DJ 1 +.TH DJ 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME dj \(en disk jockey .\" diff --git a/docs/false.1 b/docs/false.1 index 91bd286..1dec3ce 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FALSE 1 +.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME false \(en do nothing, unsuccessfully .\" diff --git a/docs/fop.1 b/docs/fop.1 index 295d9ff..fe1a3c5 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH fop 1 +.TH FOP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME fop \(en field operator .\" diff --git a/docs/hru.1 b/docs/hru.1 index 8b898f8..b24671e 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 HRU 1 +.TH HRU 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME hru \(en human readable units .\" diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 905d31d..94e88a4 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH INTCMP 1 +.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME intcmp \(en compare integers .\" diff --git a/docs/mm.1 b/docs/mm.1 index 812aef7..2585cab 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -3,7 +3,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH mm 1 +.TH MM 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME mm \(en middleman .\" diff --git a/docs/npc.1 b/docs/npc.1 index 27926ee..a2c4fd8 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH NPC 1 +.TH NPC 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME npc \(en show non-printing characters .\" diff --git a/docs/rpn.1 b/docs/rpn.1 index 8a3b0fe..507789d 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH rpn 1 +.TH RPN 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME rpn \(en reverse polish notation evaluation .\" diff --git a/docs/scrut.1 b/docs/scrut.1 index 2cb687c..636c5d3 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH scrut 1 +.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME scrut \(en scrutinize file properties .SH SYNOPSIS diff --git a/docs/str.1 b/docs/str.1 index 66565b9..c3f7538 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STR 1 +.TH STR 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME str \(en test the character types of string arguments .\" diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 46eccdf..facfdeb 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STRCMP 1 +.TH STRCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME strcmp \(en compare strings .\" diff --git a/docs/swab.1 b/docs/swab.1 index 526b057..a3af1ad 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SWAB 1 +.TH SWAB 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME swab \(en swap bytes .\" diff --git a/docs/true.1 b/docs/true.1 index ecf4c8e..2e8d5eb 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH TRUE 1 +.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME true \(en do nothing, successfully .\" From 376feb9ae9a884c0f3655902c1027cebdf5b6203 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 22:52:58 -0600 Subject: [PATCH 65/81] npc.1: fixes minor details --- docs/npc.1 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/npc.1 b/docs/npc.1 index a2c4fd8..a0e503e 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH NPC 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME npc \(en show non-printing characters .\" @@ -25,10 +25,10 @@ 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 +.SH OPTIONS .IP \fB-e\fP -Prints a dollar sign ('$') before each line ending. +Prints a dollar sign ('$') before each newline. .IP \fB-t\fP Prints tab characters as '^I' rather than a literal horizontal tab. .\" @@ -52,8 +52,8 @@ 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 +This functionality is included in a separate tool because its usefulness extends +beyond that of .BR cat (1p). .\" .SH AUTHOR From 15d5761cd7f9919700cbd893f7f1d18d18bc4223 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 22:57:08 -0600 Subject: [PATCH 66/81] mm.1: fixes clunky sentence --- docs/mm.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/mm.1 b/docs/mm.1 index 2585cab..1fe64ba 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -3,7 +3,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH MM 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME mm \(en middleman .\" @@ -39,8 +39,8 @@ Causes SIGINT signals to be ignored. .\" .SH DIAGNOSTICS -If an output cannot be written to, an error occurs. Additional outputs are not -affected and writing to them continues. +If an output cannot be written to, an error occurs; however, exiting will be +deferred until writing to any other specified outputs completes. When an error is encountered, a diagnostic message is printed and the program exits with the appropriate From ee9d42d0d4b5f04f6380eb9c109adad589b10925 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:02:13 -0600 Subject: [PATCH 67/81] str.1: cleanup --- docs/str.1 | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/str.1 b/docs/str.1 index c3f7538..d45289a 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -6,7 +6,7 @@ .\" .TH STR 1 2024-06-06 "Bonsai Core Utilites 0.13.8" .SH NAME -str \(en test the character types of string arguments +str \(en test string arguments .\" .SH SYNOPSIS @@ -16,7 +16,7 @@ str .\" .SH DESCRIPTION -Test string arguments. +Test the character types of string arguments. The tests in this program are equivalent to the functions with the same names in .BR ctype.h (0p) @@ -24,11 +24,8 @@ 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. - -An empty string will cause an unsuccessful exit as none of its contents pass any -tests. +If all tests pass, the program will exit successfully. If any of the tests fail, +the program will exit unsuccessfully with an error code of 1. When invoked incorrectly, a debug message will be printed and the program will exit with the appropriate @@ -37,6 +34,9 @@ error code. .\" .SH CAVEATS +None of an empty string\(cqs contents pass any of the tests, so the program will +exit unsuccessfully if one is specified. + There\(cqs no way of knowing which argument failed the test without re-testing arguments individually. From 53d5a1db73542cc9a11a1e9356f0a5f232c225f9 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:09:15 -0600 Subject: [PATCH 68/81] hru.1: italics and removes clunky sentences --- docs/hru.1 | 24 +++++++++++++----------- docs/str.1 | 2 +- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/hru.1 b/docs/hru.1 index b24671e..acd5876 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 HRU 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME hru \(en human readable units .\" @@ -15,9 +15,9 @@ hru 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. +Byte counts will be read in the form of whole numbers from the standard input +and be written to the standard output the same number converted to a higher unit +of data as defined by the \fIInternational System of Units\fP. The program will convert the byte count to the highest unit possible where the value is greater than one. @@ -35,10 +35,8 @@ 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 +readable. This functionality is useful not only in this context, so the decision +was made to split it into a new tool. The original functionality from GNU\(cqs .BR ls (1) can be emulated with .BR fop (1) @@ -46,8 +44,12 @@ 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) +The standard unit prefixes as specified by the +.I Bureau International des Poids et Mesures +.RI ( BIPM ) +in the ninth edition of +.I The International System of Units +.RI ( SI ) are utilized for the ouput of conversions. .\" .SH AUTHOR @@ -64,4 +66,4 @@ 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 +.I The International System of Units (SI) 9th Edition diff --git a/docs/str.1 b/docs/str.1 index d45289a..55dd0bb 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STR 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME str \(en test string arguments .\" From 1b299f8ee1f3cbf367327bd3eedbe600f7c32b57 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:16:25 -0600 Subject: [PATCH 69/81] rpn.1: fixes clunkiness --- docs/rpn.1 | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/rpn.1 b/docs/rpn.1 index 507789d..01e00b9 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH RPN 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME rpn \(en reverse polish notation evaluation .\" @@ -18,12 +18,12 @@ rpn Evaluate reverse polish notation. -The program evaluates reverse polish notation expressions either read from the +The program evaluates reverse polish notation expressions read either 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 +Upon evaluation, the resulting number on the stack will be printed to the +standard output. Any further numbers specified will be placed at the end of the stack. For information on for reverse polish notation syntax, see @@ -31,8 +31,8 @@ For information on for reverse polish notation syntax, see .\" .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 +If arguments are specified, they are interpreted as an expression to be +evaluated. Otherwise, whitespace-delimited numbers and operations are read from the standard input. .\" .SH DIAGNOSTICS @@ -46,11 +46,13 @@ error message and continue accepting input. .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 -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. +with the +.I 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 numbers are rounded. 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 @@ -63,8 +65,8 @@ program. A 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. +Second Edition UNIX and onward. While it implements reverse polish notation, it +still suffers from being unable to accept an expression as an argument. .\" .SH AUTHOR From 266ee20d5c7d7dc93cd925df84936ab182dcc8a4 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:18:45 -0600 Subject: [PATCH 70/81] fop.1: removes unnecessary stdin section and adds AUTHOR --- docs/fop.1 | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/fop.1 b/docs/fop.1 index fe1a3c5..b5c1b7c 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FOP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME fop \(en field operator .\" @@ -18,7 +18,7 @@ fop .\" .SH DESCRIPTION -Performs operations on specified fields in input data. +Performs operations on specified fields in data read from the standard input. .\" .SH OPTIONS @@ -26,10 +26,6 @@ Performs operations on specified fields in input data. 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. @@ -51,6 +47,12 @@ but there was no easy way to modify the field in the ouput of .BR ls (1p) without creating a new tool. .\" +.SH AUTHOR + +Written by Emma Tebibyte +.MT emma@tebibyte.media +.ME . +.\" .SH COPYRIGHT Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later From bf10689606b53588dac03d6d48ded1d8560228fd Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:20:29 -0600 Subject: [PATCH 71/81] swab.1: bold --- docs/swab.1 | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/swab.1 b/docs/swab.1 index a3af1ad..abaab0b 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SWAB 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME swab \(en swap bytes .\" @@ -56,7 +56,9 @@ error code. .\" .SH RATIONALE -This program was modeled and named after the conv=swab functionality specified +This program was modeled and named after the +.B conv=swab +functionality specified in the .BR dd (1p) utility. It additionally allows the word size to be configured. @@ -64,6 +66,12 @@ 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 AUTHOR + +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later From 59eee27979666b3eaca0c2721965bf2c82eca342 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:21:44 -0600 Subject: [PATCH 72/81] strcmp.1: or --- docs/strcmp.1 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/strcmp.1 b/docs/strcmp.1 index facfdeb..5941762 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STRCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME strcmp \(en compare strings .\" @@ -28,7 +28,7 @@ than one of the prior strings: strcmp b a .RE -and with an error code of 255 if it has a greater byte value than one of the +or with an error code of 255 if it has a greater byte value than one of the prior strings: .RS @@ -54,7 +54,8 @@ been This tool also handles integer 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 +This program\(cqs functionality may be performed on a POSIX-compliant system +with .BR test (1p). .\" .SH AUTHOR From e38dcc09b12a0fa2c1c1a7e4e645027a29bfbe56 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:27:19 -0600 Subject: [PATCH 73/81] intcmp.1: bold --- docs/intcmp.1 | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 94e88a4..2808362 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -28,19 +28,23 @@ Permits a given integer to be less than the following integer. .\" .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 -example is equivalent to evaluating \(lq1 < 2 < 3\(rq: +It may help to think of the +.BR -e , +.BR -g , +and +.B -l +options as equivalent to the infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq +operators respectively, with each option putting its symbol between every given +integer. The following example is equivalent to evaluating \(lq1 < 2 < 3\(rq: \" .RS -.R intcmp -l 1 2 3 +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. +The program will exit with a successfully for a valid expression and with an +error 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 @@ -49,7 +53,8 @@ error code. .\" .SH BUGS --egl, \(lqequal to or less than or greater than\(rq, exits 0 no matter what for +.BR -egl , +\(lqequal to or less than or greater than\(rq, always exits successfully for valid program usage and may be abused to function as an integer validator. Use .BR str (1) instead. @@ -57,9 +62,17 @@ instead. .SH CAVEATS There are multiple ways to express compound comparisons; \(lqless than or equal -to\(rq can be -le or -el, for example. +to\(rq can be +.B -le +or +.BR -el , +for example. -The inequality comparison is -gl or -lg for \(lqless than or greater than\(rq; +The inequality comparison is +.B -gl +.B or +.B -lg +for \(lqless than or greater than\(rq; this is elegant but unintuitive. .\" .SH RATIONALE From 6814111ad1a6d14ac5b514212f5a9e1a9a7c6947 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:36:52 -0600 Subject: [PATCH 74/81] dj.1: fixes many clunky sentences --- docs/dj.1 | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1572991..6073fc6 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH DJ 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME dj \(en disk jockey .\" @@ -34,13 +34,13 @@ dj .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. +reading and writing binary data to and from disks. 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. +utility and 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. @@ -50,8 +50,8 @@ immediately subsequent to the specified byte. .IP \fB-i\fP Takes a file path as an argument and opens it for use as an input. .IP \fB-b\fP -Takes a numeric argument as the size in bytes of the input buffer, with the -default being 1024. +Takes a numeric argument as the size in bytes of the input buffer, the default +being 1024. .IP \fB-s\fP Takes a numeric argument as the number of bytes to skip into the input before starting to read. If the standard input is used, bytes read to this point @@ -66,25 +66,25 @@ but for the output buffer. 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 +Accepts a single literal byte with which the input buffer is padded in the event of an incomplete read from the input file. .IP \fB-A\fP Specifying this option pads the input buffer with null bytes in the event of an -incomplete read. Equivalent to specifying +incomplete read. This is equivalent to specifying .B -a 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 +Specifies a number of reads to make. The default is 0, in which case the input is read until a partial or empty read is made. .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 +DIAGNOSTICS section. Each invocation increments the debug level of the program. .IP \fB-H\fP Prints diagnostics messages in a human-readable manner as described in the -DIAGNOSTICS section below. +DIAGNOSTICS section. .IP \fB-n\fP -Retries failed reads once more before exiting. +Retries failed reads once 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. @@ -94,13 +94,18 @@ empty. Each invocation decrements the debug level of the program. The standard input shall be used as an input if no inputs are specified or if one or more of the input files is \(lq-\(rq. .\" +.SH STANDARD OUTPUT +The standard output shall be used as an output if no inputs are specified or if +one or more of the input files is \(lq-\(rq. +.\" .SH DIAGNOSTICS -On a partial or empty read, a diagnostic message is printed (unless the +On a partial or empty read, unless the .B -q -option is specified) and the program exits (unless the +option is specified, a diagnostic message is printed. Then, 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 the following format: @@ -125,9 +130,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 information will be printed at the beginning of +execution. This output 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: @@ -148,12 +153,12 @@ If .B -n 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 +option and a count, actual byte output is the product of the count and the input +block size and therefore may be lower than expected. If the .B -a or .B -A -options are used, this could make data written nonsensical. +options are specified, this could make written data nonsensical. .\" .SH CAVEATS From d201f9228ce6e6379c845d1a541a133629da4b05 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 18 Jun 2024 16:32:20 -0600 Subject: [PATCH 75/81] Makefile: updates to use new POSIX 2024 standard features! --- Makefile | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 1952a25..15b2968 100644 --- a/Makefile +++ b/Makefile @@ -11,8 +11,7 @@ .POSIX: # if using BSD make(1), remove these pragmas because they break it -.PRAGMA: posix_202x # future POSIX standard support à la pdpmake(1) -.PRAGMA: command_comment # breaks without this? + DESTDIR ?= dist PREFIX ?= /usr/local @@ -32,9 +31,9 @@ CFLAGS += -I$(SYSEXITS) .PHONY: all all: dj false fop hru intcmp mm npc rpn scrut str strcmp swab true +# keep build/include until bindgen(1) has stdin support +# https://github.com/rust-lang/rust-bindgen/issues/2703 build: - # keep build/include until bindgen(1) has stdin support - # https://github.com/rust-lang/rust-bindgen/issues/2703 mkdir -p build/bin build/include build/lib build/o build/test .PHONY: clean @@ -67,9 +66,9 @@ build/o/libstrerror.rlib: build src/strerror.rs $(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \ src/strerror.rs +# bandage solution until bindgen(1) gets stdin support build/o/libsysexits.rlib: build $(SYSEXITS)sysexits.h - # bandage solution until bindgen(1) gets stdin support - printf '#define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \ + printf '\043define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \ > build/include/sysexits.h bindgen --default-macro-constant-type signed --use-core --formatter=none \ build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ - From f553cff09651512b609e2c394f368775fe9c674b Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 18 Jun 2024 16:33:22 -0600 Subject: [PATCH 76/81] Makefile: removes unneeded comment --- Makefile | 3 --- 1 file changed, 3 deletions(-) diff --git a/Makefile b/Makefile index 15b2968..0dee534 100644 --- a/Makefile +++ b/Makefile @@ -10,9 +10,6 @@ .POSIX: -# if using BSD make(1), remove these pragmas because they break it - - DESTDIR ?= dist PREFIX ?= /usr/local From 125b4c89300916bd3325343c71ff601be3916911 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 19 Jun 2024 02:52:58 -0600 Subject: [PATCH 77/81] README: updated for clarity --- README | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README b/README index d7a79f6..68be16c 100644 --- a/README +++ b/README @@ -1,9 +1,11 @@ “Seek not to walk the path of the masters; seek what they sought.” – Matsuo Basho -The Bonsai core utilities are the result of the careful examination of the -current state of POSIX and Unix utilies. The Unix Philosophy, “do one thing and -do it well” is its core but these tools do not cling to the names of the past. +The Bonsai core utilities are a replacement for standard POSIX utilities which +aim to fill its niche while expanding on their capabilities. These new tools are +the result of the careful examination of the current state of POSIX and Unix +utilies. The Unix Philosophy of “do one thing and do it well” are their core but +they avoid clinging to the past. The era of the original Unix tools has been long and fruitful, but they have their flaws. The new, non-POSIX era of this project started with frustration @@ -38,7 +40,7 @@ To test the utilities: $ make test -To remove all untracked files: +To remove all build and distributable files: $ make clean From e1ac40e7ee285131711117d5373825addfafb522 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 19 Jun 2024 15:03:06 -0600 Subject: [PATCH 78/81] docs: updates version number --- docs/dj.1 | 2 +- docs/false.1 | 2 +- docs/fop.1 | 2 +- docs/hru.1 | 2 +- docs/intcmp.1 | 2 +- docs/mm.1 | 2 +- docs/npc.1 | 2 +- docs/rpn.1 | 2 +- docs/scrut.1 | 2 +- docs/str.1 | 2 +- docs/strcmp.1 | 2 +- docs/swab.1 | 2 +- docs/true.1 | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 6073fc6..e229d1f 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME dj \(en disk jockey .\" diff --git a/docs/false.1 b/docs/false.1 index 1dec3ce..f86e1d8 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.9" .SH NAME false \(en do nothing, unsuccessfully .\" diff --git a/docs/fop.1 b/docs/fop.1 index b5c1b7c..6c7b991 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME fop \(en field operator .\" diff --git a/docs/hru.1 b/docs/hru.1 index acd5876..60a5afd 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 HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME hru \(en human readable units .\" diff --git a/docs/intcmp.1 b/docs/intcmp.1 index 2808362..b50b3f9 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.9" .SH NAME intcmp \(en compare integers .\" diff --git a/docs/mm.1 b/docs/mm.1 index 1fe64ba..107d5b0 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -3,7 +3,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME mm \(en middleman .\" diff --git a/docs/npc.1 b/docs/npc.1 index a0e503e..7b54e31 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME npc \(en show non-printing characters .\" diff --git a/docs/rpn.1 b/docs/rpn.1 index 01e00b9..10cd709 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME rpn \(en reverse polish notation evaluation .\" diff --git a/docs/scrut.1 b/docs/scrut.1 index 636c5d3..9dac85b 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.9" .SH NAME scrut \(en scrutinize file properties .SH SYNOPSIS diff --git a/docs/str.1 b/docs/str.1 index 55dd0bb..cfc859f 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME str \(en test string arguments .\" diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 5941762..0e5d46f 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME strcmp \(en compare strings .\" diff --git a/docs/swab.1 b/docs/swab.1 index abaab0b..97002e7 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.8" +.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.9" .SH NAME swab \(en swap bytes .\" diff --git a/docs/true.1 b/docs/true.1 index 2e8d5eb..b23021d 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.9" .SH NAME true \(en do nothing, successfully .\" From 35f49a699f5d4edb252b873dda1841645ba486a2 Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 19 Jun 2024 15:26:46 -0600 Subject: [PATCH 79/81] fop(1): fixes record separator, again --- src/fop.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fop.rs b/src/fop.rs index 1cc8152..9bf2396 100644 --- a/src/fop.rs +++ b/src/fop.rs @@ -32,7 +32,7 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; fn main() { let argv = args().collect::>(); - let mut d = 0x1E.to_string(); + let mut d = char::from(0x1E).to_string(); let mut arg_parser = Parser::new(&argv, "d:"); while let Some(opt) = arg_parser.next() { From 72f57ba08be24574ecd458f351c13ecf75d8192d Mon Sep 17 00:00:00 2001 From: emma Date: Wed, 19 Jun 2024 23:29:22 -0600 Subject: [PATCH 80/81] Makefile: adds octal disclaimer --- Makefile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Makefile b/Makefile index 0dee534..7756c56 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,9 @@ # permitted in any medium without royalty provided the copyright notice and this # notice are preserved. This file is offered as-is, without any warranty. +# The octal escape \043 is utilized twice in this file as make(1p) will +# interpret a hash in a rule as an inline comment. + .POSIX: DESTDIR ?= dist From 4b3333d8d31eae5a0d1a3f5c8601c696179150c2 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 21 Jun 2024 03:23:39 -0600 Subject: [PATCH 81/81] fop(1): record separator worky now? --- docs/dj.1 | 2 +- docs/false.1 | 2 +- docs/fop.1 | 2 +- docs/hru.1 | 2 +- docs/intcmp.1 | 2 +- docs/mm.1 | 2 +- docs/npc.1 | 2 +- docs/rpn.1 | 2 +- docs/scrut.1 | 2 +- docs/str.1 | 2 +- docs/strcmp.1 | 2 +- docs/swab.1 | 2 +- docs/true.1 | 2 +- src/fop.rs | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index e229d1f..7d28ac8 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME dj \(en disk jockey .\" diff --git a/docs/false.1 b/docs/false.1 index f86e1d8..5b582dd 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.9" +.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.11" .SH NAME false \(en do nothing, unsuccessfully .\" diff --git a/docs/fop.1 b/docs/fop.1 index 6c7b991..f7afa54 100644 --- a/docs/fop.1 +++ b/docs/fop.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH FOP 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME fop \(en field operator .\" diff --git a/docs/hru.1 b/docs/hru.1 index 60a5afd..346f200 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 HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME hru \(en human readable units .\" diff --git a/docs/intcmp.1 b/docs/intcmp.1 index b50b3f9..315cda2 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.9" +.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.11" .SH NAME intcmp \(en compare integers .\" diff --git a/docs/mm.1 b/docs/mm.1 index 107d5b0..3ca0722 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -3,7 +3,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME mm \(en middleman .\" diff --git a/docs/npc.1 b/docs/npc.1 index 7b54e31..51cb851 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME npc \(en show non-printing characters .\" diff --git a/docs/rpn.1 b/docs/rpn.1 index 10cd709..7d3b477 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME rpn \(en reverse polish notation evaluation .\" diff --git a/docs/scrut.1 b/docs/scrut.1 index 9dac85b..1e17f7e 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.9" +.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.11" .SH NAME scrut \(en scrutinize file properties .SH SYNOPSIS diff --git a/docs/str.1 b/docs/str.1 index cfc859f..6f01125 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME str \(en test string arguments .\" diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 0e5d46f..2ff08f6 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME strcmp \(en compare strings .\" diff --git a/docs/swab.1 b/docs/swab.1 index 97002e7..1c75705 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.9" +.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.11" .SH NAME swab \(en swap bytes .\" diff --git a/docs/true.1 b/docs/true.1 index b23021d..ebf8916 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.9" +.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.11" .SH NAME true \(en do nothing, successfully .\" diff --git a/src/fop.rs b/src/fop.rs index 9bf2396..5244300 100644 --- a/src/fop.rs +++ b/src/fop.rs @@ -32,7 +32,7 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; fn main() { let argv = args().collect::>(); - let mut d = char::from(0x1E).to_string(); + let mut d = '\u{1E}'.to_string(); let mut arg_parser = Parser::new(&argv, "d:"); while let Some(opt) = arg_parser.next() {