From a30152d7834187d7a5a7c1f6b914f63ed0098ce7 Mon Sep 17 00:00:00 2001 From: emma Date: Fri, 2 Feb 2024 20:12:12 -0700 Subject: [PATCH] rpn.1: made more precise --- docs/rpn.1 | 52 +++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/docs/rpn.1 b/docs/rpn.1 index 21131ce..ee1afec 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -1,4 +1,5 @@ .\" Copyright (c) 2024 Emma Tebibyte +.\" Copyright (c) 2024 DTB .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . @@ -7,47 +8,48 @@ .SH NAME -npc \(en reverse polish notation evaluation +rpn \(en reverse polish notation evaluation .SH SYNOPSIS -rpn [integers...] [operations...] +rpn +.RB [numbers...]\ [operators...] .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. +Rpn parses and and evaluates reverse polish notation either from the standard +input or by parsing its arguments. See the STANDARD INPUT section. + +For information on for reverse polish notation syntax, see rpn(7). .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. +If rpn is passed arguments, it interprets them as an expression to be evaluated. +Otherwise, it reads whitespace-delimited numbers and operations from the +standard input. + +.SH CAVEATS + +Due to precision constraints and the way floats are represented in accordance +with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point +arithmetic has rounding errors. This is somewhat curbed by using the +second-highest float that can be represented in line with this standard to round +numbers to before outputting. .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. +An infix notation calculation utility, bc(1p), is included in the POSIX +standard, but it doesn’t accept expressions as arguments; in scripts, any +predefined, non-interactive input must be piped into the program. A dc(1) +pre-dates the standardized 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 @@ -60,4 +62,4 @@ Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later .SH SEE ALSO -bc(1p), dc(1) +rpn(7), bc(1p), dc(1), IEEE 754