on Tue, Dec 25, 2001 at 02:44:17AM +0100, Carel Fellinger (cfelling@iae.nl) wrote:
> On Mon, Dec 24, 2001 at 03:07:41PM -0800, Karsten M. Self wrote:
> ...
> > I ***DESPISE*** info. The pinfo alternative helps somewhat, but the
> > basic concept still sucks. It should be scrapped for a searchable
> > format based on HTML, XHTML, or preferably something like DocBook
> > capable of creating multiple output formats.
>
> I don't get this, just as I don't understand people bashing Stallman.
> What is it in the program that is so horrible to ***DESPISE*** it?
- 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.
- 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).
- 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).
- 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.
- 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.
- 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.
[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.
> It *is* searchable from within info, it *has* several output formats
> as it is LaTeX based. And the basic concept seems valid.
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.
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.
> Okee, the interface is not to everybodies likening:), so improve.
No. Divorce.
Thou shalt render content and presntation asunder. It was a fatal sin
in 1987 when Info was developed. It remains a sin.
> Okee, the translation into other formats has its problems:), so
> improve.
No. Realize you've been one-upped and passed by.
Man works for simple docs. Use man2html to present man pages via a web
interface. Convert the Info content to one or the other. ***AND BACK
FILL THE !@#$%^&*() MAN PAGES YOU'VE DEPRECATED FOR THE PAST FIFTEEN
YEARS***.
Hmm...actually, dwww and info2www seems to answer a bit of this issue.
I've never really played with dwww a whole mess, it actually seems to
answer a number of the issues I've got.
> But the search works for me
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.
> , and the idea that there is more to documenting a program then merely
> listing what options it has seems okee.
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.
> And going through a tree like doc structure is quit common these days.
>
> So what is it that makes you (and others) react so vehemently?
Um. Answered? ;-)
Peace.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What part of "Gestalt" don't you understand? Home of the brave
http://gestalt-system.sourceforge.net/ Land of the free
We freed Dmitry! Boycott Adobe! Repeal the DMCA! http://www.freesklyarov.org
Geek for Hire http://kmself.home.netcom.com/resume.html
Attachment:
pgpFSR7ScCrWQ.pgp
Description: PGP signature