> Date: Fri, 7 Apr 2006 19:11:49 +0200 > From: Stepan Kasal <[EMAIL PROTECTED]> > Cc: Dave Jarvis <[EMAIL PROTECTED]> > > Eli thinks that the problem is that Dave doesn't know the various info > readers well enough. I think that the problem might be that we know them > too well, and we are not open for views which look at out current > practice from distance and show what is obviously broken. > (I have the impression that Dave knows enough details, he just haven't > list the perspective.)
My problem with Dave wasn't complaints about Info, it was _useless_ complaints. He seems to think that a Help system should assume no prior knowledge on the user's part. For example, he saw a problem in the fact that "info --help" and "info --usage" do different things, whereas ``info'' and ``help'' are synonyms. (And this is only an example of his approach.) To me, this sounds incredibly silly. It should be quite obvious to anyone involved in this business that using modern computers requires _gobs_ of contextual knowledge and jargon/slang. Info documentation tries to do many things, but one thing it does _not_ try to do is teach users all this initial knowledge, and nor should it try to, IMO. Another example of Dave's unconstructive approach is his insistence that only Unix and GNU systems have this problem, while MS-Windows doesn't. That's simply not true. Try typing "help" at the Windows command prompt, and you will see something very similar to what Bash displays. And the GUI Help system is not much better. For example, its opening screen doesn't give me a clue where to find information about code development support tools. In fact, I find the opening screen quite useless. Now, it is easy to mock _any_ software, and it is especially easy to mock a Help system which starts with a tutorial about itself. Such bootstrap style situations are notoriously hard to get right, and the Info manual about itself did indeed change in major ways during the years, as user experience and comments poured in. It (the Info tutorial) is still evolving. What we need is constructive suggestions, not silly mocking. As for being ``not open to differing views'', you, Stepan, and others should know that this is about the last thing the Texinfo project can be accused of. Several major features were added to Info over the years because users were unhappy with some aspects of Info's behavior. Examples include the --usage and --vi-keys options. If the critique is serious and specific, it is received with an open mind. > I use good old man. Yes, it's not hypertext FWIW, Emacs makes man pages behave as hypertext. > and it's not suitable for > viewing the whole books of technical documentation (called Texinfo in > our GNU-speak), but it is sufficient as a ``help''. IMHO, man pages are only sufficient for learning the command-line switches. They never explain any background about the programs, and almost never say anything besides the bare-bones switches. It is impossible to _learn_ about a package you never used from man pages alone, unless it is a very simple program or package. > I'm afraid we should admit to ourselves that at our times, the > hypertext browser area is dominated by HTML browsers, so we should > just use one. HTML browsers are not a good substitute for Info because they lack several extremely useful and efficient commands, such as the index search commands and the apropos features. Without these features, all one can do with a manual is to search its entire text for strings, or try to find what one wants by traversing the TOC. In large manuals, this is simply too inefficient. When I want to find something in a manual, if I cannot find it in a matter of seconds, I become very irritated, because I cannot afford wasting many minutes on fruitless searches through gobs of material I have no interest in. If something like that happens in an Info manual, it generally means that one or more index entries are missing. Fortunately, most large Info manuals are very well indexed. > When I need a documentation for a command, I use `man' or google. > There are two exceptions where I use the Info system: the autoconf and > automake manual. I don't use emacs to access it: I;m afraid it would > take a few seconds for start, and I'm afraid I'd have to press C-xC-c > instead of q. Emacs is supposed to be always running; if you don't use it for your routine work, starting it just for Info is not for you. > I use the info command, for example `info autoconf' it brings me to > the usage page[1], and I press `u' twice to get to (Autoconf)Top. > Then I hold downarrow to get to `Portable Shell' section, Enter,s > then I hold downarrow for another two seconds to get to the menu below > the text and choose one of the last three items. That's a terribly inefficient use of Info. > This procedure seems to contain some moves which are just a waste of > time. I think I should do something about it, prehaps install the HTML > versions of Autoconf and Automake manuals, and make a few bookmarks. Emacs supports bookmarks. And if you are willing to add bookmark support to Info, I'm sure Karl will gratefully accept patches. However, this: > (If it were possible to have bookmarks in the standalone info browser, > I would still hesitate to learn another bookmark system.) seems to say that you don't really want bookmarks in Info, all you want is HTML. Fine, that's your prerogative, but please don't try to convince us heavy Info users, who are accustomed to its superior search capabilities, that HTML is the way of the future. > I just tried ``info awk'' now: it brings me to ``man gawk'', because > in the ``man'' world, there is an alias, but not in the dirlist file. Either you have an old Gawk version installed or this is an installation problem on your machine, because gawk.texi I have does have 2 dir entries, one for gawk and another for awk. > I tried the pinfo command, and I'm not happy with it: > 1) The description of the package in my description says that it is > better because it looks like lynx. Then it is better to use the > HTML format of Texinfo manuals, and a browser of my choice, perhaps > lynx, perhaps something which better matches my needs. > 2) `pinfo autoconf' brought me the man page (it seems it doesn't use > /usr/local/share/info/dir) and I wasn't able to access the dir node, > neither by `t', nor by `d', so I hit `q'. Try tkinfo, then, perhaps it will suit you better. (I myself use Emacs exclusively, when I'm in a GUI environment, and in text only environment the stand-alone Info is very adequate for what I need.) > GNU official positions seems to be that the info system is phasing > out the man pages. (Perhaps the feeling is that the `man' is too > UNIXy and thus not ``free enough.'') No, the GNU project thinks that man pages are simply not good enough as documentation. However, please note that this is an entirely different issue: this thread is not about documentation quality of the Info _manuals_, it is about user interface and efficiency of the Info _readers_. > I'd agree with Dave that it's time to phase out Info output format. If there's a better format, maybe. > Using an HTML browser for accessing the Texinfo manuals seems to be > more reasonable. I tried to explain above why it isn't, at least for me. > I think some distribution use a local web server for help system. I > don't think it's that bad, beacuse you can easily install a local > search engine into it. Given enough time and effort, one can do _anything_. The question is not what _can_ be done, the question is what works out of the box. Let's not forget that most people don't have time to hack every deficiency they bump into, they usually have some real work to do and some real deadlines to meet. When I need to find something in the docs, I need it _now_, and installing a search engine and tuning it is something I cannot afford wasting my time on. > [2] It seems that the distribution adds a symlink > /usr/share/man/man1/awk.1.gz -> gawk.1.gz > it's not the gawk itself. But again, why is the direntry missing? I don't know. It's something specific to your machine, cause on mine there are both gawk and awk direntries > because no one notices, man has still much bigger impact than info. I suggest not to jump to such general conclusions based on your single machine. I'd say no one notices because no one but you have this problem ;-) _______________________________________________ Texinfo home page: http://www.gnu.org/software/texinfo/ [email protected] http://lists.gnu.org/mailman/listinfo/bug-texinfo
