Info tutorial is out of date

Info tutorial is out of date

[Drew Adams]

I just tried the beginning of the Info tutorial again, after a lapse of a
couple decades (!). It doesn't seem to have changed much. I remembered it
with more fondness than I felt this time around. Keep in mind that, like
Info, it was created long before the Web and mice and such. Back around that
campfire, it made sense to explain in detail about nodes and menus and the
magic keys you used to get around. Nowadays, some of it seems quaint, some
seems crippling.

Here's my rant; take it for what you will. Hope it helps somehow.

The start of the tutorial teaches you `n', then `p', then `m', then `C-l',
and so on. Those keys should be regarded nowadays as shortcuts - quick
alternatives to the obvious navigational equivalents of clicking links or
using the menu-bar menu. Don't forget that the user somehow got into the
Info tutorial with no help - probably by clicking the link at the `dir'
node.

I don't even see why `C-l' is mentioned anymore, especially at the very
beginning of the tutorial. It was important back when 14K baud was a fast
transmission speed and your screen got "garbaged" (to quote the tutorial)
from time to time. You needed to learn `C-l' at the beginning, because if
your screen got garbled then you were lost in the tutorial - that was a game
in itself (much more interesting than invisible text). `C-l' is just a
vestige of the bad-ole-days - lose it.

With absolutely no instruction, a user will figure out immediately how to
move among nodes - the equivalent of `n', `p', `u', and `m', because they
*see* the corresponding links and buttons. Clicking links and buttons is a
fine way to get around, to get the info you need - at least in the
beginning. Teaching `n' and `p' does not need to take up the first several
minutes of the tutorial - it should be presented much later, perhaps in a
(brief) lesson on keyboard shortcuts.

It's OK at some point to point out that, unlike Web pages but like the
structure of a book, Info nodes are organized into a tree (menu): up, next,
and so on. But a lite version of that explanation will suffice, nowadays.
Again, all this emphasis on navigation commands is but a vestige of a time
when there were no links or buttons, when the universe was still a mouseless
void.

What it *is* important to teach up front are the important functionalities
of Info that are *not* so obvious (visible). Foremost among these are `i',
`s', and `l' (and, later, `g').

The first thing the tutorial should do is take a tour of the menu-bar menu -
that is, those menu items that are the most important. This is also the
opportunity to point out the key bindings indicated in the menu. That is the
way to introduce the shortcuts `i', `s', and `l', for instance - in passing.

Touring the menu can also be used to introduce the structure of a normal
Info manual. By that, I don't mean menus with up and next, so much as
showing that there is a table of contents (or two or three) and an index,
and how to use them effectively. And if the Info manual had a glossary (it
should, especially since it has its own jargon), then that could be
introduced too.

Users will also find the toolbar by themselves, and they may use that first
for some things (such as index lookup), because it is more obvious than the
menu-bar menu. It's worth taking a tour of the menu because it shows the
keyboard shortcuts, which the toolbar icons do not. Showing the menu-bar
menu and its shortcuts will help wean newbies from the toolbar, at least in
terms of awareness.

BTW, the help text (tooltip) for the search toolbar icon should not scare
people away by mentioning regular expressions. It should say simply `Search
the manual'. If you don't think that's enough, then it could say `Search the
manual (regexp is OK)'. None of the tooltips should use the word "file" -
they should say "manual". And we should think about changing the keyword
`File:' at the top of each node to `Manual:' - there is no reason that users
should think in terms of files here.

I'll say one more time, in passing, that an icon for deletion (X) should not
be used for quitting Info - that is a bad idea. Several other possibilities
were suggested previously (e.g. the international icon for an exit: arrow
exiting a room), and there are lots of quit icons to choose from. But that
particular X is often used for deletion, a confusion we don't want here.

The Info tutorial itself should be accessible (listed) in the menu of the
first node of the Info manual. Instead, it is only mentioned in the text of
that node, in terms of `h'. Before entering the tutorial, we should tell
users how to exit it, to get back where they were. BTW, `h' should not bring
up the tutorial, it should display a mini-version of what `C-h m' shows: a
short list of the main key bindings - about the same as what's in the
menu-bar menu, but with some explanation. There is no need to have a key
binding just to bring up the Info tutorial - people won't be doing that 30
times a day.

In general (exceptions can be made), key bindings should not be introduced
until much later, and then they should be introduced as shortcuts for
functionalities the user already knows by then. It is the functionalities
that should be on the agenda, not the keys. The emphasis is all wrong in
this respect. You lose the forest of functionalities because of all the
trees of keys.

The node `Invisible text in Emacs Info' is incomprehensible to me
("invisible text is really a part of the text"!?). Yow! Why are we telling
users about killing and yanking Info text? (I guess printing is OK.) Why is
this near the beginning of the tutorial? I really, really do not get this.

This node (`Help-Inv') will scare anyone away from using Info. It is worse
than unneeded; it is a downright nuisance. 3/4 of it is  composed of crazy
disclaimers that users won't understand ("Only the invisibility property is
affected by Visible mode" (yow!), and "When, in this tutorial, we refer to
the `Emacs' behavior, we mean the _default_ Emacs behavior" (YOW!!)). BTW,
what is the reason for the menu in this node? It doesn't seem to be used or
useful or understandable.

The rule in the tutorial should be that we don't tell people things - we
walk them through doing things. Node `Help-Inv' is not just confusing and
useless; it also violates this rule. If it were really important for users
to know about `visible-mode' and such, then the tutorial should walk them
through using it. But in this case, please don't; just get rid of this node!
This appears to be an ugly hack to enable the same tutorial to be used in
Emacs and standalone Info. Spare the user this kind of all-too-visible
bandaid.

In general, instead of introducing so many key bindings (e.g. `]'), the
tutorial should spend the user's time taking a tour of Info *functionality*.
Touring the menu-bar menu is a good way to explore the main functionalities:
show what's there and what it does. In addition to the features in the
menu-bar menu, teach SPC and DEL - that's about it. In the menu-bar menu,
teach these first: `q', `l', `s', and `g'. Why? because they're not obvious
(visible, as in links and buttons), and they're essential.

Most of what is presented now in the tutorial is either obvious or arcane.
The most important things to teach are index lookup and search. They should
be done with care, and simple regexp search can be taught here with useful
examples. It's good to teach `goto-node' (`g') too, because people will find
instructions in emails and on Web sites to go to node `Blah'.

Perhaps some of my remarks are inappropriate wrt the standalone reader - I
don't know. I used the tutorial only inside Emacs. Adjust my remarks as
needed. If the standalone Info still uses only keyboard keys, so that
everything I suggested above is irrelevant, then perhaps we need two
different tutorials now.

HTH.

Re: Info tutorial is out of date

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

[...]

> In general (exceptions can be made), key bindings should not be
> introduced until much later, and then they should be introduced as
> shortcuts for functionalities the user already knows by then. It is
> the functionalities that should be on the agenda, not the keys. The
> emphasis is all wrong in this respect. You lose the forest of
> functionalities because of all the trees of keys.

I disagree with most of your posting.  Mouse navigation remains an
inefficient crutch compared to keys.  It is somewhat efficient for
exact cursor positioning, but that still requires letting go of the
keyboard.  Using info efficiently entails using the keys.  Of course,
this is doubly important on ttys or for disabled people, but in any
case there is absolutely no sane rationale for futzing around with
scroll bars when the space bar is fully accessible.

And most scroll bars don't even allow you changing the direction of
scrolling without having to move the mouse

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: Info tutorial is out of date

[Drew Adams]

    > In general (exceptions can be made), key bindings should not be
    > introduced until much later, and then they should be introduced as
    > shortcuts for functionalities the user already knows by then. It is
    > the functionalities that should be on the agenda, not the keys. The
    > emphasis is all wrong in this respect. You lose the forest of
    > functionalities because of all the trees of keys.

    I disagree with most of your posting.

I figured someone would ;-). The tutorial might have gotten where it is
mostly out of neglect, but I figured there might also be some active forces
involved. Someone wrote node `Help-Inv' (should be named `Invisible-Hell')
fairly recently, for example. Anyway, there's room for disagreement; it's
really I who's disagreeing with the status quo, after all.

    Mouse navigation remains an inefficient crutch compared to keys.

Generally true. We're on the same team here - I have no stock in mice (or
anything else, unfortunately).

The point is to ease the learning of Info. The most important thing to learn
is what Info is, what it has to offer, what you can do with it, why you
should be interested in it - that is, its *features*, not how you can most
efficiently use those features. *What* first, with an easy-learning-curve,
super-simple, obvious *how*, to help introduce the *what*. More efficient
*how* learning later, if at all.

If you want, the tutorial could be split in two: first "What Info Is" (with
simple how-to, to get the points across), second "How To Use Info
Efficiently". My point is this: first things first. If I don't understand
what Info is all about, why would I go through the effort of learning and
practicing its key bindings? I have nothing against recommending that one
learn to use keys for efficiency, but let's first get the main point across.

    It [mouse] is somewhat efficient for
    exact cursor positioning, but that still requires letting go of the
    keyboard.  Using info efficiently entails using the keys.

This is about learning - in particular learning what Info is, what it is
for, how it is laid out/structured, how to find information with it.

    Of course, this is doubly important on ttys or for disabled people,

Huh? Want to bet whether disability is better served by a single-point
device or a keyboard full of keys and chording? Of course, it can depend on
the disability. Think of all the jokes when the mouse first came out, about
how it was designed for a one-armed person with one finger. Using a full
keyboard, and chording especially, is hardly for everyone.

But really, if we're already reaching to the "disabled" to bolster an
argument here, then we're reaching for straws. The point is not about which
interaction with Info is most efficient for which group of people on which
equipment; it is about how to teach what Info is all about, how to give
people an initial access to the manuals (which is what Info is for), how to
get them comfortable with Info and have them see how it can be useful to
them.

People find their own preferred ways to interact with programs and
equipment, and it's easy enough to find the keys that you and I both
promote.

I mentioned two ways those keys can be made more visible (more visible than
trudging through the current tutorial): 1) have `h' show a short list of key
bindings with one-line descriptions, 2) the menu-bar menu shows key bindings
at a glance. Both of these give an *overall* view of the important key
bindings, and they provide quick reminders. (`h' would mention SPC and DEL
also, which the menu-bar menu doesn't show.)

I also mentioned the need to have specific tutorial instruction for those
keys (e.g. SPC and DEL) that are *not* so obvious. Teaching `n' right away
is a waste of time, not because `n' is useless, but because there is an
obvious (if perhaps somewhat slower) way to do the same thing. The point is
to get quickly to the point, not to spend time teaching how to use the
keyboard.

As to the fingers-leaving-the-keyboard argument: That is not such a strong
argument for Info, where people are reading, not editing. Yes, using the
keyboard for SPC and DEL has no mouse equivalent (AFAIK); otherwise, you can
get by about as fast with the mouse as with keys, in Info. But I won't try
to win that argument, because it is not an important argument - what's
important is the argument over what we're trying to teach.

You know, touch typing is also much more efficient than (the "inefficient
crutch" of) pecking with one finger (though I've seen cases to the
contrary!). Should we start the Info tutorial with a lesson in touch typing,
because it is more efficient? This is about *getting information*; it's not
about teaching the fastest way to do that - that can come later.

    but in any
    case there is absolutely no sane rationale for futzing around with
    scroll bars when the space bar is fully accessible. And most scroll
    bars don't even allow you changing the direction of
    scrolling without having to move the mouse

Excuse me? Did someone mention scroll bars in this context? What is that all
about?

On the contrary, didn't I say that SPC and DEL should be taught explicitly
(and early) in the tutorial, because they are not obvious (visible)? What
are you talking about wrt scroll bars?

Here's my criticism, in a nutshell:

1) teach what Info is about, first;

2) start using the obvious how-to (e.g. links, buttons, menu-bar), to teach
#1;

3) teach the non-obvious how-to (e.g. SPC, DEL) also;

4) don't bother teaching the obvious, if more-efficient, how-to (e.g. `n'),
except possibly as an efficiency booster, after getting the real message
across.

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> when the universe was still a mouseless
> void.

i have no mouse attached (under X), you insensitive clod.

primordially yours,
thi

Re: Info tutorial is out of date

[Alan Mackenzie]

Hi, Drew!

It doesn't seem to be your evening for "me too!" answers.  ;-)

On Sat, Jul 15, 2006 at 07:44:42AM -0700, Drew Adams wrote:

[ .... ]

> Here's my rant; take it for what you will. Hope it helps somehow.

> The start of the tutorial teaches you `n', then `p', then `m', then
> `C-l', and so on. Those keys should be regarded nowadays as shortcuts
> - quick alternatives to the obvious navigational equivalents of
> clicking links or using the menu-bar menu. Don't forget that the user
> somehow got into the Info tutorial with no help - probably by clicking
> the link at the `dir' node.

`n' and `p' are not shortcuts - they're the prime method of using the
functions.  Rather, the mouse equivalents should be regarded as ambages.

[ .... ]

> With absolutely no instruction, a user will figure out immediately how
> to move among nodes - the equivalent of `n', `p', `u', and `m',
> because they *see* the corresponding links and buttons.

I've just put up this tutorial.  I don't see these links and buttons.

> Clicking links and buttons is a fine way to get around, to get the
> info you need - at least in the beginning. Teaching `n' and `p' does
> not need to take up the first several minutes of the tutorial - it
> should be presented much later, perhaps in a (brief) lesson on
> keyboard shortcuts.

Not every setup has mouse ambages.  Mine doesn't.  Neither will every
beginner's.  `n' and `p' are thus important, and should be described
first.

> It's OK at some point to point out that, unlike Web pages but like the
> structure of a book, Info nodes are organized into a tree (menu): up,
> next, and so on. But a lite version of that explanation will suffice,
> nowadays.  Again, all this emphasis on navigation commands is but a
> vestige of a time when there were no links or buttons, when the
> universe was still a mouseless void.

Parts of the universe are still mouseless.

> What it *is* important to teach up front are the important functionalities
> of Info that are *not* so obvious (visible). Foremost among these are `i',
> `s', and `l' (and, later, `g').

> The first thing the tutorial should do is take a tour of the menu-bar menu -
> that is, those menu items that are the most important. This is also the
> opportunity to point out the key bindings indicated in the menu. That is the
> way to introduce the shortcuts `i', `s', and `l', for instance - in passing.

What's a menu-bar?  My Emacs setup hasn't got one (whatever it might
be ;-).  I would suggest that, perhaps, some of the current turgidity of
the tutorial could be superseded with sentences like "if you are on a
WIMP system, you can also get .... by clicking ... with the
\(left\|middle\|right\) mouse button."

> Touring the menu can also be used to introduce the structure of a normal
> Info manual. By that, I don't mean menus with up and next, so much as
> showing that there is a table of contents (or two or three) and an index,
> and how to use them effectively. And if the Info manual had a glossary (it
> should, especially since it has its own jargon), then that could be
> introduced too.

> Users will also find the toolbar by themselves, ....

What's a tool-bar?  My set-up hasn't got one (whatever it might be ;-)

[ .... ]

> In general (exceptions can be made), key bindings should not be introduced
> until much later, and then they should be introduced as shortcuts for
> functionalities the user already knows by then. It is the functionalities
> that should be on the agenda, not the keys. The emphasis is all wrong in
> this respect. You lose the forest of functionalities because of all the
> trees of keys.

That's gorgeous alliteration.  :-)

However, not all Emacs setups have mouses.  One of the prime
attractivenesses of Emacs for me is being able to use it on a plain
character screen without it being cluttered up with window borders,
mice, scroll-bars, menus, task-bars, wine-bars, tool-bars, crow-bars,
and what ever else glaziers might conjure up.  Judging by the occasional
exchange on the newsgroups, I'm far from alone.

There's a general principle in Emacs, tacit though it may be, that ALL
actions in ALL modes can be performed solely by keyboard, with the
exception of those few things which are essentially non-textual.  EVERY
Emacs setup has a working keyboard.  IMAO, we should not imply that tty
users are somehow inferior, or wierd, or a pain in the backside (even if
they're true ;-).  We should carry on describing Info operations in
terms of key presses, giving mouse ambages parenthetically.

> The node `Invisible text in Emacs Info' is incomprehensible to me
> ("invisible text is really a part of the text"!?). Yow! Why are we telling
> users about killing and yanking Info text? (I guess printing is OK.) Why is
> this near the beginning of the tutorial? I really, really do not get this.

Er, I have to agree here.  I've never seen any invisible text in Info.
Info-hide-note-references is unbound.  Maybe I should fire up Emacs 20
(or 19.34?) to see what this meant.

[ .... ]

But looking at this tutorial, I too think it could do with a little
sprucing up.

> HTH.

-- 
Alan Mackenzie (Munich, Germany)

Re: Info tutorial is out of date

[martin rudalics]

> Er, I have to agree here.  I've never seen any invisible text in Info.

... isn't the purpose of invisible text that it can't be seen?

RE: Info tutorial is out of date

[Drew Adams]

    i have no mouse attached (under X), you insensitive clod.
    
Do we need to call each other names?

RE: Info tutorial is out of date

[Drew Adams]

    > Er, I have to agree here.  I've never seen any invisible text in Info.
    
    ... isn't the purpose of invisible text that it can't be seen?
    
Nah; that's a side effect. The purpose is to be sneaky.

RE: Info tutorial is out of date

[Drew Adams]

    `n' and `p' are not shortcuts - they're the prime method of using the
    functions.  Rather, the mouse equivalents should be regarded as ambages.

Another in the Mouseless-That-Roared camp, eh? A small, but very vocal and
militant minority, apparently. Vent against he who seems to speak for the
lousy moused masses of nasty newbies. It's OK; I can take it; I have to, for
the noobs' sake ;-).

Next week I'll do battle with those (even more ferocious) who hold that only
UPPERCASE characters are pure, clear, truthful, and sufficient; lowercase
being but a lying distraction designed to take our focus off the true aim of
STRUGGLE against the dominance of MongrelMulattoMixedCharacterism. Compared
to the luddite lowercasians, the mighty mouseless are a small piece of cake
(or is it cheese?).

The point is that we do not *have* to teach people how to get to next and
previous nodes (provided they have a mouse, which most users do [OUCH!]).
That is advertised at the top of the buffer with big blazing buttons. It's
just, well, brain-dead obvious. If you blindfold yourself, then you might
need a tutorial to help you get through the living room, but if you turn
`blindfold-mode' OFF... it hurts a lot less.

We certainly don't need to spend the first several minutes of the tutorial
on `n' and `p', even for the mouseless. For the moused, we can teach `n' and
`p' later, after they know what Info is all about. (Hint: it is not about
`n' or `p'; it has something to do with finding `Info'rmation.)

    > With absolutely no instruction, a user will figure out immediately how
    > to move among nodes - the equivalent of `n', `p', `u', and `m',
    > because they *see* the corresponding links and buttons.

    I've just put up this tutorial.  I don't see these links and buttons.

I see them, using emacs -q. I see them in Emacs 20, 21, 22. In Emacs 20 and
21, I don't see the toolbar (SMTB, BTW), but I see the Next and Previous
buttons, and I see Next and Previous in the Info menu-bar menu. Maybe I'm in
a parallel universe; yes, that's it: I've been m-m-mmoused!

    > Clicking links and buttons is a fine way to get around, to get the
    > info you need - at least in the beginning. Teaching `n' and `p' does
    > not need to take up the first several minutes of the tutorial - it
    > should be presented much later, perhaps in a (brief) lesson on
    > keyboard shortcuts.

    Not every setup has mouse ambages.  Mine doesn't.

Ah, so that's why you don't see the Info menu or the Next and Previous
buttons. Someone cut off Little Mousey.

    Neither will every beginner's. `n' and `p' are thus important, and
    should be described first.

Perhaps not every beginner. Perhaps only 99.99% of them. Exaggeration? Or is
it more like 1/100,000? Let's be generous: 90% have a mouse. Just a guess,
but we could place bets (no fair looking first). Oops, all bets are off - I
couldn't resist looking...
http://www.answers.google.com/answers/threadview?id=334862 ('course that's
by a group that's obviously part of the Mouse conspiracy - hmphf!).

Being generous, I'd support having two versions of the tutorial, or a single
version that works for both the moused (90%) and the unmoused (10%, but very
important). If we can show/no-show buttons, then we can no doubt
show/no-show an introductory crutch node that teaches the mouseless how to
`n' and `p', so they can get to the heart of the tutorial along with the
rest of the party.

The real point is that the emphasis of the tutorial is not sufficiently on
what Info is for. Teach what first, and how second.

    > It's OK at some point to point out that, unlike Web pages but like the
    > structure of a book, Info nodes are organized into a tree (menu): up,
    > next, and so on. But a lite version of that explanation will suffice,
    > nowadays.  Again, all this emphasis on navigation commands is but a
    > vestige of a time when there were no links or buttons, when the
    > universe was still a mouseless void.

    Parts of the universe are still mouseless.

Part of the universe might use Emacs on a cell phone or an IPod too, or (who
knows?) on a Cap'n Crunch whistle. And, in part of the universe, people use
screen readers instead of screens.

