Info-scroll-prefer-subnodes default in Emacs.

Info-scroll-prefer-subnodes default in Emacs.

[Luc Teirlinck]

I am rewriting parts of the Info tutorial.  This took me a little bit
longer than expected, because I had to learn texinfo first (which I
had never used before) and because I checked the entire tutorial for
undocumented differences between the Emacs and stand-alone versions.
I am about ready to send a proposed revision to Karl for review.
Before I can do that however, I feel that the following problem needs
to be addressed.

One of the differences between the Emacs and stand-alone versions is
the behavior of <SPC>.  The tutorial describes the stand-alone
version.  I could try to torture the brains of unsuspecting newbies by
trying to explain them the subtleties of the Emacs version.  However,
I believe that it would make a lot more sense to change the default
Emacs behavior to the stand-alone behavior, by changing the default
value of Info-scroll-prefer-subnodes from t to nil.

Description of the stand-alone behavior:

   <SPC> and <DEL> not only move forward and backward through the
current node.  They also move between nodes.  <SPC> at the end of a
node moves to the next node; <DEL> (or <BACKSPACE>) at the beginning
of a node moves to the previous node.  In effect, these commands
scroll through all the nodes in an Info file as a single logical
sequence.  You can read an entire manual top to bottom by just typing
<SPC>, and move backward through the entire manual from bottom to top
by typing <DEL> (or <BACKSPACE>).

My comments:

Makes sense, is intuitive, easy to understand, and obviously useful.
Perfectly consistent with the usual Emacs behavior of <SPC> in other
read-only documentation-style buffers.

Emacs behavior:

Same a stand-alone, except when menus come in sight.  Then things get
wild.  Then we go to some menu entry.  Surprising enough to newbies.
But which menu entry?

Consider the following part of the dir file:

* CC Mode: (ccmode).   Emacs mode for editing C, C++, Objective-C,
                          Java, Pike, and IDL code.
* CL: (cl).	       Partial Common Lisp support for Emacs Lisp.

With point on the "J" of "Java" where do we go to?  To CL, "of
course".  It might actually make more sense for <SPC> to do that than
for RETURN (which now visits CC Mode) because RETURN is supposed to
visit the node to which the description refers, whereas <SPC> is
supposed to scroll FORWARD and hence visiting CL might make
(relatively) more sense than visiting CC mode.  Might be OK for some
advanced users, but way too complicated and subtle for newbies (as
well as for me, actually).

Throughout Emacs, <SPC> in read-only buffers usually scrolls forward
but does NOT visit "the next thing referenced past point".  

Somebody tries C-h i for the very first time.  Huge dir buffer.  So
the first thing we do is what we are used to do in documentation style
read-only buffers, say NEWS (C-h n), we type <SPC> to browse through
the huge list of entries.  What happened?  Where did we go to and why?

