Re: [OT] enum man page review
Jan Hauke Rahm wrote:
> I attached the asciidoc input file as well as the generated man page
> (for easier reading if you're unfamiliar with asciidoc).
Thanks!
> ENUM(1)
> =======
> :man source: enum {enumversion}
> :man manual: enum {enumversion}
>
>
> NAME
> ----
>
> enum - seq- and jot-like enumerator
>
>
> SYNOPSIS
> --------
>
> GENERAL
> ~~~~~~~
>
> *enum* [ 'OPTIONS' ] 'LEFT' ".." 'COUNT'"x" 'STEP' ".." 'RIGHT'
>
>
> SHORTCUTS
> ~~~~~~~~~
>
> *enum* [ 'OPTIONS' ] 'LEFT' 'STEP' 'RIGHT'
>
> *enum* [ 'OPTIONS' ] 'LEFT' 'RIGHT'
>
> *enum* [ 'OPTIONS' ] 'RIGHT'
>
> ...
>
>
> DESCRIPTION
> -----------
>
> *enum* enumerates values (numbers) from 'LEFT' to 'RIGHT'
> adding/subtracting 'STEP' each time. If 'STEP' is not provided it is
> implied.
Maybe "if 'STEP' is not provided a default is used"?
> No more than 'COUNT' values are printed. Before printing,
> values are passed through a formatter. Please see 'OPTIONS' for
> details on controlling the formatter or 'EXAMPLES' for use cases.
>
> Further details on usage of *enum* are covered in 'USAGE IN DETAIL'.
of
Or just "Further *enum* usage details are covered".
> EXAMPLES
> --------
Isn't it more conventional for OPTIONS to precede EXAMPLES?
>
> USE IN FOR-LOOPS
> ~~~~~~~~~~~~~~~~
>
> --------------------------------------
> for i in $(enum 1 3); do
> touch file_${i}
> done
> --------------------------------------
(Checks... fair enough, dash doesn't expand "touch file_{1..3}")
> USE FOR RANDOM NUMBERS
> ~~~~~~~~~~~~~~~~~~~~~~
>
> --------------------------------------
> number=$(enum --random 3 .. 10)
> --------------------------------------
>
> instead of native Bash like
>
> --------------------------------------
> f() { min=$1; max=$2; echo $((RANDOM * (max - min + 1) / 32767 + min)); }
> number=$(f 3 10)
> --------------------------------------
(I'd never noticed that $(( RANDOM-SCHMANDOM )) is valid!)
> SHOWING AN ASCII TABLE
> ~~~~~~~~~~~~~~~~~~~~~~
>
> --------------------------------------
> enum -f '[%3i] "%c"' 0 127
> --------------------------------------
>
>
> OPTIONS
> -------
>
> RANDOM MODE
> ~~~~~~~~~~~
>
> *-r, --random*::
> Produces random numbers instead of monotone sequences,
> potentially with duplicates.
I'm more familiar with "monotonic sequences", though the web says
both occur. If it's the random numbers that may include duplicates
(which obviously it is), I'd say
Produces random numbers (potentially with duplicates)
instead of monotonic sequences.
> *-i, --seed*='NUMBER'::
> Pass 'NUMBER' as initializer to the random number generator.
> By default, the RNG is initialized from the current time and
> the process ID of the running instance of *enum*.
Why "seed" but "-i"? (Okay, "-s" is taken.)
What happens if you use -i without -r? And isn't there a way of
initialising the RNG from /dev/random, so that it's, well, random?
> FORMATTING
> ~~~~~~~~~~
>
> *-b, --dumb*='TEXT'::
> Overrides the output format to 'TEXT' without interpolating
> placeholders. For instance, *enum -b "foo % 10" 3x* produces
> the string "foo % 10" three times.
Why "dumb" but "-b" (when "-d" isn't taken)? A jotism?
> *-c, --characters*::
> Overrides the output format to `%c` producing characters.
> For example, *enum -c 65 67* produces the letters "A", "B" and "C".
>
> *-e, --equal-width*::
> Equalize width by padding with leading zeroes.
> NOTE: In case of mixed negative and non-negative numbers
> (e.g. with *enum -e -- -10 1*), non-negative values will compensate
> the lack of a leading minus with an extra zero to be of equal width.
Make that "in ^the^ case of" (plain "in case of" can be ambiguous).
And they "will compensate ^for^ the lack".
> *-f, --format*='FORMAT'::
> Overrides the default output format with 'FORMAT'.
> For details on allowed formats please see printf(3). +
> If 'FORMAT' does not contain any placeholders, *enum* will error out
> with code 1. In contrast, jot would have appended the number's
> value instead. To make numbers appear at the end, please adjust
> 'FORMAT' accordingly with *enum*.
(Shouldn't "jot" and "seq" get some sort of commandname markup? No,
okay.)
To make numbers appear at the end with *enum*,
adjust 'FORMAT' appropriately.
> *-l, --one-line*::
Why "one-line" but "-l" (when "-1" and "-o" aren't taken)?
> Shortcut for "*-s ' '*" which means having a white space as separator
> instead of a new line.
Still "a white space" even if my xterm is cyan-on-magenta? And
remember newline is also whitespace. I think you mean just
Shortcut for "*-s ' '*" which means having a space instead of
a newline as separator.
> *-n, --omit-newline*::
> Omits the trailing newline from printing.
"From output", just in case anyone's daft enough to think this is a
lineprinter-specific feature.
> *-p, --precision*='COUNT'::
> Overrides automatic selection of precision to print 'COUNT'
> decimal places, e.g. "0.100" for 'COUNT' = 3.
> By default, the number of digits to print is computed from the
> arguments given and the potentially computed step size.
Does that mean "from the arguments given and the (given or computed)
step size"?
> *-s, --separator*='TEXT'::
> Overrides the separator that is printed between values.
> By default, values are separated by a newline.
>
> *-w, --word*='FORMAT'::
> Alias for --format, copied from jot.
> For GNU seq's *--equal-width* shortcut *-w* please see *-e*, instead.
Alias for --format, for compatibility with jot.
For GNU seq's *-w* meaning *--equal-width*, see *-e*.
> *-z, --zero, --null*::
> Print null bytes as separator, not a newline.
A shortcut like "--one-line"; a pity they don't have aliases -0, -1!
> OTHER
> ~~~~~
>
> *-h, --help*::
> Outputs usage information and exits with code 0 (success).
>
> *-V, --version*::
> Displays version information and exits with code 0 (success).
Hmm, but there's no -v...
> USAGE IN DETAIL
> ---------------
>
> INVOLVED ARGUMENTS
> ~~~~~~~~~~~~~~~~~~
There are some arguments that don't get involved? Couldn't this be a
conventional ARGUMENTS section?
---------
> Basically, the command line API looks like this:
How is it an Application Programming Interface? This seems a
pointless use of jargon. How about:
The logic of *enum*'s command line parameters is:
> *enum* [ 'OPTIONS' ] 'LEFT' ".." 'COUNT'"x" 'STEP' ".." 'RIGHT'
>
> Four arguments are involved:
>
> - 'LEFT', the value to start enumeration with
> - 'COUNT', the number of values to produce (in some cases less)
so "the (maximum) number of values to produce"?
> - 'STEP', the gap from one value to another
> - 'RIGHT', the value to stop enumeration at (in some cases before)
>
> Not all four arguments are needed, though specifying all four is possible.
> For a list of all valid combinations see 'VALID COMBINATIONS' below.
> Details on derivation of defaults are addressed in 'DERIVATION OF DEFAULTS'.
>
>
> VALID COMBINATIONS
> ~~~~~~~~~~~~~~~~~~
> With four arguments:
>
> - enum 'LEFT' ".." 'COUNT'"x" 'STEP' ".." 'RIGHT'
>
> With three arguments:
>
> - enum 'LEFT' 'COUNT'"x" 'RIGHT'
> - enum 'LEFT' ".." 'COUNT'"x" 'STEP' ".."
> - enum ".." 'COUNT'"x" 'STEP' ".." 'RIGHT'
> - enum 'LEFT' ".." 'COUNT'"x" ".." 'RIGHT'
> - enum 'LEFT' ".." 'STEP' ".." 'RIGHT'
> - enum 'LEFT' 'STEP' 'RIGHT' (for GNU seq compatibility)
>
> With two arguments:
>
> - enum ".." 'COUNT'"x" 'STEP' ".."
> - enum ".." 'COUNT'"x" ".." 'RIGHT'
> - enum ".." 'STEP' ".." 'RIGHT'
> - enum 'LEFT' ".." 'COUNT'"x" ".."
> - enum 'LEFT' ".." 'STEP' ".."
> - enum 'LEFT' ".." 'RIGHT'
> - enum 'LEFT' 'RIGHT' (for GNU seq compatibility)
>
> With one argument:
>
> - enum ".." 'STEP' ".."
> - enum ".." 'COUNT'"x" ".."
> - enum ".." 'RIGHT'
> - enum 'RIGHT' (for GNU seq compatibility)
> - enum 'LEFT' ".."
> - enum 'COUNT'"x"
>
> With less then three arguments, defaults apply.
^
> Details are described in 'DERIVATION OF DEFAULTS' below.
Less *than*. Oh, except the pedants'll get you if you don't say
"fewer than".
> DERIVATION OF DEFAULTS
> ~~~~~~~~~~~~~~~~~~~~~~
>
> AUTO-SELECTION OF PRECISION
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^
> *enum* distinguishes between "2", "2.0", "2.00" and so on:
>
> --------------------------------------
> # enum 1 2
> 1
> 2
>
> # enum 1 2.0
> 1.0
> 1.1
> [..]
> 1.9
> 2.0
> --------------------------------------
>
> Also, if the derived step has more decimal places than the
> specified values for 'LEFT' and 'RIGHT', the output precision
> will be raised to that of step
Okay, not "STEP", but "to that of the step value"?
> --------------------------------------
> # enum 1 .. 3x .. 2
> 1.0
> 1.5
> 2.0
> --------------------------------------
>
> A specified precision always takes precedence:
>
> --------------------------------------
> # enum -p 2 1 .. 3x .. 2
> 1.00
> 1.50
> 2.00
> --------------------------------------
>
>
> ARGUMENT DEFAULTS
> ^^^^^^^^^^^^^^^^^
> In general, any three arguments are needed; three lead to the fourth.
I don't think you can say that.
In general, three arguments are needed; any three imply the fourth.
> This equation brings them together:
>
> 'LEFT' + ('COUNT' - 1) * 'STEP' = 'RIGHT'
>
> If you specify less than three of them (see 'VALID COMBINATIONS'), the
> unspecified ones are derived or set to their defaults:
In theory those pedants I mentioned would insist on s/less/fewer/
here too, but that seems vaguely ludicrous to me. Two is less than
three, not fewer!
> - 'LEFT' defaults to 1 (unless 'STEP' and 'RIGHT' are specified, see
> 'DERIVATION OF LEFT' below)
> - 'COUNT' is infinity, unless it can be derived from the other three values.
> - 'STEP' defaults to 1, unless it can be derived.
> - 'RIGHT' is +/-infinity, unless it can be derived from the other three
> values.
(Checks asciidoc markup can handle +/- ...yup)
> DERIVATION OF LEFT
> ^^^^^^^^^^^^^^^^^^
> In general, 'LEFT' defaults to 1:
>
> --------------------------------------
> # enum .. 3
> 1
> 2
> 3
> --------------------------------------
>
> If 'STEP' and 'RIGHT' is given, it is derived as
>
> 'LEFT' = 'RIGHT' - 'STEP' * floor('RIGHT' / 'STEP')
>
> --------------------------------------
> # enum .. 4 .. 10
> 2
> 6
> 10
> --------------------------------------
>
> If, in addition to 'STEP' and 'RIGHT', 'COUNT' is given, it is derived as:
>
> 'LEFT' = 'RIGHT' - ('COUNT' - 1) * 'STEP'
>
> --------------------------------------
> # enum .. 2x 4 .. 10
> 6
> 10
> --------------------------------------
>
>
> GENERATION OF VALUES
> ~~~~~~~~~~~~~~~~~~~~
> When a custom step is requested, values are produced as following:
follows:
>
> value[0] = LEFT + 0 * STEP
> value[1] = LEFT + 1 * STEP
> ..
> value[i] = LEFT + i * STEP
>
> Else, to avoid imprecision adding up, values are produced as following:
Otherwise,
>
> value[0] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 0
> value[1] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 1
> ..
> value[i] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * i
>
> Production stops when either 'COUNT' values have been produced or 'RIGHT'
> has been reached, whichever hits first. When all 4 values are given in
four
> perfect match they hit at the same time.
>
>
> RANDOM MODE
> -----------
>
> Basically, random mode differs in these regards:
>
> - Produced values are random.
> - Argument 'COUNT' defaults to 1 (one).
> - Argument 'LEFT' (always!) defaults to 1 (one).
> - Argument 'RIGHT' is required: Random does not mix with infinity.
>
> We will now cover these differences in detail.
The problem with first person is that it's always hard to be sure
who's included. Here apparently I'm one of the people being invited
to join you (which is really more like the patronising "doctor's we"
that means "you", since obviously the speaker here doesn't need to
be reminded). But next time you use "we", a few paragraphs lower,
it's clear that I'm an outsider.
This section covers these differences in detail.
>
> COUNT DEFAULTS TO 1 (ONE)
> ~~~~~~~~~~~~~~~~~~~~~~~~~
>
> In random mode only one value is produced, by default:
>
> --------------------------------------
> # enum 1 4
> 1
> 2
> 3
> 4
>
> # enum -r 1 4
> 3
> --------------------------------------
>
> By specifying count you can produce more values at a time:
>
> --------------------------------------
> # enum -r 1 .. 3x .. 4
> 2
> 1
> 3
> --------------------------------------
>
>
> LEFT ALWAYS DEFAULTS TO 1 (ONE)
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> When you need increasing numbers up to a certain maximum (say 10),
> each apart by a certain step (say 4) you can let *enum* calculate
> the needed starting value for you:
I'd probably say "each separated by".
> --------------------------------------
> # enum .. 4 .. 10
> 2
> 6
> 10
> --------------------------------------
>
> In random mode 'LEFT' is never calculated and defaults to 1 (one):
>
> --------------------------------------
> # enum -r .. 5x 4 .. 10
> 1
> 1
> 9
> 1
> 5
> --------------------------------------
>
>
> RANDOM DOES NOT MIX WITH INFINITY
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> In general, *enum* supports running towards infinity:
>
> --------------------------------------
> # enum 1 .. 2.0 ..
> 1.0
> 3.0
> 5.0
> [..]
> --------------------------------------
>
> However, in random mode *enum* would now produce random numbers from 1 to
> infinity (or a big number like 'FLT_MAX' from '<float.h>'), which we have
> decided against.
(Did we? Oh well, here it's unambiguous, and you're right next to:)
So what happens? Does it error out?
> HISTORY
> -------
>
> *enum* is a fusion of GNU seq and jot, feature-wise. At the core both tools
> print sequences of numbers. GNU seq has a clean interface but very limited
> functionality. jot on the other hand offers more advanced features, like
> producing random numbers, at the cost of a rather unfriendly interface.
>
> With *enum* we try to offer a tool with the power of jot and a usable,
> easily memorable interface. *enum* is licensed under a BSD license and
> written in C89 for maximum portability.
>
> In the following sections we will take a look at differences in detail.
Flipping from exclusive to inclusive "we" again. Let's stick to
exclusive and turn this into:
The following sections take a look at the differences in detail.
>
> COMPARISON TO JOT
> -----------------
>
> Using *enum* instead of jot offers two main advantages:
>
> - improved usability and
> - uniform behavior across distributions and operating systems.
>
> Still (as of 2010-10-03), jot implementations differ subtly among
> DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD and OS X. For
> instance the command 'jot - 0 5' produces
Are you going to amend this whenever you update the file? I'd put
the datestamp somewhere else myself.
"Differ among" sounds wrong. I've heard that Americans are taught
at school to avoid "between" with multiple complements as
"illogical", but that's the natural way of saying it, and it makes
it clear that the differences are inter- rather than intra-OS.
Also, serial comma.
At present, jot implementations still differ subtly between
DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD, and OS X.
For instance the command 'jot - 0 5' produces
> - 6 integers from 0 to 5 on FreeBSD and OS X,
>
> 0 1 2 3 4 5
>
> - 100 integers from 0 to 99 on NetBSD, and
>
> 0 1 2 [..] 97 98 99
>
> - 100 integers from 0 to 5 (with consecutive duplicates) on
> DragonFlyBSD, MirOS BSD and OpenBSD.
,
>
> 0 0 0 0 0 0 0 0 0 0 1 1 [..] 4 4 5 5 5 5 5 5 5 5 5 5
>
> Basically, the full feature set of jot plus a few enhancements is contained
> in *enum*. Names of parameters have been retained for increased
> compatibility, e.g. *-p 2* works with *enum* as it does with jot:
Your third use of "Basically...", but I've taken one out already.
> --------------------------------------
> # jot -p 2 3
> 1.00
> 2.00
> 3.00
>
> # enum -p 2 3
> 1.00
> 2.00
> 3.00
> --------------------------------------
>
> Please see OPTIONS above for further details.
>
>
> ADDITIONAL FEATURES
> ~~~~~~~~~~~~~~~~~~~
>
> The features that *enum* offers over jot include:
^extra
>
> MORE MEMORABLE COMMAND LINE USAGE
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> In order to produce 3 random numbers between 1 and 10 inclusively, you
> would run
(Optional) "three random numbers between one and ten (inclusively)"
> --------------------------------------
> jot -r 3 1 10
> --------------------------------------
>
> with jot. We find these alternative calls to *enum* more intuitive:
(Exclusive we, which is the kind I'm leaving in.)
> --------------------------------------
> enum -r 1 .. 3x .. 10
> enum -r 1 3x 10
> --------------------------------------
>
>
> CUSTOM RESOLUTION OF RANDOM
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^
> With *enum* you can specify the gap between possible random values.
> These two cases illustrate the difference between a gap of 2 and 3:
>
> --------------------------------------
> # enum -r 4 .. 100x 2 .. 10 | sort -u -n
> 4
> 6
> 8
> 10
>
> # enum -r 4 .. 100x 3 .. 10 | sort -u -n
> 4
> 7
> 10
> --------------------------------------
Okay, I get it, but it took a while. Maybe you should say something
like "you can specify that the possible values to be randomly
selected from have a particular spacing".
> SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD and OS X:
,
>
> --------------------------------------
> # jot -w %g%g 3
> jot: too many conversions
> --------------------------------------
>
> jot on NetBSD:
>
> --------------------------------------
> # jot -w %g%g 3
> jot: unknown or invalid format `%g%g'
> --------------------------------------
>
> *enum* on any platform:
>
> --------------------------------------
> # enum -f %g%g 3
> 11
> 22
> 33
> --------------------------------------
>
>
> NULL BYTES AS SEPARATOR
> ^^^^^^^^^^^^^^^^^^^^^^^
>
> When using format strings containing spaces, you may run into trouble in
> contexts like for loops or xargs: Spaces are treated as separators which
s
> breaks up your strings in pieces:
>
> --------------------------------------
> # enum -f 'sheep number %d' 2 | xargs -n 1 echo
> sheep
> number
> 1
> sheep
> number
> 2
> --------------------------------------
>
> To prevent this, you could pass *--null* to both *enum* and xargs:
>
> --------------------------------------
> # enum --null -f 'sheep number %d' 2 | xargs --null -n 1 echo
> sheep number 1
> sheep number 2
> --------------------------------------
Well, okay.
>
> DIFFERENCES
> ~~~~~~~~~~~
>
> HANDLING OF FORMATS WITHOUT PLACEHOLDERS
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> In contrast to jot, *enum* does not append the current value, if the
> formatting string does not contain a placeholder.
> Behavior of jot:
>
> --------------------------------------
> # jot 3 -w test_
> test_1
> test_2
> test_3
> --------------------------------------
>
> Behavior of *enum*:
>
> --------------------------------------
> # enum -w test_ 3
> test_
> test_
> test_
> --------------------------------------
>
> In order to achieve jot's output with *enum*, you could manually
> append a placeholder:
s/could/should/?
>
> --------------------------------------
> # enum -w test_%d 3
> test_1
> test_2
> test_3
> --------------------------------------
>
>
> NON-NUMBER VALUES FOR LEFT AND RIGHT
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> *enum* does not support using ASCII characters instead of their
> numerical values (e.g. "A" for 65) for 'LEFT' and 'RIGHT'.
> With jot you can do:
>
> --------------------------------------
> # jot 3 A
> 65
> 66
> 67
> --------------------------------------
>
> Inconsistently,
>
> --------------------------------------
> # jot 3 0
> 0
> 1
> 2
> --------------------------------------
>
> jot does not interpret "0" as ASCII character with code 48.
^the
> We have no intention duplicating this mix, at the moment.
^of
> COMPARISON TO GNU SEQ
> ---------------------
>
> Basically, *enum*'s usage is backwards-compatible to that of GNU seq.
>
>
> ADDITIONAL FEATURES
> ~~~~~~~~~~~~~~~~~~~
>
> The features *enum* offers over GNU seq include:
^extra
>
> RANDOM NUMBER MODE
> ^^^^^^^^^^^^^^^^^^
> *enum* supports output of constrained random numbers, e.g.
>
> --------------------------------------
> enum -r 4 .. 3x 2.0 .. 11
> --------------------------------------
>
> produces three (possibly duplicate) random numbers
> from the set {4.0, 6.0, 8.0, 10.0}.
>
>
> SUPPORT FOR INVERSE ORDERING
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> In contrast to GNU seq, *enum* supports enumerating decreasing values:
>
> --------------------------------------
> # seq 3 1
So it's less flexible than Bash's {3..1}?!
>
> # enum 3 1
> 3
> 2
> 1
> --------------------------------------
>
>
> SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> --------------------------------------
> # seq -f %g%g 3
> seq: format `%g%g' has too many % directives
>
> # enum -f %g%g 3
> 11
> 22
> 33
> --------------------------------------
>
>
> OMITTING FINAL NEWLINE
> ^^^^^^^^^^^^^^^^^^^^^^
> By specifying *-n* as a parameter, you can make *enum* omit the
> trailing newline.
>
>
> DIFFERENCES
> ~~~~~~~~~~~
>
> GNU seq's *--equal-width* shortcut *-w* conflicts with jot's *-w word*.
> We chose to make *-e* the shortcut for *--equal-width* in *enum*, instead.
>
> Also, while GNU seq is licensed under GPL v3 or later, *enum* is
> licensed under the New BSD license.
>
>
> AUTHORS
> -------
>
> Jan Hauke Rahm <jhr@debian.org>
>
> Sebastian Pipping <sping@gentoo.org>
>
>
> RESOURCES
> ---------
> Main web site: https://fedorahosted.org/enum/
>
> Gitweb: http://git.fedorahosted.org/git/?p=enum.git
>
>
> SEE ALSO
> --------
> jot(1), seq(1), printf(3), float.h(0p)
Debian Policy says "You should only use sections 1 to 9".
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: