## Tips And Tricks For The Emacspeak Audio Desktop

### T. V. Raman

Copyright © 2002 T. V. Raman

This work is being made available under the same copyright as that used by the Linux Documentation Project see LDP Copyright Notice .

Abstract

This document is a collection of productivity tips for using the Emacspeak audio desktop. Make sure you listen to this document with punctuation mode set to all to ensure that you do not miss important concepts. Note that this document is to be used in concert with the built-in online help facilities. Toward this end, the first section gives help on using Emacs online help; subsequent sections are intentionally brief since the interested user is expected to lookup the details of a command using these facilities. See How To Ask Questions The Smart Way for how you can improve your own productivity while contributing to continuously improving the tools you rely on for your work.

The latest copy of this document is always available via Emacspeak GitHub Repository and on the Emacspeak WWW site.

1. Online Help
  1.1. Interactive help.
  1.2. Online hypertext help.
  1.3. Emacspeak Hypertext Reference
  1.4. Opening info page that documents a given key.
  1.5. Opening info page that documents a given command.
  1.6. Picking from available choices.
  1.7. Minibuffer prompting and completion.
  1.8. Customizing Emacs And Emacspeak
  1.9. Browsing UNIX Man Pages
2. Files And Folders
  2.1. Working on files and folders.
  2.2. Working with remote directories.
  2.3. Locating files.
  2.4. Using UNIX find from within Emacs.
  2.5. Searching all files in a directory hierarchy.
  2.6. Search and replace across a collection of files.
3. Reading, Browsing And Skimming
  3.1. Hiding and exposing text blocks.
  3.2. use Emacs' set-selective-display to advantage when working with indented text.
  3.3. Skipping across blank lines
  3.4. Browsing structured text using Emacs outline mode
  3.5. Everything is searchable.
  3.6. Saving positions in a file.
  3.7. Working with different portions of a file at the same time.
  3.8. Accumulating Annotations While Reading
4. State Of The Emacspeak Audio Desktop
  4.1. Hearing The Current Context
  4.2. Information conveyed by command emacspeak-speak-mode-line
  4.3. Information conveyed by command emacspeak-speak-minor-mode-line
5. Multimedia On The Emacspeak Audio Desktop
  5.1. Setting State Of The Auditory Display Using AMixer
  5.2. Playing audio CDs
  5.3. Setting up music playlists
  5.4. Playing Media Streams
  5.5. Streaming media presets
  5.6.
6. Authoring Tools
7. Electronic Messaging
8. Web Browsing
  8.1. What Web Browsers Can I Use?
9. System Management And System Administration
10. Emacspeak Utilities
  10.1. Launch a root shell.
  10.2. Setting shell's working directory to buffer's current directory
  10.3. Emacspeak Clipboard
  10.4. Copying current file.
  10.5. Personal telephone directory.
  10.6. Tabbulating shell command output.
  10.7. Filtering specific columns of all lines.

### 1. Online Help

1.1. Interactive help.
1.2. Online hypertext help.
1.3. Emacspeak Hypertext Reference
1.4. Opening info page that documents a given key.
1.5. Opening info page that documents a given command.
1.6. Picking from available choices.
1.7. Minibuffer prompting and completion.
1.8. Customizing Emacs And Emacspeak
1.9. Browsing UNIX Man Pages

Tips on using Emacs online help facilities.
1.1. | Interactive help.

Online documentation is accessed using commands available on key C-h. The type of help obtained is determined by the keypress following C-h.

c looks up command run by a given key.
k looks up documentation for a given key.
w looks up key that invokes specified command.

1.2. | Online hypertext help.
| Invoke the online hypertext help system (info) by pressing C-h i. Press h when using Info to obtain a primer for first time users.
1.3. | Emacspeak Hypertext Reference
| You can open the online Emacspeak hypertext reference using key C-e TAB.
1.4. | Opening info page that documents a given key.
| Press C-h C-k followed by the key whose documentation you wish to locate.
1.5. | Opening info page that documents a given command.
| Press C-h C-f and specify the command name when prompted.
1.6. | Picking from available choices.

Hitting tab causes Emacs to complete the currently typed input as far as possible. If there is more than one choice available, Emacspeak plays auditory icon help and speaks the available choices. At this point, you can input more characters to unambiguously specify the choice. Alternatively, you can browse the completion list which is typically displayed in another window in a buffer called `*Completions*`.

