Hi Justin,
thank you so much for having a look at the text!
On Wed, Oct 20, 2010 at 12:53:38PM +0100, Justin B Rye wrote:
> Jan Hauke Rahm wrote:
> > 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"?
Well, techinically, as described below, the step can be set to a default
or be calculated. In both cases it is sort of implied, isn't it?
> > 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".
Changed.
> > EXAMPLES
> > --------
>
> Isn't it more conventional for OPTIONS to precede EXAMPLES?
Yes, and we found that annoying as you read about options maybe once but
the examples really help. :) We may change the order of topics later,
the man page evolved very recently.
> > 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.
Changed.
> > *-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.)
I didn't check this particular case but weird parameter names often come
up when we try to be compatible with jot.
> 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?
enum denies -i without -r with an error. And yes, -r also works without
-i, using a random seed. :)
> > 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?
See above. :)
> > *-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".
Changed.
> > *-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.)
Is that usually done?
> To make numbers appear at the end with *enum*,
> adjust 'FORMAT' appropriately.
Changed.
> > *-l, --one-line*::
>
> Why "one-line" but "-l" (when "-1" and "-o" aren't taken)?
-1 sounds good. We'll consider that.
> > 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.
Changed.
> > *-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.
Haha, yep.
> > *-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"?
A given step is part of the arguments (e.g. 'enum 1 2 4' has three
arguments: left, step, and right). From those the precision is computed
but also from the step size that, in other use cases, may have been
computed. I guess, you correction sounds a bit simpler. :)
> > *-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!
We'll think about -0, -1. Thing is, enum will probably get confused
about -1 meaning --one-line or the actual negative number -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...
Isn't -v standard for --verbose (which wouldn't make sense for enum)?
> > USAGE IN DETAIL
> > ---------------
> >
> > INVOLVED ARGUMENTS
> > ~~~~~~~~~~~~~~~~~~
>
> There are some arguments that don't get involved? Couldn't this be a
> conventional ARGUMENTS section?
> ---------
Probably, yes.
> > 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:
Would 'command line arguments' make sense, too? Internally, we have
considered getopt stuff (everyhthing starting with a dash) to be
parameters while the rest are arguments. I don't know if that is
useful...
> > *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"?
Changed.
> > 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".
Changed to "less than".
> > 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"?
Changed.
> > 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.
Changed.
> > 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!
Interesting. I never even thought about that.
> > 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,
I suppose, this "following" should be "follow" as well. Changed both and
the else/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
What is the rule in English? In German we write integers from 1 to 12 as
words. Is it the same in English?
> > 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.
Thanks, that makes sense.
> > 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".
Changed.
> > 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?
Yes: ERROR: Combining random and infinity not supported.
> > 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.
Okay.
> > 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.
I don't really see the difference.
> "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
Changed, except for the time stamp.
> > - 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.
> ,
Yep.
> > 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.
I know. Lack of words in my head :(
> > ADDITIONAL FEATURES
> > ~~~~~~~~~~~~~~~~~~~
> >
> > The features that *enum* offers over jot include:
> ^extra
Okay.
> > 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)"
I guess, having the actual numbers in the text makes it easier to relate
the jot call. Well, I don't know...
> > 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".
Changed.
> > SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD and OS X:
> ,
*argh* yep. I know how it works in English, it's just that German is
different here... :/
> > 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:
Oh, intersting. Changed.
> > In order to achieve jot's output with *enum*, you could manually
> > append a placeholder:
>
> s/could/should/?
Okay.
> > 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
Changed.
> > 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
Again, okay :)
> > 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}?!
Yes but enum isn't :)
> > SEE ALSO
> > --------
> > jot(1), seq(1), printf(3), float.h(0p)
>
> Debian Policy says "You should only use sections 1 to 9".
Okay, I'll have a look at that.
Again, thank you so much Justin!
Hauke
--
.''`. Jan Hauke Rahm <jhr@debian.org> www.jhr-online.de
: :' : Debian Developer www.debian.org
`. `'` Member of the Linux Foundation www.linux.com
`- Fellow of the Free Software Foundation Europe www.fsfe.org
Attachment:
signature.asc
Description: Digital signature