We can adapt the tutorial to hit a wide audience, without sacrificing the
aim (to teach what Info is about) and the lesson structure that most
naturally follows that aim.

    > What it *is* important to teach up front are the important
    > functionalities of Info that are *not* so obvious (visible).
    > Foremost among these are `i', `s', and `l' (and, later, `g').

No comment here? That's the main message of my post. That's the main problem
I saw with the tutorial. Arguments about mouse or no mouse are a sideshow
(but very important to the mouseless - don't get me wrong; I'm really not an
"insensitive clod" - a clod, maybe).

    > The first thing the tutorial should do is take a tour of the
    > menu-bar menu - that is, those menu items that are the most
    > important. This is also the opportunity to point out the key
    > bindings indicated in the menu. That is the way to introduce
    > the shortcuts `i', `s', and `l', for instance - in passing.

    What's a menu-bar?  My Emacs setup hasn't got one (whatever it might
    be ;-).  I would suggest that, perhaps, some of the current turgidity of
    the tutorial could be superseded with sentences like "if you are on a
    WIMP system, you can also get .... by clicking ... with the
    \(left\|middle\|right\) mouse button."

Suggestion recorded, for posterity. The mouseless who inherit the Earth will
erect a monument.

What do you suggest about getting the tutorial to teach about Info? Nothing
to say about that?

    > Touring the menu can also be used to introduce the structure
    > of a normal Info manual. By that, I don't mean menus with up
    > and next, so much as showing that there is a table of contents
    > (or two or three) and an index, and how to use them effectively.
    > And if the Info manual had a glossary (it should, especially
    > since it has its own jargon), then that could be
    > introduced too.

Nothing to say about that? What do you suggest about the TOC, Index,
Glossary?

    > Users will also find the toolbar by themselves, ....

    What's a tool-bar?  My set-up hasn't got one (whatever it might be ;-)

SMTB, IMO, but it's a shame you had to amputate Little Mousey to achieve
that level of ascetic enlightenment. You don't get nothing without losing
something, I guess.

    > In general (exceptions can be made), key bindings should not
    > be introduced until much later, and then they should be
    > introduced as shortcuts for functionalities the user already
    > knows by then. It is the functionalities that should be on the
    > agenda, not the keys. The emphasis is all wrong in this respect.
    > You lose the forest of functionalities because of all the
    > trees of keys.

    However, not all Emacs setups have mouses.  One of the prime
    attractivenesses of Emacs for me is being able to use it on a plain
    character screen without it being cluttered up with window borders,
    mice, scroll-bars, menus, task-bars, wine-bars, tool-bars, crow-bars,
    and what ever else glaziers might conjure up.  Judging by the occasional
    exchange on the newsgroups, I'm far from alone.

Yes, you are a small, but tight-knit group. Likewise, the
crownonebarbarians.

    There's a general principle in Emacs, tacit though it may be, that ALL
    actions in ALL modes can be performed solely by keyboard, with the
    exception of those few things which are essentially non-textual.

Gee, did someone propose to take away `n'?  Aux barricades !

    EVERY Emacs setup has a working keyboard.

Did some grinch try to snatch all the keyboards?  Le Pere Noel est une
Ordure !

    IMAO, we should not imply that tty users are somehow inferior,
    or wierd, or a pain in the backside (even if they're true ;-).

Mousequeteers might be even wierder and more inferior. They are, however,
the big, fat, ugly *majority* of users - and of noobs, in particular (99%?
99.9999%?). The tutorial is for the noobs (!) - you heard me utter it. The
tutorial is for the NOOBS. And they shall be Told of `n', but that shall not
be the First Word they shall hear.

    We should carry on describing Info operations in
    terms of key presses, giving mouse ambages parenthetically.

Nah!

    > The node `Invisible text in Emacs Info' is incomprehensible to me
    > ("invisible text is really a part of the text"!?). Yow! Why
    > are we telling users about killing and yanking Info text? (I
    > guess printing is OK.) Why is this near the beginning of the
    > tutorial? I really, really do not get this.

    Er, I have to agree here.  I've never seen any invisible text in Info.
    Info-hide-note-references is unbound.  Maybe I should fire up Emacs 20
    (or 19.34?) to see what this meant.

I think it's about standalone vs Emacs for Info. The standalone crowd
wrestled this concession from the Great GNUBIE perhaps. I'm worried about
when the 'Pod users strike.

    But looking at this tutorial, I too think it could do with a little
    sprucing up.

So let's spruce it.

RE: Info tutorial is out of date

[Drew Adams]

I said:

    Let's be generous: 90% have a mouse. Just a guess,
    but we could place bets (no fair looking first). Oops, all bets
    are off - I couldn't resist looking...
    http://www.answers.google.com/answers/threadview?id=334862

    ... the moused (90%) and the unmoused (10%)...

That's a bit misleading; sorry. The study cited only said that 90% of those
studied used the mouse heavily every day. It didn't say what percentage
*have* a mouse. 99%? 99.999%?

Here's some more from the study, FYI:

 - "80% used desktop computers (n=63,319), 9% used laptops (n=7846)
   and 11% used both desktop computers and laptops (n=8463)."

 - "the mouse was used with desktop computers at 97% of organisations
   surveyed. At 73% of these organisations, all desktop users used the
mouse.

 - "the mouse was used with laptop computers at 64% of organisations
   surveyed. At 31% of organisations, all laptop users used a mouse"

 - "the majority (90%) use a mouse on a daily basis, operating the device
   with their right hand"

 - "...mice with 2 buttons (67% of workplace assessment interviewees and
   85% of user questionnaire respondents) although 3-button mice were
   also quite common (20% of workplace assessment interviewees and 10%
   of user questionnaire respondents)"

Re: Info tutorial is out of date

[Jorgen Schaefer]

Alan Mackenzie <acm@muc.de> writes:

> Not every setup has mouse ambages.  Mine doesn't.  Neither will every
> beginner's.  `n' and `p' are thus important, and should be described
> first.

The reason to teach keyboard commands is not because some people
don't have rodents on their desks. It is not due to legacy reasons
or the lack of rodents that most Emacs users seem to prefer
keyboard commands. The reason is that keyboard navigation is fast
and efficient. It is important to teach useful interactions to
users.

Regards,
        -- Jorgen

-- 
((email . "forcer@forcix.cx") (www . "http://www.forcix.cx/")
 (gpg   . "1024D/028AF63C")   (irc . "nick forcer on IRCnet"))

Re: Info tutorial is out of date

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     `n' and `p' are not shortcuts - they're the prime method of
>     using the functions.  Rather, the mouse equivalents should be
>     regarded as ambages.
>
> Another in the Mouseless-That-Roared camp, eh? A small, but very
> vocal and militant minority, apparently.

It does not give you any thoughts that from your "majority", you are
the only one to speak up?

> The point is that we do not *have* to teach people how to get to
> next and previous nodes (provided they have a mouse, which most
> users do [OUCH!]).  That is advertised at the top of the buffer with
> big blazing buttons. It's just, well, brain-dead obvious. If you
> blindfold yourself, then you might need a tutorial to help you get
> through the living room, but if you turn `blindfold-mode' OFF... it
> hurts a lot less.
>
> We certainly don't need to spend the first several minutes of the
> tutorial on `n' and `p', even for the mouseless. For the moused, we
> can teach `n' and `p' later, after they know what Info is all
> about. (Hint: it is not about `n' or `p'; it has something to do
> with finding `Info'rmation.)

The mouse can only be used for the most important functions as a
fallback.  It does not make sense in a tutorial to focus on the less
important functions first.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Info tutorial is out of date

[Richard Stallman]

    If you want, the tutorial could be split in two: first "What Info Is" (with
    simple how-to, to get the points across), second "How To Use Info
    Efficiently".

That is a good idea, in a general sense.  However, I am not sure
it is really necessary, for the reason below.

		  My point is this: first things first. If I don't understand
    what Info is all about, why would I go through the effort of learning and
    practicing its key bindings?

Isn't it obvious to everyone what Info is all about?  It's all about
browsing documentation files.  Menus, and moving up, moving thru a
series using next and previous, are going to be obvious to anyone that
has used the WWW very much.

Thus, practically speaking, I think there isn't much to be achieved by
having a separate easier section which just teaches you "what Info is
all about".

    I also mentioned the need to have specific tutorial instruction for those
    keys (e.g. SPC and DEL) that are *not* so obvious. Teaching `n' right away
    is a waste of time, not because `n' is useless, but because there is an
    obvious (if perhaps somewhat slower) way to do the same thing.

That might be a good point.

    As to the fingers-leaving-the-keyboard argument: That is not such a strong
    argument for Info, where people are reading, not editing.

I agree, that is not a crucial issue for Info.

    1) teach what Info is about, first;

    2) start using the obvious how-to (e.g. links, buttons, menu-bar), to teach
    #1;

    3) teach the non-obvious how-to (e.g. SPC, DEL) also;

Those three are an idea worth trying.  I have doubts that this would
be much easier, but there's no harm in trying it out, and maybe the
results would be good.

    4) don't bother teaching the obvious, if more-efficient, how-to (e.g. `n'),
    except possibly as an efficiency booster, after getting the real message
    across.

We definitely should teach these commands later on.

The reason for focusing on n and p rather than SPC and DEL
is partly historical.  Originally, SPC and DEL only moved
within a node.

Re: Info tutorial is out of date

[Richard Stallman]

    I don't even see why `C-l' is mentioned anymore, especially at the very
    beginning of the tutorial. It was important back when 14K baud was a fast
    transmission speed and your screen got "garbaged" (to quote the tutorial)
    from time to time. You needed to learn `C-l' at the beginning, because if
    your screen got garbled then you were lost in the tutorial - that was a game
    in itself (much more interesting than invisible text). `C-l' is just a
    vestige of the bad-ole-days - lose it.

I agree.

    With absolutely no instruction, a user will figure out immediately how to
    move among nodes - the equivalent of `n', `p', `u', and `m', because they
    *see* the corresponding links and buttons. Clicking links and buttons is a
    fine way to get around, to get the info you need - at least in the
    beginning. Teaching `n' and `p' does not need to take up the first several
    minutes of the tutorial - it should be presented much later, perhaps in a
    (brief) lesson on keyboard shortcuts.

That seems plausible to try.

    The first thing the tutorial should do is take a tour of the menu-bar menu -
    that is, those menu items that are the most important. This is also the
    opportunity to point out the key bindings indicated in the menu. That is the
    way to introduce the shortcuts `i', `s', and `l', for instance - in passing.

The menu bar is no more convenient or clear than keys.

    BTW, the help text (tooltip) for the search toolbar icon should not scare
    people away by mentioning regular expressions. It should say simply `Search
    the manual'. If you don't think that's enough, then it could say `Search the
    manual (regexp is OK)'.

That is ok.

    None of the tooltips should use the word "file" -
    they should say "manual".

It would ok.

    I'll say one more time, in passing, that an icon for deletion (X) should not
    be used for quitting Info - that is a bad idea. Several other possibilities
    were suggested previously (e.g. the international icon for an exit: arrow
    exiting a room), and there are lots of quit icons to choose from. But that
    particular X is often used for deletion, a confusion we don't want here.

I agree.

    The Info tutorial itself should be accessible (listed) in the menu of the
    first node of the Info manual. Instead, it is only mentioned in the text of
    that node, in terms of `h'.

I don't see the reason for this.  Once a person is looking at the Info
manual, he doesn't need the tutorial any more.  And he can still get to
it in the usual way.

    Before entering the tutorial, we should tell
    users how to exit it, to get back where they were.

I don't quite follow.

     BTW, `h' should not bring
    up the tutorial, it should display a mini-version of what `C-h m' shows: a
    short list of the main key bindings - about the same as what's in the
    menu-bar menu, but with some explanation. There is no need to have a key
    binding just to bring up the Info tutorial - people won't be doing that 30
    times a day.

I see your point, but at the same time, people using Info may not grasp
the idea of two-character commands.

    The node `Invisible text in Emacs Info' is incomprehensible to me
    ("invisible text is really a part of the text"!?). Yow! Why are we telling
    users about killing and yanking Info text? (I guess printing is OK.) Why is
    this near the beginning of the tutorial? I really, really do not get this.

I agree -- why teach people about this in the tutorial?
Does anyone think this is desirable?

    In general, instead of introducing so many key bindings (e.g. `]'), the
    tutorial should spend the user's time taking a tour of Info *functionality*.
    Touring the menu-bar menu is a good way to explore the main functionalities:
    show what's there and what it does. In addition to the features in the
    menu-bar menu, teach SPC and DEL - that's about it.

Other commands such as ] are also functionality.  They are a little
more advanced, as functionality goes, so perhaps they should come later.

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Do we need to call each other names?

a name is gratuitous, but w/o it, we become
statistics (moreso than we already are).

anyway, aside from mouse/nomouse, i agree that moving `i' more towards
the beginning is a good idea.  we can keep the node about invisible text
and use it to introduce `i' (and `l'):

  Although info manuals are organized like a tree, you can jump
  directly to a specific topic using @kbd{i}.  Read the following
  key sequence and then try it!

  @example
  Type           Explanation
  ------------------------------------------------------------
  i              You see the prompt "Index topic:".
  invisible      A topic not immediately visible from here.
  RET            You visit node "Help-Inv" and Emacs displays
                 a message where "invisible" was found.
  l              You return here.
  @end example

  You can now revisit the node with @kbd{r}, or use
  OTHER-SEARCH-METHODS, etc...

i think this fits in w/ your point that it is best to DO something in a
tutorial rather than just talk about it, and that navigation tasks are
of lower priority than search tasks (if those were indeed your points).

btw, i use @example for this email; the actual texinfo would probably
use @table and more extensive explanation, w/ @xref and so on.

thi

Re: Info tutorial is out of date

[Alan Mackenzie]

A wonderfullest Sunday morning, Drew!

On Sat, Jul 15, 2006 at 04:41:22PM -0700, Drew Adams wrote:
>     `n' and `p' are not shortcuts - they're the prime method of using
>     the functions.  Rather, the mouse equivalents should be regarded
>     as ambages.

> Another in the Mouseless-That-Roared camp, eh? A small, but very vocal
> and militant minority, apparently. Vent against he who seems to speak
> for the lousy moused masses of nasty newbies. It's OK; I can take it;
> I have to, for the noobs' sake ;-).

Well, there are about 100 people on the Emacs project list, and 3 have
taken exception to your m[o]usings.  Even assuming the other ~97, none
of whom has yet voiced an opinion on the matter, are confirmed habitual
mousers, that leaves 3% of users as mouse haters.  The point is, you
don't have any decent statistics and neither do I.

> Next week I'll do battle with those (even more ferocious) who hold
> that only UPPERCASE characters are pure, clear, truthful, and
> sufficient; lowercase being but a lying distraction designed to take
> our focus off the true aim of STRUGGLE against the dominance of
> MongrelMulattoMixedCharacterism. Compared to the luddite lowercasians,
> the mighty mouseless are a small piece of cake (or is it cheese?).

Drew, you've hit a raw nerve.  Whether one uses a mouse extensively or
not is a highly emotional thing, on a par with whether one uses
Microsoft Windows XP rather than GNU/Linux.  Your original post was a
rant, and you used lots of loaded words and phrases (like "shortcut").
You shouldn't be too surprised at getting flamed a little bit.
  
I think there are a lot more pure keyboard users out there than you do.
I also think that not encouraging frivolous mouse use is a Good Thing.

I'm not going through the rest of your reply in detail, because that
would just get repetitive, bore everybody to tears and make us both
unpopular on the list.  Suffice it to say I agree with your main points,
those which weren't about WIMPs and mice vs. real men.

[ .... ]

>     But looking at this tutorial, I too think it could do with a
>     little sprucing up.

> So let's spruce it.

Glad to end on a not of agreement.  :-)

-- 
Alan.

Re: Info tutorial is out of date

[Richard Stallman]

    What's a menu-bar?  My Emacs setup hasn't got one (whatever it might
    be ;-).

If you don't have a menu bar, it is because someone turned it off for
you.  The tutorial need not be designed to cope with such
customizations.

    However, not all Emacs setups have mouses.  One of the prime
    attractivenesses of Emacs for me is being able to use it on a plain
    character screen without it being cluttered up with window borders,

I think nearly all beginner users of Emacs have mice.
The Info tutorial is mainly aimed at these beginners.

    Er, I have to agree here.  I've never seen any invisible text in Info.

You wouldn't see it, would you ;-).

RE: Info tutorial is out of date

[Drew Adams]

        If you want, the tutorial could be split in two: first
        "What Info Is" (with simple how-to, to get the points across),
        second "How To Use Info Efficiently".

    That is a good idea, in a general sense.  However, I am not sure
    it is really necessary, for the reason below.

    		  My point is this: first things first. If I don't
              understand what Info is all about, why would I go through
              the effort of learning and practicing its key bindings?

    Isn't it obvious to everyone what Info is all about?  It's all about
    browsing documentation files.

What's an Info file?

Info is about finding information in a manual. The most important things to
teach are the structure of the manual and how to find info in it. This
means, in particular, pointing out the index, TOC, history list, and
glossary, and taking users through using `i', `s', `l', and `g' (whether by
menu or key).

It's also important to teach that you can exit with `q' and enter again
(with `C-h i') exactly where you left off. This is not obvious, and it
should be part of the tutorial: exit to do something, and come back, from
anywhere in Emacs, with `C-h i'.

It's also important to point out the difference between chronological "back"
(`l') and structural "back" (e.g. up after down, previous after next). It's
also important to teach the key bindings that are not in the menu-bar menu -
SPC and DEL. The normal book structure (up, down, next, previous) needs to
be at least mentioned, because it is not common on, e.g., the Web.

If users learn what main functionalities are available (regexp search, index
lookup, goto a named node, navigate through the history, TOC lookup,
glossary lookup) and how to use them, they've got 90% of what we need to
teach them.

    Menus, and moving up, moving thru a
    series using next and previous, are going to be obvious to anyone that
    has used the WWW very much.

Next and previous are common on the web. The up, down, next, previous book
structure of an Info manual is *not* at all common on the Web. But it is
familiar from books, so it only requires pointing out and mentioning the
book analogy.

    Thus, practically speaking, I think there isn't much to be achieved by
    having a separate easier section which just teaches you "what Info is
    all about".

I don't care whether such info is in a separate section. But, to me, what
Info is for and what you can do with it are what the tutorial should be all
about. The extra section for "how to use keyboard shortcuts to be more
efficient" is the section I would get rid of, if we got rid of one of the
two proposed sections. I don't propose getting rid of it however, just
moving it to the end.

        I also mentioned the need to have specific tutorial
        instruction for those keys (e.g. SPC and DEL) that are *not* so
        obvious. Teaching `n' right away is a waste of time, not because
        `n' is useless, but because there is an
        obvious (if perhaps somewhat slower) way to do the same thing.

    That might be a good point.

        As to the fingers-leaving-the-keyboard argument: That is
        not such a strong argument for Info, where people are reading,
        not editing.

    I agree, that is not a crucial issue for Info.

        1) teach what Info is about, first;
        2) start using the obvious how-to (e.g. links, buttons,
           menu-bar), to teach #1;
        3) teach the non-obvious how-to (e.g. SPC, DEL) also;

    Those three are an idea worth trying.  I have doubts that this would
    be much easier, but there's no harm in trying it out, and maybe the
    results would be good.

        4) don't bother teaching the obvious, if more-efficient,
           how-to (e.g. `n'), except possibly as an efficiency booster,
           after getting the real message across.

    We definitely should teach these commands later on.

I agree (and I use them, always). But what does "teach" mean here? I think
it would be enough to 1) point them out (from the menu-bar menu), 2)
recommend them, for efficiency, and 3) run through using one or two briefly.

    The reason for focusing on n and p rather than SPC and DEL
    is partly historical.  Originally, SPC and DEL only moved
    within a node.

Yes. And n and p were the only ways to get around. They are still the best
ways, but it is easier to get to the important points (to teach those firt)
using the menu-bar or links and navigation buttons to get there.

RE: Info tutorial is out of date

[Drew Adams]

        The first thing the tutorial should do is take a tour of
        the menu-bar menu - that is, those menu items that are the most
        important. This is also the opportunity to point out the key
        bindings indicated in the menu. That is the
        way to introduce the shortcuts `i', `s', and `l', for
        instance - in passing.

    The menu bar is no more convenient or clear than keys.

It's one less thing to teach, in order to get directly into the meat of what
we want to teach. The menu bar is *there*; it needs no explaining, no
practicing, no remembering.

        The Info tutorial itself should be accessible (listed) in
        the menu of the first node of the Info manual. Instead, it is only
        mentioned in the text of that node, in terms of `h'.

    I don't see the reason for this.  Once a person is looking at the Info
    manual, he doesn't need the tutorial any more.  And he can still get to
    it in the usual way.

But, then why do we introduce the tutorial in the first text of the Info
manual? We introduce it by mentioning `h'. I would instead put it in the
menu, pointing out that it is an optional node of the manual (and saying
clearly what it is).

And how else would someone get to the tutorial, except through the Info
manual?

        Before entering the tutorial, we should tell
        users how to exit it, to get back where they were.

    I don't quite follow.

You enter with `h', and then what? Introduce `q' and `C-h i' to get back
where you were in the tutorial. And if the tutorial is not a node in the
Info manual, what happens when you reach the end of it? I'd rather see it as
an optional node within the Info manual.

        BTW, `h' should not bring up the tutorial, it should display
        a mini-version of what `C-h m' shows: a short list of the main
        key bindings - about the same as what's in the
        menu-bar menu, but with some explanation. There is no need
        to have a key binding just to bring up the Info tutorial -
        people won't be doing that 30 times a day.

    I see your point, but at the same time, people using Info may not grasp
    the idea of two-character commands.

What two-character command? Just `h' to show the major key bindings. Anyway,
they will need to grasp `C-h i' to get into Info and to get back into it. I
don't follow you here.

        The node `Invisible text in Emacs Info' is incomprehensible to me
        ("invisible text is really a part of the text"!?). Yow! Why
        are we telling users about killing and yanking Info text? (I guess
        printing is OK.) Why is this near the beginning of the tutorial?
        I really, really do not get this.

    I agree -- why teach people about this in the tutorial?
    Does anyone think this is desirable?

        In general, instead of introducing so many key bindings
        (e.g. `]'), the tutorial should spend the user's time taking
        a tour of Info *functionality*. Touring the menu-bar menu is a
        good way to explore the main functionalities: show what's there
        and what it does. In addition to the features in the
        menu-bar menu, teach SPC and DEL - that's about it.

    Other commands such as ] are also functionality.  They are a little
    more advanced, as functionality goes, so perhaps they should come later.

Yes, and they are in the menu-bar. AFAIK, the only commands not in the
menu-bar are SPC and DEL.

By pointing out the existence of the menu-bar, and running users through
some of its items, users also learn the lesson that they can find Info
functionality there. Instead of remembering, six months later, the Info
lesson that ran through using `]', they can remember to check what's in the
menu-bar menu - there they'll be reminded that `]' is the binding, or
they'll learn about it for the first time.

RE: Info tutorial is out of date

[Drew Adams]

    > Another in the Mouseless-That-Roared camp, eh? A small, but very
    > vocal and militant minority, apparently.

    It does not give you any thoughts that from your "majority", you are
    the only one to speak up?

Hmm, now that you mention it... Maybe emacs-devel is a bit out of touch with
noobs?

Nah, that's not fair. Maybe 3 or 4 people on emacs-devel are?

Nah, the point is that newbies are the target for the tutorial, and they are
not subscribed to the list. I'm not the only one who can speak for them, of
course, but I didn't see any arguments from you 3 that spoke to newbie
needs. You basically went on an anti-mouse rampage.

Newbies are overwhelmingly used to using a mouse. Let them do that while
they get the basics of Info. Save the teaching of why it's better to learn
to use the keyboard for later.