1.7. | Minibuffer prompting and completion.
| Emacs uses the minibuffer when prompting for user input. When using completion in the minibuffer by hitting tab, you can switch to the `*Completions*` buffer by pressing command C-o.
1.8. | Customizing Emacs And Emacspeak
| Emacspeak can now be customized using custom and this is the recommended way for users new to Emacs to customize Emacs and Emacspeak. Command emacspeak-customize invokes Emacs' customize interface for customizing Emacspeak. Use custom to customize Emacs packages that support this feature. Note that not all Emacs packages are fully customizable via custom.
1.9. | Browsing UNIX Man Pages
| Use Emacs command man to view UNIX manual pages using a speech-enabled interface. This interface provides structured browsing which is something missing when viewing UNIX man pages inside a traditional pager program.

### 2. Files And Folders

2.1. Working on files and folders.
2.2. Working with remote directories.
2.3. Locating files.
2.4. Using UNIX find from within Emacs.
2.5. Searching all files in a directory hierarchy.
2.6. Search and replace across a collection of files.

This section contains tips on working efficiently with files and folders, both local and remote.
2.1. | Working on files and folders.
| Use command dired (directory editor) normally bound to C-x d to operate on files and folders.
2.2. | Working with remote directories.
| Built-in Emacs package tramp provides seamless access to remote files and folders by using UNIX ssh behind the scenes. To open a remote directory, specify the directory location as /username@host:/path when prompted by command dired. Note that in the above, username defaults to anonymous.
2.3. | Locating files.
| Use locate and locate-with-filter to find files and folders on your hard drive. Matching files and folders are displayed using the same interface as provided by command dired. These commands use the locate database that is typically rebuilt nightly on standard Linux systems.
2.4. | Using UNIX find from within Emacs.
| Use commands find-name-dired, find-grep-dired and find-dired to use UNIX find to locate files and folders on your hard drive.
2.5. | Searching all files in a directory hierarchy.
| Install and use Emacs package igrep ---an extended Emacs interface to UNIX grep to search all files in a directory. For simpler tasks use command grep-dired and command find-grep-dired.
2.6. | Search and replace across a collection of files.

When working on a project consisting of many files, build a tags table using UNIX command etags and use it to advantage from within Emacs with commands such as

find-tag
tags-search
tags-query-replace

### 3. Reading, Browsing And Skimming

3.1. Hiding and exposing text blocks.
3.2. use Emacs' set-selective-display to advantage when working with indented text.
3.3. Skipping across blank lines
3.4. Browsing structured text using Emacs outline mode
3.5. Everything is searchable.
3.6. Saving positions in a file.
3.7. Working with different portions of a file at the same time.
3.8. Accumulating Annotations While Reading

This section contains tips for efficiently working with large amounts of content using speech output.
3.1. | Hiding and exposing text blocks.

You can hide blocks of text when skimming a file. A block of text is defined as a sequence of contiguous lines starting with a common prefix e.g., cited lines in an email message or blocks of comments in programming languages. See commands

C-e j emacspeak-hide-or-expose-block
C-e C-j emacspeak-hide-speak-block-sans-prefix

to use these features.

3.2. | use Emacs' set-selective-display to advantage when working with indented text.
| When working with content that uses indentation to reflect structure, you can use Emacs' built-in set-selective-display to advantage and selectively collapse/expand contents. Emacs comes with additional package that enable such structured traversal, as an example, see hideshow.
3.3. | Skipping across blank lines

Use commands

emacspeak-skip-blank-lines-backward
emacspeak-skip-blank-lines-forward

to move across contiguous blank lines.

3.4. | Browsing structured text using Emacs outline mode

Emacs outline facility provides a powerful tool for browsing textual material based on its implicit structure. By default, command outline-minor-mode sets up Emacs to recognize lines beginning with `***` as header lines. This can be changed on a per buffer basis by setting up Emacs variable `outline-regexp` to a regular expression that matches header lines. When using Emacs view-mode to read text, this feature is especially useful when combined with Emacspeak built-in feature that loads a directory specific file to customize Emacspeak on a per-directory basis. Thus, one can organize electronic texts by placing files for a given book in a specific directory, and then creating a file called `.espeak.el` in that directory that sets up things like Emacs variable `outline-regexp`.

3.5. | Everything is searchable.
| Everything is searchable in Emacs. Use this to advantage when working with all forms of content, since it is often more efficient to use Emacs commands C-s and C-r to perform forward or backward incremental search to locate relevant information than to listen to the content.
3.6. | Saving positions in a file.
| Use Emacs mark to save temporary positions in a file. Use built-in Emacs bookmark to save the position across Emacs sessions. Use built-in Emacs package desktop to have Emacs automatically recreate the state of the audio desktop on restart.
3.7. | Working with different portions of a file at the same time.

Display the file in different Emacs windows or frames; Emacs allows you to display different portions of the file in each window or frame. Use Emacspeak commands

