inforants

This is part of The Pile, a partial archive of some open source mailing lists and newsgroups.



Return-Path: <redhat-devel-list-admin@redhat.com>
Date: Mon, 21 Aug 2000 07:52:34 -0500
From: Dave Ihnat <ignatz@dminet.com>
To: redhat-devel-list@redhat.com
Subject: Info vs. Man (Was Re: basename()?)

On Mon, Aug 21, 2000 at 01:01:37PM +0200, jfm2@club-internet.fr wrote:
> It should be the opposite: let's move off the obsolete man pages: thay
> were great in the seventies but today we have far more powerful
> machines who allow far richer ways of provising information.

That's fine; but info is NOT the way to go.  It's an awkward, sadly outdated
interface.

There is STILL a need for manpage-style documentation.  Man pages are
intended to be brief, concise developer or user notes.  You shouldn't
get theory of design, discussion of performance tradeoffs, etc. in a
man page; there should be a full document behind man page sets that
provides that kind of information.

I don't want to wade through reams of material I no longer need once I've
learned a package or system; I want brief usage reminders (without bloating
my software.)  And I want an intuitive interface; info sux at that.

===

From: teg@redhat.com (Trond Eivind=?iso-8859-1?q?_Glomsr=F8d?=)
Newsgroups: gated.redhat-devel-list
Subject: Re: basename()?
Date: 21 Aug 2000 09:40:53 -0400

ingo@blank.pages.de (Ingo Luetkebohle ) writes:

> On Mon, Aug 21, 2000 at 09:10:43AM +1000, Tony Nugent wrote:
> > I **HATE** info, it is the most un-intuiative utility I've ever come
> > across.
> 
> There's a small utilitity called "pinfo" which makes info reading on
> the console slightly less painfull. The interface is modelled on lynx.
> Check out freshmeat for the URL.

pinfo is included in pinstripe (7.0beta) - also, the emacs interface
isn't too bad.

I would surely like something similar to "man functionname", though. 

===

Date: Mon, 21 Aug 2000 10:16:56 -0400
From: Nalin Dahyabhai <nalin@redhat.com>
To: redhat-devel-list@redhat.com
Subject: Re: basename()?

On Mon, Aug 21, 2000 at 04:44:33AM -0700, Venkatesh Krishnamurthi wrote:
>   I find pinfo to be a very nice console mode info viewer.  Pinfo can be found
> at:
> 
>   http://zeus.polsl.gliwice.pl/~pborys/stable-version/pinfo-0.6.0.tar.gz

The pinfo package was in Power Tools at least going back to 6.1, and as
Trond mentioned, it moved to the main distribution in Pinstripe.

===

Date: Mon, 21 Aug 2000 10:39:00 -0400 (EDT)
From: Stephen Schaefer-NCS Sr SE <stephen@networks.com>
Subject: Re: Info vs. Man (Was Re: basename()?)
To: redhat-devel-list@redhat.com

On 21 Aug, Dave Ihnat wrote:
> On Mon, Aug 21, 2000 at 01:01:37PM +0200, jfm2@club-internet.fr wrote:
>> It should be the opposite: let's move off the obsolete man pages: thay
>> were great in the seventies but today we have far more powerful
>> machines who allow far richer ways of provising information.
> 
> That's fine; but info is NOT the way to go.  It's an awkward, sadly outdated
> interface.
> 
> There is STILL a need for manpage-style documentation.  Man pages are
> intended to be brief, concise developer or user notes.  You shouldn't
> get theory of design, discussion of performance tradeoffs, etc. in a
> man page; there should be a full document behind man page sets that
> provides that kind of information.
> 
> I don't want to wade through reams of material I no longer need once I've
> learned a package or system; I want brief usage reminders (without bloating
> my software.)  And I want an intuitive interface; info sux at that.

