overgrown/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-06-17 "Bonsai Core Utilites 0.13.11"
.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

.IP \fB-a\fP
Opens subsequent outputs for appending rather than updating.
.IP \fB-e\fP
Use the standard error as an output.
.IP \fB-i\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.
.IP \fB-o\fP
Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
no outputs are specified, the standard output shall be used.
.IP \fB-u\fP
Ensures neither input or output will be buffered.
.IP \fB-n\fP
Causes SIGINT signals to be ignored.
.\"
.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 CAVEATS

Existing files are not truncated on ouput and are instead overwritten.
.\"
.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			`.\"`
fop(1): record separator worky now? 2024-06-21 03:23:39 -06:00			`.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.11"`
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`
			`.RB ( -aenu )`
			`.RB ( -i`
			`.RB [ input ])`
			`.RB ( -o`
			`.RB [ 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: subsequent outputs are opened for appending 2024-03-29 16:26:41 -06:00			`Opens subsequent 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.`
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-i\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`
			`no inputs are specified, the standard input shall be used.`
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-o\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`
			`no outputs are specified, the standard output shall be used.`
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-u\fP`
mm.1: updated man page 2024-03-26 18:44:05 -06:00			`Ensures neither input or output will be buffered.`
docs: formatting 2024-06-04 16:11:33 -06:00			`.IP \fB-n\fP`
mm.1: updated man page 2024-03-26 18:44:05 -06:00			`Causes SIGINT signals to be ignored.`
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: wording, consistency with dj.1 2024-03-27 00:14:34 -06:00			`.SH CAVEATS`
mm(1): add 2024-02-17 23:43:22 -07:00
mm.1: wording, consistency with dj.1 2024-03-27 00:14:34 -06:00			`Existing files are not truncated on ouput and are instead overwritten.`
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)`