It is 100% irrelevant whether emacs-devel subscribers have or use a mouse.
The only relevant question for the issue at hand (Info) that has to do with
mouse vs keyboard is this: am I wrong that *newbies* are overwhelmingly used
to using a mouse? If I'm not wrong, then there is no reason to sidetrack the
start of the Info tutorial just to put them on the keyboard track.

    > The point is that we do not *have* to teach people how to get to
    > next and previous nodes (provided they have a mouse, which most
    > users do [OUCH!]).  That is advertised at the top of the buffer with
    > big blazing buttons. It's just, well, brain-dead obvious. If you
    > blindfold yourself, then you might need a tutorial to help you get
    > through the living room, but if you turn `blindfold-mode' OFF... it
    > hurts a lot less.
    >
    > We certainly don't need to spend the first several minutes of the
    > tutorial on `n' and `p', even for the mouseless. For the moused, we
    > can teach `n' and `p' later, after they know what Info is all
    > about. (Hint: it is not about `n' or `p'; it has something to do
    > with finding `Info'rmation.)

    The mouse can only be used for the most important functions as a
    fallback.  It does not make sense in a tutorial to focus on the less
    important functions first.

Your last sentence was precisely why I wrote my feedback.

The most important functions are `i', `s', `g', `l', SPC, DEL, and perhaps
`T' and `L' (and maybe even `M-n'). They are certainly *NOT* `n', `p', `u',
`d', and `m'.

I think that must be our basic disagreement: what are the most important
Info functions and features to teach? Do we need to start by teaching `n',
`p', `u', `d', and `m'?

RE: Info tutorial is out of date

[Drew Adams]

    > Another in the Mouseless-That-Roared camp, eh? A small, but very vocal
    > and militant minority, apparently. Vent against he who seems to speak
    > for the lousy moused masses of nasty newbies. It's OK; I can take it;
    > I have to, for the noobs' sake ;-).

    Well, there are about 100 people on the Emacs project list, and 3 have
    taken exception to your m[o]usings.  Even assuming the other ~97, none
    of whom has yet voiced an opinion on the matter, are confirmed habitual
    mousers, that leaves 3% of users as mouse haters.  The point is, you
    don't have any decent statistics and neither do I.

1. I'm *not* a mouser. Except to click links sometimes, I use keys in Info
(and Emacs). This is not about what I use or what you use or 27% or 97% of
emacs-devel use; it is about how best to teach newbies about Info.

2. Most people never speak up on an issue. That doesn't say anything about
where they stand on the issue, or even if they care about it at all.

3. If mouse vs keyboard practices are relevant to this discussion at all
(it's a discussion about the Info tutorial, remember?), then the users to
measure are *not* the 100 emacs-devel subscribers. People who don't use
Emacs, and Emacs newbies, are the target audience for the tutorial, not us.
This is an important point - what you or I do daily with mice and keyboards
is unimportant (irrelevant) to the design of the tutorial. The tutorial is
not for us.

4. The reaction to my post from 3 people who don't use a mouse was all about
*them*, not about the target tutorial community. It was all about their own
anti-mousing, and ~zero about the ideas in my post for improving the
tutorial. IOW, their own anti-mouse button got pushed somehow, and any real
debate on the ideas I raised was drowned.

I'm glad, BTW, that I don't often use the mouse, myself; otherwise, I might
have felt targeted by the reaction and tried to defend mousing as somehow
superior (which it is not). As it is, I know your reaction is misplaced. I
only wish the real issues were discussed, if there is disagreement on those.

5. I raised lots of ideas about emphasizing the important Info stuff. People
don't need to agree with all of those ideas, but there was little uptake on
them, except from RMS (and, later, from Thi). Does lack of response to my
main suggestions mean that 100% (minus RMS and I) don't support the ideas? I
don't think you can fairly reason that way.

Mousing or not seems to be a hot-button issue for those who don't use a
mouse. To me, it is a non-issue. I don't promote use of the mouse, and I am
all for recommending in the tutorial (and elsewhere) that newbies learn to
use keyboard commands.

You missed the point - it's about *what Info is about*, and it's not about
`n', `p', `u', and `d'. It's about finding information. The easiest and
quickest way we can bring newbies to the real information is what we should
aim for. Teaching `n' etc. up front is a wasteful distraction from the real
goal.

    > Next week I'll do battle with those (even more ferocious) who hold
    > that only UPPERCASE characters are pure, clear, truthful, and
    > sufficient; lowercase being but a lying distraction designed to take
    > our focus off the true aim of STRUGGLE against the dominance of
    > MongrelMulattoMixedCharacterism. Compared to the luddite lowercasians,
    > the mighty mouseless are a small piece of cake (or is it cheese?).

    Drew, you've hit a raw nerve.  Whether one uses a mouse extensively or
    not is a highly emotional thing, on a par with whether one uses
    Microsoft Windows XP rather than GNU/Linux.  Your original post was a
    rant, and you used lots of loaded words and phrases (like "shortcut").
    You shouldn't be too surprised at getting flamed a little bit.

I don't care if I'm flamed; I enjoyed the exchange, as entertainment.

My original post was not at all a rant; the fact that you see it that way
says something about your hot button.

My followup posts to your rants were sardonic and meant to be humorous. But
I'm not on a rant to promote mice - far from it. I have nothing I'm pushing
here; even my suggestions for the tutorial are offered with no special drive
behind them.

Key bindings *are* shortcuts - what's wrong with that? 1) They are commonly
called "keyboard shortcuts" by many people. 2) They are shorter (quicker) to
use than clicking menus and links with a mouse - don't you agree? They are
shorter (quicker) than using `M-x' - don't you agree? What is it about
"shortcut" that sets you off?

    I think there are a lot more pure keyboard users out there than you do.

Who knows? I tried to offer some objective info - do you have something to
add to that?

Keep in mind that the audience to be measured for mouse/keyboard use is not
the members of emacs-devel, or even the users of Emacs; it is the non-users
and the new users of Emacs, for the most part.

    I also think that not encouraging frivolous mouse use is a Good Thing.

I'm not encouraging mouse use, "frivolous" or otherwise. I proposed that we
get to the heart of the teaching matter in Info right away, using the
obvious tools available that everyone knows how to use: links and buttons. I
didn't weigh in on the keyboard vs mouse issue at all - I didn't even know
there was such an issue - it's your hot button, not mine. I mentioned
mouse-usage statistics in my followup to your rant because I think it's a
mistake to orient the entire Info tutorial to the use patterns of a tiny
minority.

I don't mind accomodating that minority (and I suggested a couple ways that
could be done); what I object to is hijacking the tutorial, distracting
learners from the subject at hand - which is what Info is.

(Yes, "hijacking" is inexact here, since the tutorial already has that
orientation. But it has that orientation, IIUC, only for historical reasons,
not because emacs-devel decided that keyboard shortcuts `n', `p' etc were
the most important thing to teach first.)

I don't see the point in making the first half of the Info tutorial a battle
for keyboardism against creeping mousism. Get the new users to the info on
Info right away. Bring them to keyboard heaven afterward.

    I'm not going through the rest of your reply in detail, because that
    would just get repetitive, bore everybody to tears and make us both
    unpopular on the list.

Thank you.

    Suffice it to say I agree with your main points,
    those which weren't about WIMPs and mice vs. real men.

Thank you again. Perhaps we can discuss the details - of disagreement, for
example - of the main points.

    > So let's spruce it.

    Glad to end on a not[e] of agreement.  :-)

As am I.

RE: Info tutorial is out of date

[Drew Adams]

    i agree that moving `i' more towards the beginning is a good idea.
    we can keep the node about invisible text and use it to introduce
    `i' (and `l'):

      Although info manuals are organized like a tree, you can jump
      directly to a specific topic using `i'.

I wouldn't call index entries "topics". I'd reserve that term for node
names. To me, `g' is for jumping to a topic; `i' is for looking up something
(not a topic, but anything) in the index.

      Read the following key sequence and then try it!

      Type           Explanation
      ------------------------------------------------------------
      i              You see the prompt "Index topic:".
      invisible      A topic not immediately visible from here.
      RET            You visit node "Help-Inv" and Emacs displays
                     a message where "invisible" was found.
      l              You return here.

I didn't understand this at first, because it is in the form of a table. I
thought each row was separate; I didn't understand that you meant to type
process the rows in sequence. Perhaps numbering the rows would help.

I think something like this would be better, though:

  Type: i invisible RET

  When you hit `i', you are prompted for something to look up
  in the index. You type `invisible' and hit `RET' to look up
  "invisible".

  Look-up finds Info node `Help-Inv', and it takes you there.
  That node explains invisibility.

  To get back to the node where you hit `i', use `l'.

That said, I really don't think node `Help-Inv' is helpful (or I don't
understand it). I also don't think your instructions above should use the
word "visible" in the context of talking about "invisible"; that just
confuses things.

I think it's better to have separate lessons for `l' and `r', on the one
hand, and `i' on the other.

I'd suggest taking a tour of the Index with `i' and visiting the TOC with
`T'. Since the TOC display is different from other Info pages, a mini-lesson
on using it could be helpful. Likewise, for `L' and the history display.

There should also be a brief visit to the glossary. BTW, there is no index
entry for "glossary" in the Emacs manual, and there is no glossary in the
Emacs-Lisp manual (and the Info manual).

We should also perhaps have a command for glossary lookup - perhaps `G'.

    i think this fits in w/ your point that it is best to DO something in a
    tutorial rather than just talk about it, and that navigation tasks are
    of lower priority than search tasks (if those were indeed your points).

Yes.

Re: Info tutorial is out of date

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > Another in the Mouseless-That-Roared camp, eh? A small, but very
>     > vocal and militant minority, apparently.
>
>     It does not give you any thoughts that from your "majority", you are
>     the only one to speak up?
>
> Hmm, now that you mention it... Maybe emacs-devel is a bit out of touch with
> noobs?
>
> Nah, that's not fair. Maybe 3 or 4 people on emacs-devel are?
>
> Nah, the point is that newbies are the target for the tutorial, and they are
> not subscribed to the list. I'm not the only one who can speak for them, of
> course, but I didn't see any arguments from you 3 that spoke to newbie
> needs. You basically went on an anti-mouse rampage.

It is not a productive style of discussion to discard every argument
not leading to the desired result by using deprecatory invectives.

I repeat: there is little sense in telling people how to do
complicated things with the keyboard without telling them how to do
the simple things.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Date: 16 Jul 2006 04:29:42 -0400
> 
>   Although info manuals are organized like a tree, you can jump
>   directly to a specific topic using @kbd{i}.

`i' is not for jumping to something, it's for _looking_up_ something.
The difference is that, in order to jump, you need to _know_ what you
are looking for, whereas `i' is mainly useful when you _don't_know_.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sun, 16 Jul 2006 10:33:40 -0700
> 
> Info is about finding information in a manual.

That is only one of the two main uses of an Info manual.  The other
one is to read the manual in its entirety, or at least read some large
chunk of it in the order of the node structure.  Please don't forget
the latter usage pattern, as it's no less important than the former.

Re: Info tutorial is out of date

[Jay Belanger]

"Drew Adams" <drew.adams@oracle.com> writes:
...
> Newbies are overwhelmingly used to using a mouse. Let them do that while
> they get the basics of Info. 

Once they're used to it, they're less likely to change.

> Save the teaching of why it's better to learn to use the keyboard
> for later.

When it will be too late for many.  If indeed it is better to use the
keyboard (and I think it is), it seems a bad idea to begin by teaching
bad habits, however easy these habits may be.

Jay

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 4. The reaction to my post from 3 people who don't use a mouse was all
> about *them*, not about the target tutorial community. It was all
> about their own anti-mousing, and ~zero about the ideas in my post for
> improving the tutorial. IOW, their own anti-mouse button got pushed
> somehow, and any real debate on the ideas I raised was drowned.

i am not anti-mouse for myself bereft of empathy for the newbie
(although i realize that such feeling can never be accurately
transmitted via email).

IME, taking a mouse-is-irrelevant approach in a tutorial is like "tough
love"; i have successfully coached people on info (and emacs) usage w/
the preface "leave the mouse alone for now -- you might need it later
but probably less than you'd think".  maybe i was just lucky.

> You missed the point - it's about *what Info is about*, and it's not
> about `n', `p', `u', and `d'. It's about finding information. The
> easiest and quickest way we can bring newbies to the real information
> is what we should aim for. Teaching `n' etc. up front is a wasteful
> distraction from the real goal.

everything is wasteful distraction.  @xref{life}, @ref{entropy}.
 
thi

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

Eli Zaretskii <eliz@gnu.org> writes:

> `i' is not for jumping to something, it's for _looking_up_ something.
> The difference is that, in order to jump, you need to _know_ what you
> are looking for, whereas `i' is mainly useful when you _don't_know_.

you are right.  sorry for the imprecision.

thi

Re: Info tutorial is out of date

[Lennart Borgman]

Jay Belanger wrote:
>> Save the teaching of why it's better to learn to use the keyboard
>> for later.
>>     
>
> When it will be too late for many.  If indeed it is better to use the
> keyboard (and I think it is), it seems a bad idea to begin by teaching
> bad habits, however easy these habits may be.
>   
I too think that the keyboard is better, but in my mind is right now a 
song with an awful text:

"If you want to teach them they can't learn then make sure they have to 
learn a lot of details at once."

I am sure someone has some better text for this! ;-)

Re: Info tutorial is out of date

[Jay Belanger]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> Jay Belanger wrote:
>>> Save the teaching of why it's better to learn to use the keyboard
>>> for later.
>>>
>>
>> When it will be too late for many.  If indeed it is better to use the
>> keyboard (and I think it is), it seems a bad idea to begin by teaching
>> bad habits, however easy these habits may be.
>>
> I too think that the keyboard is better, but in my mind is right now a
> song with an awful text:
>
> "If you want to teach them they can't learn then make sure they have to
> learn a lot of details at once."
>
> I am sure someone has some better text for this! ;-)

Is that an actual song?  I like it.  What is the name of it?  I'm sure
most people agree with the sentiment, too.
But what little at a time is being taught, should be taught correctly.  
If the consensus is that using the mouse is the right way, fine; but I
disagree with the idea of letting bad habits form and overcoming them
later.

Jay

Re: Info tutorial is out of date

[Lennart Borgman]

Jay Belanger wrote:
> Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>
>   
>> Jay Belanger wrote:
>>     
>>>> Save the teaching of why it's better to learn to use the keyboard
>>>> for later.
>>>>
>>>>         
>>> When it will be too late for many.  If indeed it is better to use the
>>> keyboard (and I think it is), it seems a bad idea to begin by teaching
>>> bad habits, however easy these habits may be.
>>>
>>>       
>> I too think that the keyboard is better, but in my mind is right now a
>> song with an awful text:
>>
>> "If you want to teach them they can't learn then make sure they have to
>> learn a lot of details at once."
>>
>> I am sure someone has some better text for this! ;-)
>>     
>
> Is that an actual song?  I like it.  What is the name of it?  I'm sure
> most people agree with the sentiment, too.
>   
Unfortunately it is not a real song ;-)

> But what little at a time is being taught, should be taught correctly.  
> If the consensus is that using the mouse is the right way, fine; but I
> disagree with the idea of letting bad habits form and overcoming them
> later.
>   
Yes, but the thing is that if they can use their old habits for a while 
they can learn much, much faster.

Re: Info tutorial is out of date; mouse usage

[David Kastrup]

Dieter Wilhelm <dieter@duenenhof-wilhelm.de> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> "Drew Adams" <drew.adams@oracle.com> writes:
>>
>>>     `n' and `p' are not shortcuts - they're the prime method of
>>>     using the functions.  Rather, the mouse equivalents should be
>>>     regarded as ambages.
>>>
>>> Another in the Mouseless-That-Roared camp, eh? A small, but very
>>> vocal and militant minority, apparently.
>>
>> It does not give you any thoughts that from your "majority", you are
>> the only one to speak up?
>
> Your perspective is a bit biased.  I would assume that Emacs
> developers tend to shortcuts. But what is with the "normal" users?
> I'd like to speak out for the mute majority and Drew Adams.

I don't get your point.  You present the mouse as a crutch when people
refuse to learn a more direct way.  But the purpose of a tutorial
is not to make people rely on crutches.  The visual aids for mouse
usage are available anyway: we don't need to teach people how to use
them.

What requires teaching with regard to a mouse is not how to press
labelled buttons.  Things like marking regions, dragging, cutting,
using scrollbars and so on: those are mouse functionality that
requires teaching.  Pressing labelled buttons doesn't, except for
buttons with incomprehensible labels.  I would consider it ok to
mention the toolbar buttons (which are just labelled with graphical
stuff) in a tutorial, and it would actually be a good idea to show
them as pictograms (info can do graphics, can't it?) when doing so.

But I don't see the point in mentioning that clicking an a "Next" line
will change to the next node.  And in particular I don't see the point
in omitting to mention the keyboard command for it.

> So the question is should the Emacs developers pander to the habits
> of casual, lazy, pampered masses?  I think yes, because the
> facilities are there and a few of these operator might be gradually
> guided to an "advanced" stage.

But the point of being "casual, lazy, pampered" with regard to the
mouse is that one does not need to remember how to do things.  And if
one does not need to remember, one does not require an explanation in
the first place.

We _do_ cater for that sort of laziness already by providing the
_functionality_.

I don't know why you took this off-list without giving a reason, so I
post the reply back to the list again.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: Info tutorial is out of date; mouse usage

[Drew Adams]

    > I'd like to speak out for the mute majority and Drew Adams.

    I don't get your point.  You present the mouse as a crutch when people
    refuse to learn a more direct way.  But the purpose of a tutorial
    is not to make people rely on crutches.  The visual aids for mouse
    usage are available anyway: we don't need to teach people how to use
    them.

No one has proposed teaching people how to use the mouse to navigate etc. We
do not *need* to *teach* that - it's *obvious*, immediate, apparent, QED,
CQFD. Even the blind can tell that a `Next' button is there. You said it:
"The visual aids for mouse usage are available anyway."

The same is not true of `n', `m', etc. - those are not obvious. However,
users need *not* use those shortcuts at all to learn how to use Info and
what features Info offers. And they can still see that those shortcuts are
available by looking 1) in the menu-bar Info menu or 2) in the `h'
keybindings list that I proposed. No need to use `n', and no need to teach
`n'.

The reason for taking a tour of the menu bar is not to teach how to use the
menu bar to do things; it is to teach the real content of Info; it is to
*get to* that content as quickly as possible, without teaching any
navigational preliminaries.

If you want, instead, to take the tour of important Info functionalities by
using `h' (the version I proposed: just a list of key bindings with one-line
descriptions), that's OK with me too. The point is to get to the important
stuff first, and not teach `n', `p', `u', etc. So, have the tutorial teach
`h' first (the bindings list) if you like, and then use that to explore `i',
`s', `g', `l', SPC, DEL, and so on. I don't care about the menubar and the
mouse - it's about the *functionalities*.

    What requires teaching with regard to a mouse is not how to press
    labelled buttons.  Things like marking regions, dragging, cutting,
    using scrollbars and so on: those are mouse functionality that
    requires teaching.  Pressing labelled buttons doesn't, except for
    buttons with incomprehensible labels.  I would consider it ok to
    mention the toolbar buttons (which are just labelled with graphical
    stuff) in a tutorial, and it would actually be a good idea to show
    them as pictograms (info can do graphics, can't it?) when doing so.

Again, there is no need to teach use of the mouse in the Info tutorial. Or
the toolbar. Or the menubar. Those are all obvious.

Teaching use of the mouse functionalities that you propose (selection, etc.)
could be useful, but not as part of the *Info* tutorial - it has nothing to
do with Info.

    But I don't see the point in mentioning that clicking an a "Next" line
    will change to the next node.  And in particular I don't see the point
    in omitting to mention the keyboard command for it.

Absolutely no one has proposed that kind of thing - never, no how, no way,
no sir; so please stop imagining that boogey man. The point is, on the
contrary, to get rid of teaching how to navigate structural links.

And no one has ever proposed omitting mention of keyboard shortcuts for
operations carried out, for example, by mouse. Please reread the posts.

In fact, for all I care, you could even rename Next, etc. links to include
their shortcuts, like we do in the menu: Next (`n'): Foo Bar. I'm *not*
proposing that, but I wouldn't object strongly. We should not have to teach
`n' (or `Next'), IMO.

Re: Info tutorial is out of date

[Mathias Dahl]

> > Newbies are overwhelmingly used to using a mouse. Let them do that while
> > they get the basics of Info.
>
> Once they're used to it, they're less likely to change.

If the main point is to teach new users how to use Info and Emacs
through it, I think we should concentrate on doing that in the way
that we think is easiest for *them*, not us. I am willing to "risk"
(what harm would it do, really?) that a user continues to use the
mouse, as long as he continues to use Emacs. They might later learn
how to do the same things using the keyboard and maybe that change if
they like that better.

Re: Info tutorial is out of date

[Mathias Dahl]

> ~zero about the ideas in my post for improving the
> tutorial. IOW, their own anti-mouse button got pushed somehow, and any real
> debate on the ideas I raised was drowned.

I agree. Most answers has been about technicalities and not the main
issue, to get new users to learn how to use Emacs. I have been
evangelizing for six years now and let me tell you, it's not easy. *I*
know that it is worth getting over the hurdle that many people hit
when they first try Emacs. I actually don't remember what kept *me*,
an old Windoze user, hanging in there. probably it was a combination
of GNU-philosophy and the overall "strangness" of Emacs (I tend to
want to try "strange" things or things other don't like). And of
course keyboard macros from heaven! :)

At work I am trying to see if I can lure the less technical of our
staff, the Technial Writers (sounds techy, but it is not), to use
Emacs. My plan is to push hard for things like abbrevs, skeletons and
other "auto typing" facilities.

Re: Info tutorial is out of date

[Mathias Dahl]

> > Key bindings *are* shortcuts - what's wrong with that? 1) They are
> > commonly called "keyboard shortcuts" by many people. 2) They are
> > shorter (quicker) to use than clicking menus and links with a mouse -
> > don't you agree? They are shorter (quicker) than using `M-x' - don't
> > you agree? What is it about "shortcut" that sets you off?
>
> It's one of those sort of words/phrases so beloved of
> journalists/salesmen/politicians that can be used to denigrate something,
> yet the j/s/p, when called on it, can convincingly pretend it was totally
> innocent and factual, as you have done in the preceding paragraph.

I understood Drew perfectly and I did not stop a second thinking that
he might have used it in a "journalist" sense. The reason is probably
that he and me have always used the same name for it, "keyboard
shortcut". Of all the things I have heard people call this during the
ten years I have been using computers professionally, this is the most
common of them (I use Windows at work). In the Emacs world, "key
sequence" is probably more correct, at least technically.