Amen; the cumulative user interface annoyances with info are awful
(and I'm and emacs fan!); but the idea that extensive and in-depth
documentation be organized in a hyper-linked tree with extensive
indexing is good.  In fact, it would be just peachy if I could
navigate the info documentation with my web browser.  I thought there
was supposed to be a texinfo to html translator, but for some reason
the texinfo documents aren't delivered that way, and it would be a
redundant use of space.  An alternative might be a CGI program that
would let the web server translate the .info files into html on the
fly; has anyone written something like that?

===

Date: Mon, 21 Aug 2000 10:45:59 -0400 (EDT)
From: "Mike A. Harris" <mharris@meteng.on.ca>
To: redhat-devel-list@redhat.com
Subject: Re: basename()?

On Mon, 21 Aug 2000, Venkatesh Krishnamurthi wrote:


> I find pinfo to be a very nice console mode info viewer.
> Pinfo can be found at:

>  http://zeus.polsl.gliwice.pl/~pborys/stable-version/pinfo-0.6.0.tar.gz

Thanks for the tip.  If I find pinfo useful, I'll rpmologize it
and put it up somewhere..

===

From: Alan Shutko <ats@acm.org>
Date: 21 Aug 2000 11:00:29 -0400

Stephen Schaefer-NCS Sr SE <stephen@networks.com> writes:

> Amen; the cumulative user interface annoyances with info are awful
 
info is a pretty bad program (although some of the most notorious
complaints, like not recognizing arrow keys, have been rectified), but
reading them in Emacs is a whole lot nicer.  

In any case, Info files and the Emacs browser offer a few advantages
which need to be integrated into any more "modern" doc systems:

* I can hit "i" and look up a word in the index, and be bounced
  directly to the first hit.  I can hit "," to go to subsequent hits.

* I can do a regexp search through the document.

* I can page through the document in a linear fashion, without finding
  and manually clicking on the link.  In other words, I can use a
  command of the help browser to navigate (which can be a button, be
  a key command, etc).

* I can use keyboard commands for everything, like hitting "m" and
  tab-completing which link I want to follow.

Some of these features can be gotten in certain web browsers with a
web server which indexes the files, but none of them exist in, say,
the GNOME help browser looking at local files.

===

Date: Mon, 21 Aug 2000 11:29:58 -0400
From: Matt Fahrner <Matt.Fahrner@coat.com>

Frankly I prefer "man" because it is concise and to the point. Yes, we
need extended documentation, but often it's a major pain to dig through
"info" and "/usr/doc" pages to find the information you're looking for.
Everytime I run into a (mostly) empty man that points me to these I just
lapse into a state of depression because I know I'll be fighting to find
what I'm after (I really wish they'd put even the most basic man page
with just the command line options if nothing else). Yes, incidentally,
HTML documentation is great (prefered by me over other non-man choices)
but I find it generally too slow to work with when I "just want the
facts mam".

I'd probably live with just about anything as long as it's consistent,
but everyone has their idea of what the perfect choice is and wants to
reinvent the wheel. One of the things I don't like Open Source is
everyone thinks "they know better" and ultimately we end up with the
software equivalent of the Tower of Babel. "man", though not perfect,
would work pretty damn well if everyone would just settle on it and keep
the pages up to date.

===

From: jfm2@club-internet.fr
Subject: Re: basename()?
Date: Mon, 21 Aug 2000 18:15:26 +0200 (CEST)
> 
> On Mon, 21 Aug 2000, Tony Nugent wrote:
> 
> >> At 10:35 8/19/00 -0700, Joseph Malicki wrote:
> >> >glibc is documented in info, not manpages. the manpages there are just
> >> >an incomplete and in some cases inaccurate collection, werent they from
> >> >libc5 or something?  The wonders of GNU software.......
> >> 
> >> then can we please get rid of the stupid man pages?
> >
> >Can we please get rid of the stupid info pages, and have a set of
> >updated man pages to replace them?
> >
> >(Just wanted to "put my hand up for the opposition", since I'm no
> >fan of info pages).
> 
> Is it truely the info pages you hate, or just the info user
> interface program?  I suspect the latter.  I like what info is
> TRYING to do - hyperlink documentation in a useful manner, but
> the UI just plain sucks.  HTML'ing it means I can choose my own
> UI - Lynx/Netscape, etc..
> 
> The info documents are very useful.  Try reading them with
> midnight commander in the /usr/info dir, or with less or
> something.  You get a bunch of crap here and there, but don't
> have to screw with the crappy info UI.  ;o)
> 

Info, the program, was never intended to be the main reader for info
pages.  It was just a quick hack written for VI users.  GNU is Not
Unix and GNU's official editor is not VI but Emacs. GNU Emacs or
Xemacs make for a far superior info-page reader to info (the program).
The Gnome help system is also able to display info pages.

A problem with info pages is that quite often they are far too
exhaustive for the user who just wants to know how to invoke a
program: just try to find in them the complete list of arguments for
gcc.  But this is not so much info's fault than the way the doc is
organized.

