diff --git a/docs/dj.1 b/docs/dj.1 index 1e286f5..f5dbe18 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -1,14 +1,13 @@ .\" 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 dj 1 - +.\" +.TH DJ 1 .SH NAME - dj \(en disk jockey - +.\" .SH SYNOPSIS dj @@ -43,118 +42,155 @@ dj .R [ .B output offset .R ]) +.\" +.SH DESCRIPTION -.SH USAGE +Perform precise read and write operations on files. This utility is useful for +reading and writing binary data to and from disks, hence the name. -The -.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 +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. + +When seeking or skipping to a byte, writing or reading starts at the byte +immediately subsequent to the specified byte. +.\" +.SH OPTIONS + +.IP \fB-i\fP +Takes a file path as an argument and opens it for use as an input. +.IP \fB-b\fP +Takes a numeric argument as the size in bytes of the input buffer, with the +default being 1024. +.IP \fB-s\fP +Takes a numeric argument as the number of bytes to skip into the input +before starting to read. If the standard input is used, bytes read to this point +are discarded. +.IP \fB-o\fP +Takes a file path as an argument and opens it for use as an output. +.IP \fB-B\fP +Does the same as .B -b -option takes a numeric argument as the size in bytes of the input buffer and -the -.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 -.B -S -option skips a number of bytes through the output before starting to write from -the input. If the input is a stream the bytes are read and discarded. If the -output is a stream, nul characters are printed. -.PP -The +but for the output buffer. +.IP \fB-S\fP +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 +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 .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 -.B -c -option specifies an amount of reads to make, and if 0 (the default) dj will -continue reading until a partial or empty read. -.PP -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. +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. +.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. +.IP \fB-H\fP +Prints diagnostics messages in a human-readable manner as described in the +DIAGNOSTICS section below. +.IP \fB-n\fP +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 +one or more of the input files is \(lq-\(rq. +.\" .SH DIAGNOSTICS -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 +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: + +.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 -If the +.RE + +This format for diagnostic output is designed to be machine-parseable for +convenience. For a more human-readable format, the .B -H -option is specified dj instead uses this following format: -.PP +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} -.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) -status. +.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\(cqt pertain to the read-write cycle, a +diagnostic message is printed and the program exits with the appropriate +.BR sysexits.h (3) +status. +.\" .SH BUGS If .B -n -is specified along with a specified count, actual byte output may be lower than -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. -.PP +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 -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. - +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 -Copyright (C) 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(1) +.BR dd (1p) diff --git a/docs/false.1 b/docs/false.1 index 6883802..91bd286 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -1,35 +1,35 @@ .\" 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 . - +.\" .TH FALSE 1 - .SH NAME - 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, +.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 new file mode 100644 index 0000000..295d9ff --- /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 + +.IP \fB-d\fP +Sets a delimiter by which the input data will be split into fields. The default +is an ASCII record separator. +.\" +.SH STANDARD INPUT + +Data will be read from the standard input. +.\" +.SH CAVEATS + +Field indices are zero-indexed, which may be unexpected behavior for some users. +.\" +.SH RATIONALE + +With the assumption that tools will output data separated with ASCII field +separators, there is a need for the ability to modify select fields in this data +easily and quickly. + +The idea for this utility originated in the fact that the GNU +.BR ls (1) +utility contains a +.B -h +option which enables human-readable units in file size outputs. This +functionality was broken out into +.BR hru (1), +but there was no easy way to modify the field in the ouput of +.BR ls (1p) +without creating a new tool. +.\" +.SH COPYRIGHT + +Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later +. +.\" +.SH SEE ALSO +.BR sed (1p) diff --git a/docs/hru.1 b/docs/hru.1 index c75cb73..8b898f8 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -2,56 +2,66 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH rpn 1 - +.\" +.TH HRU 1 .SH NAME - hru \(en human readable units - +.\" .SH SYNOPSIS hru - +.\" .SH DESCRIPTION -Hru reads byte counts in the form of whole numbers from the standard input and -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 +.BR sysexits.h (3) +and print an error message. +.\" .SH RATIONALE -The GNU project’s 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 -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 -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 -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 f370755..905d31d 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -1,78 +1,92 @@ .\" 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 . - -.TH intcmp 1 - +.\" +.TH INTCMP 1 .SH NAME - intcmp \(en compare integers - +.\" .SH SYNOPSIS intcmp -.RB ( -eghl ) +.RB ( -egl ) .RB [ integer ] .RB [ integer... ] - .SH DESCRIPTION +Compare integers to each other. +.\" +.SH OPTIONS -Intcmp compares integers. +.IP \fB-e\fP +Permits given integers to be equal to each other. +.IP \fB-g\fP +Permits a given integer to be greater than the following integer. +.IP \fB-l\fP +Permits a given integer to be less than the following integer. +.\" +.SH EXAMPLES -.SH USAGE - -The -e option permits given integers to be equal to each other. If combined -with -g or -l, only adjacent integers in the argument sequence can be equal. -.PP -The -g option permits a given integer to be greater than the following integer. -.PP -The -l option permits a given integer to be less than the following integer. -.PP It may help to think of the -e, -g, and -l options as equivalent to the -infix algebraic “=”, “>”, and “<” operators respectively, with each option -putting its symbol between every given integer. For example, +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 -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 -code in the event of an error. +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 +.BR sysexits.h (3) +error code. +.\" .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 -program usage and may be abused to function as an integer validator. -Use str(1) instead. +-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. + +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. - -Strcmp’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 2244588..812aef7 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -2,13 +2,11 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - +.\" .TH mm 1 - .SH NAME - mm \(en middleman - +.\" .SH SYNOPSIS mm @@ -17,60 +15,59 @@ mm .RB [ input ]) .RB ( -o .RB [ output ]) - +.\" .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 -.B -e -option. -.PP -The -.B -u -option ensures neither input or output will be buffered. -.PP -The -.B -n -option tells mm to ignore SIGINT signals. - +.IP \fB-a\fP +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. 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. 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 +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. -.PP -On error mm prints a diagnostic message and exits with the appropriate -sysexits.h(3) status. +If an output cannot be written to, an error occurs. Additional outputs are not +affected and writing to them continues. -.SH BUGS - -Mm does not truncate existing files, which may lead to unexpected results. +When an error is encountered, a diagnostic message is printed and the program +exits with the appropriate +.BR sysexits.h (3) +status. +.\" +.SH CAVEATS +Existing files are not truncated on ouput and are instead overwritten. +.\" .SH RATIONALE -Mm was modeled after the cat and tee utilities specified in POSIX. - +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 -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 - -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 7f66c3d..27926ee 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -1,68 +1,74 @@ .\" 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 . - -.TH npc 1 - +.\" +.TH NPC 1 .SH NAME - 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-" +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. -.PP -The -.B -e -option prints a currency sign ('$') before each line ending. -.PP -The -.B -t -option prints tab characters as "^I" rather than a literal horizontal tab. +.\" +.SH USAGE +.IP \fB-e\fP +Prints a dollar sign ('$') before each line ending. +.IP \fB-t\fP +Prints tab characters as '^I' rather than a literal horizontal tab. +.\" .SH DIAGNOSTICS -Npc prints a debug message and exits with the appropriate sysexits(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 +.BR 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 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. - -This functionality should be a separate tool because its usefulness extends -beyond that of cat(1p). +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). +.\" .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 - -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 2197fbe..8a3b0fe 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -3,68 +3,82 @@ .\" .\" 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 -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. -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 -If arguments are passed to rpn, it interprets them as an expression to be +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 an error, a debug message will be printed and the program will +exit with the appropriate +.BR sysexits.h (3) +error code; however, in the event of a syntax error, the program will print an +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 (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 -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 -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 7a5107a..2cb687c 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -1,93 +1,86 @@ .\" 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 scrut 1 - .SH NAME - scrut \(en scrutinize file properties - .SH SYNOPSIS scrut -.RB ( -bcdefgkprsuwxLS ) +.RB ( -LSbcdefgkprsuwx ) .RB [ file... ] - +.\" .SH DESCRIPTION -Scrut determines if given files comply with the opted 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 -.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 -.B -S -requires the given files to exist and be sockets. +.IP \fB-L\fB +Requires the given files to exist and be symbolic links. +.IP \fB-S\fP +Requires the given files to exist and be sockets. +.IP \fB-b\fP +Requires the given files to exist and be block special files. +.IP \fB-c\fP +Requires the given files to exist and be character special files. +.IP \fB-d\fP +Requires the given files to exist and be directories. +.IP \fB-e\fP +Requires the given files to exist, and is redundant to any other option. +.IP \fB-f\fP +Requires the given files to exist and be regular files. +.IP \fB-g\fP +Requires the given files to exist and have their set group ID flags set. +.IP \fB-k\fP +Requires the given files to exist and have their sticky bit set. +.IP \fB-p\fP +Requires the given files to exist and be named pipes. +.IP \fB-r\fP +Requires the given files to exist and be readable. +.IP \fB-u\fP +Requires the given files to exist and have their set user ID flags set. +.IP \fB-w\fP +Requires the given files to exist and be writable. +.IP \fB-x\fP +Requires the given files to exist and be executable. +.\" +.SH DIAGNOSTICS -.SH EXIT STATUS +When invoked incorrectly, a debug message will be printed and the program will +exit with the appropriate +.BR sysexits.h (3) +error code. +.\" +.SH RATIONALE -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. - -.SH STANDARDS - -Scrut is nearly compatible with POSIX's test utility though it is narrower in -scope. Notably, the +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 ecf71ee..66565b9 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -1,58 +1,60 @@ .\" 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 . - +.\" .TH STR 1 - .SH NAME - str \(en test the character types of string arguments - +.\" .SH SYNOPSIS str .RB [ type ] .RB [ string... ] - +.\" .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. +The tests in this program are equivalent to the functions with the same names in +.BR 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. -.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. +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. -.SH DEPRECATED FEATURES +An empty string will cause an unsuccessful exit as none of its contents pass any +tests. -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 -(''). +When invoked incorrectly, a debug message will be printed and the program will +exit with the appropriate +.BR sysexits.h (3) +error code. +.\" +.SH CAVEATS -.SH BUGS - -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. -.PP -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 -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 - -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 14c0d0d..84b661d 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -1,62 +1,75 @@ .\" 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 . - +.\" .TH STRCMP 1 - .SH NAME - strcmp \(en compare strings - +.\" .SH SYNOPSIS strcmp .RM [ string ] .RB [ strings... ] - +.\" .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. -.R strcmp b a -) -and 255 if an earlier string has a lesser byte value (e.g. -.R strcmp a b -). - +Check whether string arguments are the same. +.\" .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). +The program will exit successfully if the strings are identical. Otherwise, it +will exit with an error code of 1 if a string passed has a lesser byte value +than one of the prior strings: -.SH UNICODE +.RS +.R strcmp b a +.RE -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. +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 +.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. - -Strcmp’s functionality may be performed on a POSIX-compliant system with -test(1p). +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\(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(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 a0c1be3..0ca19e8 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -1,14 +1,13 @@ .\" 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 swab 1 - +.\" +.TH SWAB 1 .SH NAME - swab \(en swap bytes - +.\" .SH SYNOPSIS swab @@ -17,55 +16,58 @@ swab .R [ .B word size .R ]) +.\" +.SH DESCRIPTION -.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 +.IP \fB-f\fP +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 +cleanly divisible by 2, otherwise the block of bytes being processed can\(cqt be +halved. +.\" .SH EXAMPLES -The following sh(1p) line: +The following +.BR sh (1p) +line: -.R printf 'hello world!\n' | swab +.RS +.R printf 'hello world!\(rsn' | 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 +.BR sysexits.h (3) +error code. +.\" .SH RATIONALE -Swab was modeled 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. +This program was modeled and named after the conv=swab functionality specified +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. +.\" .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 - -dd(1p) +.BR dd (1p) diff --git a/docs/true.1 b/docs/true.1 index 3c292d8..ecf4c8e 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -1,35 +1,36 @@ .\" 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 . - +.\" .TH TRUE 1 - .SH NAME - 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 \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)