Re: Info tutorial is out of date

[Alan Mackenzie]

Hi, Drew!

On Sun, Jul 16, 2006 at 10:33:42AM -0700, Drew Adams wrote:
>     > Another in the Mouseless-That-Roared camp, eh? A small, but very
>     > vocal and militant minority, apparently. Vent against he who
>     > seems to speak for the lousy moused masses of nasty newbies. It's
>     > OK; I can take it; I have to, for the noobs' sake ;-).

>     Well, there are about 100 people on the Emacs project list, and 3
>     have taken exception to your m[o]usings.  Even assuming the other
>     ~97, none of whom has yet voiced an opinion on the matter, are
>     confirmed habitual mousers, that leaves 3% of users as mouse
>     haters.  The point is, you don't have any decent statistics and
>     neither do I.

> 1. I'm *not* a mouser. Except to click links sometimes, I use keys in
> Info (and Emacs). This is not about what I use or what you use or 27%
> or 97% of emacs-devel use; it is about how best to teach newbies about
> Info.

The discussion is not entirely unlike C-n vs. <down arrow> in the Emacs
tutorial.  What was the consensus there?

[ .... ]

> Mousing or not seems to be a hot-button issue for those who don't use a
> mouse. To me, it is a non-issue. I don't promote use of the mouse, and
> I am all for recommending in the tutorial (and elsewhere) that newbies
> learn to use keyboard commands.

Your suggested change to that tutorial would be promoting mouse use at
the expense of keyboard use.  You are conflating what is widespread and
usual with what is good.  This is bad!  There's no innocent get-out here
- not for you, not for me.

[ .... ]

>     Drew, you've hit a raw nerve.  Whether one uses a mouse extensively
>     or not is a highly emotional thing, on a par with whether one uses
>     Microsoft Windows XP rather than GNU/Linux.  Your original post was
>     a rant, and you used lots of loaded words and phrases (like
>     "shortcut").  You shouldn't be too surprised at getting flamed a
>     little bit.

> I don't care if I'm flamed; I enjoyed the exchange, as entertainment.

> My original post was not at all a rant; the fact that you see it that way
> says something about your hot button.

Er, didn't you yourself describe your original post as a rant?  ;-)

[ .... ]

> Key bindings *are* shortcuts - what's wrong with that? 1) They are
> commonly called "keyboard shortcuts" by many people. 2) They are
> shorter (quicker) to use than clicking menus and links with a mouse -
> don't you agree? They are shorter (quicker) than using `M-x' - don't
> you agree? What is it about "shortcut" that sets you off?

It's one of those sort of words/phrases so beloved of
journalists/salesmen/politicians that can be used to denigrate something,
yet the j/s/p, when called on it, can convincingly pretend it was totally
innocent and factual, as you have done in the preceding paragraph.

A bit like you can denigrate Lisp by calling it a "traditional" language,
with the undertones of "something so old-fashioned that a with-it modern
hacker wouldn't want to waste his time learning it".  Or like you could
denigrate a musical performance by calling it "workmanlike", carrying the
undertones "all the notes were in the right place, yet deeper musical
meaning was lacking".

In English, "shortcut" usually carries connotations of something naughty.
Like "the boys took a shortcut across the farmer's field" or "the
engineers, being pressed for time, took shortcuts in the maintenance
schedule, thus causing the aeroplane to crash".  Thus when you call a key
sequence a "shortcut", you're transmitting the subliminal message "this
is somehow illegitimate and the mouse action is the canonical correct way
to invoke the function".  I suspect this was deliberate, introduced by a
genius of a wordsmith around the time that mice were just catching on, in
the early 1980s.

What's wrong with the neutral term "key sequence"?

>     I think there are a lot more pure keyboard users out there than you
>     do.

> Who knows? I tried to offer some objective info - do you have something
> to add to that?

What you quoted missed the point.  Sure 99.9999% of computers are
equipped with mice, and they get used day in day out.  Who doesn't fire
up Firefox (or that ghastly proprietary program it's steadily
superseding) every day and mouse it?  Even I do, so I'd get included
amongst habitual mouse users in that survey.  A more pertinent question
would be "do you regularly use an application without recourse to the
mouse?"

>     I also think that not encouraging frivolous mouse use is a Good
>     Thing.

> I'm not encouraging mouse use, "frivolous" or otherwise. I proposed
> that we get to the heart of the teaching matter in Info right away,
> using the obvious tools available that everyone knows how to use: links
> and buttons. I didn't weigh in on the keyboard vs mouse issue at all -
> I didn't even know there was such an issue - it's your hot button, not
> mine. I mentioned mouse-usage statistics in my followup to your rant
> because I think it's a mistake to orient the entire Info tutorial to
> the use patterns of a tiny minority.

We're back in C-n vs. <down arrow> territory now.  You ARE weighing in on
the mouse vs. keyboard issue.  You are proposing telling people to use
mouse clicks instead of key sequences, and have opined that those key
sequences are incidental rather than essential.  I disagree with you here
- it seems to me like telling a newbie musician not to bother learning to
play scales, just to go directly to the music, the important stuff.

I have experience of telling ordinary computer users about key sequences:
"You know, you can type alt-f s to save the file rather than grasping for
the mouse.", and they typically 'phone me up a day or two later with
"Alan, thank you!  It's SO MUCH easier that way!".

[ .... ]

> I don't see the point in making the first half of the Info tutorial a
> battle for keyboardism against creeping mousism. Get the new users to
> the info on Info right away. Bring them to keyboard heaven afterward.

The sooner you start learning to play scales, the sooner you can play
Beethoven half decently.

[ .... ]

> Thank you again. Perhaps we can discuss the details - of disagreement,
> for example - of the main points.

I don't disagree with your other main points.  "Me too!".

>     > So let's spruce it.

>     Glad to end on a not[e] of agreement.  :-)

[e]?  Outch!

> As am I.

-- 
Alan.

RE: Info tutorial is out of date

[Drew Adams]

    > 1. I'm *not* a mouser. Except to click links sometimes, I use keys in
    > Info (and Emacs). This is not about what I use or what you use or 27%
    > or 97% of emacs-devel use; it is about how best to teach newbies about
    > Info.

    The discussion is not entirely unlike C-n vs. <down arrow> in the Emacs
    tutorial.  What was the consensus there?

I don't know, and I don't have time to check. You check and let us know, if
it's pertinent.

    > Mousing or not seems to be a hot-button issue for those who
    > don't use a mouse. To me, it is a non-issue. I don't promote use of
    > the mouse, and I am all for recommending in the tutorial (and
    > elsewhere) that newbies learn to use keyboard commands.

    Your suggested change to that tutorial would be promoting mouse use at
    the expense of keyboard use.

Not at all. Howzat?

    You are conflating what is widespread and usual with what is good.

No, believe me, I am not. I am conflating what is widespread with what users
will know when they first come to Emacs and Info. Know whom you communicate
with. Know your pupil. Know even your enemy, if you want to look at it that
way.

    This is bad!

What is bad? Using a mouse?

    There's no innocent get-out here - not for you, not for me.

Keep your ideas about evil for the local Anti-Mouse League meetings. I don't
see what that has to offer here. I like rodents of all sorts, as long as
they don't eat all the corn and rice.

    >     Drew, you've hit a raw nerve.  Whether one uses a mouse
    >     extensively or not is a highly emotional thing,

Not to me it's not, BTW. I could not care less about whether someone uses a
mouse extensively or not. Just doesn't excite me either way. Sorry.

    >     Your original post was a rant, and you used lots of loaded
    >     words and phrases (like "shortcut").  You shouldn't be too
    >     surprised at getting flamed a little bit.

    > My original post was not at all a rant; the fact that you see
    > it that way says something about your hot button.

    Er, didn't you yourself describe your original post as a rant?  ;-)

You're right, but I meant that I was ranting when I expressed disappointment
with Info, criticizing it left and right.

I was not ranting about my proposed changes - far from it. And I was not
ranting for or against the use of a mouse. Never, no how.

    > Key bindings *are* shortcuts - what's wrong with that? 1) They are
    > commonly called "keyboard shortcuts" by many people. 2) They are
    > shorter (quicker) to use than clicking menus and links with a mouse -
    > don't you agree? They are shorter (quicker) than using `M-x' - don't
    > you agree? What is it about "shortcut" that sets you off?

    It's one of those sort of words/phrases so beloved of
    journalists/salesmen/politicians that can be used to denigrate
    something, yet the j/s/p, when called on it, can convincingly
    pretend it was totally innocent and factual, as you have done
    in the preceding paragraph.

Like "paragraph"? That's one of those so-called words/phrases so beloved of
evil-doers that can be used to denigrate us flat-earthers. Also,
"convincingly" - gotta hate that one too.

Huh? Are you putting me on, Alan? What is the evil conspiracy behind the
phrase "keyboard shortcut" or the word "shortcut"? Is it because it has
"short" in it? I really don't get it. Please believe me that I am not
pretending anything, innocent and factual or otherwise. What is sinister
about "shortcut"?

    A bit like you can denigrate Lisp by calling it a "traditional"
    language...

That's your fantasy, not mine. Please don't bring in everything under the
moon, here. No one is putting down Lisp or shortcuts (err... key bindings).
Get a hold of yourself, please.

    In English, "shortcut" usually carries connotations of
    something naughty.

Not in my English, it doesn't. Maybe that's the problem. Not in American
English (to my knowledge); it does not. As with any word, it *can* carry a
connotation of naughtiness, depending on the context.

BTW, if it did carry a connotation of naughtiness, then I'd say we should
adopt it immediately, and sprinkle it liberally all over the Emacs docs and
UI. *That* would settle the shortcut vs mouse war once and for all, in your
favor. Naughtiness always wins, especially with the young'ns. Tell them the
mouse is the "proper" and "clean" way to go, and everyone will become a
keyboard convert overnight.

    Like "the boys took a shortcut across the farmer's field" or "the
    engineers, being pressed for time, took shortcuts in the maintenance
    schedule, thus causing the aeroplane to crash".

You are really stretching things. You can take a shortcut doing anything; it
can lead to good and improvement or bad and disaster. Tell a Frenchman that
he took a shortcut to get from Paris to the ski slopes and he'll beam with
pride as a "bison fute" (the sole bison clever enough to leave the herd and
find a shorter way 'round).

I think you're way off base, here, Alan, unless "shortcut" has some special
meaning in your neck of the woods. It certainly does not everywhere I've
ever set my feet - or else I've been oblivious to the secret connotation all
these years.

Yes, "The building contractor took shortcuts with the welds, and thus
compromised safety and quality" is a sentence that uses "shortcut" as a bad
thing. But that's not the only way to use it.

    Thus when you call a key sequence a "shortcut", you're transmitting
    the subliminal message "this is somehow illegitimate and the
    mouse action is the canonical correct way to invoke the function".

Nonsense! You're not serious, are you? This is a joke, right?

    I suspect this was deliberate, introduced by a genius of a wordsmith
    around the time that mice were just catching on, in the early 1980s.

And I suspect a touch of paranoia - no offense. Unless this is all just a
big hoax - that would be a good one on me! A really good one!

    What's wrong with the neutral term "key sequence"?

Nothing. Nothing wrong with "key binding" either.

And nothing wrong with communicating with those misled millions who
(shudder!) mistakenly think the right term is "keyboard shortcut".

I proposed adding a jargon glossary to the manual long ago, which was done,
I believe. I pointed out that "yank" means (roughly) "paste", and so on. I
didn't propose replacing "yank" by "paste", I proposed only pointing out to
newbies that Emacs jargon used "yank" for what they might know as "paste".
It's about bridging the gap between what people know and what you want them
to know.

BTW, think how derogatory "yank" is to us Yanks, Alan. How would you like it
if we called it "britting" or "scotting" or "krauting"? Well, think how us
Yanks feel when you call it "yanking". Unacceptable insensitivity.

And "yank" can mean to hang a man, too. Now that I think of it, I suspect
that "yank" was introduced intentionally to insult yankees, especially those
who have a past relative who was unfairly hung.

Not to mention the naughty connotation of "yanking" on you-know-what and the
assonant term "wanking". Yes, there is veritably nasty stuff underneath,
when you scratch the surface of the Emacs terminology. There's a PhD
dissertation on this waiting for someone who is interested in investigating
further.

And what about "killing" a buffer or text? What kind of subliminal message
was RMS trying to push on our innocent youth? How many millions have already
been corrupted by him and his words that kill? No wonder there are more and
more gangs, drugs, and guns on the streets. Corrupter of youth! Prepare the
hemlock now!

    >     I think there are a lot more pure keyboard users out
    >     there than you do.

    > Who knows? I tried to offer some objective info - do you have
    > something to add to that?

    What you quoted missed the point.  Sure 99.9999% of computers are
    equipped with mice, and they get used day in day out.

OK, what *is* the point?

*My* point about all this mice-and-keyboard nonsense is that if 99.9999% of
users who might become interested in using Info are already used to using a
mouse, then let's accomodate them. *If* we have a battle against mice (and I
don't), then let's take that battle out of the Info tutorial.

    Who doesn't fire
    up Firefox (or that ghastly proprietary program it's steadily
    superseding) every day and mouse it?  Even I do,

I'm quite ashamed of you, Alan, really. You know there are ways around that,
don't you. What good excuse do you have? What about Emacs as a Web browser?
What about Lynx? Do you sleep well at night after an evening of your filthy,
mousey scum surfing? For shame!

Father, forgive him, for he has  m o u s e d.

BTW, how do you fool Emacs into thinking you don't have a mouse, so it
doesn't feel ashamed of you? Do you unplug mousey when you use Emacs? Oh,
there's an option for that? Pretty sneaky. (Trying to pretend to me that you
didn't know what a mouse was... hah!)

    so I'd get included amongst habitual mouse users in that survey.
    A more pertinent question would be "do you regularly use an
    application without recourse to the mouse?"

OK. How many do you think would answer "yes" to your "more pertinent"
question? 0.0001%? 1%? 10%? Does it matter to you? Your mind's made up
already, isn't it? What if it were only 0.0000000001% who regularly use an
app without mouse? Would that persuade you? Be honest. I don't think so.

    >     I also think that not encouraging frivolous mouse use is a Good
    >     Thing.

    > I'm not encouraging mouse use, "frivolous" or otherwise. I proposed
    > that we get to the heart of the teaching matter in Info right away,
    > using the obvious tools available that everyone knows how to use:
    > links and buttons.
    > I didn't weigh in on the keyboard vs mouse issue at all -
    > I didn't even know there was such an issue - it's your hot button, not
    > mine. I mentioned mouse-usage statistics in my followup to your rant
    > because I think it's a mistake to orient the entire Info tutorial to
    > the use patterns of a tiny minority.

    We're back in C-n vs. <down arrow> territory now.  You ARE
    weighing in on the mouse vs. keyboard issue.  You are proposing
    telling people to use mouse clicks instead of key sequences,

I don't think so. When did you hear me say that we should tell people to use
the mouse, rather than keyboard? On the contrary, I've said repeatedly that
we can recommend that they use the  s h o r t c u t s.

I've said more than once that using the mouse to navigate is *not* (NOT,
_NOT_, *NOT*) something that needs to be taught. No one should ever waste
time trying to teach people to navigate with a mouse - never. There - happy?
I've said it again.

    and have opined that those key
    sequences are incidental rather than essential.

No. *Teaching* those key sequences is incidental to learning about *Info*.
Please read all the words; the meaning suffers, otherwise.

    I disagree with you here - it seems to me like telling a newbie
    musician not to bother learning to
    play scales, just to go directly to the music, the important stuff.

You disagree with yourself here, because you've misunderstood what I said.

    I have experience of telling ordinary computer users about key
    sequences: "You know, you can type alt-f s to save the file rather than
    grasping for the mouse.", and they typically 'phone me up a day or
    two later with "Alan, thank you!  It's SO MUCH easier that way!".

I support you in that. Good job. I've done that too. Keep it up.

    > I don't see the point in making the first half of the Info tutorial a
    > battle for keyboardism against creeping mousism. Get the new users to
    > the info on Info right away. Bring them to keyboard heaven afterward.

    The sooner you start learning to play scales, the sooner you can play
    Beethoven half decently.

    > Perhaps we can discuss the details - of disagreement,
    > for example - of the main points.

    I don't disagree with your other main points.  "Me too!".

Re: Info tutorial is out of date

[Richard Stallman]

    Well, there are about 100 people on the Emacs project list, and 3 have
    taken exception to your m[o]usings.  Even assuming the other ~97, none
    of whom has yet voiced an opinion on the matter, are confirmed habitual
    mousers, that leaves 3% of users as mouse haters.

I am a mouse-disliker, but I am also an experienced Emacs user
and I don't need to use the tutorial to learn how.

I am sure there are other experienced Emacs users that dislike the
mouse, but the question is about beginners.  Isn't it clear that
nearly all beginners use the mouse?

Re: Info tutorial is out of date

[Jay Belanger]

Richard Stallman <rms@gnu.org> writes:
...
> I am sure there are other experienced Emacs users that dislike the
> mouse, but the question is about beginners.  Isn't it clear that
> nearly all beginners use the mouse?


Yes; but I think that expecting them to use the mouse when they first
learn Emacs is effectively encouraging them to use it extensively
while they continue to use Emacs.  I think, to some extent,  it's
teaching them to use the mouse when they use Emacs.

Jay

Re: Info tutorial is out of date

[Stefan Monnier]

> When it will be too late for many.  If indeed it is better to use the
> keyboard (and I think it is), it seems a bad idea to begin by teaching
> bad habits, however easy these habits may be.

I think it's pretentious to think that we can influence people's habits
so easily.

I think the best option to satisfy both camps is to end the tutorial with
a section about "how to use Emacs more efficiently" where we describe key
bindings for those operations that can easily be accomplished with arrow
keys, mice, menu-bars, scroll-bars, you name it.


        Stefan

Re: Info tutorial is out of date

[Luc Teirlinck]

Stefan Monnier wrote:

   I think the best option to satisfy both camps is to end the tutorial with
   a section about "how to use Emacs more efficiently" where we describe key
   bindings for those operations that can easily be accomplished with arrow
   keys, mice, menu-bars, scroll-bars, you name it.

I believe that there is some confusion here.  I have not followed this
thread in detail, but it seems to be obviously about the Info manual,
not about the Emacs manual.  The Info manual tries to teach the user
how to use the Info system, not how to use Emacs.  Unless there has
been a policy change, Info is meant to replace the man pages in the
GNU system.  That is, people would do `info find' instead of
`man find' from a command line.  This brings up the standalone Info
reader and should be usable by GNU users who use, say, vim as their
editor and do not even know how to use Emacs.

`h' brings up the Info manual not just in Emacs Info, but also in the
standalone Info reader.  Of course, it must tell people how to use the
standalone Info reader, because for some GNU users this is the only
one they are going to use and even for Emacs users, it sometimes will
be more convenient to use the standalone version when they are in an xterm.

Of course, Emacs users must also be able to learn how to use Emacs
Info.  Emacs Info is too close to the standalone Info to justify two
separate manuals, especially since many people may want to learn how
to use both readers and we should not force them to read two manuals
most of whose contents just duplicate each other.

The Info reader has no menu bar and no Emacs style header line.
Scroll bars and mice do not seem to work with it.

Sincerely,

Luc.

Re: Info tutorial is out of date

[Luc Teirlinck]

>From my previous reply:

   The Info reader has no menu bar and no Emacs style header line.
   Scroll bars and mice do not seem to work with it.

I was, of course, referring to the standalone Info reader.

Sincerely,

Luc.

Re: Info tutorial is out of date

[Luc Teirlinck]

>From my previous message:

   Stefan Monnier wrote:

      I think the best option to satisfy both camps is to end the tutorial with
      a section about "how to use Emacs more efficiently" where we describe key
      bindings for those operations that can easily be accomplished with arrow
      keys, mice, menu-bars, scroll-bars, you name it.

   I believe that there is some confusion here.  I have not followed this
   thread in detail, but it seems to be obviously about the Info manual,
   not about the Emacs manual.

I meant: not about the Emacs tutorial.

Sincerely,

Luc.

Re: Info tutorial is out of date

[Eli Zaretskii]

> Date: Sun, 16 Jul 2006 22:54:47 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: karl@freefriends.org, belanger@truman.edu, emacs-devel@gnu.org
> 
> [this thread] seems to be obviously about the Info manual, not about
> the Emacs manual.

Yes.

> The Info manual tries to teach the user how to use the Info system,
> not how to use Emacs.

Correct.

> Unless there has been a policy change, Info is meant to replace the
> man pages in the GNU system.  That is, people would do `info find'
> instead of `man find' from a command line.  This brings up the
> standalone Info reader and should be usable by GNU users who use,
> say, vim as their editor and do not even know how to use Emacs.

Right.  (Except that one could set up their system so that "info FOO"
shows the related document in Emacs, not in the stand-alone reader.
But the default is certainly as you describe.)

> `h' brings up the Info manual not just in Emacs Info, but also in the
> standalone Info reader.

Yes.

> Of course, it must tell people how to use the standalone Info reader

Only the bare basics, because the more advanced features of the
stand-alone Info reader are documented in a separate manual, which
describes the stand-alone reader, and it alone.

> Of course, Emacs users must also be able to learn how to use Emacs
> Info.  Emacs Info is too close to the standalone Info to justify two
> separate manuals, especially since many people may want to learn how
> to use both readers and we should not force them to read two manuals
> most of whose contents just duplicate each other.

100% agreement.

> The Info reader has no menu bar and no Emacs style header line.
> Scroll bars and mice do not seem to work with it.

The current Info manual tries (sometimes very hard) to strike the
right balance between the handy GUI features available in Emacs and
the total lack thereof in the stand-alone reader.  It is quite
possible that the manual can be improved, but I'd rather see a
concrete proposal (in the form of patches or even a total rewrite)
than hear more of the endless discussions in this thread about the
relative merits and demerits of using the mouse and the tool bar.

Would someone who thinks they know how to make the Info manual less
``out of date'' please submit their proposed changes, so we could make
this discussion more practical?

TIA

Re: Info tutorial is out of date

[Alan Mackenzie]

Morning, Drew!

> > Key bindings *are* shortcuts - what's wrong with that? 1) They are
> > commonly called "keyboard shortcuts" by many people. 2) They are
> > shorter (quicker) to use than clicking menus and links with a mouse -
> > don't you agree? They are shorter (quicker) than using `M-x' - don't
> > you agree? What is it about "shortcut" that sets you off?

