20 Sep
2017
20 Sep
'17
1:35 a.m.
On Tue, Sep 19, 2017 at 10:01:57AM -0700, Jon Steinhart wrote:
OK, here's another one that's good for chest
thumping...
I am not a fan of texinfo. It doesn't provide any benefits (to me) over man.
I suppose that it was trailblazing in that it broke manual pages up into
sections that couldn't easily be viewed concurrently long before the www and
web pages that broke things up into multiple pages to make room for more ads.
If you take a look at how perl handles its man pages, with 188 man
pages in section 1:
...
perlsyn Perl syntax
perldata Perl data structures
perlop Perl operators and precedence
perlsub Perl subroutines
...
I find that info system, with its hypertext linking, to be far more
convenient. I've occasionally wished that the perl documentation was
available in info file format.
But sometimes the extra complexity of, say, gdb or gmake, provides a
lot of convenience. And the question is whether man is a sufficient
way to provide documentation. I would humbly submit that the choice
of using man pages as used by perl is an existence proof that man is
*not* the optimal way to provide documentation for a sufficiently
complex language or program.
(If the answer is that Unix programs should never be that complicated;
that's fine. But at least for me personally, I prefer to use gdb,
with its texinfo/info files, over adb with its man page. If you want
to argue that "real programmers" should be able to decipher structure
layouts by looking at C structure declarations and creating adb macros
by hand, and that DWARF annotations are for the weak and sickly, fair
enough. :-)
- Ted