docs/rpn.1: added manpage

docs/rpn.1

@@ -0,0 +1,63 @@
+.\" 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/>.
+
+.TH rpn 1
+
+.SH NAME
+
+npc \(en reverse polish notation evaluation
+
+.SH SYNOPSIS
+
+rpn [integers...] [operations...]
+
+.SH DESCRIPTION
+
+Rpn parses reverse polish notation and adds characters to the stack until there
+is an operation. See rpn(7) for more details on the syntax of reverse polish
+notation.
+
+.SH STANDARD INPUT
+
+If rpn is passed arguments, it interprets those arguments as an expression to
+be evaluated. Otherwise, it reads characters from standard input to add to the
+stack.
+
+.SH DIAGNOSTICS
+
+If encountering a syntax error, rpn will exit with the appropriate error code
+as defined by sysexits.h(3) and print an error message.
+
+.SH CAVEATS
+
+Due to the complexity of integer storage in memory, rpn is only capable of
+parsing decimal integers.
+
+Additionally, due to the laws of physics, floating-point math can only be as
+precise as slightly less than the machine epsilon of the hardware on which rpn
+is running.
+
+.SH RATIONALE
+
+POSIX has its own calculator in the form of bc(1p), which uses standard input
+for its calculations. Pair the clunkiness of piping expressions into it and its
+use of standard notation, it was clear what rpn should be.
+
+There are no mathematics in the qi(1) shell because it was decided early on that
+math was the job of a specific tool and not the shell itself. Thus, rpn was
+born.
+
+.SH AUTHOR
+
+Written by Emma Tebibyte <emma@tebibyte.media>.
+
+.SH COPYRIGHT
+
+Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/agpl.html>.
+
+.SH SEE ALSO
+
+bc(1p), dc(1)