Re: Texinfo vs man
>>>>> "Wouter" == Wouter Verhelst <wouter@grep.be> writes:
Wouter> I never said that; I only said that good on-line documentation
Wouter> should concise and to-the-point information. Full, extensive
Wouter> documentation should be put in a HOWTO, a book, or on a website
Wouter> -- not in the primary on-line documentation tool.
As a long time user of Unix and Linux, I find it very useful that HOWTOs and
info are available on-line. Indeed, I never buy any book about Linux, but I
still know a real lot about it. This should never be changed.
Compared to HOWTOs, info files can be navigated much more easily, and is
much more consistent in format. Also, writers of info pages typically make
indices more than those of HOWTOs. Even if authors of HOWTOs make indices,
they are much less useful than info indices as they don't have the amount of
navigation aids as in info. I consider an info page to be much better than
a HOWTO in every regard, except that the developer must spend more effort.
Compared to a book and a web page, info files can be searched in text, which
is hard to be done in a book or a set of web pages in any format (even in
PS). A single page web-site, which would allow searching, is
out-of-question for the long load time and the huge memory it eats up in the
browser (causing it to be slow). Info files are also easier to put into a
distribution and let others find. On the flip side, a web site can contain
graphical information that cannot be easily put on an info file. So they
are approximately on par.
And a book which actually costs money is not affordable (or even available)
for everybody, and even if for you they are, it might be undesirable to pay,
trying a software, find that it is not suitable and repeat.
In any case, I can use info in both a stand-alone info program and within
Emacs, allowing me to use the key bindings that I'm familiar of. This makes
info stand apart from most other tools like the browser, c'os all
alternatives cannot provide the speed of access that I'm used to in info.
Wouter> If you have more information, I'm happy to learn about it; but
Wouter> let me start off by disagreeing with the stance that being
Wouter> "terse" or giving "inadequate explanation of the underlying
Wouter> concepts" is necessarily a problem.
Manuals serve two purposes: for new-comers to learn how to use the programs,
and for users who do not use the program often enough to get the
information. Accordingly there are two sorts of documentations, man pages
and info files. But I'd argue that at many times, the inadequate
explanation is really a problem even for the latter. When I read the man
page of ls, I see the "-l" option described as follows:
-l use a long listing format
Now I use ls -l. What I see are lines like this:
drwx--S--- 2 kkto kkto 48 2003-09-14 14:11 .Trash/
For me, interpreting such lines is now basic instinct. But for first time
users of the option (or even for those who haven't been paying enough
attention to it before), where to know what the "2" and "-rwx--S---" means?
Why there are two "kkto"? A quick on-line documentation should at least
solve such problems. But you can read the man page yourselves to see
whether it satisfies the requirement.
On the other hand, listing all possibilities of ls outputs will make the
manual long and difficult to navigate. There's a point where you really
don't like reading a single page as long as the manpage of bash(1). It
makes much more sense to put such documentations in info format.
Indeed, for the terse documentation, it is easy to just have a short info
page containing the current information of man. If I'm to find something to
unify to, I'll take the same approach as GNU and unify to info.
Regards,
Isaac.
Reply to: