Merge branch 'hru' (closes #33)

docs/hru.1

@@ -0,0 +1,57 @@
+.\" 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
+
+hru \(en human readable units
+
+.SH SYNOPSIS
+
+hru
+
+.SH DESCRIPTION
+
+Hru reads byte counts in the form of whole numbers from the standard input and
+writes to the standard output the same number converted one of the units of data
+defined by the International System of Units.
+
+The program will convert the byte count to the highest unit possible where the
+value is greater than one.
+
+.SH DIAGNOSTICS
+
+If encountering non-integer characters in the standard input, hru will exit with
+the appropriate error code as defined by sysexits.h(3) and print an error
+message.
+
+.SH RATIONALE
+
+The GNU project’s ls(1) implementation contains a human-readable option (-h)
+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
+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
+program.
+
+.SH STANDARDS
+
+Hru follows 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 (SI).
+
+.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
+
+GNU ls(1), The International System of Units (SI) 9th Edition