docs: fixed formatting of many manpages
This commit is contained in:
parent
127192185f
commit
a6fd1108c6
GPG Key ID:
06FA419A1698C270
156
docs/dj.1
156
docs/dj.1
@ -1,4 +1,5 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
@ -46,84 +47,117 @@ dj
|
||||
|
||||
.SH USAGE
|
||||
|
||||
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
|
||||
.B -b
|
||||
option takes a numeric argument as the size in bytes of the input buffer and
|
||||
the
|
||||
.B -A
|
||||
.RS
|
||||
Takes no arguments and pads with nuls.
|
||||
.RE
|
||||
|
||||
.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
|
||||
.RS
|
||||
Does the same as
|
||||
.B -b
|
||||
but for the output buffer.
|
||||
.RE
|
||||
|
||||
.B -H
|
||||
.RS
|
||||
Prints diagnostics messages in an alternate manner as described in the
|
||||
DIAGNOSTICS section below.
|
||||
.RE
|
||||
|
||||
.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
|
||||
output is a stream, nul characters are printed.
|
||||
.PP
|
||||
The
|
||||
.RE
|
||||
|
||||
.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
|
||||
.RS
|
||||
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
|
||||
.RE
|
||||
|
||||
.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
|
||||
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.
|
||||
.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
|
||||
.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.
|
||||
option is specified.
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
By default statistics are printed for input and output to the standard error in
|
||||
the following format:
|
||||
|
||||
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
|
||||
.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
|
||||
.RE
|
||||
|
||||
If the
|
||||
.B -H
|
||||
option is specified dj instead uses this following format:
|
||||
.PP
|
||||
option is specified, dj instead uses the following format:
|
||||
|
||||
.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)
|
||||
.RE
|
||||
|
||||
In non-recoverable errors that don’t pertain to dj’s read-write cycle, a
|
||||
diagnostic message is printed and dj exits with the appropriate sysexits.h(3)
|
||||
status.
|
||||
|
||||
.SH BUGS
|
||||
@ -136,7 +170,7 @@ expected (the product of the count multiplied by the input block size). If the
|
||||
or
|
||||
.B -A
|
||||
options are used this could make data written nonsensical.
|
||||
.PP
|
||||
|
||||
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.
|
||||
@ -146,15 +180,15 @@ versions of lowercase options.
|
||||
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
|
||||
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.
|
||||
|
||||
.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>.
|
||||
|
||||
.SH SEE ALSO
|
||||
|
||||
dd(1)
|
||||
dd(1p)
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
@ -13,7 +13,7 @@ intcmp \(en compare integers
|
||||
.SH SYNOPSIS
|
||||
|
||||
intcmp
|
||||
.RB ( -eghl )
|
||||
.RB ( -egl )
|
||||
.RB [ integer ]
|
||||
.RB [ integer... ]
|
||||
|
||||
@ -23,35 +23,52 @@ Intcmp compares integers.
|
||||
|
||||
.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
|
||||
.B -e
|
||||
.RS
|
||||
Permits given integers to be equal to each other. If combined with
|
||||
.B -g
|
||||
or
|
||||
.B -l
|
||||
, 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
|
||||
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
|
||||
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
|
||||
|
||||
Intcmp prints a debug message and exits with the appropriate sysexits.h(3) error
|
||||
code in the event of an error.
|
||||
|
||||
.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
|
||||
|
||||
-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.
|
||||
|
||||
|
||||
31
docs/npc.1
31
docs/npc.1
@ -1,5 +1,5 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
@ -13,29 +13,31 @@ 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-"
|
||||
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
|
||||
.RS
|
||||
Prints a currency sign (“$”) before each line ending.
|
||||
.RE
|
||||
|
||||
.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
|
||||
|
||||
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.
|
||||
|
||||
.SH BUGS
|
||||
@ -45,8 +47,9 @@ Npc 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.
|
||||
using a standard tool. A popular extension to cat(1p), the
|
||||
.B -v
|
||||
option, is the bandage solution GNU and other software suites use.
|
||||
|
||||
This functionality should be a separate tool because its usefulness extends
|
||||
beyond that of cat(1p).
|
||||
|
||||
107
docs/scrut.1
107
docs/scrut.1
@ -1,4 +1,5 @@
|
||||
.\" 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,
|
||||
.\" 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
|
||||
|
||||
.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
|
||||
.RS
|
||||
Requires the given files to exist and be symbolic links.
|
||||
.RE
|
||||
|
||||
.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
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
@ -24,10 +24,10 @@ the function of the same name within ctype(3).
|
||||
.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.
|
||||
|
||||
@ -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
|
||||
arguments individually.
|
||||
.PP
|
||||
|
||||
If a character in a string isn't valid ASCII str will exit unsuccessfully.
|
||||
|
||||
.SH AUTHOR
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user