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

[Drew Adams <drew.adams@oracle.com>]

> how composite glyphs work in Emacs...  I went to the Emacs manual
> in info mode and typed 'i composite RET'; the response was "No
> `composite' in index"

To begin with, I would expect that the Emacs manual would be a bad
choice for information about composite glyphs.  (Char composition
is covered briefly in the Emacs manual, and if you type `compos
TAB' then you see candidate `compose character'.  But that's not
the same thing.)

> Since I'm supposedly expert I switched to the for-experts-only
> Elisp manual 

It is not at all for-experts-only.  It is simply the Lisp manual
for Emacs.

> and typed 'i composite RET', and got sent to an irrelevant page
> about composite types.

FWIW, had you typed `compos TAB', that would have been expanded to
`composit', and you would have seen candidates `composition (text
property)' and `composition property, and point display', together
with the irrelevant entry you followed, `composite types
(customization)'.

> In short, the info-mode indexes were utterly a failure for
> this example.

Eggert-mode + info-mode was 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.)

Hm.  They might not cover the information you want, but it's not
true that they do not talk about composite glyphs anywhere.

 `composition'
  This text property is used to display a sequence of characters
  as a single glyph composed from components.  But the value of the
  property itself is completely internal to Emacs and should not be
  manipulated directly by, for instance, `put-text-property'.

But yes, that is not very much info about composite glyphs.

If the info you are looking for is *not in the manuals*,
then it is certainly not a failure of their indexing that
consulting the indexes didn't help you find that info.
That's a no-brainer.

> In contrast, Google searches were reasonably helpful.

No, not wrt the Emacs manual; not per your example.

No one has claimed that the Emacs manuals replace
Internet-wide searches for information about Emacs.
Or that they should or could do that.  Red herring.

It's not about one or the other, manuals vs Internet.
There will always be more information about Emacs on the
Internet than is contained in the Emacs manuals - the
manuals are on the Internet.

> 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.

No one denies that Internet searching is powerful and helpful.
But it didn't help you, in this example, to find something in
the Emacs manuals - something that isn't there.

IOW, hardly a demonstration of the failings of Info indexing.

> 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.

Do you also understand that it's not about a choice *between*
"traditional manual" and "the use-Google approach"?  That's a
false choice.  No one is out to replace googling.

There can be more than one tool in your tool belt, just as
there is more than one book in the library.  Choose both,
not between.

Sticking with the library, your little anecdote is like this
one: I went to the library and looked in the index of a book
for information about TVs.  I didn't find anything about TVs
there.  I even searched every page of that book, but I found
nothing about TVs.  Damn!

Then I asked the librarian for help, and s?he pointed me
(immediately!) to plenty of magazines and books that talk
about TVs.  Clearly that first book's index is total crap -
utterly a failure.

> But what can I say?  It often works way better,

Yes, of course it works better at some things - many things.
Most things.  It indexes the entire web!  Everyday.  Very
well.  That's really not the point.

Is it better at navigating the Emacs manuals?  Is it better
at helping you find information in the Emacs manuals?  Those
are reasonable & interesting questions that might lead to
our improving a user's experience with the manuals.

But arguing that googling is powerful is a waste of time.
And telling us that if you google poorly you can end up 
with noise is also a waste of time.  We all google.
We all know its strengths and weaknesses.

> we should be exploiting this technology

What's your proposition for exploiting the technology?
I exploit it everyday, when I search for things.  Just
what did you have in mind?

Google and other search engines already index our
manuals for full-text search.  You can already use web
search to find information in the manuals.  That's not
a missing feature.

What is missing in the web versions of the manuals has
already been discussed somewhat.  Some of what's missing
could perhaps be provided, even including Info-style
navigation and indexing perhaps.

And even including the feature of *being inside Emacs*,
if you browse and search the web using Emacs.

I don't do the latter, personally.  But if I end up in
the web manual from some Internet search, I do sometimes
copy the node name and then yank it into my local Emacs
manual (Info), for further navigation and investigation.

(That's essentially the manual inverse of what the code
does that I sent a couple days ago, which makes the link
in the other direction, from Info node to web-manual node.)

And I don't move back to Info inside Emacs just because
Info has better navigation and investigation features
for the manuals (for now, at least).  I do it also
because *Emacs is where I want to be* when I am consuming
information about Emacs - because I use the information
with Emacs.

That feature of local Info should also be a no-brainer,
when it comes to the Emacs manuals: you want to *use*
the information about Emacs for Emacs, with Emacs.

> rather than limiting ourselves to the
> not-particularly-successful tactic of asking people to
> send us bug reports and fixes for our manuals.

Again, a strange, black-&-white either-or.  No one has
argued that we should limit ourselves to soliciting bug
reports and fixes for the manuals.

But had you found that there *was* a section of the manual
that covered composite glyphs the way you wanted, and had
you felt it was not easy to find that section using `i',
then I would hope that you would take the time to suggest
an index entry or two for it.

You can do both: file bug reports and search the Internet.