trinity/overgrown
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fixed formatting of many manpages

Browse Source
This commit is contained in:
Emma Tebibyte 2024-03-26 18:26:51 -06:00
parent 127192185f
commit a6fd1108c6
Signed by untrusted user: emma
GPG Key ID: 06FA419A1698C270
6 changed files with 218 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
docs/dj.1
View File

@ -1,4 +1,5 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
@ -46,84 +47,117 @@ dj
.SH USAGE .SH USAGE
The .B -A
.B -i .RS
option takes a path as an argument to open and use in place of standard input. Takes no arguments and pads with nuls.
The .RE
.B -o
option does the same in place of standard output. Dj does not truncate output
files and instead writes over the bytes in the existing file.
.PP
The
.B -b
option takes a numeric argument as the size in bytes of the input buffer and
the
.B -B .B -B
option does the same for the output buffer, the default for both being 1024 .RS
bytes, or one kibibyte (KiB). Does the same as
.PP .B -b
The but for the output buffer.
.B -s .RE
option takes a numeric argument as the number of bytes to skip into the input
before starting to read, and the .B -H
.RS
Prints diagnostics messages in an alternate manner as described in the
DIAGNOSTICS section below.
.RE
.B -S .B -S
option skips a number of bytes through the output before starting to write from .RS
Skips a number of bytes through the output before starting to write from
the input. If the input is a stream the bytes are read and discarded. If the the input. If the input is a stream the bytes are read and discarded. If the
output is a stream, nul characters are printed. output is a stream, nul characters are printed.
.PP .RE
The
.B -a .B -a
option takes one argument of one byte in length and pads the input buffer with .RS
that byte in the event that a read doesn't fill the input buffer, and the Takes one argument of one byte in length and pads the input buffer with
.B -A that byte in the event that a read doesn’t fill the input buffer, and the
option takes no arguments and pads with nuls. .RE
The
.B -b
.RS
Takes a numeric argument as the size in bytes of the input buffer, with the
default being 1024 bytes or one kibibyte (KiB).
.RE
.B -c .B -c
option specifies an amount of reads to make, and if 0 (the default) dj will .RS
Specifies an amount of reads to make, and if 0 (the default) dj will
continue reading until a partial or empty read. continue reading until a partial or empty read.
.PP .RE
.B -d
.RS
Prints all debug information, user-specified or otherwise, before program
execution.
.RE
.B -i
.RS
Takes a path as an argument to open and use in place of standard input.
.RE
.B -n
.RS
Causes dj to exit on two consecutive empty reads instead of one.
.RE
.B -o
.RS
Does the same as
.B -i
but in place of standard output. Dj does not truncate output
files and instead writes over the bytes in the existing file.
.RE
.B -s
.RS
Takes a numeric argument as the number of bytes to skip into the input
before starting to read.
.RE
.B -q
.RS
Suppresses error messages which print when a read or write is partial or
empty. When
.B -q
is specified twice suppresses diagnostic output entirely.
.RE
.SH DIAGNOSTICS
On a partial or empty read, dj prints a diagnostic message (unless the On a partial or empty read, dj prints a diagnostic message (unless the
.B -q .B -q
option is specified) and exits (unless the option is specified) and exits (unless the
.B -n .B -n
option is specified, in which case only two consecutive empty reads will cause option is specified.
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.
.SH DIAGNOSTICS By default statistics are printed for input and output to the standard error in
the following format:
The .RS
.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
.R {records read} {ASCII unit separator} {partial records read} .R {records read} {ASCII unit separator} {partial records read}
.R {ASCII record separator} {records written} {ASCII unit separator} .R {ASCII record separator} {records written} {ASCII unit separator}
.R {partial records written} {ASCII group separator} {bytes read} .R {partial records written} {ASCII group separator} {bytes read}
.R {ASCII record separator} {bytes written} {ASCII file separator} .R {ASCII record separator} {bytes written} {ASCII file separator}
.PP .RE
If the If the
.B -H .B -H
option is specified dj instead uses this following format: option is specified, dj instead uses the following format:
.PP
.RS
.R {records read} '+' {partial records read} '>' {records written} .R {records read} '+' {partial records read} '>' {records written}
.R '+' {partial records written} ';' {bytes read} '>' {bytes written} .R '+' {partial records written} ';' {bytes read} '>' {bytes written}
.R {ASCII line feed} .R {ASCII line feed}
.PP .RE
The
.B -q In non-recoverable errors that don’t pertain to dj’s read-write cycle, a
option suppresses error messages which print when a read or write is partial or diagnostic message is printed and dj exits with the appropriate sysexits.h(3)
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. status.
.SH BUGS .SH BUGS
@ -136,7 +170,7 @@ expected (the product of the count multiplied by the input block size). If the
or or
.B -A .B -A
options are used this could make data written nonsensical. options are used this could make data written nonsensical.
.PP
Many lowercase options have capitalized variants and vice-versa which can be Many lowercase options have capitalized variants and vice-versa which can be
confusing. Capitalized options tend to affect output or are more intense confusing. Capitalized options tend to affect output or are more intense
versions of lowercase options. versions of lowercase options.
@ -146,15 +180,15 @@ versions of lowercase options.
Dj was modeled after the dd utility specified in POSIX but adds additional Dj was modeled after the dd utility specified in POSIX but adds additional
features: typical option formatting, allowing seeks to be specified in bytes features: typical option formatting, allowing seeks to be specified in bytes
rather than in blocks, allowing arbitrary bytes as padding, and printing in a 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 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 conversion, which may be dd’s original intent but is irrelevant to its modern
use. use.
.SH COPYRIGHT .SH COPYRIGHT
Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.SH SEE ALSO .SH SEE ALSO
dd(1) dd(1p)

49
docs/intcmp.1
View File

@ -1,5 +1,5 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
@ -13,7 +13,7 @@ intcmp \(en compare integers
.SH SYNOPSIS .SH SYNOPSIS
intcmp intcmp
.RB ( -eghl ) .RB ( -egl )
.RB [ integer ] .RB [ integer ]
.RB [ integer... ] .RB [ integer... ]
@ -23,35 +23,52 @@ Intcmp compares integers.
.SH USAGE .SH USAGE
The -e option permits given integers to be equal to each other. If combined .B -e
with -g or -l, only adjacent integers in the argument sequence can be equal. .RS
.PP Permits given integers to be equal to each other. If combined with
The -g option permits a given integer to be greater than the following integer. .B -g
.PP or
The -l option permits a given integer to be less than the following integer. .B -l
.PP , only adjacent integers in the argument sequence can be equal.
.RE
.B -g
.RS
Permits a given integer to be greater than the following integer.
.RE
.B -l
.RS
Permits a given integer to be less than the following integer.
.RE
.SH EXAMPLES
It may help to think of the -e, -g, and -l options as equivalent to the It may help to think of the -e, -g, and -l options as equivalent to the
infix algebraic “=”, “>”, and “<” operators respectively, with each option infix algebraic “=”, “>”, and “<” operators respectively, with each option
putting its symbol between every given integer. For example, putting its symbol between every given integer. The following example is
equivalent to evaluating “1 < 2 < 3”:
.RS
.R intcmp -l 1 2 3 .R intcmp -l 1 2 3
is equivalent to evaluating "1 < 2 < 3". .RE
.SH DIAGNOSTICS .SH DIAGNOSTICS
Intcmp exits 0 for a valid expression and 1 for an invalid expression. Intcmp exits 0 for a valid expression and 1 for an invalid expression.
.PP
Intcmp prints a debug message and exits with the appropriate sysexits(3) error Intcmp prints a debug message and exits with the appropriate sysexits.h(3) error
code in the event of an error. code in the event of an error.
.SH BUGS .SH BUGS
There are multiple ways to express compound comparisons; “less than or equal There are multiple ways to express compound comparisons; “less than or equal
to” can be -le or -el, for example. to” can be -le or -el, for example.
.PP
The inequality comparison is -gl or -lg for “less than or greater than”; this The inequality comparison is -gl or -lg for “less than or greater than”; this
is elegant but unintuitive. is elegant but unintuitive.
.PP
-egl, "equal to or less than or greater than", exits 0 no matter what for valid -egl, “equal to or less than or greater than”, exits 0 no matter what for valid
program usage and may be abused to function as an integer validator. program usage and may be abused to function as an integer validator.
Use str(1) instead. Use str(1) instead.

31
docs/npc.1
View File

@ -1,5 +1,5 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
@ -13,29 +13,31 @@ npc \(en show non-printing characters
.SH SYNOPSIS .SH SYNOPSIS
npc npc
.RB ( -eht ) .RB ( -et )
.SH DESCRIPTION .SH DESCRIPTION
Npc reads from standard input and writes to standard output, replacing non- Npc reads from standard input and writes to standard output, replacing non-
printing characters with printable equivalents. Control characters print as a printing characters with printable equivalents. Control characters print as a
carat ('^') followed by the character '@' through '_' corresponding to the carat (“^”) followed by the character “@” through “_” corresponding to the
character replaced (e.g. control-X becomes "^X"). The delete character (0x7F) character replaced (e.g. control-X becomes “^X”). The delete character (0x7F)
becomes "^?". Characters with the high bit set (>127) are printed as "M-" becomes “^?”. Characters with the high bit set (>127) are printed as “M-”
followed by the graphical representation for the same character without the followed by the graphical representation for the same character without the
high bit set. high bit set.
.PP
The
.B -e .B -e
option prints a currency sign ('$') before each line ending. .RS
.PP Prints a currency sign (“$”) before each line ending.
The .RE
.B -t .B -t
option prints tab characters as "^I" rather than a literal horizontal tab. .RS
Prints tab characters as “^I” rather than a literal horizontal tab.
.RE
.SH DIAGNOSTICS .SH DIAGNOSTICS
Npc prints a debug message and exits with the appropriate sysexits(3) error Npc prints a debug message and exits with the appropriate sysexits.h(3) error
code in the event of an error, otherwise it exits successfully. code in the event of an error, otherwise it exits successfully.
.SH BUGS .SH BUGS
@ -45,8 +47,9 @@ Npc operates in single-byte chunks regardless of intended encoding.
.SH RATIONALE .SH RATIONALE
POSIX currently lacks a way to display non-printing characters in the terminal 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 using a standard tool. A popular extension to cat(1p), the
bandage solution GNU and other software suites use. .B -v
option, is the bandage solution GNU and other software suites use.
This functionality should be a separate tool because its usefulness extends This functionality should be a separate tool because its usefulness extends
beyond that of cat(1p). beyond that of cat(1p).

107
docs/scrut.1
View File

@ -1,4 +1,5 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
@ -21,47 +22,75 @@ Scrut determines if given files comply with the opted requirements.
.SH OPTIONS .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 .B -L
requires the given files to exist and be symbolic links. .RS
.PP Requires the given files to exist and be symbolic links.
.RE
.B -S .B -S
requires the given files to exist and be sockets. .RS
Requires the given files to exist and be sockets.
.RE
.B -b
.RS
Requires the given files to exist and be block special files.
.RE
.B -c
.RS
Requires the given files to exist and be character special files.
.RE
.B -d
.RS
Requires the given files to exist and be directories.
.RE
.B -e
.RS
Requires the given files to exist, and is redundant to any other option.
.RE
.B -e
.RS
Requires the given files to exist and be regular files.
.RE
.B -g
.RS
Requires the given files to exist and have their set group ID flags set.
.RE
.B -k
.RS
Requires the given files to exist and have their sticky bit set.
.RE
.B -p
.RS
Requires the given files to exist and be named pipes.
.RE
.B -r
.RS
Requires the given files to exist and be readable.
.RE
.B -u
.RS
Requires the given files to exist and have their set user ID flags set.
.RE
.B -w
.RS
Requires the given files to exist and be writable.
.RE
.B -x
.RS
Requires the given files to exist and be executable.
.RE
.SH EXIT STATUS .SH EXIT STATUS

8
docs/str.1
View File

@ -1,5 +1,5 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
@ -24,10 +24,10 @@ the function of the same name within ctype(3).
.SH DIAGNOSTICS .SH DIAGNOSTICS
Str exits successfully if all tests pass and unsuccessfully if a test failed. 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 Str will exit unsuccessfully if a string is empty, as none of its contents
passed the test. passed the test.
.PP
Str will print a message to standard error and exit unsuccessfully if used Str will print a message to standard error and exit unsuccessfully if used
improperly. improperly.
@ -41,7 +41,7 @@ removed in favor of using strcmp(1) to compare strings against the empty string
There's no way of knowing which argument failed the test without re-testing There's no way of knowing which argument failed the test without re-testing
arguments individually. arguments individually.
.PP
If a character in a string isn't valid ASCII str will exit unsuccessfully. If a character in a string isn't valid ASCII str will exit unsuccessfully.
.SH AUTHOR .SH AUTHOR

2
docs/strcmp.1
View File

@ -1,5 +1,5 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.