overgrown/docs/hru.1

.\" 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 HRU 1 2024-06-06 "Bonsai Core Utilites 0.13.8"
.SH NAME
hru \(en human readable units
.\"
.SH SYNOPSIS

hru
.\"
.SH DESCRIPTION

Convert counts to higher units.

The program will read byte counts in the form of whole numbers from the standard
input and write to the standard output the same number converted to a higher
unit of data as 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, the program will
exit with the appropriate error code as defined by
.BR sysexits.h (3)
and print an error message.
.\"
.SH RATIONALE

The GNU project\(cqs
.BR ls (1)
implementation contains a human-readable option (\fB-h\fP) 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
.BR ls (1)
so the decision was made to split it into a new tool. The original functionality
in GNU\(cqs
.BR ls (1)
can be emulated with
.BR fop (1)
combined with this program.
.\"
.SH STANDARDS

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)
are utilized for the ouput of conversions.
.\"
.SH AUTHOR

Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT

Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
GNU
.BR ls (1),
The International System of Units (SI) 9th Edition