From 3431172fa862dccb2a8b918161da186cfafc95f0 Mon Sep 17 00:00:00 2001
From: Mateusz Piotrowski <0mp@FreeBSD.org>
Date: Tue, 17 Mar 2020 10:02:59 +0000
Subject: [PATCH] Tell the world how to convert gigabytes to bytes with
 units(1) easily

It turns out that units(1) is not as horrible to use in scripts
as I initially thought. When the --terse flag is combined
with an appropriate output format (set via --output-format),
units(1) is actually capable of producing very nice results.
For example:

    units -o %0.f -t '4 gigabytes' bytes

is is just going to print out the expected value of 4294967296.

There is no time to waste. People have to know about it.

I am adding an example for this at the top of the examples section
because this is what users are most likely looking for.

Approved by:	bcr (mentor)
Differential Revision:	https://reviews.freebsd.org/D24096
---
 usr.bin/units/units.1 | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/usr.bin/units/units.1 b/usr.bin/units/units.1
index 32d1c9b2df00..aa019484a120 100644
--- a/usr.bin/units/units.1
+++ b/usr.bin/units/units.1
@@ -1,5 +1,5 @@
 .\" $FreeBSD$
-.Dd February 3, 2020
+.Dd March 17, 2020
 .Dt UNITS 1
 .Os
 .Sh NAME
@@ -232,7 +232,20 @@ The standard units file.
 .Ex -std
 .Sh EXAMPLES
 .Bl -tag -width 0n
-.It Sy Example 1 : No Interactive usage
+.It Sy Example 1 : No Simple conversion of units
+.Pp
+This example shows how to do simple conversions, for example from gigabytes
+to bytes:
+.Bd -literal -offset 2n
+.Li $ Ic units -o %0.f -t '4 gigabytes' bytes
+4294967296
+.Ed
+.Pp
+The
+.Fl o Cm %0.f
+part of the command is required to print the result in a non-scientific
+notation (e.g, 4294967296 instead of 4.29497e+09).
+.It Sy Example 2 : No Interactive usage
 .Pp
 Here is an example of an interactive session where the user is prompted for
 units:
@@ -261,7 +274,7 @@ units:
 .Li You want : Ic degC
         29.444444
 .Ed
-.It Sy Example 2 : No Difference between Do Ic \&| Dc No and Do Ic / Dc No division
+.It Sy Example 3 : No Difference between Do Ic \&| Dc No and Do Ic / Dc No division
 .Pp
 The following command shows how to convert half a meter to centimeters.
 .Bd -literal -offset 2n
@@ -293,7 +306,7 @@ as
 .Dq Ic 0.5/meter ,
 which is not conformable to
 .Dq Ic cm .
-.It Sy Example 3 : No Simple units file
+.It Sy Example 4 : No Simple units file
 Here is an example of a short units file that defines some basic
 units:
 .Pp
@@ -307,7 +320,7 @@ units:
 .It "ft	12 inches"
 .It "mile	5280 ft"
 .El
-.It Sy Example 4 : No Viewing units and conversions of the default units file
+.It Sy Example 5 : No Viewing units and conversions of the default units file
 The following shell one-liner allows the user to view the contents of the
 default units file:
 .Bd -literal -offset 2n