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 .