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