Re: Where do you RTFM ?
On Mon, 24 Dec 2001 20:38:49 -0800
"Karsten M. Self" <kmself@ix.netcom.com> wrote:
> - It attempts to replace, not augment, an existing, established,
> viable, useful, and effective standard. This is almost always a bad
> idea. The far better tack: provided augmented functionality. If
> your solution is compelling enough, people will transition.
Right, but doesn't apply here. Info does augment manpages. First it
fulfills the purpose of the manpage, giving exact and complete
information through the reference sections, and then it augments the
limited sections of a manpage by free chapters which try to explain
the issue in human language, often with tutorials and examples.
> - It's (largely) bound to a specific viewer. Which, if you don't use
> emacs, isn't particularly usable, and is about as intuitive
> as...well, emacs. This has changed as additional viewers are
> avilable (e.g.: pinfo -- based on lynx...but, of course, I don't
> care for lynx's keybindings, and use w3m instead....), but it's not
> fully remedied the problem. The authoring markup is distinct from
> both manpages (groff) and DocBook (SGML).
Inconsequent. Man requires groff and a pager. I can't read SGML or XML
(but hate them), specially when created by some `intelligent tool'
with no human digestable linebreaks. You need a tool to write _and_ to
read them. You can write and read info files in any text viewer/editor
including less. Of cource, then you'll lose the cross references, but
this those wouldn't work with XML either. Man pages stop being useful
when they get too long. Try locating a short word in man bash. Also,
IMHO, I don't think a slash for searching forward and a question mark
for back is intuitive, at least not more than Ctrl-S (search) Ctrl-R
(reverse search). Also, I'll always consider more intuitive and human
readable \TeX syntax than .groff, .gro^_off-text or</XML>.
> - It fragments the documentation effort. GNU favors info. Debian
> favors manpages (I've written on this in the past, references
> supporting both claims are available).
Probably true, but people still can choose, unless they get
consistenly bashed for it.
> - Info and man serve different functions. Man is meant to be a quick
> reference, putting the most likely needed information -- command
> arguments and use -- first. For Info, you've got to dig to get to
> this. It's like the "entrance tunnels" that some web wanks were
> advocating for websites for about fifteen minutes in 1997. Like I
> want to open four pages to get to your site.... Info puts shit in
> the way of what I'm looking for.
Both, man and info have a learning curve. That you forgot about yours
concerning man doesn't make this untrue. One of the declared aims of
info is to provide a frame to write introductions or tutorials which
wouldn't fit well into a man page, because that is limited to a
reference manual. Info also provides that. If I already know a program
but need to remember some option or syntax, I'll use for instance
info's command reference, but if I don't know the program, and may be
really don't have an idea what it is about, I'll read the info from
the beginning to the point where I got the idea.
> - It splits a programs docs into multiple pages. In electronic
> format, single, large, documents which can be searched through
> readily (gee: that sounds like a manpage under 'less') is more
> useful than a set of smaller docs which can't be as readily scanned.
Try Ctrl-S, which will search through all files. Don't want to type
info? You also can use (z)grep (same work but less useful).
> - GNU project manpages frequently include a passage:
>
> This man page is not kept up to date except when volunteers want
> to maintain it. If you find a discrepancy between the man page
> and the software, please check the Info file, which is the
> authoritative documentation.
This is the choice of the program's authors. We'll have to respect
it. And some will be more happy (me) than others (you) :-)
>
> [Taken from the gcc manpage]
>
> ...followed by dire warnings that the manpage may not be updated,
> etc., etc. At which point the pitiless reader turns to the info
> document...which in many cases is a copy of the same manpage (now
> presented in an unfamiliar document viewer). Houston, we've got a
> problem.
This is the choice of debian maintainers.
> The basic concept is valid. However, what seems to have happened in the
> world is that we got several rival document and hypertext languages in
> about the same five minute period of 1987. Tim Berners-Lee happened to
> win the race. Ironically, man pages translate quite well to HTML, and
> DocBook / LDP has largely filled the niche Info is more suited to:
> providing a more substantial, book-styled, document suitable for
> browsing rather than a quick reference.
If I can open info on any terminal, I do prefer it over lynx and would
never want to have to wait for mozilla starting up, (which is possibly
not even installed on such machine). This sounds to me like when I had
to interview a guy for a job, who told me that he uses Star Office to
edit configuration files (my question was expecting vi, emacs,
etc).
It is obvious that man pages translate easy to HTML: they are so
simple and limited, that they translate well to anything, including
info.
> Info _was_ a really good idea at its time. Binding it to an emacs-style
> editor made a bit of sense. But things have changed, the computing
> audience has exploded beyond Richard's dreams (both in general, and for
> GNU/Linux specifically), and I'd venture to suggest that most people
> using GNU/Linux either don't know emacsen or don't use them as their
> principle editing environment. This is no longer a principally
> technical community, even on the "techincal" platform.
I'm happy belonging to a minority.
[...]
> I've got _no_ idea how to access this search function. The _only_ time
> I use the info browser is...when I'm using info. Whereas with man, I
> use the same less pager that I'm using to read any other text file. I
> hit manpages probably a few dozen times a day. I'd be (un)lucky to hit
> info as many times per month.
Try Ctrl-H to get help in info. I use info and man. My biological RAM
is very limited, but it's still enough to deal with both. Oh, and info
info works as well as man man.
> There is _one_ problem I consistently see with manpages: a lack of
> examples. A manpage should explain _what_ the function does, provide a
> brief synopsis of _why_ (e.g.: when do you want to use foo), and then
> ***SHOW YOU HOW***. See my earlier comment today WRT setting the system
> clock with 'date'. Syntax isn't presented in the manpage. Remedying
> this single failing of man pages would do no end of good.
Some manpages do, but they have not been designed for that, nor is it
their purpose. Manpages with examples miss their basic aim: to should
provide a quick but complete reference. No space for examples (nor is
there a traditional secion for examples). It would render the pages
much longer and more difficult to get an overview. There is no index
in man. Info is designed to deal well with this. Using several levels of
indices, references and cross-references, you can locate quickly any
information you are looking for without reading the whole thing once
more (you did read it the first time, did you?) OTOH, often I try
--help before using man, if I just need a reminder.
> > So what is it that makes you (and others) react so vehemently?
>
> Um. Answered? ;-)
No.
--
Christoph Simon
ciccio@kiosknet.com.br
---
^X^C
q
quit
:q
^C
end
x
exit
ZZ
^D
?
help
.
Reply to: