Volker Kuhlmann
Fact is GNU has no man page for tar.
I have been involved in that `tar' man page affair, so I can try my best to reply to questions. There are two main sources of documentation: the Texinfo manual, and the `--help' output. In the 1.12 series, if I remember well, there is an installed `man' page, which is automatically derived from the `--help' output through Brendan O'Dea `help2man' nice tool. This `man' page even explains how to get to the remainder of the documentation. However:
"tar --help" only gives you a summary not good enough for understanding.
Indeed, `--help' output for almost any program is meant as a reminder, and is no substitute for the real documentation. Of course, we all know the folklore by which people will resort to reading the real documentation only when everything else fails. Nevertheless, `--help' is sufficient for remembering, but surely not enough to learn. And so is the `tar' man page.
As Lenz pointed out, "info tar" will give you the basics.
In fact, it should give you not only the basics, but all available information. This is the full reference. Go to the `Invoking tar' or `tar invocation' node if you are in quick need and do not want to see the tutorial, concepts, and such more complete information. By the way, for every program accessible through `info PROGRAM', there should be an `Invoking PROGRAM' or `PROGRAM invocation' node. This is mandated by GNU standards. If you find a PROGRAM without such a node, you may report it as a bug.
SuSE decided not to ship out-of-date junk instead. Having bad unknowingly is worse than having nothing.
The small `tar' man page which comes with 1.12 _is_ up-to-date, as it carefully reflects `--help' output. Even if I tried reasonably hard for `info tar' (which only gives access to an on-line version of the printed manual) to give adequate information, it might still have a few mistakes, but it is generally good. If there was really no documentation at all, than my own feeling is that an out-dated `man' page would be better than nothing, indeed. But if there is a reasonably correct information in some format, distributing an out-dated `man' page would surely be a mistake, as it would bring confusion, and raise frustration. We should not place documentation format above documentation adequacy. I guess I could write entertaining and unbelievable chapters on the real history of `tar' documentation :-). -- François Pinard http://www.iro.umontreal.ca/~pinard -- To unsubscribe send e-mail to suse-linux-e-unsubscribe@suse.com For additional commands send e-mail to suse-linux-e-help@suse.com Also check the FAQ at http://www.suse.com/Support/Doku/FAQ/
On Sun, Jan 16, 2000 at 11:10:17AM -0500, François Pinard wrote:
Volker Kuhlmann
writes: Fact is GNU has no man page for tar.
I have been involved in that `tar' man page affair, so I can try my best to reply to questions.
There are two main sources of documentation: the Texinfo manual, and the `--help' output. In the 1.12 series, if I remember well, there is an installed `man' page, which is automatically derived from the `--help' output through Brendan O'Dea `help2man' nice tool. This `man' page even explains how to get to the remainder of the documentation. However:
"tar --help" only gives you a summary not good enough for understanding.
I haven't looked at help2man, but I'm guessing it makes a manified file in the man directories. I wonder if this could be done on the fly, i.e., by storing the command `/usr/bin/help2man "/usr/bin/tar --help"` or whatever? There would have to be an indication that the man page was derived this way, of course, and programs with real manpages wouldn't get or need this treatment. I suppose the man command itself could be extended to try help2man on an argument with no manpage. Similarly, while the info system is not flat, and thus not easily converted to manpages, I wonder if there is a way to make an interface to info docs through the man facility? Surely this has already been discussed (to death?) somewhere, and I haven't looked into it (yet?), but it might make the system easier to deal with. Currently there are a (growing?) number of ways to get help/documentation on programs and commands, including man, info, --help, -h, html pages, pod docs (for Perl). To me some of the most annoying are the commands, e.g., many in KDE, that (seem to) lack anything other than the KDE help information, which I think is html. I'm not griping, and appreciate that at least the information is accessible, if nothing else by browsing the sources. Each help/documentation mechanism has its pros and cons, and I doubt if the *nix world is ready for one true standard. Perhaps the "No manual entry for tar" message could be extended to suggest other approaches, e.g., No manual entry for tar (try 'info tar', 'tar --help', 'tar -h', ...) On the other hand, command line jockeys need to learn this stuff anyway, and there is something to be said for keeping man's output lean. ...
I guess I could write entertaining and unbelievable chapters on the real history of `tar' documentation :-).
I'd be entertained to read it. Ken -- Ken Irving Trident Software jkirving@mosquitonet.com -- To unsubscribe send e-mail to suse-linux-e-unsubscribe@suse.com For additional commands send e-mail to suse-linux-e-help@suse.com Also check the FAQ at http://www.suse.com/Support/Doku/FAQ/
participants (2)
-
jkirving@mosquitonet.com
-
pinard@iro.umontreal.ca