How to Introduce Emacspeak ¶

Info and Help ¶

Your friend will want to learn a great many keystroke commands, but if he is like me, he will continually forget them, too.

So you need to teach him how to use Info, which is where he can listen to the Emacspeak manual. And you need to teach him how to use help. This way, he can always learn more, or relearn what he has forgot.

The first commands I learned were:

Control-h Control-e

Give a brief overview of Emacspeak.

I use this command all the time, to remind me of other commands.

(In most Emacs documentation, this command, Control-h Control-e is written as C-h C-e.)

Control-e left-brace

Speak paragraph.

With a prefix arg, speak the rest of the current paragraph. With a negative prefix arg, read from the start of the current paragraph to the current position, that is, to point.

Control-u

The universal-argument. This is the prefix arg.

Use as a prefix to some interactive commands, such as Control-u Control-e left-brace, which speaks the rest of the current paragraph.

To read from the beginning of the current paragraph to point, type Control-u hyphen one Control-e left-brace.

Control-e left-angle-bracket

Speak a page.

With a prefix arg, speak the rest of the current page.

I often use the Control-u Control-e left-angle-bracket command.

Control-e s

Stop speech.

Control-h i

Start Info.

In Info, press h for an Info tutorial.

Control-h t

Start the Emacs Tutorial.

Your friend will also need to learn the regular movement and search keys. The Emacs Tutorial is good for this. But first teach him how to listen to Info and to use the online help.

Note that the Emacs Tutorial contains left and right angle brackets in two places. To hear them in Emacspeak, you must set the punctuation mode to all, with the command:

Control-e d p all RET

Otherwise, the brackets will not be spoken. (The RET at the end of the command means to press the Return key after typing all.)

