From 63a0c683f9803fe8b5023e07ceac1fc0bd922e51 Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 26 Mar 2024 19:22:30 -0600 Subject: [PATCH] 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