svn commit: r359032 - head/usr.bin/units

[Mateusz Piotrowski]

Author: 0mp (doc,ports committer)
Date: Tue Mar 17 10:02:59 2020
New Revision: 359032
URL: https://svnweb.freebsd.org/changeset/base/359032

Log:
  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

Modified:
  head/usr.bin/units/units.1

Modified: head/usr.bin/units/units.1
==============================================================================
--- head/usr.bin/units/units.1	Tue Mar 17 09:12:47 2020	(r359031)
+++ head/usr.bin/units/units.1	Tue Mar 17 10:02:59 2020	(r359032)
@@ -1,5 +1,5 @@
 .\" $FreeBSD$
-.Dd February 3, 2020
+.Dd March 17, 2020
 .Dt UNITS 1
 .Os
 .Sh NAME
@@ -232,8 +232,21 @@ 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:
 .Bd -literal -offset 2n
@@ -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