In most Emacs documentation, a command such as Control-e left-brace command is written as C-e {. If you are listening in Emacspeak, you have to set the punctuation mode to all; otherwise, you will not hear the left-brace spoken.

Movement ¶

As for movement: incremental search is the most important way of moving around documents. This command is bound to Control-s, which is usually written as C-s. Often people do not think of a search command as a movement command, but it is.

Moreover, Emacs incremental search provides the single best user interface for a search command that exists. Many other search commands require that you figure out your search string before you type, which means that the search fails when you type too little. Incremental search is nicer to use.

The character and word movement keys, and the character and word deletion keys, are reasonably easy for English speakers to learn, since they use English language mnemonics: Control-f to move forward a character, Meta-f to move forward a word. (Meta-f is usually written as M-f.) p is for previous, n is for next, b is for backwards, and d is for delete.

Control key commands are often (but not always) for character movement; Meta key commands are often (but not always) for word movement.

Keybindings ¶

You will want to explain the use of Meta. You might tell your friend that on many modern keyboards, a Meta key is what is now, generally and erroneously, labeled Alt, spelled A L T, and usually written ALT. (Genuine Alt keys can and do exist; but the default keybinding for many machines automatically makes the key labeled Alt be a Meta key. Naturally, you should set up the machine so that a key labeled Alt takes on a Meta keybinding, for example with the install-keymap emacs2 command.)

Worse, in some cases, people press the Escape key to simulate a Meta keypress. The Escape key is usually written ESC. No one in their right mind uses an Escape key, unless forced by a really old keyboard.

While I am speaking of keybindings, and to be complete, please be sure the control key is the key to the left of the A key. This is something you should set up; you don’t need to explain any of this.

You may have to change the keybinding. On some keyboards, the key to the left of the A key is labeled Caps_Lock. It is as if the keyboard manufacturers think that computers are typewriters from 1885. Moreover, they put the key labeled Control in an awkward spot, and then provide default keybindings that match the labels. You have to change the keybindings.

Generally, the proper keymap is in

/usr/share/keymaps/i386/qwerty/emacs2.kmap.gz

or

/usr/share/kbd/keymaps/i386/qwerty/emacs2.kmap.gz

You can install the keymap permanently on your system for a console with the shell command:

install-keymap emacs2

(This may be a Debian specific command; it copies the emacs2.kmap.gz file to the /etc/console/boottime.kmap.gz file, which is loaded into the kernel at boot-time. The older and widely used command is loadkeys; when you run it, you have to specify the full path to the file.

(For example, to install the proper keymap, you might type

loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz

(Note that since files in the /usr/ directory are sometimes not available early during the boot process, it is a good idea to copy the /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz to the /etc/console/boottime.kmap.gz file. This is what the install-keymap command does. If you don’t have an install-keymap command, you can copy the file yourself and put a loadkeys /etc/console/boottime.kmap.gz command into one of your boot scripts.)

X Windows Keybindings ¶

If you are using an X Windows graphical user interface, you may need to specify the keymap that X uses in addition to specifying the keymap used by a console.

You can put the following commands in your ~/.xsession or ~/.xinitrc file:

xmodmap -e "clear Lock"
xmodmap -e "add Control = Caps_Lock"

Some systems reverse the meaning of the Help key, which is Control-h, and the Delete key. The node Keyboard Translations in the Emacs manual describes what to do.

You can go directly to that node in Info by evaluating the following expression, that is to say, by positioning point after the final parenthesis and typing Control-x Control-e, which is usually written as C-x C-e:

(info "(emacs)Keyboard Translations")

(Please remember to note my use of the jargon word ‘point’; it needs to be explained as the place in the text where editing commands operate.)

Setting the Speech Rate ¶

Returning to what you might talk about early on with your friend:

He may want to set the voice synthesizer speech rate. I use both the dtk-set-predefined-speech-rate command:

Control-e d 1
Control-e d 2
Control-e d 3

and the dtk-set-rate command, such as

Control-e d r 230 RET

Probably it is a good idea to pick one of these commands. Two sets of commands may overload his memory.

As he gains more experience, your friend will be able to understand text spoken faster and faster, and will want to increase its speed.

Note that in both set-rate commands, an interactive prefix means to set the speech rate globally. Otherwise, it is set only for the current buffer.

Your friend may want to set rates globally, so it is worth telling him about typing Control-u first.

Basic Commands Reference ¶

For a description of the basic commands, see the node ‘Reading’ in the Info file emacspeak.info

(info "(emacspeak)Reading")

(As I said earlier, you can go directly to that node by evaluating the Emacs Lisp expression: position point after the final parenthesis and type Control-x Control-e.)

Perhaps evaluation is too much too soon, since it means remembering a new command as well as figuring out where ‘point’ is. On the other hand, I think it is worth illustrating the action, since it opens up future possibilities.

Incidentally, you can go directly to the Introduction node of the Emacspeak manual by evaluating:

(info "(emacspeak)Introduction")

My hope is that you will inspire your friend to experiment with many commands and learn a few of them; you will inspire him to learn how to use the help features, to listen to the Emacspeak Info manual, and then to listen to the Emacs manual.

After that, he can start using Emacs W3 or Emacs W3M mode to browse the Web, Emacs RMAIL mode to listen to Email, and Emacs mail mode to send it. You may need to make sure his machine is properly configured for all this.

Characteristics of GNU Emacs ¶

While listening to the Emacspeak Info manual, it is worth explaining some of the problems people have with the Emacs manual, to which he should listen next, or at least listen to part of it. I do not recommend listening to it all at once.

The Emacs manual is tightly written. When I first read it, I found I sometimes had to spend several minutes puzzling out a concise meaning. The good news is that it is accurate and well written. And after you understand it, the sentences make perfect sense.

When I first started, I read the manual in segments over 2 years. (This was in the 1980s.) I did not understand all that I could do at first. Indeed, for the longest time, I did not switch from using ‘ls -al’ in a command line to using Dired mode.

Some people say that the Emacs learning curve is steep.

In my experience, this is not true. It took me about five minutes to start to use Emacs productively. But I could not and did not do much at first, except write.

However, the learning curve will be steep if you try all at once to use many of the features that Emacs provides. I have described GNU Emacs as

… like having a dragon’s cave of treasures.

You should not try to be too greedy and over-stuff yourself all one sitting.

(That quotation is from the Info node "On Reading this Text" in the Info manual that introduces programming in Emacs Lisp:

(info "(eintr)On Reading this Text")

I wrote that text "as an elementary introduction for people who are not programmers", but presupposed experience with Emacs. So I doubt you or your friend will want to look at it early on. But I hope that he will keep it in mind for the future.)

Peculiarities of the Emacs manual ¶

To listen to the Emacs manual in Emacspeak, you will need to set the punctuation mode to all with the command:

Control-e d p all RET

RMS, Richard M. Stallman, wrote the Emacs manual.

Unfortunately, RMS thinks of editing as having a very large meaning. He writes as if using ls and rm in a command line is the shell equivalent of editing in Emacspeak. People who use a shell do not think of this as editing.

However, if you think about it, you will discover that the Emacspeak actions in Dired mode are a kind of editing. Indeed, the name Dired is a contraction for the phrase ‘directory editor’.

But the kind of editing that goes on in Dired is not same kind of editing as people do in an editor like vi when they press the h, j, k, and l keys to move around. People are fooled by the language.

The words mode and library are not confusing, but may not be understood immediately. The two provide the features that programs have in other interfaces. Thus Dired mode provides the same features in Emacs that the combination of ls, mv, chown, chgrp, gzip, more, vi, and rm provide in a shell. A library provides a mode.

Because of the adoption of Xerox Parc style windowing systems over the past generation, many people are confused by Emacs’ use of the words window and frame. Emacs provides for multiple windows within a frame, as it always has.

You will probably not use a graphic user interface at all; but enough people do that you will hear what they say.

Nowadays, sighted people often think of a window on a computer screen as being a contiguous, usually rectangular space, what in Emacs is called a frame. That is because Emacs was designed initially to fill a complete display as a tiling window manager. (A tiling window manager is one in which windows do not overlap, but are contiguous, like physical tiles.) Parts of the display were called windows because they enabled a sighted person to look at all or part of a buffer.

Companies like Apple and Sun, and the X Consortium, copied Emacs jargon for their own windows, to mean a part of a screen. (Or else the notion of a window was generic and commonplace.)

Thus, the term window started out and continues to mean a part of a display.

But when Apple, Sun, and the X Consortium, and their followers, adopted the term window to mean a part of a display, they lacked a term to handle a part of a window. (The word ‘pane’ was suggested, but never popular, because it sounds similar to the word ‘pain’, spelled p a i n, and because some people were accustomed to material windows that were not made up of multiple ‘panes of glass’.)

However, in those days, mostly the 1980s, windows seldom contained parts, other than a menu or tool bar or panel that applied to a whole window. Thus, one spreadsheet would appear in one window; one file would appear in another.

Indeed, many of the non-Emacs programs I use today in a graphic user interface still tend to put one set of contents, with its associated panels and tool bars, into one window: for example, XMMS, Mozilla, or gnome-apt.

With Emacs, on the other hand, you could always put a directory listing, two files, and an email message into four different parts of an Apple or X style window (although most people keep to one or two parts most of the time). These different parts had always been themselves called windows, and so they remained. Hence, the invention of the term frame to refer to a segment of a display as produced by an X or Sun user interface program.

Nowadays, you can start different frames in an instance of Emacspeak that is not running in a graphical user interface. One frame overlies another. The mode line will tell you which frame you are in. (Type Control-e m to listen to the mode line. That key chord calls the emacspeak-speak-mode-line command. The frame number is listed in the second and subsequent frames.)

Emacs jargon can be brutal. Some people are upset by the use of the word ‘kill’ to mean ‘cut’ as in ‘cut and paste’. (The word ‘cut’ also upsets some people, but generally less than the word ‘kill’.) In Emacs, an entity ‘killed’ can be resurrected, which I think of as a Christian form of meaning.

Some years ago, at the transition from Emacs version 18 to version 19, I offered to convert every use in Emacs of the word kill to clip. There were more than 400 such uses. You could clip a segment of text, and if it were never put back, it would be deleted. Alternatively, you could yank the segment from the clip-ring. I picked clip as the replacement word since it has four letters and fits the older formatting and language without requiring much rewriting.

Moreover, had I changed the term to ‘cut’, people would have expected me to replace the word yank with ‘paste’, to fit the phrase ‘cut and paste’. But I do not like the word ‘paste’; I no longer literally paste clips onto a sheet of paper as I did when I was young. It makes more sense to me to yank a segment back from the clip-ring.

However, RMS never wanted me to make the replacement. I think part of the reason is that at that time, RMS still enjoyed what I think of as a dead joke: the manual for version 18 Emacs said:

… you don’t have to kill all the text in one command; you can keep killing line after line, or word after word, until you have killed it all, and you can still get it all back at once. (Thus we join television in leading people to kill thoughtlessly.)

(The parenthetical remark about television was removed sometime later and the other wording slightly improved.)

Perhaps more significantly, RMS asked many people whether they were bothered by the jargon use of kill. They said ‘no’. It turned out that RMS asked people he thought of as significant, namely people at M.I.T. I think that was too narrow a group. But that is what happened, and I still think it was a mistake.

Most important of all, please emphasize and explain that Emacspeak is safer than many programs. What you write is automatically saved to disk. This means you can work with unreliable power supplies, or learn by trying out new things and make what otherwise would be catastrophic mistakes.

You can experiment and learn.