Re: On being web-friendly and why info must die

[Alexis]

David Kastrup writes:

> address@hidden (Phillip Lord) writes:
>
>> I would agree with this. I am, of course, glad that Emacs doc has an
>> index, but in general, indexes are disappearing from documentation,
>> because it's just as easy to search and less effort for the authors.
>
> Just as easy to search?  No.  Less effort for the authors?  Yes.  Search
> becomes fabulously useless where command names are built from common
> words or get frequently referenced elsewhere.

+10. Finding information in the Emacs and Emacs Lisp manuals via the
index is a profoundly pleasant change from my typical
documentation experiences.

>From Emacs, i open the Emacs Lisp Reference Manual /within Emacs/, press
'i', type 'buffer', press RET, and am immediately taken to chapter 26,
"Buffers".

Now contrast that with opening the ELRM in Iceweasel, as a single page,
and then using text search within that page. i use the KeySnail addon
:-), so i press C-s and type 'buffer'. The first match is the link to
chapter 19, "Minibuffers". The next match is in the summary description
of that chapter, "Using the minibuffer to read input." It's the /third/
match that's the link to the "Buffers" chapter.

The gains of manually-tweaked indexes over pure search might seem modest
in this instance, but i've had experiences of trying to search through
/long/ manpages for certain text using nothing but text matching, and
compared to the experience of using the indexes of Emacs documentation,
it's .... rather painful. For example, try accessing the documentation
for the '-vo' option in the manpage for mplayer(1) ....

So, no, i can't agree with the assertion that using search is
necessarily just as easy for end users as using a well-maintained index.


Alexis.