emacspeak-speak-predefined-window
emacspeak-speak-this-buffer-other-window-display
emacspeak-speak-this-buffer-previous-display
emacspeak-speak-this-buffer-next-display

to listen to a given portion of a file whilst working on a different portion of the same file.

3.8. | Accumulating Annotations While Reading
| It is often useful to be able to jot down comments or notes while reading a large document. Rather than switching back and forth between the document you are reading and the document where the comments are being jotted down, you can use Emacspeak utility emacspeak-annotate-add-annotation --see that command's online documentation for details on its use.

### 4. State Of The Emacspeak Audio Desktop

4.1. Hearing The Current Context
4.2. Information conveyed by command emacspeak-speak-mode-line
4.3. Information conveyed by command emacspeak-speak-minor-mode-line

This section contains tips on querying and updating the status of the Emacspeak audio desktop. See section status commands in the Emacspeak online manual for additional details.
4.1. | Hearing The Current Context

Emacs buffers are the building bloks of the Emacspeak audio desktop. Current context is thus determined by the current buffer ---i.e., the buffer with which the user is presently interacting. The state of the current buffer is continuously updated visually by Emacs on the modeline (see the Emacs online tutorial for details on the visual display)--- the status is spoken by Emacspeak whenever there is a context change. You can explicitly request this context information using command emacspeak-speak-mode-line; additional details are provided by command emacspeak-speak-minor-mode-line.

4.2. | Information conveyed by command emacspeak-speak-mode-line

Command emacspeak-speak-mode-line is optimized to convey the most relevant information first. Different user options control additional status information that may be spoken by this command. When possible, this command uses tones and auditory icons to make the spoken feedback more succinct. Here is a brief summary listing the various items of status information conveyed by command emacspeak-speak-mode-line:

Shell-mode The working directory is spoken for shell-mode buffers.
which-function When which-function-mode is activated using command emacspeak-toggle-which-function, the name of the function containing the cursor is spoken. This is useful in programming modes.
mail-alert Produces an auditory icon indicating newly arrived mail and is controlled via command emacspeak-toggle-mail-alert.
buffer-modified An auditory tone when the contents of the current buffer has been modified since it was last saved.
buffer-read-only An auditory tone when the current buffer is read-only.
buffer-name The name of the current buffer.
line-number Current line number when line-number-mode is active.
column-number Current column number when column-number-mode is active.
mode-name Name of the buffer's major mode ---this is what determines specialized behavior within Emacs buffers.
percentage Percentage of point into the current buffer.
frame-info If more than one Emacs frame is active, then the title of the current frame is spoken. Emacs typically uses multiple frames when running in a graphical environment.
recursion-info Current recursion level when recursive edit is in progress; note that you enter recursive edit in Emacs in very few specialized cases.

Finally, note that the feedback is designed using the principle no news is good news, thus, in many cases the absence of a cue is itself a cue. As an example, Emacspeak produces an auditory tone only if a buffer is read-only --the absence of the tone indicates the buffer can be editted which is usually the case. Similarly, no tone is produced when a buffer does not need saving.

4.3. | Information conveyed by command emacspeak-speak-minor-mode-line

Command emacspeak-speak-minor-mode-line typically conveys additional information including:

Minor modes that are active e.g., voice-lock
Version number of files under revision control.
Current encoding system in use.

### 5. Multimedia On The Emacspeak Audio Desktop

5.1. Setting State Of The Auditory Display Using AMixer
5.2. Playing audio CDs
5.3. Setting up music playlists
5.4. Playing Media Streams
5.5. Streaming media presets
5.6.

This section contains tips on using the various multimedia features of the Emacspeak audio desktop.
5.1. | Setting State Of The Auditory Display Using AMixer
| The state of the auditory display can be set and updated using command emacspeak-audio-setup. The available settings depend on the sound card in use.
5.2. | Playing audio CDs
| Emacspeak built-in command cd-tool uses the command-line tools provided by RPM package cdp. This is convenient for playing tracks from a CD. Use cdcd from within an Emacs shell for more complex tasks such as querying a CDDB database.
5.3. | Setting up music playlists

Application mplayer can play music listed in a playlist file --typically such files are given the extension `.m3u`. A playlist file contains names of MP3 files, one per line. To create a playlist file for use with mplayer, you might execute the following command from within a shell buffer:

>                 cd $HOME/music
>                 find . -name '*.mp3'  > playlist.m3u

5.4. | Playing Media Streams

