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

[Eli Zaretskii]

> Date: Mon, 22 Dec 2014 12:25:19 +0700
> From: Yuri Khan <address@hidden>
> Cc: Eli Zaretskii <address@hidden>, Tom <address@hidden>, 
>       Emacs-Devel devel <address@hidden>
> 
> I use Google to search for information about Emacs, unless I know
> exactly what I’m looking for.

That's a mistake.  The Info's 'i' command is precisely the means to
use when you do NOT know exactly what you are looking for.  I urge you
to try that next time: at 'i's prompt type some word or phrase that
you think relates to the subject you are after, and see what happens.
You can also use TAB to see possible completions, once you've typed
some part of the subject.  If the first hit is not what you want, type
',' to see more hits.

The Info manuals are indexed up front with this usage pattern in mind,
and you'd be surprised how efficient this search can be.  Well, with
good manuals, anyway.  (Emacs manuals are good.)  We add index entries
all the time to continuously improve the indexing.

> On the other hand, when my question is more like “How do I <do X> in
> Emacs”, I’m not specifically looking for a page in the Emacs manual.
> Rather, I want a page in the manual, plus a range of ways how other
> people do X, and a range of opinions on why X is the wrong thing to
> want to do. Google gives me that. Info doesn’t. *By searching with
> Google, I extend the scope of my search beyond the Emacs manual.*

You also get a load of crap.  Just sifting through all that trying to
make up your mind what is true and what's wrong will take you on a
small research trip.

Instead, start with looking up the subject in the manual, using the
'i' command and the hyper-links in the nodes where 'i' takes you.
_Then_, after you know what the manuals say, by all means use Google
or some other search engine to expand your knowledge.  The difference
is that you no longer need to find the documentation itself, just how
the feature is used and what are its alternatives (some of that is
also in the manual, btw).

> Additionally, the HTML rendition of the Emacs manual is more
> convenient to read for me, because of these differences:
> 
> * The HTML version wraps to the size of my browser. The Info version
> is hard-wrapped for 72 columns.

I encourage you (or anyone else) to enhance info.el, which will remove
or hide the newlines from the explanatory text, and then use word-wrap
and wrap-prefix to get the same effect as you see in HTML browsers.
(Not that I understand why it would be more readable to have the
description in 200-column lines, but if someone wants such a feature,
why not?)  The only not-entirely-trivial part here is to identify the
lines where the newlines should be kept, like examples, list items,
etc.  But there are enough clues in the text to identify those, in the
same manner as we identify the section headings.

> * The HTML version uses my preferred proportional font for prose and
> my preferred monospace font for code. The Info version is monospace
> throughout, except for headings.

Likewise: should be easy to do this for Info.  Patches are welcome.

> * The HTML version uses text styles to highlight different kinds of
> text (keys, commands, paths, arguments, etc.). The Info version uses
> the spacing grave accent and the straight single quote and all-caps
> formatting.
> * The HTML version uses typographic quotes “”. The Info version uses
> straight quotes "".

Some of this is simply untrue nowadays, I guess you haven't looked at
an Info manual for a few years.  The rest (like using CAPS for
arguments) is again not too hard to teach Info to do.  Once more,
patches welcome.

> To summarize the above, 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.*

If this is an itch to scratch, I invite you and others to scratch it.
Should be a fine project, and not a hard one, either.  Volunteers are
welcome.

> * Firefox provides pixelwise autoscrolling on middle mouse button, and
> opens links in new tabs when middle-clicked. Emacs Info has no
> pixelwise scrolling

Emacs does support pixelwise scrolling, you can see it in action when
scrolling a large image or very large text.  Making this work for
"normal" text is not hard, it's just that no one did it.  Again,
volunteers are welcome.  (I can provide hints and help on this one, if
necessary.)

> no autoscrolling

Not sure what that means.  Emacs certainly auto-scrolls when point
enters the scroll-margin.

> and prefers to have no more than one *info* buffer.

Not true.  I have between 40 and 50 *info* buffers in my Emacs session
at any given time (I wrote the info-display-manual command to help me
manage them efficiently), and see no problems with that.

> Replacing the Info output format with HTML and replacing the Emacs
> Info browser with an Emacs HTML-Info browser might help with the
> readability issue.

As was written many times here, HTML-Info browser you are talking
about doesn't exist.  It needs to be coded first.  Existing HTML
browsers lack a few important features, they were identified in these
discussions.  It is not useful to compare a live, working program with
an _idea_ of a program.  It certainly makes no sense to claim the idea
is much better than the program.

> Improving the Emacs display engine might provide a better reading
> experience.

The Emacs display engine doesn't need to be improved to support the
features you miss.  What we need is motivated individual(s) who would
sit down and code this in Lisp using _existing_ features.  I hope you
will be that volunteer, or that someone else will come soon, because
frankly, I enjoy much more seeing Emacs improve and helping others
improve it than talk-talk-talk about that.

> But the search scope issue requires an all-encompassing Web search
> engine.

I suggest to give another chance to the Info's 'i' command.  You might
even like it.  If the initial experience is not good enough, come back
and tell why, maybe we could help; after all, using Google efficiently
also takes some practice.  (FWIW, I usually land right on the spot
using 'i' on my first attempt, sometimes the second, and it's not
because I remember all the index entries by heart, far from it.)

Please note that I never said Info is a replacement for searching the
net.  That is a red herring.  What I am saying is that whenever you
need accurate information about some Emacs feature, you should first
look up its description in the manuals.  Then, armed with that
knowledge, go search the net for more info, if you need to.  Most
probably your Google query will be different if you follow this
paradigm.

Btw, if you, or someone else, are ambitious, I can suggest a larger
and more challenging project: add a front end to Info's search
capabilities that can accept queries in more-or-less natural language,
not unlike Google.  Examples of such queries:

  . "how do I do SOMETHING?"
  . "what is THAT-THING?"
  . "look for SUBJECT but excluding THIS-CRAP"

etc.  Bonus points for maintaining a database of user-specific
preferences and personal style of queries, and applying that to future
queries.

Interested?