I am also quite sure there was a converter for info to HTML (llok out
for info2html in google or freshmeat) but navigating with lynx is not
precisely pleasant and I certainly don't want to use the memory
leaking Netscrape.

===

Date: Mon, 21 Aug 2000 18:20:12 +0200
From: Ingo Luetkebohle <ingo@blank.pages.de>
To: redhat-devel-list@redhat.com
Subject: Re: info-documentation (was: Re: basename()?)

On Mon, Aug 21, 2000 at 10:44:47AM -0400, Mike A. Harris wrote:
> Agreed.  Docbook seems to be the documentation choice du jour.  I
> have no idea anything other than that though.  I haven't seen any
> docbook docs, and have no idea how to create or read them.

http://www.docbook.org/

(some) Tools are at http://www.sgmltools.org/

> As soon as I find out, something else will have replaced it.

Due to the fact that, using XSLT or DSSSL, SGML/XML can be
transformed into anything else, it is hoped that your
statement will not prove true.

===

Date: Mon, 21 Aug 2000 12:49:26 -0400 (EDT)
From: "Michael Sterrett -Mr. Bones.-" <msterret@coat.com>
To: redhat-devel-list@redhat.com
Subject: Re: Info vs. Man (Was Re: basename()?)

While I prefer man pages due to their concise nature, in dealing with
the reality of info pages, I've found TkInfo invaluable.  It's definitely
worth checking out.

    http://math-www.uni-paderborn.de/~axel/tkinfo/

===

Date: Mon, 21 Aug 2000 10:15:55 -0700
From: Joe Brenner <doom@kzsu.stanford.edu>

Stephen Schaefer-NCS Sr SE <stephen@networks.com> writes:

> > Amen; the cumulative user interface annoyances with info are awful
>  
> info is a pretty bad program (although some of the most notorious
> complaints, like not recognizing arrow keys, have been rectified), but
> reading them in Emacs is a whole lot nicer.  
> 
> In any case, Info files and the Emacs browser offer a few advantages
> which need to be integrated into any more "modern" doc systems:
> 
> * I can hit "i" and look up a word in the index, and be bounced
>   directly to the first hit.  I can hit "," to go to subsequent hits.
> 
> * I can do a regexp search through the document.
> 
> * I can page through the document in a linear fashion, without finding
>   and manually clicking on the link.  In other words, I can use a
>   command of the help browser to navigate (which can be a button, be
>   a key command, etc).
> 
> * I can use keyboard commands for everything, like hitting "m" and
>   tab-completing which link I want to follow.
> 
> Some of these features can be gotten in certain web browsers with a
> web server which indexes the files, but none of them exist in, say,
> the GNOME help browser looking at local files.

I'm agreed that "info" is very useful, particularly when you
use it from inside of emacs.  I was wondering what trouble
people really have with it?  There's a complaint that info
nodes are too verbose for some people, but that's really
more of a style thing than a software thing (nothing stops
you from having, say, an appendix on a subject with just 
reference information in it).  The UI doesn't bother me
particularly, it just seems like any keyboard oriented
program: you need to invest some time in learning the
commands, and then you can keep your hands off the rodent.  

When I get documentation in html, I end up looking at it in
lynx (unless it has a lot of diagrams) which strikes me is
being a lot less convenient than "info".

(And while we're on the subject of style: I think the "man"
page style is favored by CS geeks, who always seem to be
chasing after mathematical precision in some form or
another.  The rest of us might be forgiven if we'd like to
see something written in English...)

Oh, and please: no "P"DF.


===

Date: Mon, 21 Aug 2000 10:33:03 -0700
From: Joe Brenner <doom@kzsu.stanford.edu>

Ingo Luetkebohle <ingo@blank.pages.de> wrote:

> Ok, calming down: texinfo has never caught on outside of the GNU area
> apart from very few exceptions. Thats largely due to the
> unfriendliness of the accompanying software and also due to the fact
> that the underlying technology is almost as old as groff is -- ok, it
> can do hypertext. Thats all it has to offer. 

Well, there is also the point that the Gnu people wanted to
stop writing everything twice.  They generate both info
nodes and printed documentation from the same source files.

Which is not to say that texinfo is the only way of doing it
(certainly not these days).  I'm not so sure that the right
thing for them to do is to drop everything and switch to the
latest-greatest-newest most buzzword-compliant file format,
though. 

> Its gross arrogance to assume that users will want to learn
> a new way of getting information every other year for no
> other reason than that the authors don't like the old
> anymore -- for reasons which they have to account for
> themselves.