Install mplayer -- this is an open source media player. Once you have this installed and configured, you can use Emacspeak's built-in Media Player front-end provided by module emacspeak-m-player.el to conveniently play streaming media from anywhere on the audio desktop --see command emacspeak-multimedia. Note that when playing a stream, you can use all the single-keystroke navigation commands provided by emacspeak-m-player by prefixing them with C-e ; from anywhere on the audio desktop; alternatively, you can use C-e ;; to switch to a special Emacs buffer that contains mplayer and then execute mplayer commands directly.

5.5. | Streaming media presets
| Streaming media on the WWW is often well-hidden behind several mouse clicks. Emacspeak allows you to configure your favorite streams as an organized hierarchy. The Emacspeak distribution comes with such a collection of streams I listen to on a frequent basis. You can access these by using standard Emacs completion when prompted for a `media Resource` by command emacspeak-m-player.
5.6. |
| The ImageMagick package provides a powerful set of image manipulation tools --for an excellent overview see the online article command-line graphics

### 6. Authoring Tools

This section contains tips on authoring structured documents for online and print publishing. See the relevant section of the online Emacspeak manual for further details on document authoring on the Emacspeak desktop.

### 7. Electronic Messaging

This section contains tips about electronic messaging on the Emacspeak desktop. For further details, see the relevant section of the online Emacspeak manual on electronic messaging.

### 8. Web Browsing

8.1. What Web Browsers Can I Use?

8.1. | What Web Browsers Can I Use?

There are a number of available options, none of which are completely satisfactory. Here is a summary of what is available.

1. eww. EWW is built-in with Emacs 24.4 and later. Emacspeak's web-specific wizards make up for many of the short-comings encountered when navigating complex web sites.

2. W3. This is still my web browser of choice though it has sadly fallen by the way-side in the last few years. W3 lacks the features you need to interact with many commerce sites, but is a very flexsible and powerful solution for efficiently browsing content. Emacspeak's web-specific wizards make up for many of the short-comings encountered when navigating complex web sites and these wizards work best with the W3 browser. Emacs command: w3.

3. Emacs W3M This is a light-weight browser compared to W3 and provides an Emacs interface to the underlying W3M browser. It is a good solution for browsing content --especially on slow machines. Emacs command: w3m.

4. Lynx. The oldest terminal based browser of them all. It's still a good solution for some interactive sites, but its lack of support for tables can make some sites very confusing. Emacspeak command: emacspeak-lynx.

5. Links. This is Links with an i and not to be confused with the older Lynx browser. It has rudimentary Javascript support and is under active development. Emacspeak command: emacspeak-links.

### 9. System Management And System Administration

This section contains tips on managing your system.

### 10. Emacspeak Utilities

10.1. Launch a root shell.
10.2. Setting shell's working directory to buffer's current directory
10.3. Emacspeak Clipboard
10.4. Copying current file.
10.5. Personal telephone directory.
10.6. Tabbulating shell command output.
10.7. Filtering specific columns of all lines.

This section gives tips on using some of the built-in productivity tools bundled with Emacspeak. Most of these are implemented in module emacspeak-wizards.
10.1. | Launch a root shell.
| Never run Emacspeak as the root user. Instead use Emacspeak command emacspeak-root to create a root shell after starting Emacspeak.
10.2. | Setting shell's working directory to buffer's current directory
| You often find yourself switching to the shell buffer and then executing cd to switch to the directory containing the file you were working on. Emacspeak wizard emacspeak-wizards-shell-toggle switches to a running shell buffer and automatically executes command cd so you are in the right working directory.
10.3. | Emacspeak Clipboard

Emacspeak provides a clipboard facility to enabling cut and paste across different emacspeak sessions, see commands

emacspeak-clipboard-copy
emacspeak-clipboard-paste

10.4. | Copying current file.
| Emacspeak command emacspeak-copy-current-file lets you copy the file being visited to a different location ---this is a convenient way of publishing to a WWW server.
10.5. | Personal telephone directory.
| Emacspeak command emacspeak-speak-telephone-directory lets you maintain a telephone directory as a simple text file.
10.6. | Tabbulating shell command output.
| Many UNIX commands produce tabulated output, e.g., command df for displaying a disk usage summary. You can use Emacspeak command emacspeak-speak-run-shell-command to run such commands and have the tabular output available for browsing using Emacspeak's table browsing facilities.
10.7. | Filtering specific columns of all lines.

This is most useful when working with log files. Command emacspeak-speak-line-set-column-filter enables you to filter out uninteresting columns of each line as it is spoken. Note that columns are filtered out by making them inaudible ---in order for this to take effect, voice-lock needs to be active in the current buffer. You can invert the sense of the filter by invoking command emacspeak-toggle-speak-line-invert-filter.