I believe that the obvious thing to do is to change the default value
of `Info-scroll-prefer-subnodes' from t to nil.  Way more transparent
to newbies and eliminates one more difference between the Emacs and
stand-alone versions.  Advanced users who find the more complex
current Emacs behavior more convenient can easily customize the
variable.

Sincerely,

Luc.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Richard Stallman]

The reason SPC has this behavior in Emacs is that it uses the value of
point to keep track of its position in the node structure, for moving through
the subnodes of a given node.  I am a little surprised that SPC can work
right without doing that, but apparently it does.

Does just setting Info-scroll-prefer-subnodes to nil give entirely the
same behavior as in stand-alone info?  If so, let's change that
default.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Luc Teirlinck]

Richard Stallman wrote:

   Does just setting Info-scroll-prefer-subnodes to nil give entirely the
   same behavior as in stand-alone info?

Yes it does.  

   If so, let's change that default.

Should I change the default and write a NEWS entry?  I guess we also
need NEWS entries for kill-whole-line, vis-mode, the new behavior of R
and friends in dired when applied to . and .. (assuming a final
decision was made on that issue, this was not completely clear) and
for Info-hide-note-references which never got mentioned in the NEWS.
I could write NEWS entries for kill-whole-line and vis-mode and, if
desired, for the two other issues.

There is actually one problem, which occurs in indices.  This problem
occurs both in the Emacs and the stand-alone version.  Actually index
menus are "weird" and cause a variety of problems which I will
describe (at least those I actually know of) in this message and the
next.

In emacs Info or stand-alone info do g (emacs)Key Index RETURN.

Now, in Emacs with Info-scroll-prefer-subnodes set to t, SPC
immediately carries us to (emacs)Shell Commands in Dired, the node
referenced by the first Index entry.  Not very useful (at least in my
opinion), but consistent.

With Info-scroll-prefer-subnodes set to nil or in the stand-alone
Info, we first scroll through the index and then go to 
(emacs)Shell Commands in Dired.  It would be more consistent with the
"browse through everything consecutively as if it were one single
document" philosophy if we went to the next node, (emacs)Option Index
instead.

There are related problems.  In Emacs Info, `]' and `[' behave as
usual in Indices.  In the stand-alone version, they do not.  (Just try
to "browse" through the various Emacs manual indices using `]' and `['
in the stand-alone Info.)

There is no easy solution for the problems described in the preceding
two paragraphs and they all have the same cause.

It would be easy to change the behavior of Emacs Info with
Info-scroll-prefer-subnodes set to nil to move through the consecutive
indices in the logical way by borrowing code from the Emacs versions
of `]' and '['.  I would guess that it would not be excessively
difficult to change all involved stand-alone behavior by adopting the
"algorithm" used by Emacs `]' and `[' to determine whether we are in
an index or not.  The problem is that the method used by `[' and `]''
is not a very reliable "algorithm" at all.  To Emacs `]' and `[' we
are in an index if and only if the node name contains the word
"index".  There are plenty of legitimate reasons for a non-index node
name to contain the name "index".  For instance, 
(texinfo)Index Entries is an actual example.  Fortunately this node
does not contain a menu, or Emacs `[' and ']' could have behaved
extremely confusingly in that neighborhood.  A reliable functioning of
Emacs `[' and ']' would require the convention that a non-index node
with a menu should *not* have the word "index" in its name.  This
convention seems to strict.

I believe all the above problems could be easily fixed once one could
answer the following question:

How do we determine reliably whether or not a node is an Index?

I do not believe that the method used by Emacs `[' and `]':
if and only if the node name contains the word "index" is reliable
enough by any means.

Sincerely,

Luc.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Luc Teirlinck]

>From my previous message:

   I believe all the above problems could be easily fixed once one could
   answer the following question:

   How do we determine reliably whether or not a node is an Index?


I noticed, after sending this, in info.el:

;  - a menu item ending with ": " (but not ":: ") is an index entry

If this is considered reliable enough, I could rewrite the Emacs
versions of SPC, [ and ] to check for such menu items in addition to
the node name containing the word "index".  That would solve all
problems I described for the Emacs version.  In that case, somebody
else would need to take care of the stand-alone version.

Sincerely,

Luc.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Luc Teirlinck]

>From my previous message:

   I noticed, after sending this, in info.el:

   ;  - a menu item ending with ": " (but not ":: ") is an index entry

   If this is considered reliable enough, I could rewrite the Emacs

Sorry, sometimes I mail stuff to quickly.  The above does not make any
sense.  ANY menu entry, not just an index entry ends in a colon (even
though Emacs makes it invisible by default).

So please disregard this particular (silly) message.  Sorry.

Sincerely,

Luc.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Richard Stallman]

    I noticed, after sending this, in info.el:

    ;  - a menu item ending with ": " (but not ":: ") is an index entry

This is not reliable.  Any menu can have entries that end in just one
colon.  See info.texi.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Eli Zaretskii]

> Date: Mon, 23 Jun 2003 21:55:03 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> With Info-scroll-prefer-subnodes set to nil or in the stand-alone
> Info, we first scroll through the index and then go to 
> (emacs)Shell Commands in Dired.  It would be more consistent with the
> "browse through everything consecutively as if it were one single
> document" philosophy if we went to the next node, (emacs)Option Index
> instead.

An index is just a giant menu, as far as the Info readers are
concerned.  So they behave as they do with menus; they don't have any
special treatment for indices.

