Karl Berry <[EMAIL PROTECTED]> writes:
> Niels, the fundamental problem is that way one writes texinfo manuals
> and the way one writes man pages are quite different. At least I could
> never accomplish it -- one or the other always suffered.
I think it would make sense, sometimes. For lsh, there is a plethora
of quite complex options. The --help message lists them very briefly,
without trying to explain it (and I don't like awfully long --help
messages; lsh's is currently 76 lines which is slightly too much to be
convenient). I think gcc is a similar case, its --help message doesn't
mention the interesting options (and if it did, it would become
unwieldy); while a dump the the invocation node and it's subnodes
would be more "man"agable.
I agree that a man page and a texinfo manual are quite different. To
me, a man page should be a terse, fairly complete reference. It's
somewhere between the --help message, which is a short reminder when
you already know what you want to do, and the texinfo manual which is
both a tutorial and a reference. But I think dumping a subset of the
texinfo manual would make an adequate man page, at least in the case
of lsh, where that section is intended to provide a terse but complete
reference.
When looking at the gcc man page I happen to have installed on this
machine, I think that is actually a relevant example; there is a short
introduction which I'm not sure if it is present in the info manual
(and which should be static enough to handle with an @ifman
construction), and then a complete (although perhaps outdated) list of
all the options in a logical order. I guess the latter part it is just
a dump of the corresponding nodes in the texinfo manual, more or less
manually reformatted. To me, the result seems like a nice and adequate
terse reference.
> My strong recommendation is to use help2man. It has sufficient hooks to
> create excellent man pages. It also encourages better and more standard
> --help output, which I would bet far more people read than anything else.
> And by reusing the --help output, it's more likely to be up to date than
> if the man page is written completely on its own.
I'll try it, even though I find it a little pointless to use man tool
instead of tool --help, if the former doesn't provide any more
information.
> This is the best solution I know of. It is far more practical than the
> dreams of converting texinfo usage nodes into man pages, in my
> (not-so-humble-in-this-case) opinion. It is being used in all the GNU
> *utils distributions and the texinfo distribution, maybe others.
Why do you think it is unrealistic? For technical or stylistic
reasons? I can well believe that a man output option to makeinfo is a
bad solution for most tools, for stylistic resons, but I believe it
would be very worthwhile for those tools that have a fairly complex
usage (but still less complex than e.g bash).
Regards,
/Niels