> It's one of those sort of words/phrases so beloved of
> journalists/salesmen/politicians that can be used to denigrate something,
> yet the j/s/p, when called on it, can convincingly pretend it was totally
> innocent and factual, as you have done in the preceding paragraph.

Er, I didn't mean to say that.  What I really wanted to say was the
_effect_ of your paragraph was indistinguishable from the j/s/p's.  I
apologise for saying you were doing this knowingly.  I sure you weren't.

-- 
Alan.

Re: Info tutorial is out of date

[Alan Mackenzie]

Morning, Drew!

On Sun, Jul 16, 2006 at 06:07:30PM -0700, Drew Adams wrote:

[ .... ]

> I was not ranting about my proposed changes - far from it. And I was not
> ranting for or against the use of a mouse. Never, no how.

>     > Key bindings *are* shortcuts - what's wrong with that? 1) They
>     > are commonly called "keyboard shortcuts" by many people. 2) They
>     > are shorter (quicker) to use than clicking menus and links with a
>     > mouse - don't you agree? They are shorter (quicker) than using
>     > `M-x' - don't you agree? What is it about "shortcut" that sets
>     > you off?

>     It's one of those sort of words/phrases so beloved of
>     journalists/salesmen/politicians that can be used to denigrate
>     something, yet the j/s/p, when called on it, can convincingly
>     pretend it was totally innocent and factual, as you have done in
>     the preceding paragraph.

> Like "paragraph"? That's one of those so-called words/phrases so
> beloved of evil-doers that can be used to denigrate us flat-earthers.
> Also, "convincingly" - gotta hate that one too.

> Huh? Are you putting me on, Alan?

No, I'm being entirely sincere.

> What is the evil conspiracy behind the phrase "keyboard shortcut" or
> the word "shortcut"? Is it because it has "short" in it? I really don't
> get it. Please believe me that I am not pretending anything, innocent
> and factual or otherwise. What is sinister about "shortcut"?

[ .... ]

>     In English, "shortcut" usually carries connotations of
>     something naughty.

> Not in my English, it doesn't. Maybe that's the problem. Not in
> American English (to my knowledge); it does not. As with any word, it
> *can* carry a connotation of naughtiness, depending on the context.

At the very least, "shortcut" implies "non-canonicity".  Nobody would
ever describe the direct motorway between two cities as a "shortcut",
even if it weren't blocked by traffic jams most of the time.  So if you
call a key sequence a "shortcut", you're implying "this isn't the
standard way of doing this operation".

[ .... ]

> Nonsense! You're not serious, are you? This is a joke, right?

I'm being entirely serious.

[ .... ]

>     What's wrong with the neutral term "key sequence"?

> Nothing. Nothing wrong with "key binding" either.

"Key binding" is less good for newbies, because it stresses a
relationship of being tied together rather than an act of pressing keys.
This could be somewhat puzzling.

> And nothing wrong with communicating with those misled millions who
> (shudder!) mistakenly think the right term is "keyboard shortcut".

[ .... ]

> BTW, think how derogatory "yank" is to us Yanks, Alan. How would you
> like it if we called it "britting" or "scotting" or "krauting"? Well,
> think how us Yanks feel when you call it "yanking". Unacceptable
> insensitivity.

"Yank" and "yank" are two distinct words, just as "spring", "spring" and
"spring" (a helix of wire, a source of fresh water, and the time after
winter) are three.  "Shortcut" is but one.  I have no problems with
somebody "scotching" rumours, "welshing" on a debt (as long as it's not
to me ;-) or applying "english" to a bouncing ball.  

[ .... ]

>     so I'd get included amongst habitual mouse users in that survey.  A
>     more pertinent question would be "do you regularly use an
>     application without recourse to the mouse?"

> OK. How many do you think would answer "yes" to your "more pertinent"
> question? 0.0001%? 1%? 10%? Does it matter to you? Your mind's made up
> already, isn't it? What if it were only 0.0000000001% who regularly use
> an app without mouse? Would that persuade you? Be honest. I don't think
> so.

I think it would be around 10%.  Certainly more than 1%.  It would be a
good deal more if the doc for proprietary programs actually put keyboard
sequences and mouse actions side by side, rather than relegating
"keyboard shortcuts" to an appendix.  I think that if the Info tutorial
were to relegate `n' and `p' to an appendix, that would cause fewer
newbies to use them.  I think that would be a bad thing.

[ .... ]

>     I have experience of telling ordinary computer users about key
>     sequences: "You know, you can type alt-f s to save the file rather
>     than grasping for the mouse.", and they typically 'phone me up a
>     day or two later with "Alan, thank you!  It's SO MUCH easier that
>     way!".

> I support you in that. Good job. I've done that too. Keep it up.

Which is why I believe `n' and `p' should be introduced as the normal way
of going to the next/previous node.  It helps newbies make an informed

-- 
Alan.

Re: Info tutorial is out of date

[Alan Mackenzie]

Morning, Richard!

On Sun, Jul 16, 2006 at 09:40:57PM -0400, Richard Stallman wrote:
>     Well, there are about 100 people on the Emacs project list, and 3
>     have taken exception to your m[o]usings.  Even assuming the other
>     ~97, none of whom has yet voiced an opinion on the matter, are
>     confirmed habitual mousers, that leaves 3% of users as mouse
>     haters.

> I am a mouse-disliker, but I am also an experienced Emacs user and I
> don't need to use the tutorial to learn how.

> I am sure there are other experienced Emacs users that dislike the
> mouse, but the question is about beginners.  Isn't it clear that nearly
> all beginners use the mouse?

Yes, but surely not all.  Might it still be that in poorer countries
there are newbies with PCs of insufficient power to support X?  There are
surely disabled people who cannot use a mouse without severe difficulty.
As well as lots of people who don't like using mice (at least 4 of whom
contribute to Emacs ;-)  [Could it perhaps be that Emacs is a magnet for
mouse-dislikers?]

I think it would be bad in an Emacs tutorial to create an impression that
a mouse was needed.  Separating out the description of `n' and `p' to an
appendix might well do this.

-- 
Alan.

Re: Info tutorial is out of date

[Sascha Wilde]

Alan Mackenzie <acm@muc.de> wrote:
> On Sun, Jul 16, 2006 at 09:40:57PM -0400, Richard Stallman wrote:
>>     Well, there are about 100 people on the Emacs project list, and 3
>>     have taken exception to your m[o]usings.  Even assuming the other
>>     ~97, none of whom has yet voiced an opinion on the matter, are
>>     confirmed habitual mousers, that leaves 3% of users as mouse
>>     haters.
>
>> I am a mouse-disliker, but I am also an experienced Emacs user and I
>> don't need to use the tutorial to learn how.

FWIW count me in...  ;-)

>> I am sure there are other experienced Emacs users that dislike the
>> mouse, but the question is about beginners.  Isn't it clear that nearly
>> all beginners use the mouse?
>
> Yes, but surely not all.  Might it still be that in poorer countries
> there are newbies with PCs of insufficient power to support X?  There are
> surely disabled people who cannot use a mouse without severe difficulty.
> As well as lots of people who don't like using mice (at least 4 of whom
> contribute to Emacs ;-)  [Could it perhaps be that Emacs is a magnet for
> mouse-dislikers?]

While I do fully agree, that changing the tutorial in a more mousy gui
clicking direction is a bad idea, I think the argumentation is getting
in the wrong direction here.  It's not primary about technologically
or physically disabled people, or about some stubborn mouse-haters --
it's about teaching beginners how to use emacs (or in this case info)
in an efficient way.

It's true, that most beginners nowadays know how to use a mouse, and
it might be also true, that most of them expect things to work by
pointing and clicking, _but_ that's not what we should teach them,
because it's not the best (fastest, efficient, most flexible) way to
do it.

Emacs is a very powerful tool (as we all know), enabling new users to
experience this power IMO means to teach them how to do it the best
way from the beginning.

Learning something new is always harder than sticking with old
habits, but it can be very enlightening, too.  :-)

cheers
sascha
-- 
Sascha Wilde
We're Germans and we use Unix. That's a combination of two 
demographic groups known to have no sense of humour whatsoever.
  -- Hanno Mueller in de.comp.os.unix.programming

Re: Info tutorial is out of date

[Robert J. Chassell]

    ... the question is about beginners.  Isn't it clear that nearly
    all beginners use the mouse?

Yes, nowadays, nearly all beginners use the mouse.  But that is not
the question.  The questions are

  * based on their previous knowledge, will beginners (who are sighted
    and using their vision and their hands) understand the use of the
    mouse in a plain Emacs or will they expect to use the mouse in a
    different way?

    Presuming that beginners single click (double clicking fails) on
    `Help', they will see the `Emacs Tutorial' listed as the first
    option and may click on that line.  (You have to read the Emacs
    manual to learn about going to the Info help.  The Emacs manual is
    nine lines down the `Help' menu.)

    The only change to Tutorial, the Emacs manual, or the Info help
    that I would suggest is writing these two sentences at or near the
    beginning:

        For many actions, you can click on a topic with a mouse
        button.  This tutorial focuses on the more efficient key
        sequences.

  * based on their previous knowledge, will beginners unlearn
    inefficent habits and begin to use key sequences appropriately?

    I hope so.  But according to my experience and all I have read, it
    is harder for people to unlearn what they learned previously than
    to learn rightly the first time.  And when undertaking a change,
    we must work with what people already know.

    The one thing we should never do is encourage the wrong habits.

The two answers mean we should not teach inefficent habits and we
should recognize that most beginners will already know conventions for
use of the mice. (Indeed, some will have learned one set of
conventions so well they will call that set `intuitive'!)

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Info tutorial is out of date

[Robert J. Chassell]

        In English, "shortcut" usually carries connotations of
        something naughty.

    Not in my English, it doesn't. Maybe that's the problem. Not in
    American English (to my knowledge); it does not. As with any word,
    it *can* carry a connotation of naughtiness, depending on the
    context.

That is a difference.  I was born an American, am an American, and
grew up learning American English.  When I was young, I used shortcuts
frequently.  Their use meant crossing others' fields and empty lots.
As a child I got away with a lot, but I learned that I was not
supposed to cross others' property without their permission.

You had a different experience than me.  It is closer to the original
American experience (in the states I know of).

In England, the presumption was that you were forbidden to walk or
hunt on others' property without permission.  In contrast,
traditionally, in the states I know of in the US, you could walk and
hunt on others' property so long as you were not visibly forbidden.
This is just the opposite of the English law.

Thus, in the US, you were legally permitted to cross a vacant lot so
long as it lacked `no tresspassing' signs.  My sense is that over the
past century or so the culture in the US has changed or is changing.
(In many states, the law has not caught up with the culture.)  Your
experience is old.  Mine is an indication of the old English and the
new American culture.

Thus, for many, the word `shortcut' does suggest badness.  

Moreover, it is more effective as a term for badness when a person
does not think of that.  That is to say, the less conscious you are

  * that the metaphor comes from the notion of crossing someone else's
    vacant lot or field, and

  * that in the culture that action is defined as wrong,

then the more useful the word is to a writer who wishes to suggest
that a `shortcut' is somewhat bad without overtly saying so.

A good writer will not even be aware of the reason he picked the word.
It will `fit' his task.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Info tutorial is out of date

[Alan Mackenzie]

Afternoon!

On Sun, Jul 16, 2006 at 10:33:42AM -0700, Drew Adams wrote:

Something I feel shouldn't be left to pass uncommented:

> The most important functions are `i', `s', `g', `l', SPC, DEL, and
> perhaps `T' and `L' (and maybe even `M-n'). They are certainly *NOT*
> `n', `p', `u', `d', and `m'.

In my own Info use, I use:

`u' and `l', `TAB' and `CR' (on links) all the time;
<page up>, <page down> also all the time;

`n' and `m' quite often, `p' a little less so.
`s', `t' and `d' every now and then.
`g' I only really use for going to an index or navigating
   "my own" info file (which I know like the back of my hand).
`[' and `]' practically never.
`i', `SPC', `DEL', `b', `q' I can't remember ever using (maybe I should
   read the tutorial ;-).

I frequently browse through the Emacs manual by following a link, then
using `u' once or twice "to find out where I am" followed by `l' to get
back to that link.

I think everybody has their own pattern for using these commands, and it
is not at all certain that `n', `p', `u', `d', and `m' are secondary in
importance.

> I think that must be our basic disagreement: what are the most
> important Info functions and features to teach? Do we need to start by
> teaching `n', `p', `u', `d', and `m'?

Disregarding `m', I think that's almost the same question as "do we wish
to teach that (most?) manuals are hierarchically structured?".

-- 
Alan.

Re: Info tutorial is out of date

[Mathias Dahl]

> It's not primary about technologically
> ...
> it's about teaching beginners how to use emacs (or in this case info)
> in an efficient way.

This "efficiency" argument comes up over and over again and I think
that should not be priority 1 here. I am all for doing things in as
efficient manner as possible (one thing Emacs is very good at) but we
should not risk scaring users by introducing unfamiliar things at the
early stages. Let efficiency come later.

If I were to introduce someone for Emacs, say by creating a small
.emacs file for them to ease things up, I would have added `cua-mode'
to that file, even though I don't use it myself (I would like to have
known about it when I first started). If this user likes Emacs I am
sure he/she will sooner or later switch to whatever is most efficient
for him/her.

So:

1. Make it easy for a beginner to find information and learn how to use Emacs.
2. Hint on how to do things more "efficient" (there are many opinions
on what is most efficient).

Re: Info tutorial is out of date

[Lennart Borgman]

Mathias Dahl wrote:
>
> 1. Make it easy for a beginner to find information and learn how to 
> use Emacs.
Yes, that is efficient -- for the beginners but not for those trying to 
make it easy for the beginners.
> 2. Hint on how to do things more "efficient" (there are many opinions
> on what is most efficient).
That is the way I believe.

Re: Info tutorial is out of date

[Richard Stallman]

		      My point is this: first things first. If I don't
		  understand what Info is all about, why would I go through
		  the effort of learning and practicing its key bindings?

	Isn't it obvious to everyone what Info is all about?  It's all about
	browsing documentation files.

    What's an Info file?

    Info is about finding information in a manual. The most important things to
    teach are the structure of the manual and how to find info in it. This

We are failing to communicate, because this isn't "what Info is all about".
What Info is all about is browsing documentation.
What you're talking about here are details of how one does that.

Re: Info tutorial is out of date

[Richard Stallman]

    > Save the teaching of why it's better to learn to use the keyboard
    > for later.

    When it will be too late for many.  If indeed it is better to use the
    keyboard (and I think it is), it seems a bad idea to begin by teaching
    bad habits, however easy these habits may be.

It is important for people to learn to use Emacs with the keyboard
rather than with the mouse.  However, the choice of keyboard or mouse
makes much less difference for Info.  So I disagree with that
conclusion when applied to the Info tutorial.

RE: Info tutorial is out of date

[Drew Adams]

    Emacs Info is too close to the standalone Info to justify two
    separate manuals

Today. But that closeness is artificial. There is no reason for a newbie
Emacs user to go through extra hoops (e.g. node `Help-Inv' and starting with
lessons on `n', `p' etc.) just for our packaging considerations. It's about
user convenience, not our own convenience.

I see no reason why we can't have two versions of the tutorial. Those two
versions could of course use single-sourcing; that is, the same source code
could be used to generate both. In documentation, that is done all the time,
and that is already the kind of thing we do when we create Info and Tex
versions of a manual from the same source code.

RE: Info tutorial is out of date

[Drew Adams]

    There are surely disabled people who cannot use a mouse without
    severe difficulty.

For "mouse" read "pointer device", and yes, for many disabled people it's
*easier* to use a pointer device than a keyboard. But this shouldn't be our
first criterion, anyway.

    I think it would be bad in an Emacs tutorial to create an
    impression that a mouse was needed.

Agreed.

    Separating out the description of `n' and `p' to an
    appendix might well do this.

Why? If those key sequences are documented, and are included in the tutorial
(even if not at the beginning), and are visible in the menu-bar Info menu,
and are available in a quick-help bound to `h', why would someone get the
impression that a mouse is necessary?

RE: Info tutorial is out of date

[Drew Adams]

    It's not primary about technologically
    or physically disabled people, or about some stubborn mouse-haters --
    it's about teaching beginners how to use emacs (or in this case info)
    in an efficient way.

    It's true, that most beginners nowadays know how to use a mouse, and
    it might be also true, that most of them expect things to work by
    pointing and clicking, _but_ that's not what we should teach them,
    because it's not the best (fastest, efficient, most flexible) way to
    do it.

I think everyone agrees that:

1. We should not teach users how to use the mouse to navigate.

2. We should not teach users that using the mouse is the best way to go.

3. We should tell users that using the keyboard is quicker than using the
mouse.

The question is whether the tutorial should start by teaching you how to
navigate with the keyboard.

    Emacs is a very powerful tool (as we all know), enabling new users to
    experience this power IMO means to teach them how to do it the best
    way from the beginning.

What's "the beginning"?  Unlike the jesuits, we don't get most new users
"from the beginning", unfortunately.

The question is whether it is more important to start the Info tutorial with
Info features, or start it with a tutorial on navigating the Info structure
with the keyboard. That's the issue we're debating, so far (hopefully, we'll
eventually move on to discuss what are the important Info features, and how
best to present them).

To me, structural navigation is not the goal; it is a means to achieve the
goal, which is getting info from a manual (whether quick look-up or
front-to-back reading).

The question is whether or not teaching structural navigation is a
prerequisite to teaching Info features. If not, it can be taught afterward,
if it is taught at all.

I claim that it is not a prerequisite for the vast majority of newbies,
because they can navigate using the mouse (which they are used to and
comfortable with). Structural navigation needs no teaching - it's obvious.

Since it is not a prerequisite to teach structural navigation, and it is not
the goal, let's relegate it to the end of the tutorial, as a Performance
Enhancement lesson. Though it's not needed to access information, it is
useful, so let's include it, but not at the start.

    Learning something new is always harder than sticking with old
    habits, but it can be very enlightening, too.  :-)

The "something new" that we really want to teach in the Info tutorial is how
to get to information that is in the manual; it is not teaching people that
the keyboard is better than the mouse.

RE: Info tutorial is out of date

[Drew Adams]

    > The most important functions are `i', `s', `g', `l', SPC, DEL, and
    > perhaps `T' and `L' (and maybe even `M-n'). They are certainly *NOT*
    > `n', `p', `u', `d', and `m'.

    In my own Info use, I use:
    `u' and `l', `TAB' and `CR' (on links) all the time;
    <page up>, <page down> also all the time;

    `n' and `m' quite often, `p' a little less so.
    `s', `t' and `d' every now and then.
    `g' I only really use for going to an index or navigating
       "my own" info file (which I know like the back of my hand).
    `[' and `]' practically never.
    `i', `SPC', `DEL', `b', `q' I can't remember ever using (maybe I should
       read the tutorial ;-).

Glad to see some discussion finally on what's important to teach in Info!
That's just what we need, to advance the schmilblick.

I don't disagree with much of what you say here, but it's good to
prioritize, since the list of useful commands is long. And thanks for
reminding us that visible links can be accessed by `CR' from the keyboard,
not just via `m' and `f' - another reason to lower the priority of teaching
`m' and `f'.

As a first step in the direction of prioritization, I would put everything
that is purely a keyboard alternative to something that is obvious (e.g. a
link or button) as a lower priority. That means: `u', `CR', `m', `p', `d',
and `f'. We don't need to drop teaching these useful shortcuts, but we can
do it later in the tutorial.

Secondly, I think <page up> and <page down> are also pretty obvious, and
don't need to be a high priority. They're not visible in Info itself, as is
a Next link, but they're pretty standard and the keys are usually labeled
appropriately.

`TAB' is useful and non-obvious, although it is of use primarily to keyboard
users. It could perhaps be presented along with SPC and DEL, which should
have a high priority, IMO. Or, it could be presented with other navigational
keyboard shortcuts, at a lower priority. The fact that it has no alternative
that is visible argues for a higher priority than things like `n' and `p'.

`q' is fairly important, and its presentation should be coupled with `C-h
i', pointing out that re-entering Info puts you back where you last were
(not an obvious feature). I imagine that you use `C-x 0', which I guess
amounts to the same thing, but a newbie might not think of it. Since `q' is
a shortcut for Quit in the menubar menu, I would not put this at a high
priority. But since the feature of re-entering where you left off is not
obvious, I would not put it at a low priority either. Pointing out this
feature is more important than teaching use of `n' and `p' to be more
efficient.

I personally would place `b', `]', and `[' at a somewhat lower priority, but
these are not obvious, so the question might be debated.

I personally would place `g' at an intermediate priority. It is not obvious,
and it has no alternative. When you need it, you need it.

    I frequently browse through the Emacs manual by following a link, then
    using `u' once or twice "to find out where I am" followed by `l' to get
    back to that link.

Interesting (and I do the same). Nothing wrong with this use pattern, but I
wonder if a command that tells you where are (in the manual hierarchy)
wouldn't be useful. It could be bound, for example, to `.' (a la `pwd').
(Yes, I know that `.' is currently a synonym for `b'.) It could display a
"breadcrumbs" message such as this: (emacs) Top > Minibuffer > Completion >
Completion Commands.

    I think everybody has their own pattern for using these commands, and it
    is not at all certain that `n', `p', `u', `d', and `m' are secondary in
    importance.

It's not that they are not important. It's that *teaching* them is less
important, because there are obvious (visible) alternatives. But we've been
'round that bush before...

    > I think that must be our basic disagreement: what are the most
    > important Info functions and features to teach? Do we need to start by
    > teaching `n', `p', `u', `d', and `m'?

    Disregarding `m', I think that's almost the same question as "do we wish
    to teach that (most?) manuals are hierarchically structured?".

It's enough to: 1) say that manuals are hierarchically structured, and 2)
point out the Next, Previous, and Up links as manifestations of this
structure. And 3) distinguish structural navigation from chronological
navigation (`l', `r').

RE: Info tutorial is out of date

[Drew Adams]

    > Newbies are overwhelmingly used to using a mouse. Let them do
    > that while they get the basics of Info.

    Once they're used to it, they're less likely to change.

They're already used to it - there are no more virgin users.

    > Save the teaching of why it's better to learn to use the keyboard
    > for later.

    When it will be too late for many.  If indeed it is better to use the
    keyboard (and I think it is), it seems a bad idea to begin by teaching
    bad habits, however easy these habits may be.

