harakit/docs/mm.1

.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\"
.\" 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/>.
.\"
.TH MM 1 2024-07-14 "Harakit X.X.X"
.SH NAME
mm \(en middleman
.\"
.SH SYNOPSIS

mm
.RB [ -aetu ]
.RB [ -i\ input ]
.RB [ -o\ output ]
.\"
.SH DESCRIPTION

Catenate input files and write them to the start of each output file or stream.
.\"
.SH OPTIONS

.IP \fB-a\fP
Opens outputs for appending rather than updating.
.IP \fB-e\fP
Use the standard error as an output.
.IP \fB-t\fP
Causes outputs to be overwritten instead of being truncated.
.IP \fB-u\fP
Ensures neither input or output will be buffered.
.IP \fB-i\fP\ \fIinput\fP
Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
no inputs are specified, the standard input shall be used. If specified as the
last option and if there are trailing arguments to the program, they shall be
appended to the list of files to use as inputs.
.IP \fB-o\fP\ \fIoutput\fP
Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
no outputs are specified and the
.B -e
option is not specified, the standard output shall be used. If specified as the
last option and if there are trailing arguments to the program, they shall be
appended to the list of files to use as inputs.
.\"
.SH DIAGNOSTICS

If an output cannot be written to, an error occurs; however, exiting will be 
deferred until writing to any other specified outputs completes.

When an error is encountered, a diagnostic message is printed and the program
exits with the appropriate
.BR sysexits.h (3)
status.
.\"
.SH RATIONALE

The
.BR cat (1p)
and
.BR tee (1p)
programs specified in POSIX together provide similar functionality. The
separation of the two sets of functionality into separate APIs seemed
unncessary.
.\"
.SH COPYRIGHT

Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR cat (1p),
.BR dd (1),
.BR dj (1),
.BR tee (1p)
mm(1): add 2024-02-17 23:43:22 -07:00			`.\" Copyright (c) 2024 DTB <trinity@trinity.moe>`
			`.\"`
			`.\" 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/>.`
docs: updates to use man(7) macros to fix formatting 2024-06-02 18:47:14 -06:00			`.\"`
mm.1: reflects new changes 2024-07-14 18:38:02 -06:00			`.TH MM 1 2024-07-14 "Harakit X.X.X"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH NAME`
			`mm \(en middleman`
docs: updates to use man(7) macros to fix formatting 2024-06-02 18:47:14 -06:00			`.\"`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00			`.SH SYNOPSIS`

mm(1): add 2024-02-17 23:43:22 -07:00			`mm`
mm(1): added -t for disabling truncation; mm.1: updated docs 2024-07-13 23:56:30 -06:00			`.RB [ -aetu ]`
docs, src: updates usage text for utilities 2024-06-29 05:18:20 -06:00			`.RB [ -i\ input ]`
			`.RB [ -o\ output ]`
docs: updates to use man(7) macros to fix formatting 2024-06-02 18:47:14 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH DESCRIPTION`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00
mm.1: updated man page 2024-03-26 18:44:05 -06:00			`Catenate input files and write them to the start of each output file or stream.`
docs: updates to use man(7) macros to fix formatting 2024-06-02 18:47:14 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH OPTIONS`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-a\fP`
mm(1): added -t for disabling truncation; mm.1: updated docs 2024-07-13 23:56:30 -06:00			`Opens outputs for appending rather than updating.`
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-e\fP`
mm.1: wording, consistency with dj.1 2024-03-27 00:14:34 -06:00			`Use the standard error as an output.`
mm(1): added -t for disabling truncation; mm.1: updated docs 2024-07-13 23:56:30 -06:00			`.IP \fB-t\fP`
			`Causes outputs to be overwritten instead of being truncated.`
			`.IP \fB-u\fP`
			`Ensures neither input or output will be buffered.`
docs, src: fixing man page and usage text readability 2024-06-29 05:28:23 -06:00			`.IP \fB-i\fP\ \fIinput\fP`
fop.1: removes Unicode representation of RS; hru.1: removes erroneous line break; mm.1: formatting & grammar; npc.1: dollar sign, not currency sign; rpn.1: syntax error; scrut.1: move description to DESCRIPTION; str.1: comma; swab.1: wording & escape codes; true.1: formatting 2024-06-05 23:07:15 -06:00			`Opens a path as an input. If one or more of the input files is \(lq-\(rq or if`
mm.1: reflects new changes 2024-07-14 18:38:02 -06:00			`no inputs are specified, the standard input shall be used. If specified as the`
			`last option and if there are trailing arguments to the program, they shall be`
			`appended to the list of files to use as inputs.`
docs, src: fixing man page and usage text readability 2024-06-29 05:28:23 -06:00			`.IP \fB-o\fP\ \fIoutput\fP`
fop.1: removes Unicode representation of RS; hru.1: removes erroneous line break; mm.1: formatting & grammar; npc.1: dollar sign, not currency sign; rpn.1: syntax error; scrut.1: move description to DESCRIPTION; str.1: comma; swab.1: wording & escape codes; true.1: formatting 2024-06-05 23:07:15 -06:00			`Opens a path as an output. If one or more of the output files is \(lq-\(rq or if`
mm(1): makes -e block inferring stdout as an output, mm.1: reflects changes to -e 2024-07-14 14:15:55 -06:00			`no outputs are specified and the`
			`.B -e`
mm.1: reflects new changes 2024-07-14 18:38:02 -06:00			`option is not specified, the standard output shall be used. If specified as the`
			`last option and if there are trailing arguments to the program, they shall be`
			`appended to the list of files to use as inputs.`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH DIAGNOSTICS`

mm.1: fixes clunky sentence 2024-06-17 22:57:08 -06:00			`If an output cannot be written to, an error occurs; however, exiting will be`
			`deferred until writing to any other specified outputs completes.`
mm.1: updated man page 2024-03-26 18:44:05 -06:00
fop.1: removes Unicode representation of RS; hru.1: removes erroneous line break; mm.1: formatting & grammar; npc.1: dollar sign, not currency sign; rpn.1: syntax error; scrut.1: move description to DESCRIPTION; str.1: comma; swab.1: wording & escape codes; true.1: formatting 2024-06-05 23:07:15 -06:00			`When an error is encountered, a diagnostic message is printed and the program`
mm.1: fixed manpage reference formatting 2024-06-03 23:45:26 -06:00			`exits with the appropriate`
			`.BR sysexits.h (3)`
			`status.`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH RATIONALE`

mm.1: fixed manpage reference formatting 2024-06-03 23:45:26 -06:00			`The`
			`.BR cat (1p)`
			`and`
			`.BR tee (1p)`
			`programs specified in POSIX together provide similar functionality. The`
			`separation of the two sets of functionality into separate APIs seemed`
			`unncessary.`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH COPYRIGHT`

docs: formatting 2024-06-04 16:11:33 -06:00			`Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later`
mm(1): add 2024-02-17 23:43:22 -07:00			`<https://gnu.org/licenses/agpl.html>.`
docs: removed unnecessary comments 2024-06-03 23:07:19 -06:00			`.\"`
mm(1): add 2024-02-17 23:43:22 -07:00			`.SH SEE ALSO`
docs: updates to use man(7) macros to fix formatting 2024-06-02 18:47:14 -06:00			`.BR cat (1p),`
			`.BR dd (1),`
			`.BR dj (1),`
			`.BR tee (1p)`