I might suggest that it's kind of arrogant to try and give
orders to unpaid volunteer labor.  

If you want to help update the gnu manpages, I'm sure the
FSF wouldn't chase you away. 

===

From: Alan Shutko <ats@acm.org>
Date: 21 Aug 2000 13:33:22 -0400

Joe Brenner <doom@kzsu.stanford.edu> writes:

> I'm agreed that "info" is very useful, particularly when you
> use it from inside of emacs.  I was wondering what trouble
> people really have with it? 

Oh, I can tell you those things too.  (Can you tell I've experienced
this argument before?)

The usual complaints are:

* It's got a crappy interface:  The standalone program definately
  does, and alternative viewers are not always apparent to the people
  complaining about info.  Maybe they wouldn't complain with a better
  interface.

* It's too hard to find stuff in it.  Usually, those complaining are
  looking for command-line flags, which are fairly buried in most info
  documents.  Those complaining are also usually unaware of info
  features such as the easy-to-access index and the ability to search
  the whole document by regexp.

* It's another format, and I don't want to have to look in two
  places.  A fairly legit argument, but man is just unsuited to large
  documentation sets.  Personally, I'd rather have an info file than
  Perl's 80 independant man pages, since info makes it easier to
  navigate and search that volume of documentation.

* It's unstandard, we should have HTML.  Sure, but as I posted, right
  now the infrastructure around HTML makes it more difficult to use,
  although you'll get a nice happy browser to click around in.

So, really, if there had been a better non-Emacs interface, I think
Info wouldn't have such a bad rap.

===

From: Alan Shutko <ats@acm.org>
Date: 21 Aug 2000 13:59:20 -0400

Ingo Luetkebohle <ingo@blank.pages.de> writes:

> [<rant>]Its gross arrogance to assume that users will want to learn a new
> way of getting information every other year for no other reason than
> that the authors don't like the old anymore -- for reasons which
> they have to account for themselves. [</rant>]

I just can't resist mentioning that info.el has been around since
1985, and the standalone info has been around since 1987.  

===

Date: Mon, 21 Aug 2000 14:20:20 -0400 (EDT)
From: "Mike A. Harris" <mharris@meteng.on.ca>
To: redhat-devel-list@redhat.com
Subject: GNU info  (was something else)

On Mon, 21 Aug 2000, Nitebirdz wrote:

>> > However, if the OS is CLI-based, then I'd better know the exact
>> > command I'm supposed to enter and all its flags, ect.
>> 
>> That's not true.  There are definately ways to discover ways to do
>> things on a CLI.  I certainly don't know exactly how to do everything
>> I do every day, but I somehow manage to figure them out, using a CLI.
>> 
>
>I disagree again.  We cannot seriously compare the use of a Help page
>written in SGML to the manual pages.  For one thing, in order to even
>check the manual pages you already have to know about the existence of the
>"man" command and even the name of the command whose manual page you want
>to read.  

Here's the funny part.  Everyone says how GNU info is the GNU
project's official documentation format.  A new user without a
clue where to get help, is likely to guess at a few things.  One
of the most likely "guesses" is to type "help".

