-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hrvoje Niksic wrote: > 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.
I'd noticed. :) I haven't looked at the script that does this work; I had assumed that it was some standard tool for this task, but perhaps it's something more custom? > 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. Right; by "complete manual", I didn't mean to include such things as FAQ sections, etc. But yes, it means that one can't simply directly translate TeXinfo docs into its exact equivalent in *roff. > As for the "stub" man page... Debian for one finds it unacceptable, > and I can kind of understand why. Yeah, especially since they're frequently forced to leave out the "authoritative" manual. > 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. And thanks very much for that; it has been very informative. - -- Micah J. Cowan Programmer, musician, typesetting enthusiast, gamer... http://micah.cowan.name/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD4DBQFGnor27M8hyUobTrERCACzAJYgEZydf/ESX6rCjfYjY76jdNyIAJwPSPZ6 mom+r7VqREv5gGJaSSgQPw== =SGgY -----END PGP SIGNATURE-----
