Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx> writes: > On Sat, 4 Aug 2007, David Kastrup wrote: >> > >> > You must be kidding. Texinfo is the worst documentation format EVER. >> >> Oh come on. It was the first hyperlinked and hierarchical format >> before HTML even existed. > > Yes. And it should have died after html took its place. The problem is that html, not even now, offers useful standardized structural navigation information, so no reader can offer keypresses to follow the non-existing information. I'd really like HTML to have taken its place. However, in spite of all the bloat of HTML processors (firefox takes more memory than Emacs, and Emacs is my bloody _desktop_), and in spite of it being orders of magnitude slower, it does not offer this navigation. It offers no cross-page search facilities. You can't navigate through the structure of the equivalent of hundreds of printed pages in an HTML browser. Not by navigating, not by plain text searching. I'll be all set to bury Texinfo once HTML has taken its place. Unfortunately, it has taken a different place up to now. >> Actually, a decade ago the Emacs-internal info reader was worse >> than it is now. > > Wow. I've used the emacs one, and the stand-alone info one, and both > are pretty horrid. You're saying that they used to be _worse_? The standalone reader was rather horrid a few years ago: it used not to know the normal page and cursor commands and beeped at quite a few things. It is quite better now. Bit it is not Emacs. > (Admittedly, my GNU emacs-fu is very weak. I use an emacs-like > editor, but it's just an editor, and it's subtly different, so I > actually find the "real" emacs to be really disturbing on so many > levels ;) > >> [ structure ] >> >> And as opposed to AsciiDoc, there _are_ readers that make use of >> this information. > > None that any normal user would want to use. Linus, do you really think that the editor _you_ use is used by more people than Emacs? Think again. Anyway, Emacs might, for all your polemics are worth, be an editor that a "normal user" would not want to use: it has a tough learning curve. It has considerably flattened in recent years, and particularly Emacs 22 is a big step forward, but no sane person would use Emacs if there was anything else that sucked less. There isn't. And in spite of all your denial, there isn't for Texinfo, either. You can't do a plain text search through hundreds of HTML pages. You need a single page for that, and then navigation, already bad in HTML, becomes absolutely horrid. Your best bet nowadays might be a PDF reader with plain text search in the document intended for printing. Something which has a page layout and fonts not suited for screen reading. You can't usefully find your way through a hundreds-pages manual page. > The thing is, html does a much better job of all of that, simply > because there are useful readers. But there aren't. Not for documents of several hundred pages. Not until you download all of them and then do a grep on the flat files when you are looking for some keyword anywhere in the whole bunch. That is an amount of suckage that neither Emacs nor the info reader could ever hope to replicate. > The same, btw, goes for man-pages: even though they have no > structure at all, just the fact that normal people know how to use > them, they are actually superior to info pages! For single pages, yes. For hundreds of pages, this falls apart. Man pages don't scale. > That's something that the FSF seems to have missed in their push for > info format: a lot of FSF programs have really substandard > man-pages, but that doesn't mean that people read the info ones > _anyway_. Because the readers are so disgustingly horrible, plain > man-pages are actually much more useful, despite the fact that they > don't have any cross-referencing etc. Again, you presume to know the rest of the world, and the rest of the world is "normal" and just like you. I will readily agree with you that for the longest time, reading info files outside of Emacs was painful enough to make it mostly useless. With the current standalone info reader, it is merely annoying. And inside of Emacs (and using Emacs is not as much the equivalent of doing appendectomy on yourself with a fork because there is no _equivalent_ to do the same job, but has progressed to a reasonably sharp knife), info has moved from "tolerable" to "quite usable" under Emacs 22: you can easily search whole documents, single nodes, chapters. Pretty much everything is clickable by mouse (with mouse button 1), including the structural information that _stays_ on top of your window. Anyway, like it or not, the current form of git documentation is not structured, and that means that it is very hard to get the big picture. Texinfo might have readers that suck, but other formats don't have readers doing the job at all when we are talking about finding your way in a document of some hundred pages. PDF at the current point of time is about the closest you can come, and it is print-oriented and slow. And it certainly does not offer something like typing i assembl RET in order to jump through the index at the first page referring to assembly language. Like with TeX itself, the scandal is not that decade-old technology is still in use, but rather that nobody has replaced it with anything actually doing the same job, in spite of all the information being freely available and in spite of the old technology being really arcane. Find me an HTML reader that allows keypress-based structured navigation through documents of a few hundred pages, and _then_ talk about Texinfo being supplanted. Heck, _nobody_ likes Texinfo, including myself. It is a stupid format and not remarkably fun to write or understand. It is just that there are no bloody tools doing the same job. After all these years, and in spite of a really terrible standalone reader for the longest time. I can perfectly well understand your lack of enthusiasm. And feel free to call me and the FSF and info and who- and whatever else any name you like (you won't be able to refrain anyhow). But the fact remains that the best way to find some information in the current git documentation is not using HTML. It is not using man, unless you already know what you are looking for. No, currently the _only_ viable search interface into git's documentation as a whole consists of grep and less. And for your favorite "normal user" scapegoat, that sucks even worse than the standalone info reader, let alone Emacs. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
