From c32c554e03f8f7fdd62bbf981bbf70e3fe318f71 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 3 Jun 2024 23:07:19 -0600 Subject: [PATCH] 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 . .\"