Re: tail: Tiny documentation issue

[Bob Proulx]

Schmidt, Kriss A wrote:
> I was trying to work with the 'tail' command and ran into a little problem.

Thanks for the report.  Do you have a suggestion on how to improve the
wording?

> The "--help" states:
> 
> "If the first character of N (the number of bytes or lines) is a '+',
> print beginning with the Nth item from the start of each file, otherwise,
> print the last N items in the file.  N may have a multiplier suffix:
> b 512, k 1024, m 1024*1024."

I think you are missing the important part.  The --help output also says:

  Usage: tail [OPTION]... [FILE]...
    -n, --lines=N            output the last N lines, instead of the last 10

Those are a very important lines.  They describe N.  N is the argument
to the -n or --lines option.

  tail -n N
  tail --lines=N

Examples:

  tail -n 5 SOMEFILE
  tail --lines=5 SOMEFILE

Therefore the documentation that talks about N is talking about *that* N.

  If the first character of N (the number of bytes or lines) is a `+',
  print beginning with the Nth item from the start of each file, otherwise,
  print the last N items in the file.  N may have a multiplier suffix:
  b 512, k 1024, m 1024*1024.

If the first character of N is a + then it starts at the Nth item.
Examples:

  tail -n +5 SOMEFILE
  tail --lines=+5 SOMEFILE

> But this does not work as expected.  Comparing it to the 'head'
> command, '-' is used, so I tried that and it works as expected.

I assume that you didn't realize that N is an argument to the "-n" /
"--lines" option.  It all makes sense then.

> I hope this helps improve the product, which I rely on.  If it's
> been reported already, please disregard.

If you have suggestions for improving the documentation they would be
appreciated.  But the words must be kept exact, precise and concise so
as to be able to remain in the --help output.

Also note that the info documentation contains the full documentation
on the command.  There is good information on this topic in the full
manual.  It includes discussion of the obsolete syntax too.

     For compatibility `tail' also supports an obsolete usage `tail
  -COUNT[bcl][f] [FILE]', which is recognized only if it does not
  conflict with the usage described above.  COUNT is an optional
  decimal number optionally followed by a size letter (`b', `c', `l')
  to mean count by 512-byte blocks, bytes, or lines, optionally
  followed by `f' which has the same meaning as `-f'.  New scripts
  should use `-c COUNT[b]', `-n COUNT', and/or `-f' instead.

     On older systems, the leading `-' can be replaced by `+' in the
  obsolete option syntax with the same meaning as in counts, and
  obsolete usage overrides normal usage when the two conflict.  This
  obsolete behavior can be enabled or disabled with the
  `_POSIX2_VERSION' environment variable, but portable scripts should
  avoid commands whose behavior depends on this variable.  For
  example, use `tail -- - main.c' or `tail main.c' rather than the
  ambiguous `tail - main.c', `tail -c4' or `tail -c 10 4' rather than
  the ambiguous `tail -c 4', and `tail ./+4' or `tail -n +4' rather
  than the ambiguous `tail +4'.

> Thank you for helping us Unix folks survive in the DOS world,

We would rather have you join us in the GNU world.  :-)

Bob