From 70cbc52c932e799b4b9e863d73adbdf95006184c Mon Sep 17 00:00:00 2001 From: emma Date: Sun, 2 Jun 2024 18:47:14 -0600 Subject: [PATCH] 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)