Hi Jim,
Thanks for the quick response - so much for those (typically among the
proprietary suppliers whose support is worst) who say Free Software
lacks support ;^)
> The main trick is knowing that the `real' documentation ...
ah, I see.
I guess that's why the COPYRIGHT notice is (mildly inappropriately)
for the program described, without saying so, rather than for the man
page itself ... of course, since copyright notices became optional
some time ago, this is not an issue.
Perhaps it would be worth making the situation obvious earlier;
e.g. add a second line to DESCRIPTION along the lines of
This is just terse help: SEE ALSO points to full documentation.
added to the man page while adding the SEE ALSO section; or, indeed,
the whole SEE ALSO section could be made redundant by adding
For full documentation use command: info coreutils sort
to the --help output after what becomes the first line of DESCRIPTION.
As an ageing emacs junkie, it occurs to me that mentioning that
C-h i d m sort
is another route to SEE ALSO's destination. Then again, anyone who
needs it can probably work that out from what you said ;^)
>> ... +$n is an undocumented form of -k $(( 1 + $n )). If it is
>> deprecated, then the man page should say so ...
> It does say so -- in the real (`info sort') documentation.
(nod)
>> Saying "(origin 1)" meant something to me, but I suspect a newcomer
>> would be more likely to understand "(left-most field is number 1)".
> But then it wouldn't fit on one line :-) 1/2
and I see the info page is suitably clearer :-)
> At least one option (`b') can be applied to either
> the start field or end field -- or to both, but it's a little
> esoteric and not often useful.
ah, OK.
I tentatively guess *trailing* space is ignored for all fields ?
> SIZE may be followed by the following multiplicative suffixes: % 1%
> of memory, b 1, K 1024 (default), and so on for M, G, T, P, E, Z, Y.
woaaah ! Yotta-bytes ? Even 64-bit machines are going to have trouble
addressing that big (1L << 80) a chunk of memory ! (Same problem for
zetta-bytes.) I guess that's what you call "forward compatibility" ;^)
I think the above should say "byte" where it's the unit and be
punctuated as:
SIZE may be followed by the following multiplicative
suffixes - %: 1% of memory; b: 1 byte; K: 1024 bytes
(default); and so on for M, G, T, P, E, Z, Y.
I also note that the paragraph beginning "Mandatory options" belongs
in the preamble, since it doesn't (I assume) apply only to the
Ordering options ! So it should appear before that sub-heading.
The indentation leaves a little to be desired. The explanative texts
for -b, -t and --help itself appear inline with the actual option
illustrations (which is fine for the --help output but not so good for
the man page); and it would be nicer if at least the sub-headings -
"Ordering options" and "Other options:" - were less indented than the
actual option illustration (the running text could sensibly share
their indentation), e.g.
DESCRIPTION
Write sorted concatenation of all FILE(s) to standard output.
This is just terse help: SEE ALSO points to full documentation.
Mandatory arguments to long options are mandatory for short options
too.
Ordering options:
-b, --ignore-leading-blanks
ignore leading blanks
and so on (it almost seems a shame to give a help text when the long
option is so informative). Yes, I am a pythonista; and no, I don't
remember enough [gnt]roff to know how to fix that. I learned a new
format - HTML - over a decade ago, and have forgotten several old ones
from disuse.
Thanks again for your help,
Eddy.
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