3 root@asdf:~# help
GNU bash, version 1.14.7(1)
Shell commands that are defined internally.  Type `help' to see
this list. Type `help name' to find out more about the function `name'.
Use `info bash' to find out more about the shell in general.

A star (*) next to a name means that the command is disabled.

 %[DIGITS | WORD] [&]               . filename
 :                                  [ arg... ]
 alias [ name[=value] ... ]         bg [job_spec]
 bind [-lvd] [-m keymap] [-f filena break [n]



They might then try "info bash" as suggested by the help command.




File: features.info,  Node: Top,  Next: Bourne Shell Features,
Prev: (DIR),  U\p: (DIR)

Bash Features
*************

   Bash contains features that appear in other popular shells,
and some features that only appear in Bash.  Some of the shells
that Bash has borrowed concepts from are the Bourne Shell (`sh'),
the Korn Shell (`ksh'), and the C-shell (`csh' and its successor,
`tcsh'). The following menu breaks the features up into
categories based upon which one of these other shells inspired
the feature.

   This manual is meant as a brief introduction to features found
in Bash.  The Bash manual page should be used as the definitive
reference on shell behavior.




The last paragraph here says the man page is the definitive
reference but of course doesn't say how to access it.  So here we
have a GNU program claiming the man page is official definitive
reference.

Which is it?  info or manpage?  Often people are told the info
docs are definitive.  It is NOT 100% though.  How does one know
which to look at?

Honestly though, a new user nowadays to Linux, is almost 95% or
more likely to try it out with either GNOME or KDE.  They are
highly likely to discover the help system in each and will find
the manpages and info docs right there.  If they read the stuff
they'll learn.  The default web browser page links to tonnes of
online documentation and learning aids.

The main problem I see is not knowing where something is
documented to start with.  Is is manpage/info/html or
nonexistant.  Especially confusing when one manpage references
another nonexistant one.


>Again, I'm a big supporter of Linux and open source in general.
>I am _convinced_ that Linux will sooner or later win the
>desktop market too.  However, I cannot in good faith deny that
>Windows is more user-friendly right now. The price to pay?  
>Less power, of course.  Not only that, but you're limited to
>whichever options the desginer of the GUI decided to add to
>his/her tool.

Agreed.  My mother just recently started using a 486 I gave her
with no graphics available.  She's using "lynx", "pine" and
"mc" having NEVER used a computer EVER before.  She PREFER's
oddly enough to use these programs over Netscape, and X.  She
fumbles around, but likes it better than using a mouse.  She uses
a mouse like a child takes first steps.  She couldn't click the
mouse on a 3 inch icon and get it to do anything.  I can't for
the life of me get her to connect with the thing.  So I set up
lynx/etc.. on a menu program (pdmenu), and threw a "connect to
internet" and "disconnect from internet" on there.  She looks at
the help in Lynx, Pine and is getting aroudn ok.

She thinks Windows is hard when she visits me and uses my
computer.  She wishes to use Lynx instead.  Just shows that user
friendly is very very very relative to WHO the user is.  She is
probably the least experienced computer user imaginable.  Granted
the CLI would kill her for sure, but that is besides the
point.  It depends on a given persons own thought processes what
is easy and what is not.  An individual thing.

===

Date: Mon, 21 Aug 2000 14:34:07 -0400
From: Matt Fahrner <Matt.Fahrner@coat.com>

Alan Shutko wrote:
> I just can't resist mentioning that info.el has been around since
> 1985, and the standalone info has been around since 1987.

Touche!  ;-)

I still think there's too many re-implimentations out there (even if
this isn't one of them). After a while everyone keeps rewriting things
and all we end up is with "noise". On the other hand, things like
"bash", "less", and "ncftp" *are* really major improvements...

===

Date: Mon, 21 Aug 2000 22:52:24 +0200
From: Ingo Luetkebohle <ingo@blank.pages.de>
To: redhat-devel-list@redhat.com
Subject: Re: info-documentation (was: Re: basename()?)

On Mon, Aug 21, 2000 at 01:59:20PM -0400, Alan Shutko wrote:
> I just can't resist mentioning that info.el has been around since
> 1985, and the standalone info has been around since 1987.  

Ok, and GML (the precursor to SGML, which in turn was precursor to
XML) has been around since 1967 and was standardized as SGML in
1978. That only proves that good ideas can take a while to catch on,
be it texinfo or generalized markup.

However, my point was not to criticize texinfo in itself. I was trying
to point that from an end-users perspective the perfectly good reasons
that the GNU project might have had could be less understandable and
that their *software* offering was not blessed with an intuitive user
interface. "man"s interface, while simple, is intuitive :)

===

Date: Mon, 21 Aug 2000 22:56:36 +0200
From: Ingo Luetkebohle <ingo@blank.pages.de>
To: redhat-devel-list@redhat.com
Subject: Re: info-documentation (was: Re: basename()?)

On Mon, Aug 21, 2000 at 10:33:03AM -0700, Joe Brenner wrote:
> I might suggest that it's kind of arrogant to try and give
> orders to unpaid volunteer labor.  

Please -- where did I give orders? I was just trying to point out that
the way texinfo is promoted might not be the smartest way to do it and
that might account for its low order of success. Turns out that my way
of putting it was not the smartest either, so I apologize for
that. I hope that it did not invalidate the reasoning altogether.

===

Subject: Re: basename()?
From: Chris Abbey <cabbey@bresnanlink.net>
Date: Mon, 21 Aug 2000 21:26:10 -0500

At 07:35 8/21/00 -0400, Trond Eivind Glomsr

the rest of The Pile (a partial mailing list archive)

doom@kzsu.stanford.edu