I'm not suggesting we teach them *any* way to perform simple navigation
(equivalent of `n' and `p'). On the contrary, my point was that we *need
not* teach that. There is an obvious, simple way to navigate: click a link
or navigation button. No need to teach that. If you like, later in the
tutorial we can teach quicker ways to navigate ("shortcuts").

I'm not worried about the risk that users will never learn to use `n'
instead of clicking the `Next' button. You are, apparently. Info is a
browser for finding and reading manuals. The argument for keyboard shortcuts
is vastly overstated when it comes to browsing (vs editing).

RE: Info tutorial is out of date

[Drew Adams]

    > Of course, it must tell people how to use the standalone Info reader

    Only the bare basics, because the more advanced features of the
    stand-alone Info reader are documented in a separate manual, which
    describes the stand-alone reader, and it alone.

If there is a separate standalone-reader manual, then stuff that is specific
to the standalone reader should go in that manual. That dissolves the
argument that the Info manual itself must cater to people who use only the
standalone reader.

    > Emacs Info is too close to the standalone Info to justify two
    > separate manuals, especially since many people may want to learn how
    > to use both readers and we should not force them to read two manuals
    > most of whose contents just duplicate each other.

    100% agreement.

But you just acknowledged that there are already two manuals.

Wrt duplication: Surely we can DTRT, so there is no duplication. That is a
packaging problem, and it shouldn't affect what we decide should logically
go in each manual (and the order for each).

    > The Info reader has no menu bar and no Emacs style header line.
    > Scroll bars and mice do not seem to work with it.

    The current Info manual tries (sometimes very hard) to strike the
    right balance between the handy GUI features available in Emacs and
    the total lack thereof in the stand-alone reader.

Keyboard-only stuff could be presented at the start of the standalone-reader
manual, and presented in a later part of the Info manual. The standalone
manual could be built to not include that information twice.

The presentation in each case would likely be slightly different: For Emacs
users, keyboard shortcuts would be presented as a performance-enhancement
tip. For standalone Info, they would be presented at the beginning, as a
prerequisite lesson. This could be done by single-sourcing, while still
sharing much of the content.

Yes, as Lennart pointed out, making things easier for the user sometimes
means more work for the preparer.

    It is quite
    possible that the manual can be improved, but I'd rather see a
    concrete proposal (in the form of patches or even a total rewrite)
    than hear more of the endless discussions in this thread about the
    relative merits and demerits of using the mouse and the tool bar.

I agree. A discussion on what needs to be taught, in what priority, is the
first step. I offered some suggestions, as did Alan. And on that we are not
so far apart.

    Would someone who thinks they know how to make the Info manual less
    ``out of date'' please submit their proposed changes, so we could make
    this discussion more practical?

I personally cannot contribute patches (they would not be accepted, because
I cannot get papers from my employer). In any case, starting with patches
would be premature. Let us agree on what to present and how, before getting
into the exact text.

Re: Info tutorial is out of date

[Jay Belanger]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > Newbies are overwhelmingly used to using a mouse. Let them do
>     > that while they get the basics of Info.
>
>     Once they're used to it, they're less likely to change.
>
> They're already used to it - there are no more virgin users.

They're not used to using the mouse with Emacs.

>     > Save the teaching of why it's better to learn to use the keyboard
>     > for later.
>
>     When it will be too late for many.  If indeed it is better to use the
>     keyboard (and I think it is), it seems a bad idea to begin by teaching
>     bad habits, however easy these habits may be.
>
> I'm not suggesting we teach them *any* way to perform simple navigation
> (equivalent of `n' and `p'). On the contrary, my point was that we *need
> not* teach that. There is an obvious, simple way to navigate: click a link
> or navigation button.

Falling back on that is effectively teaching them that's the way to do
it, or at least allowing them to teach themselves thats how to do it.

> I'm not worried about the risk that users will never learn to use `n'
> instead of clicking the `Next' button. You are, apparently.

Yes; but on my list of worries, this is fairly minor.

> Info is a browser for finding and reading manuals. The argument for
> keyboard shortcuts is vastly overstated when it comes to browsing
> (vs editing).

I would guess that someone using a mouse (or keyboard) for one part of
Emacs would use it throughout.

RE: Info tutorial is out of date

[Drew Adams]

    > They're already used to it - there are no more virgin users.

    They're not used to using the mouse with Emacs.

What we're talking about here is menu access and clicking links and buttons.
There is nothing Emacs-specific with how user users do those things in
Emacs - nothing new. I think you're grasping at straws, here.

    > I'm not suggesting we teach them *any* way to perform simple
    > navigation (equivalent of `n' and `p'). On the contrary, my
    > point was that we *need not* teach that. There is an obvious,
    > simple way to navigate: click a link or navigation button.

    Falling back on that is effectively teaching them that's the way to do
    it, or at least allowing them to teach themselves thats how to do it.

Not at all. At most, it could be said to *not* teach them to change their
nasty ways. But it does not teach them *anything* new about the
mouse/keyboard.

    > I'm not worried about the risk that users will never learn to use `n'
    > instead of clicking the `Next' button. You are, apparently.

    Yes; but on my list of worries, this is fairly minor.

Good. So we can take care of that minor risk later in the tutorial; it is
secondary.

    > Info is a browser for finding and reading manuals. The argument for
    > keyboard shortcuts is vastly overstated when it comes to browsing
    > (vs editing).

    I would guess that someone using a mouse (or keyboard) for one part of
    Emacs would use it throughout.

The question is, "Where is the right place to crusade for the keyboard?"
That lesson is a distraction from teaching Info.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 09:37:58 -0700
> 
> To me, structural navigation is not the goal; it is a means to achieve the
> goal, which is getting info from a manual (whether quick look-up or
> front-to-back reading).

Reading a manual in order is one paradigm of learning a package.  So
we cannot dispose of the structural navigation keys.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 09:37:57 -0700
> 
>     Emacs Info is too close to the standalone Info to justify two
>     separate manuals
> 
> Today. But that closeness is artificial.

No, it's deliberate: the Founding Fathers wanted to make sure it would
be possible to learn _an_ Info reader and use any of these two based
on that knowledge.

> I see no reason why we can't have two versions of the tutorial.

One reason is that it's not easy to present the right one to the user
based on her reader.  Remember: learning Info is a bootstrap-kind of
problem--you learn to use a tool by using that same tool.  If we don't
make the beginning of the bootstrap 110% reliable (which includes
showing the right manual), the results will be catastrophic.

Re: Info tutorial is out of date

[Jay Belanger]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > They're already used to it - there are no more virgin users.
>
>     They're not used to using the mouse with Emacs.
>
> What we're talking about here is menu access and clicking links and buttons.
> There is nothing Emacs-specific with how user users do those things in
> Emacs - nothing new. I think you're grasping at straws, here.

No.  They are being implicitly told that using the mouse is the way to
use Emacs.  No straws involved.

>     > I'm not suggesting we teach them *any* way to perform simple
>     > navigation (equivalent of `n' and `p'). On the contrary, my
>     > point was that we *need not* teach that. There is an obvious,
>     > simple way to navigate: click a link or navigation button.
>
>     Falling back on that is effectively teaching them that's the way to do
>     it, or at least allowing them to teach themselves thats how to do it.
>
> Not at all. At most, it could be said to *not* teach them to change their
> nasty ways. But it does not teach them *anything* new about the
> mouse/keyboard.

It tells them that that is how to use Emacs.  After all, what else
do they know?

> The question is, "Where is the right place to crusade for the keyboard?"

Hardly a crusade.

> That lesson is a distraction from teaching Info.

The question is whether teaching Info properly involves teaching the
keyboard or not.  On this, people can disagree, but using loaded
language is not helpful.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 09:54:09 -0700
> 
>     > Of course, it must tell people how to use the standalone Info reader
> 
>     Only the bare basics, because the more advanced features of the
>     stand-alone Info reader are documented in a separate manual, which
>     describes the stand-alone reader, and it alone.
> 
> If there is a separate standalone-reader manual, then stuff that is specific
> to the standalone reader should go in that manual.

See my other mail for the reasons why this would be not a good idea.
Isn't the fact that you didn't even know about that other manual's
existence tells volumes of why we shouldn't leave out stuff related to
its basics from the beginners' Info manual?

>     > Emacs Info is too close to the standalone Info to justify two
>     > separate manuals, especially since many people may want to learn how
>     > to use both readers and we should not force them to read two manuals
>     > most of whose contents just duplicate each other.
> 
>     100% agreement.
> 
> But you just acknowledged that there are already two manuals.

Please at least read the other manual before you argue about the
duplication issue.  They are two different manuals--different in
style, in preferences, and in target audience.

>     Would someone who thinks they know how to make the Info manual less
>     ``out of date'' please submit their proposed changes, so we could make
>     this discussion more practical?
> 
> I personally cannot contribute patches (they would not be accepted, because
> I cannot get papers from my employer).

Well, then someone else should, or else this discussion is a waste of
time.

> In any case, starting with patches would be premature. Let us agree
> on what to present and how, before getting into the exact text.

In my experience, people can argue forever about theoretical issues,
then quickly come to an agreement once a practical suggestion is put
on the table.

RE: Info tutorial is out of date

[Drew Adams]

    The question is whether teaching Info properly involves teaching the
    keyboard or not.

Not so black and white, please. It's whether it involves teaching the
keyboard *for structural navigation* *first*, *when* that structural
navigation can be accomplished in another, obvious way (e.g. click a link).

I've already said it makes sense to teach some keys up front (e.g. SPC,
DEL), because there is no alternative.

And I've already said it's OK to teach even the structural navigation keys,
after the important stuff has already been covered.

You want the question to be mouse vs keyboard, pure & simple. I want it to
be important functionalities first, performance enhancements second. I don't
care about mice or keyboards, one way or the other (except that I am, like
you are, in favor of recommending keys for efficiency).

Some keyboard keys are necessary to use Info, and some are unnecessary, even
if useful for efficiency. The necessary keys should be taught up front; the
unnecessary keys can be taught afterward.

No one has ever argued that no Info keys should be taught. Please stop
misrepresenting what I've said.

RE: Info tutorial is out of date

[Drew Adams]

    >     > Of course, it must tell people how to use the
    >     > standalone Info reader
    >
    >     Only the bare basics, because the more advanced features of the
    >     stand-alone Info reader are documented in a separate manual, which
    >     describes the stand-alone reader, and it alone.
    >
    > If there is a separate standalone-reader manual, then stuff
    > that is specific
    > to the standalone reader should go in that manual.

    See my other mail for the reasons why this would be not a good idea.

I read your other emails (unless there is yet another somewhere), and I
didn't see any reasons for this. Please point them out. I saw some
hand-waving about bootstrapping, but I saw no "reasons why this would be not
a good idea."

    Isn't the fact that you didn't even know about that other manual's
    existence tells volumes of why we shouldn't leave out stuff related to
    its basics from the beginners' Info manual?

No, I don't see the relation between my ignorance of the standalone-reader
manual and "why we shouldn't leave out stuff..." What's the connection? What
volumes does it tell? Can you be specific? You seem to be making an argument
to Authority and to hard-to-understand Complexity, but no specific obstacle
has been identified yet, AFAICT.

On the one hand, you call for concrete patches now ("put up or shut up", so
to speak), but on the other hand, your reasons given for your point of view
are nebulous.

    >     > Emacs Info is too close to the standalone Info to justify two
    >     > separate manuals, especially since many people may want
    >     > to learn how
    >     > to use both readers and we should not force them to
    >     > read two manuals
    >     > most of whose contents just duplicate each other.
    >
    >     100% agreement.
    >
    > But you just acknowledged that there are already two manuals.

    Please at least read the other manual before you argue about the
    duplication issue.  They are two different manuals--different in
    style, in preferences, and in target audience.

You should be able to characterize the difference for those of us on the
list. If there is a standalone-reader manual, then why not put stuff
specific to only the standalone reader in it (regardless of whether it is
advanced or not)? What's the obstacle to doing that? Why wouldn't that be
appropriate?

    >     Would someone who thinks they know how to make the Info
    >     manual less
    >     ``out of date'' please submit their proposed changes, so
    >     we could make
    >     this discussion more practical?
    >
    > I personally cannot contribute patches (they would not be
    > accepted, because
    > I cannot get papers from my employer).

    Well, then someone else should, or else this discussion is a waste of
    time.

Agreed, but design first, code second.

    > In any case, starting with patches would be premature. Let us agree
    > on what to present and how, before getting into the exact text.

    In my experience, people can argue forever about theoretical issues,
    then quickly come to an agreement once a practical suggestion is put
    on the table.

We all have experience of that, and also of headlong thrust into the wrong
implementation, without having discussed things and thought them through.
Pitfalls both ways. No sense arguing in that abstract way - please be
specific.

And, if patches do arrive, I'm not saying they shouldn't be discussed.

Anyway, I'm not convinced that we are arguing forever about abstractions.
AFAICT, even some (all?) of those adamant anti-mousers have said they agree
with most of my suggestions for the tutorial. If we can ever get past the
keyboard/mouse thing, then I think some progress might be made.

In the interest of advancing, we could even agree to table the question of
presenting `n', `p', etc., and come back to it later, after making some
headway improving Info along lines we might agree to. It's really not the
most important suggestion I made. You guys are tough to reason with, so I
give up on that argument, for now. Fuggeddabbouddit.

RE: Info tutorial is out of date

[Drew Adams]

    >     Emacs Info is too close to the standalone Info to justify two
    >     separate manuals
    >
    > Today. But that closeness is artificial.

    No, it's deliberate: the Founding Fathers wanted to make sure it would
    be possible to learn _an_ Info reader and use any of these two based
    on that knowledge.

But you pointed out things that go against that aim of the FFs, and you
pointed out that because of those things there are (already) two manuals.

    > I see no reason why we can't have two versions of the tutorial.

    One reason is that it's not easy to present the right one to the user
    based on her reader.  Remember: learning Info is a bootstrap-kind of
    problem--you learn to use a tool by using that same tool.  If we don't
    make the beginning of the bootstrap 110% reliable (which includes
    showing the right manual), the results will be catastrophic.

So, how do you deal with that problem currently, since there are apparently
already two manuals? Somehow, you are able to tell, and to give the
standalone-reader reader the standalone-only manual.

Your bootstrap doesn't need to teach anything about `n' and `p', does it?
This is all very abstract. Why don't you show us something concrete that
presents a real obstacle to doing things the right way?

RE: Info tutorial is out of date

[Drew Adams]

    > To me, structural navigation is not the goal; it is a means
    > to achieve the
    > goal, which is getting info from a manual (whether quick look-up or
    > front-to-back reading).

    Reading a manual in order is one paradigm of learning a package.  So
    we cannot dispose of the structural navigation keys.

No. The proper conclusion is that we cannot dispose of *structural
navigation*. This does not necessarily have anything to do with *keys*.

Anyway, no one proposed to dispose of either structural navigation or
structural-navigation keys. The proposal was to *postpone* (not dispose of)
*teaching* about structural-navigation *keys*. Each of those 3 qualifiers is
important.

And then, only the keys that have obvious, visible alternatives would be
taught later. I specifically argued for teaching SPC and DEL up front. You
can read an entire manual, in order, from front to back, using just SPC.

I didn't paint things in black & white terms, and it's not honest to
characterize my proposal that way.

Re: Info tutorial is out of date

[Richard Stallman]

	The only change to Tutorial, the Emacs manual, or the Info help
	that I would suggest

The Emacs tutorial and the Info tutorial are two different questions.
The Emacs tutorial teaches the keys because that's the efficient way
to edit with Emacs.  But the subject here is the Info tutorial.  That is
a different issue, because

(1) it's more basic
(2) it's not about how to use Emacs, it's about how to use Info
(3) it's not just for use IN Emacs

Re: Info tutorial is out of date

[Richard Stallman]

    Of course, Emacs users must also be able to learn how to use Emacs
    Info.  Emacs Info is too close to the standalone Info to justify two
    separate manuals, especially since many people may want to learn how
    to use both readers and we should not force them to read two manuals
    most of whose contents just duplicate each other.

Absolutely right.

    The Info reader has no menu bar and no Emacs style header line.
    Scroll bars and mice do not seem to work with it.

I did not know that.

We should make it support X (I will add that to our task list).  In
the mean time, this means that the Info tutorial must not assume a
mouse.

Nonetheless, some of the suggested changes that Drew made are good ones.
The topic of invisible text is confusing, and some of the commands
could be done in a different order.

Re: Info tutorial is out of date

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> I think it's pretentious to think that we can influence people's habits
> so easily.

I don't think so.

My observation has been that the sort of person who tries Emacs _at all_
(which e.g. excludes your average PHB etc) is relatively open-minded
about such things, and willing to give something "new" (heh) a go.

It's perhaps silly for a tutorial to pretend the mouse/etc don't exist,
but basically people already know how to use them, so I think not much
really be said other than a note explaining _why_ the tutorial
concentrates on key bindings.

-Miles
-- 
My spirit felt washed.  With blood.  [Eli Shin, on "The Passion of the Christ"]

Re: Info tutorial is out of date

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> Key bindings *are* shortcuts - what's wrong with that? 1) They are
> commonly called "keyboard shortcuts" by many people. 2) They are
> shorter (quicker) to use than clicking menus and links with a mouse -
> don't you agree? They are shorter (quicker) than using `M-x' - don't
> you agree? What is it about "shortcut" that sets you off?

It's a loaded term -- it implies that they are a "quick _alternative_"
to some other primary, more "proper," method of invoking the command.

