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

docs: updates to use man(7) macros to fix formatting

Browse Source
This commit is contained in:
Emma Tebibyte 2024-06-02 18:47:14 -06:00
parent b7f52902b6
commit 70cbc52c93
Signed by untrusted user: emma
GPG Key ID: 06FA419A1698C270
13 changed files with 406 additions and 495 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
docs/dj.1
View File

@ -3,15 +3,13 @@
.\" .\"
.\" 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/>.
.\"
.TH dj 1 .TH DJ 1
.SH NAME .SH NAME
dj \(en disk jockey dj \(en disk jockey
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
dj dj
.RB ( -AdHnq ) .RB ( -AdHnq )
.RB ( -a .RB ( -a
@ -44,102 +42,63 @@ dj
.R [ .R [
.B output offset .B output offset
.R ]) .R ])
.\"
.SH OPTIONS .SH OPTIONS
.\"
.B -i .IP \fB-i\fP
.RS
Takes a file path as an argument and opens it for use as an input. Takes a file path as an argument and opens it for use as an input.
.RE .IP \fB-b\fP
.B -b
.RS
Takes a numeric argument as the size in bytes of the input buffer, with the Takes a numeric argument as the size in bytes of the input buffer, with the
default being 1024. default being 1024.
.RE .IP \fB-s\fP
.B -s
.RS
Takes a numeric argument as the number of bytes to skip into the input 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 before starting to read. If the standard input is used, bytes read to this point
are discarded. are discarded.
.RE .IP \fB-o\fP
.B -o
.RS
Takes a file path as an argument and opens it for use as an output. Takes a file path as an argument and opens it for use as an output.
.RE .IP \fB-B\fP
.B -B
.RS
Does the same as Does the same as
.B -b .B -b
but for the output buffer. but for the output buffer.
.RE .IP \fB-S\fP
.B -S
.RS
Skips a number of bytes through the output before starting to write from 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. the input. If the output is a stream, null characters are printed.
.RE .IP \fB-a\fP
.B -a
.RS
Accepts a single literal byte with which input buffer is padded in the event Accepts a single literal byte with which input buffer is padded in the event
of an incomplete read from the input file. of an incomplete read from the input file.
.RE .IP \fB-A\fP
.B -A
.RS
Specifying this option pads the input buffer with null bytes in the event of an Specifying this option pads the input buffer with null bytes in the event of an
incomplete read. Equivalent to specifying incomplete read. Equivalent to specifying
.B -a .B -a
with a null byte instead of a character. with a null byte instead of a character.
.RE .IP \fB-c\fP
.B -c
.RS
Specifies a number of reads to make. The default is zero, in which case the 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. input is read until a partial or empty read is made.
.RE .IP \fB-d\fP
.B -d
.RS
Prints invocation information before program execution as described in the Prints invocation information before program execution as described in the
DIAGNOSTICS section below. Each invocation increments the debug level of the DIAGNOSTICS section below. Each invocation increments the debug level of the
program. program.
.RE .IP \fB-H\fP
.B -H
.RS
Prints diagnostics messages in a human-readable manner as described in the Prints diagnostics messages in a human-readable manner as described in the
DIAGNOSTICS section below. DIAGNOSTICS section below.
.RE .IP \fB-n\fP
.B -n
.RS
Retries failed reads once more before exiting. Retries failed reads once more before exiting.
.RE .IP \fB-q\fP
.B -q
.RS
Suppresses error messages which print when a read or write is partial or Suppresses error messages which print when a read or write is partial or
empty. Each invocation decrements the debug level of the program. empty. Each invocation decrements the debug level of the program.
.RE
.SH STANDARD INPUT .SH STANDARD INPUT
.\"
The standard input shall be used as an input if no inputs are specified or if 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 .SH DIAGNOSTICS
.\"
On a partial or empty read, a diagnostic message is printed (unless the On a partial or empty read, a diagnostic message is printed (unless the
.B -q .B -q
option is specified) and the program exits (unless the option is specified) and the program exits (unless the
.B -n .B -n
option is specified). option is specified).
.\"
By default, statistics are printed for input and output to the standard error in By default, statistics are printed for input and output to the standard error in
the following format: the following format:
@ -175,12 +134,12 @@ as the only argument:
.R out=<stdout> obs=1024 seek=0 debug= 3 noerror=0 .R out=<stdout> obs=1024 seek=0 debug= 3 noerror=0
.RE .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 diagnostic message is printed and the program exits with the appropriate
sysexits.h(3) status. sysexits.h(3) status.
.\"
.SH BUGS .SH BUGS
.\"
If If
.B -n .B -n
is specified along with the is specified along with the
@ -191,29 +150,29 @@ of the count and 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.
.\"
.SH CAVEATS .SH CAVEATS
.\"
Existing files are not truncated on ouput and are instead overwritten. Existing files are not truncated on ouput and are instead overwritten.
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.
.\"
.SH RATIONALE .SH RATIONALE
.\"
This program was based on the dd(1p) utility as specified in POSIX. While 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 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 irrelevant to its modern use. Because of this, this program eschews character
conversion and adds typical option formatting, allowing seeks to be specified conversion and adds typical option formatting, allowing seeks to be specified
in bytes rather than in blocks, allowing arbitrary bytes as padding, and 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 .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
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.\"
dd(1p) .BR dd (1p)

40
docs/false.1
View File

@ -3,32 +3,34 @@
.\" .\"
.\" 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/>.
.\"
.TH FALSE 1 .TH FALSE 1
.SH NAME .SH NAME
false \(en do nothing, unsuccessfully false \(en do nothing, unsuccessfully
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Do nothing regardless of operands or standard input. Do nothing regardless of operands or standard input. An exit code of 1 will
An exit code of 1 will always be returned. always be returned.
.\"
.SH RATIONALE .SH RATIONALE
.\"
In POSIX.1-2017, false(1p) exists for the construction of control flow and loops In POSIX.1-2017,
based on a failure. This implementation functions as described in that standard. .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 .SH AUTHOR
.\"
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
This work is marked with CC0 1.0. To see a copy of this license, visit This work is marked with CC0 1.0. To see a copy of this license, visit
<http://creativecommons.org/publicdomain/zero/1.0>. <http://creativecommons.org/publicdomain/zero/1.0>.
.\"
.SH SEE ALSO .SH SEE ALSO
.\"
true(1p) .BR true (1p)

58
docs/fop.1
View File

@ -3,58 +3,58 @@
.\" .\"
.\" 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/>.
.\"
.TH fop 1 .TH fop 1
.SH NAME .SH NAME
fop \(en field operator fop \(en field operator
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
fop fop
.RB ( -d ) .RB ( -d )
.RB [ delimiter ] .RB [ delimiter ]
.RB index .RB index
.RB program... .RB program...
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Performs operations on specified fields in input data. Performs operations on specified fields in input data.
.\"
.SH OPTIONS .SH OPTIONS
.\"
.B -d .IP \fB-d\fP
.RS
Sets a delimiter by which the input data will be split into fields. The default Sets a delimiter by which the input data will be split into fields. The default
is an ASCII record separator (␞). is an ASCII record separator (␞).
.RE
.SH STANDARD INPUT .SH STANDARD INPUT
.\"
Data will be read from the standard input. Data will be read from the standard input.
.\"
.SH CAVEATS .SH CAVEATS
.\"
Field indices are zero-indexed, which may be unexpected behavior for some users. Field indices are zero-indexed, which may be unexpected behavior for some users.
.\"
.SH RATIONALE .SH RATIONALE
.\"
With the assumption that tools will output data separated with ASCII field 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 The idea for this utility originated in the fact that the GNU
a .BR ls (1)
utility contains a
.B -h .B -h
option which enables human-readable units in file size outputs. This 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 functionality was broken out into
the field in the ouput of ls(1p) without a new tool. .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 .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
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.\"
sed(1p) .BR sed (1p)

56
docs/hru.1
View File

@ -2,58 +2,60 @@
.\" .\"
.\" 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/>.
.\"
.TH hru 1 .TH HRU 1
.SH NAME .SH NAME
hru \(en human readable units hru \(en human readable units
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
hru hru
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Convert counts to higher units. Convert counts to higher units.
.\"
The program will read byte counts in the form of whole numbers from the standard 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. 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 The program will convert the byte count to the highest unit possible where the
value is greater than one. value is greater than one.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
If encountering non-integer characters in the standard input, the program will 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 exit with the appropriate error code as defined by sysexits.h(3) and print an
error message. error message.
.\"
.SH RATIONALE .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 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 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 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. program.
.\"
.SH STANDARDS .SH STANDARDS
.\"
The standard unit prefixes as specified by the Bureau International des Poids 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 et Mesures (BIPM) in the ninth edition of The International System of Units
(SI) are utilized for the ouput of conversions. (SI) are utilized for the ouput of conversions.
.\"
.SH AUTHOR .SH AUTHOR
.\"
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .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
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .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

107
docs/intcmp.1
View File

@ -3,90 +3,87 @@
.\" .\"
.\" 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/>.
.\"
.TH intcmp 1 .TH INTCMP 1
.SH NAME .SH NAME
intcmp \(en compare integers intcmp \(en compare integers
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
intcmp intcmp
.RB ( -egl ) .RB ( -egl )
.RB [ integer ] .RB [ integer ]
.RB [ integer... ] .RB [ integer... ]
.SH DESCRIPTION .SH DESCRIPTION
Compare integers to each other. Compare integers to each other.
.SH OPTIONS
.SH USAGE .IP \fB-e\fP
.B -e
.RS
Permits given integers to be equal to each other. Permits given integers to be equal to each other.
.RE .IP \fB-g\fP
.B -g
.RS
Permits a given integer to be greater than the following integer. Permits a given integer to be greater than the following integer.
.RE .IP \fB-l\fP
.B -l
.RS
Permits a given integer to be less than the following integer. Permits a given integer to be less than the following integer.
.RE
.SH EXAMPLES .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 \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq operators respectively, with
putting its symbol between every given integer. The following example is each option putting its symbol between every given integer. The following
equivalent to evaluating “1 < 2 < 3”: example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
.RS .RS
.R intcmp -l 1 2 3 .R intcmp -l 1 2 3
.RE .RE
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
The program will exit with a status code of 0 for a valid expression and with a The program will exit with a status code of 0 for a valid expression and with a
code of 1 for an invalid expression. code of 1 for an invalid expression.
In the event of an error, a debug message will be printed and the program will 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 .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 The inequality comparison is -gl or -lg for \(lqless than or greater than\(rq;
to” can be -le or -el, for example. this is elegant but unintuitive.
.\"
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.
.SH RATIONALE .SH RATIONALE
.\"
The traditional tool for integer comparisons in POSIX and other Unix shells has 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. been
These parts of its functionality have been broken out into multiple utilities. .BR test (1).
This tool also handles string comparisons and file scrutiny. These parts of its
This program’s functionality may be performed on a POSIX-compliant system with functionality have been broken out into multiple utilities.
test(1p).
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
.\"
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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
<https://gnu.org/licenses/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR scrut (1),
strcmp(1), scrut(1), str(1), test(1p) .BR strcmp (1),
.BR str (1),
.BR test (1p)

51
docs/mm.1
View File

@ -2,62 +2,41 @@
.\" .\"
.\" 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/>.
.\"
.TH mm 1 .TH mm 1
.SH NAME .SH NAME
mm \(en middleman mm \(en middleman
.SH SYNOPSIS .SH SYNOPSIS
.\"
mm mm
.RB ( -aenu ) .RB ( -aenu )
.RB ( -i .RB ( -i
.RB [ input ]) .RB [ input ])
.RB ( -o .RB ( -o
.RB [ output ]) .RB [ output ])
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Catenate input files and write them to the start of each output file or stream. Catenate input files and write them to the start of each output file or stream.
.\"
.SH OPTIONS .SH OPTIONS
.\"
.B -a .IP -a
.RS
Opens subsequent outputs for appending rather than updating. Opens subsequent outputs for appending rather than updating.
.RE .IP -e
.B -e
.RS
Use the standard error as an output. Use the standard error as an output.
.RE .IP -i
.B -i
.RS
Opens a path as an input. Without any inputs specified mm will use the 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 standard input. The standard input shall be used as an input if one or more of
the input files is “-”. the input files is “-”.
.RE .IP -o
.B -o
.RS
Opens a path as an output. Without any outputs specified mm will use the 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 standard output. The standard output shall be used as an output if one or more
of the output files is “-”. of the output files is “-”.
.IP -u
.RE
.B -u
.RS
Ensures neither input or output will be buffered. Ensures neither input or output will be buffered.
.RE .IP -n
.B -n
.RS
Causes SIGINT signals to be ignored. Causes SIGINT signals to be ignored.
.RE
.SH DIAGNOSTICS .SH DIAGNOSTICS
@ -84,5 +63,7 @@ Copyright (c) 2024 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
.BR cat (1p),
cat(1p), dd(1), dj(1), tee(1p) .BR dd (1),
.BR dj (1),
.BR tee (1p)

61
docs/npc.1
View File

@ -3,20 +3,18 @@
.\" .\"
.\" 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/>.
.\"
.TH npc 1 .TH NPC 1
.SH NAME .SH NAME
npc \(en show non-printing characters npc \(en show non-printing characters
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
npc npc
.RB ( -et ) .RB ( -et )
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Print normally non-printing characters. Print normally non-printing characters.
The program reads from standard input and writes to standard output, replacing 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-' 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.
.\"
.SH USAGE .SH USAGE
.\"
.B -e .IP -e
.RS
Prints a currency sign ('$') before each line ending. Prints a currency sign ('$') before each line ending.
.RE .IP -t
.B -t
.RS
Prints tab characters as '^I' rather than a literal horizontal tab. Prints tab characters as '^I' rather than a literal horizontal tab.
.RE .\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
In the event of an error, a debug message will be printed and the program will 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 .SH BUGS
.\"
The program operates in single-byte chunks regardless of intended encoding. The program 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 using a standard tool. A popular extension to
.BR cat (1p),
the
.B -v .B -v
option, is the bandage solution GNU and other software suites use. option, is the bandage solution GNU and other software suites use.
.\"
This functionality is a separate tool because its usefulness extends beyond that This functionality is a separate tool because its usefulness extends beyond that
of cat(1p). of
.BR cat (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.SH COPYRIGHT .SH COPYRIGHT
@ -69,7 +69,8 @@ Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
.SH SEE ALSO .SH SEE ALSO
cat(1p), cat-v(1) .BR cat (1p),
.BR cat-v (1)
.I UNIX Style, or cat -v Considered Harmful .I UNIX Style, or cat -v Considered Harmful
by Rob Pike by Rob Pike

85
docs/rpn.1
View File

@ -3,20 +3,19 @@
.\" .\"
.\" 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/>.
.\"
.TH rpn 1 .TH rpn 1
.SH NAME .SH NAME
rpn \(en reverse polish notation evaluation rpn \(en reverse polish notation evaluation
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
rpn rpn
.RB [numbers...]\ [operators...] .RB [ numbers... ]
.RB [ operators... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Evaluate reverse polish notation. Evaluate reverse polish notation.
The program evaluates reverse polish notation expressions either read from the 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. stack.
For information on for reverse polish notation syntax, see rpn(7). For information on for reverse polish notation syntax, see rpn(7).
.\"
.SH STANDARD INPUT .SH STANDARD INPUT
.\"
If arguments are passed , they are interpreted as an expression to be evaluated. If arguments are passed, they are interpreted as an expression to be
Otherwise, it reads whitespace-delimited numbers and operations from the evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
standard input. the standard input.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
In the event of a syntax error, the program will print an 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 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 .SH CAVEATS
.\"
Due to precision constraints and the way floats are represented in accordance Due to precision constraints and the way floats are represented in accordance
with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point with the IEEE Standard for Floating Point Arithmetic (\fIIEEE 754\fP),
arithmetic has rounding errors. This is somewhat curbed by using the floating-point arithmetic has rounding errors. This is somewhat curbed by using
machine epsilon as provided by the Rust standard library to which to round 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 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. the program can handle based on the platform and hardware of any given machine.
.\"
.SH RATIONALE .SH RATIONALE
.\"
An infix notation calculation utility, bc(1p), is included in the POSIX An infix notation calculation utility,
standard, but does not accept expressions as arguments; in scripts, any .BR bc (1p),
predefined, non-interactive input must be piped into the program. A dc(1) is included in the POSIX standard, but does not accept expressions as arguments;
pre-dates the standardized bc(1p), the latter originally being a preprocessor in scripts, any predefined, non-interactive input must be piped into the
for the former, and was included in UNIX v2 onward. While it implements reverse program. A
polish notation, it still suffers from being unable to accept an expression as .BR dc (1)
an argument. 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 .SH AUTHOR
.\"
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later Copyright (c) 2024 Emma Tebibyte. 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
.BR bc (1p),
bc(1p), dc(1), rpn(7), IEEE 754 .BR dc (1),
.BR rpn(7),
.I IEEE 754

122
docs/scrut.1
View File

@ -3,122 +3,86 @@
.\" .\"
.\" 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/>.
.\"
.TH scrut 1 .TH scrut 1
.SH NAME .SH NAME
scrut \(en scrutinize file properties scrut \(en scrutinize file properties
.SH SYNOPSIS .SH SYNOPSIS
.\"
scrut scrut
.RB ( -bcdefgkprsuwxLS ) .RB ( -bcdefgkprsuwxLS )
.RB [ file... ] .RB [ file... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Determine if files comply with requirements. Determine if files comply with requirements.
.\"
.SH OPTIONS .SH OPTIONS
.\"
.B -L .IP -L
.RS
Requires the given files to exist and be symbolic links. Requires the given files to exist and be symbolic links.
.RE .IP -S
.B -S
.RS
Requires the given files to exist and be sockets. Requires the given files to exist and be sockets.
.RE .IP -b
.B -b
.RS
Requires the given files to exist and be block special files. Requires the given files to exist and be block special files.
.RE .IP -c
.B -c
.RS
Requires the given files to exist and be character special files. Requires the given files to exist and be character special files.
.RE .IP -d
.B -d
.RS
Requires the given files to exist and be directories. Requires the given files to exist and be directories.
.RE .IP -e
.B -e
.RS
Requires the given files to exist, and is redundant to any other option. Requires the given files to exist, and is redundant to any other option.
.RE .IP -e
.B -e
.RS
Requires the given files to exist and be regular files. Requires the given files to exist and be regular files.
.RE .IP -g
.B -g
.RS
Requires the given files to exist and have their set group ID flags set. Requires the given files to exist and have their set group ID flags set.
.RE .IP -k
.B -k
.RS
Requires the given files to exist and have their sticky bit set. Requires the given files to exist and have their sticky bit set.
.RE .IP -p
.B -p
.RS
Requires the given files to exist and be named pipes. Requires the given files to exist and be named pipes.
.RE .IP -r
.B -r
.RS
Requires the given files to exist and be readable. Requires the given files to exist and be readable.
.RE .IP -u
.B -u
.RS
Requires the given files to exist and have their set user ID flags set. Requires the given files to exist and have their set user ID flags set.
.RE .IP -w
.B -w
.RS
Requires the given files to exist and be writable. Requires the given files to exist and be writable.
.RE .IP -x
.B -x
.RS
Requires the given files to exist and be executable. Requires the given files to exist and be executable.
.RE .\"
.SH DIAGNOSTICS
.SH EXIT STATUS .\"
If the given files comply with the specified requirements, the program will exit If the given files comply with the specified requirements, the program will exit
successfully. If not, it exits unsuccessfully. successfully. If not, it exits unsuccessfully.
When invoked incorrectly, a debug message will be printed and the program will When invoked incorrectly, 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)
.SH STANDARDS error code.
.\"
The test(1p) utility contains functionality that was broken out into separate .SH RATIONALE
programs. Thus, the scope of this program is narrower than it. 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 .B -h
option is now invalid and therefore shows usage information instead of being an option is now invalid and therefore shows usage information instead of being an
alias to the modern alias to the modern
.B -L .B -L
option. option.
.\"
.SH AUTHOR .SH AUTHOR
.\"
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.SH SEE ALSO .SH SEE ALSO
access(3p), lstat(3p), test(1p) .BR access (3p),
.BR lstat (3p),
.BR test (1p)

44
docs/str.1
View File

@ -3,28 +3,27 @@
.\" .\"
.\" 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/>.
.\"
.TH STR 1 .TH STR 1
.SH NAME .SH NAME
str \(en test the character types of string arguments str \(en test the character types of string arguments
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
str str
.RB [ type ] .RB [ type ]
.RB [ string... ] .RB [ string... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Test string arguments. Test string arguments.
The tests in this program are equivalent to the functions with the same names in 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 .SH DIAGNOSTICS
.\"
If all tests pass, the program will exit with an exit code of 0. If any of the 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. 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 When invoked incorrectly, a debug message will be printed and the program will
exit with the appropriate sysexits.h(3) error code. 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 There’s no way of knowing which argument failed the test without re-testing
arguments individually. arguments individually.
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
.\"
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
Copyright © 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/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR ctype (3p),
ctype(3p), strcmp(1), ascii(7) .BR strcmp(1),
.BR ascii(7)

66
docs/strcmp.1
View File

@ -3,61 +3,63 @@
.\" .\"
.\" 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/>.
.\"
.TH STRCMP 1 .TH STRCMP 1
.SH NAME .SH NAME
strcmp \(en compare strings strcmp \(en compare strings
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
strcmp strcmp
.RM [ string ] .RM [ string ]
.RB [ strings... ] .RB [ strings... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Check whether string arguments are the same. Check whether string arguments are the same.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
The program will exit successfully if the strings are identical. Otherwise, it 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 exits with the value 1 if an earlier string has a greater byte value than a
later string (e.g. later string (e.g. strcmp b a) and 255 if an earlier string has a lesser byte
.R strcmp b a value (e.g. strcmp a b).
)
and 255 if an earlier string has a lesser byte value (e.g.
.R strcmp a b
).
When invoked incorrectly, a debug message will be printed and the program will When invoked incorrectly, 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)
.SH UNICODE error code.
.\"
.SH CAVEATS
.\"
The program will exit unsuccessfully if the given strings are not identical; 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 therefore, Unicode strings may need to be normalized if the intent is to check
visual similarity and not byte similarity. visual similarity and not byte similarity.
.\"
.SH RATIONALE .SH RATIONALE
.\"
The traditional tool for string comparisons in POSIX and other Unix shells has 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. been
These parts of its functionality have been broken out into multiple utilities. .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 This program’s functionality may be performed on a POSIX-compliant system with
test(1p). .BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
.\"
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
Copyright © 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/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR strcmp (3),
strcmp(3), intcmp(1), scrut(1), test(1p) .BR intcmp (1),
.BR scrut (1),
.BR test (1p)

54
docs/swab.1
View File

@ -3,43 +3,36 @@
.\" .\"
.\" 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/>.
.\"
.TH swab 1 .TH SWAB 1
.SH NAME .SH NAME
swab \(en swap bytes swab \(en swap bytes
.\"
.SH SYNOPSIS .SH SYNOPSIS
.\"
swab swab
.RB ( -f ) .RB ( -f )
.RB ( -w .RB ( -w
.R [ .R [
.B word size .B word size
.R ]) .R ])
.\"
.SH USAGE .SH USAGE
.\"
Swap the latter and former halves of a block of bytes. Swap the latter and former halves of a block of bytes.
.\"
.SH OPTIONS .SH OPTIONS
.\"
.B -f .IP -f
.RS
Ignore system call interruptions. Ignore system call interruptions.
.RE .IP -w
.B -w
.RS
Configures the word size; that is, the size in bytes of the block size 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 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 cleanly divisible by 2, otherwise the block of bytes being processed can't be
halved. halved.
.RE .\"
.SH EXAMPLES .SH EXAMPLES
.\"
The following sh(1p) line: The following sh(1p) line:
.RS .RS
@ -51,27 +44,24 @@ Produces the following output:
.RS .RS
.R ehll oowlr!d .R ehll oowlr!d
.RE .RE
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
.\"
In the event of an error, a debug message will be printed and the program will 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 sysexits.h(3) error code.
.\"
.SH RATIONALE .SH RATIONALE
.\"
This program was modeled and named after the This program was modeled and named after the conv=swab functionality specified
.R conv=swab in the dd(1p) utility. It additionally allows the word size to be configured.
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 This functionality is useful for fixing the endianness of binary files produced
on other machines. on other machines.
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright (c) 2024 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
.BR dd (1p)
dd(1p)

36
docs/true.1
View File

@ -3,32 +3,34 @@
.\" .\"
.\" 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/>.
.\"
.TH TRUE 1 .TH TRUE 1
.SH NAME .SH NAME
true \(en do nothing, successfully true \(en do nothing, successfully
.\"
.SH DESCRIPTION .SH DESCRIPTION
.\"
Do nothing regardless of operands or standard input. Do nothing regardless of operands or standard input.
An exit code of 0 will always be returned. An exit code of 0 will always be returned.
.\"
.SH RATIONALE .SH RATIONALE
.\"
In POSIX.1-2017, true(1p) exists for the construction of control flow and loops In \fIPOSIX.1-2017\fP,
based on a success. This implementation functions as described in that standard. .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 .SH AUTHOR
.\"
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
This work is marked with CC0 1.0. To see a copy of this license, visit This work is marked with CC0 1.0. To see a copy of this license, visit
<http://creativecommons.org/publicdomain/zero/1.0>. <http://creativecommons.org/publicdomain/zero/1.0>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR false (1p),
false(1p) .BR true (1p)