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.