Re: [OT] enum man page review
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?
I suppose I was thinking of that as a default that may either depend
on (whatever) or be a fallback value, but that's an unclear way to
put it, especially with its dubious concept of a fallback default.
The trouble with "if STEP is not provided it is implied" is that it
sounds as if it might mean something like "the string STEP is
implied", rather than "a value for the parameter STEP is implied".
One simple way to avoid that is
... If 'STEP' is not provided a value is implied.
[...]
(Never mind my option-shuffling suggestions, remember I'm not even
an enum user!)
[...]
>>> 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...
Probably "arguments" is better than "parameters", because readers
are less likely to wonder which things count.
>>> 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?
The rule I grew up with is "zero to twenty"; and personally if I had
a text where the only numbers mentioned were unhyphenated one-word
integers I would be happy to write "ninety". But I seem to be
unfashionable - the Associated Press style guide even takes it down
to "one to ten". Wait, except at the start of a sentence. Unless
it's a year. Ugh.
>>> 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.
I just thought it might be more of a pain remembering to update it
with "still true" the following Tuesday when you fix a comma; a
timestamp in a header somewhere seems less of an implied promise to
check every time!
>>> 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...
Yes, hence the "Optional", since it is after all immediately
followed by the "jot -r 3 1 10". Sorry Sebastian, changing one but
not all just seems weird! Let's keep it in digits.
>>> 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... :/
It's a disputed issue in English, with en_US styleguides being
likely to insist on it while en_GB ones may even forbid it. Either
rule applied too rigidly can run into trouble - compare
http://en.wikipedia.org/wiki/Serial_comma#Resolving_ambiguity
http://en.wikipedia.org/wiki/Serial_comma#Creating_ambiguity !
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: