Re: Have you all gone crazy? Was: On being web-friendly and why info must die

[Paul Eggert]

Yuri Khan wrote:

> the HTML version “feels like” an electronic
> version of a well-typeset printed book. The Info version feels like an
> electronic version of a samizdat book typed on a typewriter.
> *Readability counts.*

This is a fair point.  It's partly because the process we use to generate an 
Emacs distribution still uses Texinfo 4 to generate the info files.  We should 
at least use Texinfo 5, so that the info files have proper quotes, which would 
be an improvement (although, unfortunately, it would not address your other 
points, where our info readers indeed have problems).

> Improving the Emacs display engine might provide a
> better reading experience. But the search scope issue requires an
> all-encompassing Web search engine.

I agree that better use of search engines would be a big improvement.  Others 
have argued in this thread that our manual indexes suffice, but I'm afraid my 
experience is otherwise.

Just today, for example, I needed to come up to speed on how composite glyphs 
work in Emacs, a topic I knew little about; at first I didn't even remember what 
they were.  I hardly ever use the Emacs manuals' indexes due to my 
unsatisfactory past experiences with them, but since they're a current topic of 
discussion in this thread I thought I'd try them again. I went to the Emacs 
manual in info mode and typed 'i composite RET'; the response was "No 
`composite' in index" (complete with those amateurish circa-1980 
not-really-quotes -- "samizdat", I'll have to remember that description :-). 
Since I'm supposedly expert I switched to the for-experts-only Elisp manual and 
typed 'i composite RET', and got sent to an irrelevant page about composite 
types.  In short, the info-mode indexes were utterly a failure for this example. 
 Which isn't surprising, since none of the Emacs manuals talk about composite 
glyphs anywhere.  (I verified this by using other tools, as this was faster than 
using info mode would have been.)

In contrast, Google searches were reasonably helpful.  The search '"composite 
glyph"' quickly got me up to speed on the general topic, and '"composite glyph" 
Emacs' gave me helpful bug reports that let me intuit relevant issues reasonably 
well.

If one prefers a traditional manual, the use-Google approach can be *really* 
annoying, as it tends to throw up all sorts of trash, and I understand the 
annoyance.  Really, I do.  But what can I say?  It often works way better, and 
we should be exploiting this technology rather than limiting ourselves to the 
not-particularly-successful tactic of asking people to send us bug reports and 
fixes for our manuals.