> There are related problems.  In Emacs Info, `]' and `[' behave as
> usual in Indices.  In the stand-alone version, they do not.  (Just try
> to "browse" through the various Emacs manual indices using `]' and `['
> in the stand-alone Info.)

What's wrong with `]' and `[' in the stand-alone Info when you are in
an index?

> How do we determine reliably whether or not a node is an Index?

I don't think you can do that in any way except by looking at the
node's name.  And that's not very reliable, although in many cases it
could do the job.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Luc Teirlinck]

Eli Zaretskii wrote:

   An index is just a giant menu, as far as the Info readers are
   concerned.  So they behave as they do with menus; they don't have any
   special treatment for indices.

The Emacs Info reader does treat indices specially in certain regards.
They should be treated specially for certain purposes, for instance,
because the order of the entries has an entirely different meaning.

   What's wrong with `]' and `[' in the stand-alone Info when you are
   in an index?

For instance, in the current stand-alone Info, `]' visits the first
listed index entry instead of the next index.

Sincerely,

Luc.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Richard Stallman]

    Should I change the default and write a NEWS entry?  I guess we also
    need NEWS entries for kill-whole-line, vis-mode, the new behavior of R
    and friends in dired when applied to . and .. (assuming a final
    decision was made on that issue, this was not completely clear) and
    for Info-hide-note-references which never got mentioned in the NEWS.
    I could write NEWS entries for kill-whole-line and vis-mode and, if
    desired, for the two other issues.

Please write NEWS entries for all of them.

I decided what Dired ought to do, but it has not yet been implemented
I think.

    With Info-scroll-prefer-subnodes set to nil or in the stand-alone
    Info, we first scroll through the index and then go to 
    (emacs)Shell Commands in Dired.  It would be more consistent with the
    "browse through everything consecutively as if it were one single
    document" philosophy if we went to the next node, (emacs)Option Index
    instead.

Yes.

I see two ways to implement that.  One way is to have two kinds of
menus, one that represents the document's structure and one that
doesn't.  The index could say `* Index:' instead of `* Menu:'.  It
would work the same in m but differently in SPC.  Karl, what do you
think?

Another way is to do the index using xrefs instead of menus.

Practically speaking, changing the order of Next pointers so that the
indices come at the end might make things good enough in the Emacs
manual.  It still would not be entirely correct, though.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Karl Berry]

    I believe that the obvious thing to do is to change the default value
    of `Info-scroll-prefer-subnodes' from t to nil.  Way more transparent

FWIW, I agree.  The current emacs behavior has bothered me since it was
introduced.

Thanks,
karl

Re: Info-scroll-prefer-subnodes default in Emacs.

[Miles Bader]

karl@freefriends.org (Karl Berry) writes:
>     I believe that the obvious thing to do is to change the default value
>     of `Info-scroll-prefer-subnodes' from t to nil.  Way more transparent
> 
> FWIW, I agree.  The current emacs behavior has bothered me since it was
> introduced.

Me too (I have it set to nil personally).

I think `space for paging' is ingrained enough that messing with it like
info does is not a good idea.

-Miles
-- 
In New York, most people don't have cars, so if you want to kill a person, you
have to take the subway to their house.  And sometimes on the way, the train
is delayed and you get impatient, so you have to kill someone on the subway.
  [George Carlin]

Re: Info-scroll-prefer-subnodes default in Emacs.

[Karl Berry]

    In Emacs Info, `]' and `[' behave as
    usual in Indices.  In the stand-alone version, they do not.  

That's a bug in standalone info, I'll see if anyone wants to work on it.

    How do we determine reliably whether or not a node is an Index?

    I do not believe that the method used by Emacs `[' and `]':
    if and only if the node name contains the word "index" is reliable
    enough by any means.

I agree, but I don't see any way to do any better at present.

The only real solution I can think of is to have makeinfo insert an
invisible cookie saying `this is an index' into the info file.  That
wouldn't be hard.

Thanks,
k

Re: Info-scroll-prefer-subnodes default in Emacs.

[Karl Berry]

    One way is to have two kinds of
    menus, one that represents the document's structure and one that
    doesn't.  The index could say `* Index:' instead of `* Menu:'.  It
    would work the same in m but differently in SPC.  Karl, what do you
    think?

That sounds like a very clean idea to me, except ...
that new info files then won't be compatible with old Info readers.
We've gone to great lengths to avoid such incompatibilities in the past.

My idea along these lines was not as elegant, but it retains
compatibility: have makeinfo output a magic cookie (say ^H^[index^H^],
for the sake of argument, similar to the new cookie we use for images)
at the beginning of an index.  New info readers will recognize that, not
display it, and do the right thing.  Old info readers will display it,
which is ugly but not fatal -- the index entries would still work.

    Another way is to do the index using xrefs instead of menus.

Seems more verbose.

Re: Info-scroll-prefer-subnodes default in Emacs.

[Richard Stallman]

	One way is to have two kinds of
	menus, one that represents the document's structure and one that
	doesn't.  The index could say `* Index:' instead of `* Menu:'.  It
	would work the same in m but differently in SPC.  Karl, what do you
	think?

    That sounds like a very clean idea to me, except ...
    that new info files then won't be compatible with old Info readers.
    We've gone to great lengths to avoid such incompatibilities in the past.

    My idea along these lines was not as elegant, but it retains
    compatibility: have makeinfo output a magic cookie (say ^H^[index^H^],
    for the sake of argument, similar to the new cookie we use for images)
    at the beginning of an index.

That seems like a good idea.