[Surely you knew that... it's hardly a new topic in Emacs mailing lists...]

I think the term "shortcut", while common among the GUI set, actually
does do some harm by subtly encouraging people to think of menus as the
"standard" way of doing things.  For that reason, it really should only
be used in applications where that is indeed true, not in applications
like Emacs where it is most certainly not true.

-Miles
-- 
97% of everything is grunge

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 16:01:16 -0700
> 
>     > If there is a separate standalone-reader manual, then stuff
>     > that is specific
>     > to the standalone reader should go in that manual.
> 
>     See my other mail for the reasons why this would be not a good idea.
> 
> I read your other emails (unless there is yet another somewhere), and I
> didn't see any reasons for this. Please point them out.

The need to have the Info manual be the first manual they read.

> I saw some hand-waving about bootstrapping

Sigh.  Do you really think this style facilitates fruitful discussion?

>     Isn't the fact that you didn't even know about that other manual's
>     existence tells volumes of why we shouldn't leave out stuff related to
>     its basics from the beginners' Info manual?
> 
> No, I don't see the relation between my ignorance of the standalone-reader
> manual and "why we shouldn't leave out stuff..." What's the connection? What
> volumes does it tell? Can you be specific?

Specifically, it is not a good idea to describe basic stuff in a
manual that no one will find.
>     Please at least read the other manual before you argue about the
>     duplication issue.  They are two different manuals--different in
>     style, in preferences, and in target audience.
> 
> You should be able to characterize the difference for those of us on the
> list.

But I just did--in the text you cited above.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 16:01:16 -0700
> 
>     > I see no reason why we can't have two versions of the tutorial.
> 
>     One reason is that it's not easy to present the right one to the user
>     based on her reader.  Remember: learning Info is a bootstrap-kind of
>     problem--you learn to use a tool by using that same tool.  If we don't
>     make the beginning of the bootstrap 110% reliable (which includes
>     showing the right manual), the results will be catastrophic.
> 
> So, how do you deal with that problem currently, since there are apparently
> already two manuals?

By having the Info manual be the first item in the top-level menu.

> Your bootstrap doesn't need to teach anything about `n' and `p', does it?

I think it does, because users should know how to navigate the
structure of a manual.

RE: Info tutorial is out of date

[Drew Adams]

    > Key bindings *are* shortcuts - what's wrong with that? 1) They are
    > commonly called "keyboard shortcuts" by many people. 2) They are
    > shorter (quicker) to use than clicking menus and links with a mouse -
    > don't you agree? They are shorter (quicker) than using `M-x' - don't
    > you agree? What is it about "shortcut" that sets you off?

    It's a loaded term -- it implies that they are a "quick _alternative_"
    to some other primary, more "proper," method of invoking the command.

"Quick alternative" doesn't sound bad or loaded to me. Is "quick" bad
(quicky, perhaps)? Do you think "alternative" is loaded? Is an alternative
something inferior, or superior, or nasty for you? Is the problem that
"shortcut" is inferior and naughty or superior and haughty? This really
seems to be getting silly. I feel like I must not be in Kansas anymore...

    [Surely you knew that... it's hardly a new topic in Emacs
    mailing lists...]

Knew what? That keyboard shortcuts are quick alternatives to actions that
take longer? Yes; I knew that. That "keyboard shortcut" is a loaded term?
No; I did not know that, and I still don't know it. Do you know that?

And no, this is the first time I've fallen into the keyboard-shortcut bear
trap and been surrounded by angry spears. I've been reading this list for a
couple of years, but this reaction was a surprise to me. Learn something new
about those who inhabit the list every day...

    I think the term "shortcut", while common among the GUI set, actually
    does do some harm by subtly encouraging people to think of menus as the
    "standard" way of doing things.  For that reason, it really should only
    be used in applications where that is indeed true, not in applications
    like Emacs where it is most certainly not true.

Why do you say "menus"? I didn't. I mentioned menus and links and "using
`M-x'". I don't think of key bindings as shortcuts for just menu access. In
Emacs, they are shortcuts for commands, whether `M-x <command>' or menu
access or even macro execution. They are, in fact, "keyboard shortcuts" for
longer ways of doing things. I don't think of menus or link clicks or
`M-x...' as being more or less "proper" or "naughty" than key sequences.
Honestly, that dimension is not even on my moral map. I just don't worry
about that at all, least of all ethically.

What could be clearer than the term "keyboard shortcut" for a keyboard
action that is quicker than doing something else? In fact, now that I think
of it, although "key binding" and "key sequence" are more precise terms _for
Emacs_ (because key sequences are bound to commands and macros in Emacs), in
general (that is, not just in Emacs), the better term is probably "keyboard
shortcut", because such a beast could presumably be short for anything - any
action that's, well, longer, and, outside Emacs, there is not necessarily a
notion of "binding" the shortcuts.

RE: Info tutorial is out of date

[Drew Adams]

    >     > If there is a separate standalone-reader manual, then stuff
    >     > that is specific
    >     > to the standalone reader should go in that manual.
    >
    >     See my other mail for the reasons why this would be not a
    >     good idea.
    >
    > I read your other emails (unless there is yet another
    > somewhere), and I didn't see any reasons for this.
    > Please point them out.

    The need to have the Info manual be the first manual they read.

And what is the problem in that regard? I'm not assuming they need to read
any other manual first.

    > I saw some hand-waving about bootstrapping

    Sigh.  Do you really think this style facilitates fruitful discussion?

I'm really trying to understand you, Eli. Give me something concrete to get
hold of. Just what is the problem?

    >     Isn't the fact that you didn't even know about that other manual's
    >     existence tells volumes of why we shouldn't leave out
    >     stuff related to
    >     its basics from the beginners' Info manual?
    >
    > No, I don't see the relation between my ignorance of the
    > standalone-reader manual and "why we shouldn't leave out
    > stuff..." What's the connection? What volumes does it tell?
    > Can you be specific?

    Specifically, it is not a good idea to describe basic stuff in a
    manual that no one will find.

Which basic stuff are we talking about? Which manual? Why won't they find
it? I don't follow you at all, and I'm trying to. What is the problem you're
trying to describe?

    >     Please at least read the other manual before you argue about the
    >     duplication issue.  They are two different manuals--different in
    >     style, in preferences, and in target audience.
    >
    > You should be able to characterize the difference for those
    > of us on the list.

    But I just did--in the text you cited above.

Well, I give up. Sorry, I just don't understand your point.

RE: Info tutorial is out of date

[Drew Adams]

    >     > I see no reason why we can't have two versions of the tutorial.
    >
    >     One reason is that it's not easy to present the right one
    >     to the user based on her reader.  Remember: learning Info is a
    >     bootstrap-kind of problem--you learn to use a tool by using
    >     that same tool. If we don't
    >     make the beginning of the bootstrap 110% reliable (which includes
    >     showing the right manual), the results will be catastrophic.
    >
    > So, how do you deal with that problem currently, since there
    > are apparently already two manuals?

    By having the Info manual be the first item in the top-level menu.

And? That sounds OK to me.

    > Your bootstrap doesn't need to teach anything about `n' and
    > `p', does it?

    I think it does, because users should know how to navigate the
    structure of a manual.

If the `n' and `p' stuff is a prerequisite for standalone-Info users, can't
that stuff be put first for them?

And if `n' and `p' is not a prerequisite for Emacs-Info users, can't it be
put last? I don't understand why this is so hard. I'm not saying it's not
hard; I'm saying I don't understand the problem.

Re: Info tutorial is out of date

[Luc Teirlinck]

Richard Stallman wrote:

   Nonetheless, some of the suggested changes that Drew made are good ones.
   The topic of invisible text is confusing

I do not see what is confusing about it.  It has been claimed that it
is not very useful.  But it really is, for people using Info from
within Emacs.  The fact that quite a bit of text appears apparently
out of nowhere when yanking, printing or writing to a file can be very
confusing to people (I still quite often get surprised by it and I can
only imagine how confusing it can be for less experienced users).  The
node explains to people why that happens and how they can see exactly
what they are going to yank, print or write to file by temporarily
making all text visible using visible-mode.  This is useful knowledge,
not just for Info, but for other Emacs buffers with invisible text as well.

`visible-mode' which is introduced in this node, is used later to help
users who want to learn how to use both the Emacs and standalone Info
readers see how the same text looks in the standalone reader (and
hence understand remarks about that reader) without actually having to
launch that reader and search for the same example text in that reader.

The note also explains how readers who prefer to have the info that
Emacs (but not the standalone reader) hides by default available in
Emacs as well, can achieve that by using `Info-hide-note-references'.

I believe that all of this is useful information and the node is not
even very long.

Note that the decision to add that material to the Info manual was
made after quite some discussion on Emacs devel, with your approval
and with Karl's support.

Sincerely,

Luc.

RE: Info tutorial is out of date

[Drew Adams]

       Nonetheless, some of the suggested changes that Drew made
       are good ones. The topic of invisible text is confusing

    I do not see what is confusing about it.  It has been claimed that it
    is not very useful.  But it really is, for people using Info from
    within Emacs.  The fact that quite a bit of text appears apparently
    out of nowhere when yanking, printing or writing to a file can be very
    confusing to people (I still quite often get surprised by it and I can
    only imagine how confusing it can be for less experienced users).  The
    node explains to people why that happens and how they can see exactly
    what they are going to yank, print or write to file by temporarily
    making all text visible using visible-mode.

And the relation to Info is?

    This is useful knowledge, not just for Info, but for other
    Emacs buffers with invisible text as well.

To the question "What does it have to do with *Info*?", you seem to have
answered: nothing; it's not Info-specific.

In that case, it doesn't belong in an Info tutorial. It sounds like an
attempt to explain an Emacs invisible-text gotcha. Put it in the Emacs
manual where invisible text is discussed - after making it comprehensible.

    `visible-mode' which is introduced in this node, is used later to help
    users who want to learn how to use both the Emacs and standalone Info
    readers see how the same text looks in the standalone reader (and
    hence understand remarks about that reader) without actually having to
    launch that reader and search for the same example text in that reader.

Ah, that's what I gathered too. If that's the raison d'etre, then I say toss
it. Put it somewhere else if you like, but certainly not near the beginning
of the Info tutorial that beginner Emacs users will follow _to try to
understand how to use a manual_. It has no place there.

Besides, it's so poorly written that it is, to me, incomprehensible.

Before you explained it, I thought maybe there would be some argument for it
in the tutorial, once I understood more. Now that I understand (a little)
more, it seems to be totally inappropriate for the Info tutorial.

*IF* (I, for one, am not convinced) it were important for people who would
be using both Emacs and the standalone Info, as you say, then it could be
part of the Info _manual_ (not the tutorial). It is not written as a
tutorial procedure, anyway.

On the other hand, you seem to suggest that it is not Info-specific, and
describes an invisible text gotcha whose scope is Emacs. In that case, it
belongs in the Emacs manual (after rewriting), if it is important/useful.

    The note also explains how readers who prefer to have the info that
    Emacs (but not the standalone reader) hides by default available in
    Emacs as well, can achieve that by using `Info-hide-note-references'.

Somewhere else, please.

    I believe that all of this is useful information and the node is not
    even very long.

I believe that all of this is N characters too long, where N is its length.

    Note that the decision to add that material to the Info manual was
    made after quite some discussion on Emacs devel, with your approval
    and with Karl's support.

Maybe it's just in the wrong place, and needs to be rewritten a bit.

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> I feel like I must not be in Kansas anymore...  [...]  Learn
> something new about those who inhabit the list every day...

that's good to hear!

thi

Re: Info tutorial is out of date

[Alan Mackenzie]

Good morning, Drew!

On Mon, Jul 17, 2006 at 04:01:16PM -0700, Drew Adams wrote:
>     > To me, structural navigation is not the goal; it is a means
>     > to achieve the
>     > goal, which is getting info from a manual (whether quick look-up or
>     > front-to-back reading).

>     Reading a manual in order is one paradigm of learning a package.  So
>     we cannot dispose of the structural navigation keys.

> No. The proper conclusion is that we cannot dispose of *structural
> navigation*. This does not necessarily have anything to do with *keys*.

Just like travelling by car doesn't necessarily have anything to do with
the steering wheel or brake pedal, you mean?

> Anyway, no one proposed to dispose of either structural navigation or
> structural-navigation keys. The proposal was to *postpone* (not dispose
> of) *teaching* about structural-navigation *keys*. Each of those 3
> qualifiers is important.
 
This is what gets up my nose about what you're proposing.  All your
proposals would marginalise keyboard use.  Please recognise this, and
acknowledge that it isn't just a minor side effect, it's a critical and
essential feature of your proposed change.

You've described me and a few other people as "mouse haters".  This is
uncalled for, since my only "hate" is the resentment at being forced to
use the animal myself.  It would be more apt to describe the "other side"
as "keyboard haters": they are steadily erradicating keyboard use for
anything other than typing letters and numbers.  Firstly, they move the
documentation of key sequences away from where people will see them (as
in Gnome), then they make them unusably clunky (SuSE 8.0's installation
program was like this - that was the last SuSE I ever bought), thirdly
they leave them non-functional, presumably by bolting them on as an
afterthought and not testing them (there are lots of proprietary programs
like this).

You're proposing the first of these things.  If you "postpone" their
description to a place where it costs readers effort to find, that's
hardly better than leaving them out altogether.  I can assure you it is
maddeningly frustrating to read about some interesting feature described
with mouse actions, then have to search out a node called "Keyboard
Shortcuts", scan through a long, long table to find what could be this
feature, try it out, then somehow get back to the original node.

The structural navigation keys need to be described together with
structural navigation.  Surely?

> I didn't paint things in black & white terms, and it's not honest to
> characterize my proposal that way.

Please recognise the validity of the way other people see your proposal.

-- 
Alan.

Re: Info tutorial is out of date

[Richard Stallman]

	Emacs Info is too close to the standalone Info to justify two
	separate manuals

    Today. But that closeness is artificial.

No, they are intentionally compatible, with the same commands.

    I see no reason why we can't have two versions of the tutorial.

I don't want to maintain two.  One is enough trouble.

Re: Info tutorial is out of date

[David Hansen]

On Mon, 17 Jul 2006 20:12:22 -0400 Richard Stallman wrote:

> (3) it's not just for use IN Emacs

BTW, the rodent isn't working in the stand alone info reader
(at least not on my debian default install).

David

Re: Info tutorial is out of date

[Stefan Monnier]

> It's perhaps silly for a tutorial to pretend the mouse/etc don't exist,
> but basically people already know how to use them, so I think not much
> really be said other than a note explaining _why_ the tutorial
> concentrates on key bindings.

I think it should concentrate on features instead.  One of the features is
its perfect support for mouse-free use.  But I'm not sure it should be the
first feature mentioned.  Index lookup (i), manual-wide search (M-s), and
linear  traversal (SPC), should come before, IMO,


        Stefan

"shortcut"

[Richard Stallman]

I am not following the discussion of "shortcut" because it
does not seem like a topic worth discussing.

Re: Info tutorial is out of date

[Richard Stallman]

      The fact that quite a bit of text appears apparently
    out of nowhere when yanking, printing or writing to a file can be very
    confusing to people (I still quite often get surprised by it and I can
    only imagine how confusing it can be for less experienced users).

Copying text from an Info file is not a beginner activity.
Printing one is something a beginner might do, from confusion,
but it is not normal beginning use of Info.

It is a mistake to document obscure potentially-confusing usages
so early in the documentation for beginners.

So I believe it should be moved to an intermediate or advanced
section.

RE: Info tutorial is out of date

[Drew Adams]

    Good morning, Drew!

Good morning, Alan!

    >     So we cannot dispose of the structural navigation keys.

    > No. The proper conclusion is that we cannot dispose of *structural
    > navigation*. This does not necessarily have anything to do
    > with *keys*.

    Just like travelling by car doesn't necessarily have anything to do with
    the steering wheel or brake pedal, you mean?

No, just like traveling doesn't necessarily have anything to do with
traveling by car or using a steering wheel or a brake pedal. There are other
ways to travel than by car. (Or, perhaps it would be a closer analogy to say
that traveling by car doesn't necessarily have anything to do with using a
clutch.)

    > Anyway, no one proposed to dispose of either structural navigation or
    > structural-navigation keys. The proposal was to *postpone*
    > (not dispose of) *teaching* about structural-navigation *keys*.
    > Each of those 3 qualifiers is important.

    This is what gets up my nose about what you're proposing.  All your
    proposals would marginalise keyboard use.  Please recognise this, and
    acknowledge that it isn't just a minor side effect, it's a critical and
    essential feature of your proposed change.

First, not "all" of my proposals - only the discussion about structural
navigation. Again, gray, not black or white, all or nothing.

Second, those proposals about not teaching structural navigation would
marginalize (make unnecessary, because already unnecessary) keyboard use
_for following the Info tutorial_. That's all.

And not even that - just the first part of the tutorial. I'm in favor of
adding a lesson at the end about navigating quicker using the keyboard.
Think of it: call it "Advanced Navigation" or "Improved Navigation" or
"Super Navigation" or whatever, and newbies will be dying to learn about it.
It's just that learning that first gets in the way of learning the real
subject matter of Info: getting information from the manual.

    You've described me and a few other people as "mouse haters".  This is
    uncalled for, since my only "hate" is the resentment at being forced to
    use the animal myself.

Sorry. I'm sure you don't hate mice. And I assure you that I don't want to
force you to use a mouse.

You are not the target of the Info tutorial. And I don't even want to force
the target audience, beyond the first few tutorial lessons. And I don't
think of it as _forcing_ them, even for those first few lessons, because it
is what they are already comfortable doing. It's really not about you, Alan,
any more than it's about me. It's about Emacs newbies, who are, for the most
part, mouse oldbies.

The mouse and menu use is, in some ways, the lowest common denominator - not
in terms of platforms and hardware, but in terms of newbie knowledge. That
doesn't mean that newbies will stick with the mouse; it means that they can
rapidly appropriate & absorb the essentials of an application using the
mouse, without having to first learn other (perhaps better) ways of
interaction.

    It would be more apt to describe the "other side" as "keyboard
    haters":

Well, I'm not sure who is on that "other side", then; I'm not, in any case,
as I think I've made clear. I use the keyboard almost exclusively in Info
(for example), though I do click the occasional link, and I've stated
repeatedly that we should recommend to users that using the keyboard is
better (for N reasons etc.). I've pronounced in favor of keeping `n' etc. in
the tutorial, just moving that lesson out of the way from the beginning of
it.

    they are steadily erradicating keyboard use for
    anything other than typing letters and numbers.  Firstly, they move the
    documentation of key sequences away from where people will see them (as
    in Gnome),

I'm ignorant of all this (I don't use Gnome, unless I'm unaware of doing so
on Linux - is `gt' gnome terminal?). I'm in favor of showing shortcuts next
to menu items, and I even suggested that we could (though I stopped short of
saying that we should) add them next to "Next:" etc. buttons in Info: "Next
(`n'):".

    then they make them unusably clunky (SuSE 8.0's installation
    program was like this - that was the last SuSE I ever bought), thirdly
    they leave them non-functional, presumably by bolting them on as an
    afterthought and not testing them (there are lots of
    proprietary programs like this).

As I say, I'm ignorant of this trend. I do recognize that most apps except
Emacs don't treat shortcuts with the respect they deserve, but I can tell
you that professional users of an (old and old-fashioned) application that I
use everyday, Framemaker, use the shortcuts, simply because, well, they're
shortcuts. Some Framemaker pros don't, but most do.

I suspect this might be the tendency in apps (those that provide shortcuts):
new users use the menus (menubar, popup), toolbar and such. As they become
more familiar and proficient with the app (and the menus help them learn the
lay of the land - *very* helpful in learning), they start using keyboard
shortcuts. I know I'm like that, as are all of my colleagues. Call us lazy
or ignorant, but that's how we proceed. Almost anyone who uses an app a lot
will look for shortcuts (in the general sense of the term, not just keyboard
shortcuts), but s?he might not do that the first day.

It's important to make things easy for newbies, make them feel comfortable
and feel as if the app is not too complex and intimidating. (This is all the
more true of Emacs, which has a reputation of being complex.)

Seeing the topography of an entire app through a menu - even if you don't
use all of the menu items right away, is an important part of getting to
know the app and feeling comfortable with it. It's like reading the Emacs
manual about things that you might not use right away: you learn what's
available. A menu can serve as a feature list, and it is even hierarchically
organized - it is an outline of available features, to some extent.

Anyway, I don't mean to "push" the utility of menus too much here; my point
in saying this is that this is how, I think, most newbies (and that's all of
us, for some apps) explore and learn what an app can do. It's not
necessarily how they end up doing things with the app. Give people credit:
if they do some operation a lot, they will find the quick, efficient way to
do it. Yes, if they don't do some operation a lot, they might stick with an
inefficient, but obvious (visible) way to do it. There's no great harm in
that, IMO.

    You're proposing the first of these things.  If you "postpone" their
    description to a place where it costs readers effort to find, that's
    hardly better than leaving them out altogether.

I recognize your argument, really I do. It's true that if the Info tutorial
starts out with a lesson on using the keyboard and why it is preferable,
instead of leaving this until later, then keyboard use is emphasized more.

But that's just why I want to move it until later - yes, I want to emphasize
it less - _relative_ to what's important to teach about Info. If we accept
your argument about order, then doing it your way, by your logic, would mean
that people would give up on the real lessons on Info. If the meat of the
tutorial is "postponed" "to a place where it costs readers effort to find",
then "that's hardly better" than leaving the real meat of the tutorial out
altogether. That's your argument, as well as mine: what comes later is
emphasized less.

And that's precisely my point, from the beginning. Yes, I'm trying to favor
the teaching of Info over the teaching to use the keyboard instead of the
mouse. I think that's appropriate. It doesn't mean I don't want to teach use
of the keyboard and recommend it over mouse use. It means I want to teach
Info first. I don't apologize for that priority preference.

    I can assure you it is
    maddeningly frustrating to read about some interesting feature described
    with mouse actions, then have to search out a node called "Keyboard
    Shortcuts", scan through a long, long table to find what could be this
    feature, try it out, then somehow get back to the original node.

I'm sure it is, although I think you overstate the frustration.

On the other foot, isn't it maddeningly frustrating to have to search out a
node about how to look look up a topic in the manual, and plod through
relatively uninteresting lessons on `n' and `p' to finally get to the heart
of the matter?

    The structural navigation keys need to be described together with
    structural navigation.  Surely?

As I've said several times, I would not teach structural navigation,
_except_ as a later lesson that introduces `n', `m' etc. IOW, yes, not only
describe them together, but describe *only* key bindings for structural
navigation - I would not teach any other way to navigate structurally.

Ah, but you'll say, "Drew, you might not teach structural navigation with
the mouse explicitly, as a lesson, but you're teaching it implicitly, by
using it while teaching the important stuff."

Mea culpa. It's not a conspiracy, believe me; it's just an attempt to cut
down on teaching stuff (explicitly) that isn't a prerequisite to getting to
the heart of the matter. We can teach it (explicitly); readers will get to
it, but they will learn the more important stuff first. We might disagree on
what's the most important stuff to teach about Info; I'm not sure. If we
don't, then perhaps the only disagreement is whether we should start with
the important stuff or start with `n' etc., to make sure that readers don't
miss learning the latter.

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> It's just that learning that first gets in the way of learning the
> real subject matter of Info: getting information from the manual.

sometimes people get info from a manual by sequential browsing.
for some manuals/people/situations, this is the most natural way.

the attitude is not "i want to find out foo, don't hold me back
and waste my time w/ anything that is not foo!".

instead, it is "i think foo is in there somewhere, i'll just look
over this stuff before and around it while i'm at it.  who knows?
these might be related to foo or make it even clearer when i find it."

thi

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> On the other foot, isn't it maddeningly frustrating to have to
> search out a node about how to look look up a topic in the
> manual, and plod through relatively uninteresting lessons on `n'
> and `p' to finally get to the heart of the matter?

i don't think so.  a good tutorial is comforting at the beginning
like that, because review of familiar concepts (in this case
"next" and "previous" being consistently and coherently accessible
with `n' and `p', just like much the rest of emacs) eases the mind
into accepting new ones.  kind of like stretching before jogging.

if the concepts are not familiar, then hey, bonus.  new stuff to
enjoy.  if the concepts are familiar to the point of frustration,
a few taps on (the familiar) `n' and you are on your way.

remember, the active verb from the reader's pov is "to learn".
novelty helps learning, but also overlapping review.  that is the
actual "heart of the matter".  we cannot teach (whisk people to
the destination), we can only make the journey pleasant (present
things in a way that builds consistently upon the past).

there is no real need to wow people w/ info's features, as cool
as they are.  there is, however, a need to prevent mental schism
between info and other emacs subsystems.  if the schism can be
averted, people will wow themselves w/ what they find.  bonus:
they will be less likely to feel put upon, hoodwinked, manhandled
maltreated, rushed-along, perturbed, railroaded, cajoled or coerced.

IMHO, moving basic navigation commands to the end, as an
afterthought, runs the risk of these misunderstandings arising.
it's always easier to forego a feast than to forgive a famine.

thi

RE: Info tutorial is out of date

[Drew Adams]

    > It's just that learning that first gets in the way of learning the
    > real subject matter of Info: getting information from the manual.

    sometimes people get info from a manual by sequential browsing.
    for some manuals/people/situations, this is the most natural way.

    the attitude is not "i want to find out foo, don't hold me back
    and waste my time w/ anything that is not foo!".

    instead, it is "i think foo is in there somewhere, i'll just look
    over this stuff before and around it while i'm at it.  who knows?
    these might be related to foo or make it even clearer when i find it."

Agreed 100%, and I've stated that more than once in this thread. Both
browsing and reading the manual from front to back are useful ways to "get
information from the manual", in addition to, say, search and look-up in an
index, TOC, or glossary. All ways of getting information from the manual are
useful subjects for the tutorial.

I've stated time and again that I consider teaching SPC and DEL to be
important. SPC is really all you need to read a manual from front to back,
and together with `Next', `Previous' and the other structural-navigation
buttons and links, SPC provides all you need to browse at will, in any
direction.

FWIW, here are some of the places (quotes), throughout my posts on this
thread, where I stressed the importance of teaching SPC and DEL:

* In addition to the features in the menu-bar menu, teach SPC and DEL -
that's about it. [That's from my first post, opening the thread.]

* The most important functions are `i', `s', `g', `l', SPC, DEL, and...

* ...presented along with SPC and DEL, which should have a high priority,
IMO.

* It's also important to teach the key bindings that are not in the menu-bar
menu - SPC and DEL.

* 1) teach what Info is about, first;
  2) start using the obvious how-to (e.g. links, buttons,
     menu-bar), to teach #1;
  3) teach the non-obvious how-to (e.g. SPC, DEL) also;
  4) don't bother teaching the obvious, if more-efficient, how-to
     (e.g. `n'), except possibly as an efficiency booster, after
     getting the real message across.

