[Bug-tar] Re: tar man page

[Matthew Woehlke]

Sergey Poznyakoff wrote:
> > We just received a report on webmasters that some man page for tar
> > refers to the wrong url http://www.gnu.org/software/tar/man.
>
> The errors like that are reported every now and then. There are lots of
> `man' pages for GNU tar written by package maintainers or distributors.
>  
> > It seems that the tar distribution doesn't include a man page.
>
> There is no man page. The only and authoritative source of
> documentation is tar.texi and documents profuced from it.

...and I don't care for reading a tome when all I want is to know what 
option follows symlinks. man pages are IMO more readable than --help 
output. They are also searchable* if you have 'less' for a pager.

(*'grep' doesn't count; it's more typing and can strip content, 
resulting in having to repeat the search)

> > If that's right, it seems it would still be useful (although I know it's
> > not strictly necessary for GNU), to avoid errors like this.  You can
> > generate with help2man
>
> I believe this as an extra maintenance burden. The man page generated by
> help2man is useless, it says the same thing everybody will get
> by simply running `tar --help'.

How so? Update the build system to generate a page with help2man. That 
has to be done exactly once. (You need to also maintain --help, but 
you'd better be doing that anyway :-).)

> > to avoid having an independent source to keep updated.
>
> If it is their choice to provide it, then let them provide it. Some of man
> pages I saw (those distributed with Slackware, for example)
> contain much more info than help2man would produce, and we'd do their
> users a very doubtful favor if we replace a third party man page saying
> something with our page saying nothing useful at all.

There is nothing stopping downstream maintainers from replacing the man 
page anyway. Do you instead prefer to leave an out of date man page in 
place? What if the man page isn't even for GNU tar (e.g. when building 
from source on non-GNU-based OS's)? How is it a service to leave around 
a man page that may be Just Plain Wrong?

help2man works fine for coreutils and I haven't heard of complaints. 
Besides, help2man pages usually mention that "The full documentation for 
[tar] is maintained as a Texinfo manual. If the info and [tar] programs 
are properly installed at your site, the command 'info [tar]' should 
give you access to the complete manual." Does that qualify as "nothing 
useful at all"? Is the third party man page better than tar.texi? (If 
so, tar.texi needs to be improved!)

As someone that maintains (well, used to, I haven't put as much time 
into it recently) a GNU toolchain on almost a dozen platforms based on 
from-source builds, I would much prefer if tar would follow the rest of 
the world and provide at least a basic man page.

--
Matthew
"What is a release plan, anyway?" -- Oswald Buddenhagen
  ...who I'm sure did not mean it seriously ;-)