Micah Cowan <[EMAIL PROTECTED]> writes: > I think we should either be a "stub", or a fairly complete "manual" > (and agree that the latter seems preferable); nothing half-way > between: what we have now is a fairly incomplete manual.
Converting from Info to man is harder than it may seem. The script that does it now is basically a hack that doesn't really work well even for the small part of the manual that it tries to cover. What makes it harder is the impedance mismatch between Texinfo and Unix manual philosophies. What is appropriate for a GNU manual, for example tutorial-style nodes, a longish FAQ section, or the inclusion of the entire software license, would be completely out of place in a man page. (This is a consequence of Info being hyperlinked, which means that it's easier to skip the nodes one is not interested in, at least in theory.) On the other hand, information crucial to any man page, such as clearly delimited sections that include SYNOPSIS, DESCRIPTION, FILES or SEE ALSO, might not be found in a Texinfo document at all, at least not in an easily recognizable and extractable form. As for the "stub" man page... Debian for one finds it unacceptable, and I can kind of understand why. When I pulled the man page out of the distribution, Debian's solution was to keep maintaining the old man page and disttributing it with their package. As a result, any Debian user who issued `man wget' would read Debian-maintained man page and was at the mercy of the Debian maintainer to have ensured that the man page was updated as new features arrived. Since most Unix users only read the man page and never bother with Info, this was suboptimal -- a crucial piece of documentation was not inherited from the project, but produced by Debian. (I further didn't like that the maintainer used my original man page even though I explicitly asked them not to, but that's another matter.) When the Debian maintainer stepped down, I agreed with his successor to a compromise solution: that a man page would be automatically generated from the Info documentation which would contain at least a fairly complete list of command-line options. It was far from perfect, but it was still better than nothing, and it was deemed Good Enough. Note that I'm not saying the current solution is good enough -- it isn't. I'm just providing a history of how the current state of the affairs came to be.