* (`h' would mention SPC and DEL also, which the menu-bar menu doesn't
show.)

* I also mentioned the need to have specific tutorial instruction for those
keys (e.g. SPC and DEL) that are *not* so obvious.

* On the contrary, didn't I say that SPC and DEL should be taught explicitly
(and early) in the tutorial, because they are not obvious (visible)?

I don't see how anyone reading my posts can think that I don't acknowledge
that reading the manual from front to back and browsing it are both ways to
"get information from the manual", and therefore subjects for the tutorial.
I'm sure lots of people have given up on reading all of my posts (I don't
blame them!), but for those who have read them, I don't see how they could
not understand that I recognize manual browsing as important.

Re: Info tutorial is out of date

[Thien-Thi Nguyen]

"Drew Adams" <drew.adams@oracle.com> writes:

> I don't see how they could not understand that I recognize
> manual browsing as important.

when you use terms like "heart of the matter" and "real goal",
it is easy for me to mistake that emphasis on other features as
a de-emphasis on simple browsing.  perhaps others are the same.

i must also confess that i can't keep up w/ the volume of the
discussion.  i'll bow out of this thread now.

thi

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 21:37:27 -0700
> 
>     >     > If there is a separate standalone-reader manual, then stuff
>     >     > that is specific
>     >     > to the standalone reader should go in that manual.
>     >
>     >     See my other mail for the reasons why this would be not a
>     >     good idea.
>     >
>     > I read your other emails (unless there is yet another
>     > somewhere), and I didn't see any reasons for this.
>     > Please point them out.
> 
>     The need to have the Info manual be the first manual they read.
> 
> And what is the problem in that regard? I'm not assuming they need to read
> any other manual first.

The top-level menu in DIR is typically very long.  If the Info manual
is not the first item, we have no real hope that it will be the first
one to be read.

>     > I saw some hand-waving about bootstrapping
> 
>     Sigh.  Do you really think this style facilitates fruitful discussion?
> 
> I'm really trying to understand you, Eli. Give me something concrete to get
> hold of. Just what is the problem?

Your custom to use derogatory remarks and angry style.

>     >     Isn't the fact that you didn't even know about that other manual's
>     >     existence tells volumes of why we shouldn't leave out
>     >     stuff related to
>     >     its basics from the beginners' Info manual?
>     >
>     > No, I don't see the relation between my ignorance of the
>     > standalone-reader manual and "why we shouldn't leave out
>     > stuff..." What's the connection? What volumes does it tell?
>     > Can you be specific?
> 
>     Specifically, it is not a good idea to describe basic stuff in a
>     manual that no one will find.
> 
> Which basic stuff are we talking about?

How to use Info.

> Which manual?

info-stnd.info

> Why won't they find it?

Because it's buried in a long menu.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 17 Jul 2006 21:37:27 -0700
> 
>     >     > I see no reason why we can't have two versions of the tutorial.
>     >
>     >     One reason is that it's not easy to present the right one
>     >     to the user based on her reader.  Remember: learning Info is a
>     >     bootstrap-kind of problem--you learn to use a tool by using
>     >     that same tool. If we don't
>     >     make the beginning of the bootstrap 110% reliable (which includes
>     >     showing the right manual), the results will be catastrophic.
>     >
>     > So, how do you deal with that problem currently, since there
>     > are apparently already two manuals?
> 
>     By having the Info manual be the first item in the top-level menu.
> 
> And? That sounds OK to me.

It's okay as long as we have only one such manual.  You suggested that
the basics be divided between two.

RE: Info tutorial is out of date

[Drew Adams]

    >     >     > I see no reason why we can't have two versions of
    >     >     > the tutorial.
    >     >
    >     >     One reason is that it's not easy to present the right one
    >     >     to the user based on her reader.  Remember:
    >     >     learning Info is a bootstrap-kind of problem--you
    >     >     learn to use a tool by using
    >     >     that same tool. If we don't
    >     >     make the beginning of the bootstrap 110% reliable
    >     >     (which includes
    >     >     showing the right manual), the results will be catastrophic.
    >     >
    >     > So, how do you deal with that problem currently, since there
    >     > are apparently already two manuals?
    >
    >     By having the Info manual be the first item in the top-level menu.
    >
    > And? That sounds OK to me.

    It's okay as long as we have only one such manual.  You suggested that
    the basics be divided between two.

Put them both first (the first two in dir). Put the `n' and `p' stuff first
in either one or both, for the standalone Info manuals. I don't see why that
can't be done. Does the order within a manual need to be the same in the
Emacs version and the standalone version?

Besides, you seem to be talking about Info *manuals*. My proposal was only
about the Info tutorial. I said (above) "two versions of the tutorial"
(Emacs and standalone Info), and you went off about the order between two
Info manuals in dir (I guess?). I'm afraid you lost me on this.

RE: Info tutorial is out of date

[Drew Adams]

    >     >     > If there is a separate standalone-reader manual,
    >     >     > then stuff that is specific
    >     >     > to the standalone reader should go in that manual.
    >     >
    >     >     See my other mail for the reasons why this would be not a
    >     >     good idea.
    >     >
    >     > I read your other emails (unless there is yet another
    >     > somewhere), and I didn't see any reasons for this.
    >     > Please point them out.
    >
    >     The need to have the Info manual be the first manual they read.
    >
    > And what is the problem in that regard? I'm not assuming they
    > need to read any other manual first.

    The top-level menu in DIR is typically very long.  If the Info manual
    is not the first item, we have no real hope that it will be the first
    one to be read.

What sentence did you just reply to? I said that I am *not* assuming Info
cannot be the first. I repeat, "what is the problem?" Put the Info manual
first. Put anything you like first. Put the Info manual anywhere you like. I
haven't uttered a word about the order of the dir file. (!?)

My proposal was about the Info *tutorial*.

    > I'm really trying to understand you, Eli. Give me something
    > concrete to get hold of. Just what is the problem?

    Your custom to use derogatory remarks and angry style.

It's not because you might feel hurt or angry that someone who might have
caused you that pain was angry at you. Humoristic (attempt) and sardonically
mocking at times, admittedly, but I don't think you can point to one shred
of angry style on my part in this exchange. I might have poked a little fun
at some of what others wrote, but I wasn't angry in any way.

The same cannot be said, however, of everyone who wrote in the thread. I may
have stood my ground, defending my arguments, and I might have resorted to a
little humor, but no anger on my part - nada.

I'm not angry about this simply because I don't have an axe to grind in the
particular debate which has set some people off: mouse vs keyboard - it
interests them much more than me.

Most of my suggestions for changing Info were passed over in silence (no
debate) or received quick, me-too explicit approval with no discussion (no
debate).

It is the sole proposal to move the lessons on `n' and `p' to the end of the
tutorial that generated so much heat and, yes, anger on the part of some
others, and so little light. My entire contribution to that discussion was
simply to repeat the proposal and supporting arguments I had set forth from
the very beginning, pointing out misrepresentations of what I had written on
the part of others.

I probably shouldn't have continued to raise your ire, but I was having too
much fun not to, and (the real reason is) I really do believe in what I
proposed. I thought we could eventually get beyond the mouse thing, to the
other suggestions.

I fear now that nothing will change in Info, because the discussion got
sidetracked, hijacked. I'm not responsible for that, but I did respond to
questions and criticisms on the anti-mouse front, instead of ignoring them.
I hoped that we would move on to the more important proposals,
but...nothing. My guess is that anyone who might have been willing to spend
some energy trying to clean up Info a bit was burned out early on in the
anti-mouse discussion. Too bad.

We went on a complete tour of supposed denigration of Lisp, supposed
intentional subliminal meaning underneath the terms "shortcut" and "quick
alternative", and a host of other neon sideshows (yes, "sideshow" can have a
connotation of naughtiness, seediness, weirdness, dirtiness, and
monstrosity - Somethin's happenin' here, but you don' know what it is, do
you, Mr. Adams?). Amusing, maybe, but not very helpful to Emacs or Info.

    >     >     Isn't the fact that you didn't even know about that
    >     >     other manual's existence tells volumes of why we
    >     >     shouldn't leave out stuff related to
    >     >     its basics from the beginners' Info manual?
    >     >
    >     > No, I don't see the relation between my ignorance of the
    >     > standalone-reader manual and "why we shouldn't leave out
    >     > stuff..." What's the connection? What volumes does it tell?
    >     > Can you be specific?
    >
    >     Specifically, it is not a good idea to describe basic stuff in a
    >     manual that no one will find.
    >
    > Which basic stuff are we talking about?

    How to use Info.

    > Which manual?

    info-stnd.info

    > Why won't they find it?

    Because it's buried in a long menu.

So unbury it. Move it. Wherever. Whatever.

Re: Info tutorial is out of date

[Brad Collins]

Alan Mackenzie <acm@muc.de> writes:

> Yes, but surely not all.  Might it still be that in poorer countries
> there are newbies with PCs of insufficient power to support X?  

These comments are a bit off topic -- but I would like to address the
myth that third world countries are full of ancient computers which
can only run CLI environments.

Having lived for the last 20 years, mostly in the some of the most
remote regions of China, Thailand, Laos and Cambodia I can say that if
people have computers today, they are at least running Win95 on a
Pentium II boxes.

Most people are running XP on at least low to mid-range Pentium III's.
No one actually pays for software and in most places there is nowhere
to buy it even if you wanted to buy legit copies.  This makes adoption
of gnu/linux a tough sell here because Windows is the same price as
gnu/linux.

These are places with little or no electricity, no running water, and
in many cases no land based telephone lines.  If you want Internet
access you can go into any medium sized town and find inexpensive
Internet cafe's which always seem to be packed with people.

There are cell networks everywhere.  There are about 100 houses within
a 1km radius of my house, and only 2 land lines installed. But I'd
estimate that there are at least 200 or more people will cell phones
living in this same area.

In much of the rural parts of the Far East, I can safely say that the
oft repeated myth that people in third-world countries only have
access to old technology, ancient hardware and software is just not
true.

A PC in the third-world needs to operate in places with no air
conditioning, ungrounded electrical connections, dust during the dry
season, high humidity in the rainy season and are assaulted by vast
numbers of crawling and flying insects in all seasons.  Computers
don't last long in those conditions, so you don't see any old hardware
and the only new hardware anyone makes today is designed to run MS
products.

I think it's safe to say that the vast number of people even in poor
countries will learn how to use a mouse before they learn emacs or
info.

That said -- I learned emacs over a telnet connection, and when I
train people to use emacs (most of our inhouse development tools are
emacs applications) I encourage them to spend the first month learning
emacs by running it -nw in a shell window.  It's a bit severe, but it
helps force people to learn to use the keyboard and not avoid the
learning curve.  After a month, most people are comfortable enough
with the keyboard that they don't feel the need to use the mouse much
when they switch over to x.

I also don't like the term shortcut, it carries with it the idea that
it is not the recommended way to use the application and has only been
tacked on as an afterthought to appease "power users".

b/

-- 
Brad Collins <brad@chenla.org>, Bankwao, Thailand

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 18 Jul 2006 15:19:07 -0700
> 
>     >     > I read your other emails (unless there is yet another
>     >     > somewhere), and I didn't see any reasons for this.
>     >     > Please point them out.
>     >
>     >     The need to have the Info manual be the first manual they read.
>     >
>     > And what is the problem in that regard? I'm not assuming they
>     > need to read any other manual first.
> 
>     The top-level menu in DIR is typically very long.  If the Info manual
>     is not the first item, we have no real hope that it will be the first
>     one to be read.
> 
> What sentence did you just reply to?

The last two cited, of course, what else?

> I repeat, "what is the problem?" Put the Info manual first.

It _is_ the first one.  But you want two manuals to be ``the first'',
which is impossible.

> Put anything you like first. Put the Info manual anywhere you like. I
> haven't uttered a word about the order of the dir file. (!?)

The order is how we give the new user an opportunity to read the Info
manual before the other manuals.

> My proposal was about the Info *tutorial*.

"Info manual" and "Info tutorial" are the same thing.  We are talking
about the same document.

Re: Info tutorial is out of date

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 18 Jul 2006 15:19:06 -0700
> 
> Besides, you seem to be talking about Info *manuals*. My proposal was only
> about the Info tutorial.

It's the same document.

> I said (above) "two versions of the tutorial"
> (Emacs and standalone Info), and you went off about the order between two
> Info manuals in dir (I guess?).

info-stnd.info is not a tutorial, it documents the stand-alone reader
as a separate program.

Re: Info tutorial is out of date

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> I think it should concentrate on features instead.  One of the features is
> its perfect support for mouse-free use.  But I'm not sure it should be the
> first feature mentioned.  Index lookup (i), manual-wide search (M-s), and
> linear  traversal (SPC), should come before, IMO,

That seems very reasonable...

-Miles
-- 
"Though they may have different meanings, the cries of 'Yeeeee-haw!' and
 'Allahu akbar!' are, in spirit, not actually all that different."

Re: Info tutorial is out of date

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>     I think the term "shortcut", while common among the GUI set, actually
>     does do some harm by subtly encouraging people to think of menus as the
>     "standard" way of doing things.  For that reason, it really should only
>     be used in applications where that is indeed true, not in applications
>     like Emacs where it is most certainly not true.
>
> Why do you say "menus"? I didn't. I mentioned menus and links and "using
> `M-x'". I don't think of key bindings as shortcuts for just menu
> access.

Perhaps not, but that's _exactly_ how the term shortcut is used in the
GUI toolkits from which you clearly got the term (and thus the sense in
which most people that know what the term means will interpret it).

> In Emacs, they are shortcuts for commands, whether `M-x <command>' or
> menu access or even macro execution. They are, in fact, "keyboard
> shortcuts" for longer ways of doing things.

No they are not.  Commands and bindings are different things.  A binding
is not a shortcut for a command, because they are entirely different
sorts of things.

To say A is a shortcut for B implies that: (1) A and B are both
essentially the same type of action, (2) that B is in some sense the
more "normal" / proper / advertised / whatever, and (3) that A is
somehow quicker / easier than B.  There's also typically an implication
that A, while quicker than B, is also "less proper" / quick-and-dirty /
etc.

[You could say that a key binding is a shortcut for M-x command-name,
but that's a bit dodgy, because M-x command-name is not in most cases
the conventional way of invoking commands -- so it depends on the
specific command whether.]

These nuances seem fairly obvious to me.  I presume that you are a
native English speaker, but perhaps you're so immersed in the windows
world that the term shortcut has lost it's conventional connotations for
you.

-Miles
-- 
`...the Soviet Union was sliding in to an economic collapse so comprehensive
 that in the end its factories produced not goods but bads: finished products
 less valuable than the raw materials they were made from.'  [The Economist]

Re: Info tutorial is out of date

[Alan Mackenzie]

Hi, Brad!

On Wed, Jul 19, 2006 at 09:23:42AM +0700, Brad Collins wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > Yes, but surely not all.  Might it still be that in poorer countries
> > there are newbies with PCs of insufficient power to support X?  

> These comments are a bit off topic -- but I would like to address the
> myth that third world countries are full of ancient computers which
> can only run CLI environments.

Off topic they might be, but they're the most interesting to appear in
this list for some time (IMAO).

[ Information about infrastructure snipped, but read with interest. ]

> In much of the rural parts of the Far East, I can safely say that the
> oft repeated myth that people in third-world countries only have
> access to old technology, ancient hardware and software is just not
> true.

OK.  Thanks very much for the hard information.

> A PC in the third-world needs to operate in places with no air
> conditioning, ungrounded electrical connections, dust during the dry
> season, high humidity in the rainy season and are assaulted by vast
> numbers of crawling and flying insects in all seasons.

So you see even more bugs than we do.  ;-)

> Computers don't last long in those conditions, so you don't see any old
> hardware and the only new hardware anyone makes today is designed to
> run MS products.

OK.

> I think it's safe to say that the vast number of people even in poor
> countries will learn how to use a mouse before they learn emacs or
> info.

OK.

> That said -- I learned emacs over a telnet connection, and when I train
> people to use emacs (most of our inhouse development tools are emacs
> applications) I encourage them to spend the first month learning emacs
> by running it -nw in a shell window.  It's a bit severe, but it helps
> force people to learn to use the keyboard and not avoid the learning
> curve.  After a month, most people are comfortable enough with the
> keyboard that they don't feel the need to use the mouse much when they
> switch over to x.

Excellent!

> I also don't like the term shortcut, it carries with it the idea that
> it is not the recommended way to use the application and has only been
> tacked on as an afterthought to appease "power users".

Heh!  We're not so easily appeased.  ;-)

Again, thanks very much for the real data.

> Brad Collins <brad@chenla.org>, Bankwao, Thailand

-- 
Alan Mackenzie (Munich, Germany)

Re: Info tutorial is out of date

[Richard Stallman]

    That said -- I learned emacs over a telnet connection, and when I
    train people to use emacs (most of our inhouse development tools are
    emacs applications) I encourage them to spend the first month learning
    emacs by running it -nw in a shell window.

Interesting idea.  I will document this.

Re: Info tutorial is out of date

[Slawomir Nowaczyk]

On Sun, 16 Jul 2006 15:13:59 -0500
Jay Belanger <belanger@truman.edu> wrote:

#> But what little at a time is being taught, should be taught correctly.  
#> If the consensus is that using the mouse is the right way, fine; but I
#> disagree with the idea of letting bad habits form and overcoming them
#> later.

The thing is, we are not "letting the bad habits form". The bad habits
already exist... the best we can do is close our eyes, but -- contrary
to popular belief -- it won't make bad habits go away.

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

I plan on living forever. So far, so good.

Re: Info tutorial is out of date

[Slawomir Nowaczyk]

On Mon, 17 Jul 2006 09:37:59 -0700
Drew Adams <drew.adams@oracle.com> wrote:

#>     I frequently browse through the Emacs manual by following a link, then
#>     using `u' once or twice "to find out where I am" followed by `l' to get
#>     back to that link.
#> 
#> Interesting (and I do the same). Nothing wrong with this use pattern, but I
#> wonder if a command that tells you where are (in the manual hierarchy)
#> wouldn't be useful. It could be bound, for example, to `.' (a la `pwd').
#> (Yes, I know that `.' is currently a synonym for `b'.) It could display a
#> "breadcrumbs" message such as this: (emacs) Top > Minibuffer > Completion >
#> Completion Commands.

I would find such a command quite useful.

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

You can't wake a person who is pretending to be asleep.

Re: Info tutorial is out of date

[Slawomir Nowaczyk]

On Sun, 16 Jul 2006 02:25:27 -0400
Richard Stallman <rms@gnu.org> wrote:

#> 		  My point is this: first things first. If I don't understand
#>     what Info is all about, why would I go through the effort of learning and
#>     practicing its key bindings?
#> 
#> Isn't it obvious to everyone what Info is all about?  It's all about
#> browsing documentation files.  Menus, and moving up, moving thru a
#> series using next and previous, are going to be obvious to anyone that
#> has used the WWW very much.

Well, yes and no... there are a lot of other ways to browse documentation
(web browsers being one example). I think we should be pointing to the
users (in the tutorial, at least) *why* info is *better* than the
alternatives.

And starting by saying "press 'n' to go to next node" is only going to
get us a "gee, why can't those guys learn what hyperlinks are?"
reaction.

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

Tact is the knack of making a point without making an enemy.

Re: Info tutorial is out of date

[Slawomir Nowaczyk]

On Sun, 16 Jul 2006 19:49:14 +0200
David Kastrup <dak@gnu.org> wrote:

#> I repeat: there is little sense in telling people how to do
#> complicated things with the keyboard without telling them how to do
#> the simple things.

Why?

They *can* do simple things already (using a mouse), so what's the
point of telling them about things they already can do before telling
them about things they do not know about?

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

Real Programmers just whistle the binary code into the modem

Re: Info tutorial is out of date

[Jay Belanger]

Slawomir Nowaczyk <slawomir.nowaczyk.847@student.lu.se> writes:

> On Sun, 16 Jul 2006 15:13:59 -0500
> Jay Belanger <belanger@truman.edu> wrote:
>
> #> But what little at a time is being taught, should be taught correctly.
> #> If the consensus is that using the mouse is the right way, fine; but I
> #> disagree with the idea of letting bad habits form and overcoming them
> #> later.
>
> The thing is, we are not "letting the bad habits form". The bad habits
> already exist... the best we can do is close our eyes, but -- contrary
> to popular belief -- it won't make bad habits go away.

Then we shouldn't close our eyes.

Re: Info tutorial is out of date

[Richard Stallman]

    Interesting (and I do the same). Nothing wrong with this use pattern, but I
    wonder if a command that tells you where are (in the manual hierarchy)
    wouldn't be useful. It could be bound, for example, to `.' (a la `pwd').
    (Yes, I know that `.' is currently a synonym for `b'.) It could display a
    "breadcrumbs" message such as this: (emacs) Top > Minibuffer > Completion >
    Completion Commands.

It does sound useful.  In theory, this question does not always have a
well-defined answer, since Info files need not be a tree structure.
But in practice they all are, so there is a well-defined answer.  So
the command would be useful, but it needs to cope in some fashion with
the weird cases.

If someone wants to implement this and contribute it, it will be welcome.

Re: Info tutorial is out of date

[Miles Bader]

Slawomir Nowaczyk <slawomir.nowaczyk.847@student.lu.se> writes:
> Well, yes and no... there are a lot of other ways to browse documentation
> (web browsers being one example). I think we should be pointing to the
> users (in the tutorial, at least) *why* info is *better* than the
> alternatives.
>
> And starting by saying "press 'n' to go to next node" is only going to
> get us a "gee, why can't those guys learn what hyperlinks are?"
> reaction.

Nonetheless, the info browser's far more efficient browsing is a _huge_
advantage over a typical "html in a browser" solution (I use lots of
html docs, and am always amazed by how clunky and awkward everything
is).  Any but the simplest queries can be a nightmare in an html doc
tree simply because it's so slow and awkward to move around.

The other big benefits of info IMHO are more "global" functionality
(cross-node i-search is my number-one method of finding stuff these
days), and of course much better integration with the editor.

-Miles
-- 
o The existentialist, not having a pillow, goes everywhere with the book by
  Sullivan, _I am going to spit on your graves_.

Re: Info tutorial is out of date

[Slawomir Nowaczyk]

On Fri, 21 Jul 2006 08:10:07 +0900
Miles Bader <miles@gnu.org> wrote:

#> Nonetheless, the info browser's far more efficient browsing is a
#> _huge_ advantage over a typical "html in a browser" solution (I use
#> lots of html docs, and am always amazed by how clunky and awkward
#> everything is). Any but the simplest queries can be a nightmare in
#> an html doc tree simply because it's so slow and awkward to move
#> around.
#> 
#> The other big benefits of info IMHO are more "global" functionality
#> (cross-node i-search is my number-one method of finding stuff these
#> days), and of course much better integration with the editor.

I know that. You know that. Most people on this list know that.

But as Drew said many times, we are not the target audience for Info
tutorial. Those who are/should be reading the tutorial *do not* know
what is so great about the Info system. We should _start_ the tutorial
by explaining it to them, if we want them to continue reading.

Starting by saying "to move forward do X and to go back do Y" is
suboptimal (it might be OK to have a sentence or two about that, but
devoting the first two nodes to this is an overkill). People today are
accustomed that those basic things 'just work'.

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

I dream of being Bugs Bunny, but when I wake up,
I'm Daffy Duck or Wile E. Coyote.