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)