@c $Id$
@node Basic Usage
@chapter Basic Usage.

This chapter gives an overview of how to use Emacspeak; for a full
listing of Emacspeak keybindings, see @xref{emacspeak}.  Note: This
documentation should be used in conjunction with the online Emacs info
pages that extensively document Emacs itself.  These sections briefly
describe the speech-enabling extensions.  However, they should not be
considered a substitute for reading the Emacs manual.  How successfully
you use Emacspeak will depend on how well you learn your Emacs.

All Emacs navigation and editing commands have been speech enabled.
Thus, moving to the next or previous word, line or paragraph results
in the text around point being spoken.  Exactly how much text is
spoken is determined by the amount by which you moved.

In addition, Emacspeak provides  basic reading functions that can be
invoked to listen to chunks of text without moving.

@menu
* Overview::                     Basic Overview.
* Working::                      Working in Emacspeak.
* Reading::                      Reading chunks of information.
* Speech System::                Controlling Speech Output.
* Voice-lock::                   Audio Formatting.
* Status Information::           Speaking Status Information.
@end menu

@node Overview
@section Emacspeak Overview

Emacspeak provides a small number of core services around which the
remainder of the audio interface is constructed.  These essential
features of the software are briefly outlined in the following
paragraphs; the commands by which they can be controlled will be
described later in the manual.

Apart from providing a fluent spoken interface to all of Emacs' basic
editing functions, Emacspeak also includes software modules which add
speech feedback to a range of applications that can be run from within
Emacs. In this sense, Emacspeak amounts to much more than a talking
text editor; indeed, it can more aptly be characterized as a true
``audio desktop'', in which speech is treated as a first-class output modality.

Emacspeak implements a special minor mode, known as ``voice lock mode''
(@pxref{Voice-lock}) which uses distinct speech characteristics to
provide aural highlighting of specific textual constructs, such as
comments in program code, quoted strings and reserved words @xref{ Voice
Lock}. This facility is further extended when Emacspeak is used with the
@code{EWW} and @code{W3} Web browsers, to enable the semantic and
structural distinctions captured by the HTML markup to be communicated
efficiently @xref{Web Browsing}.

It is often desirable to exercise control over the pronunciation of a
word (E.G. a technical term or a reserved word in a programming
language) within specific contexts. Emacspeak maintains pronunciation
dictionaries for this purpose, which may be customized by the
user. Moreover, individual dictionaries can be activated selectively,
depending for example on the current major mode or the name of the
file which is being visited @xref{emacspeak-pronounce}.

In addition to spoken feedback, Emacspeak can generate ``auditory
icons'' @MDash{} short sound cues which alert the user to significant
events, for example the opening or deletion of a file, the completion
of an action, the arrival of an electronic mail message or the
creation of a completion buffer. Sound cues act as a supplement to the
spoken interface, and are especially valuable to the experienced user
in facilitating rapid interaction. Note that in order to support
auditory icons, the computer must be equipped with sound hardware for
which the operating system has been correctly configured
@xref{emacspeak-sounds}.

@node Working
@section  Using Emacs Buffers

While typing in an Emacs buffer, hitting space speaks the recently
typed word.  I use completion all the time; so Emacspeak will speak
the completion just inserted as well as the next possible completion.
In Emacs, use @kbd{M-x load-library @key{RETURN} completion
@key{RETURN}} for loading the completion package.

The standard Emacs prompting functions have also been speech-enabled.
Emacs prompts with available lists of completions in response to partial
input wherever appropriate  @MDash{} all forms of completion provide speech
feedback.

In addition, Emacspeak provides a number of commands for reading
portions of the current buffer, getting status information, and
modifying Emacspeak's state.

All of the commands are documented in the subsequent sections.
They can be classified into types:

@itemize @bullet
@item
Emacspeak commands for listening to chunks of information.  The names
of these commands all start with the common prefix
@code{emacspeak-speak-}.  All Emacspeak commands are bound to the
keymap @var{emacspeak-keymap} and are accessed with the key
@kbd{C-e}@footnote{ C-e is mnemonic for Emacspeak.}.  Thus,
the Emacspeak command @dfn{emacspeak-speak-line} is bound to @kbd{l} in
keymap @var{emacspeak-keymap} and can be accessed with the keystroke
@kbd{C-e l}.  If for some reason you wish to use some key other
than @kbd{C-e} as the common keyboard prefix for all Emacspeak
commands, set the variable @var{emacspeak-prefix}.

@item
The second category of commands provided by Emacspeak manipulate the
state of the speech device.  The names of these commands start with
the common prefix @code{dtk-} and are bound in keymap
@var{emacspeak-dtk-submap}.

You can access these commands via the prefix @kbd{C-e d}
@footnote{Historically, d was mnemonic for Dectalk; note that nothing
in Emacspeak is DECTalk specific.}.  Thus, the command
@dfn{dtk-set-rate} is bound to @kbd{r} in keymap
@var{emacspeak-dtk-submap} and can be executed by pressing
@kbd{C-e d r}.
@end itemize

Emacs has extensive online help; so does emacspeak.  Please use it.

This info manual is only to get you started.  You can get a summary of
Emacspeak's features by pressing @kbd{C-h C-e}

@node Reading
@section Reading Without Moving

Emacspeak speaks information as you move around within a buffer.  How
much text is spoken depends on how you move, thus, when you move by
words, you hear the current word; when you move by paragraphs, you
hear the current paragraph spoken.  In addition, the following
commands allow you to listen to information without moving point
(point is emacs terminology for the editing cursor).

Reading without moving point:

@table @kbd

@findex emacspeak-speak-char
@kindex C-e c
@item C-e c
@code{emacspeak-speak-char}

Speak character under point.  Pronounces character phonetically unless
called with a PREFIX arg.

@findex emacspeak-speak-word
@kindex C-e w
@item C-e w
@code{emacspeak-speak-word}

Speak current word.  With prefix ARG, speaks the rest of the word from
point.  Negative prefix arg speaks from start of word to point.  If
executed on the same buffer position a second time, the word is
spelled instead of being spoken.

@findex emacspeak-speak-line
@kindex C-e l
@item C-e l
@code{emacspeak-speak-line}

Speaks current line.  With prefix ARG, speaks the rest of the line
from point.  Negative prefix optional arg speaks from start of line to
point.  Voicifies if option `voice-lock-mode' is on.  Indicates
indentation with a tone or a spoken cue if audio indentation is in
use.  Indicates position of point with an aural highlight if option
`emacspeak-show-point' is turned on @MDash{} see command
@code{emacspeak-show-point} bound to @kbd{C-e C-d}.  Lines that start
hidden blocks of text, e.g.  outline header lines, or header lines of
blocks created by command `emacspeak-hide-or-expose-block' are
indicated with auditory icon ellipses.

@findex emacspeak-read-previous-line
@kindex C-e @key{UP}
@item C-e @key{UP}
@code{emacspeak-read-previous-line}

Read previous line, specified by an offset, without moving.  Default
is to read the previous line.

@findex emacspeak-read-next-line
@kindex C-e @key{DOWN}
@item C-e @key{DOWN}
@code{emacspeak-read-next-line}

Read next line, specified by an offset, without moving.  Default is to
read the next line.

@findex emacspeak-speak-paragraph
@kindex C-e p
@item C-e p
@code{emacspeak-speak-paragraph}

Speak paragraph.  With prefix arg, speaks rest of current paragraph.
Negative prefix arg will read from start of current paragraph to
point.  If voice-lock-mode is on, then it will use any defined
personality.

@findex emacspeak-speak-region
@kindex C-e r
@item C-e r
@code{emacspeak-speak-region}

Speak current region delimited by @dfn{point} and @dfn{mark}.  When
called from a program, argument START and END specify region to speak.

@findex emacspeak-speak-rectangle
@kindex C-e  cap R
@item C-e  cap R
@code{emacspeak-speak-rectangle}

Speak a rectangle of text.  Rectangle is delimited by point and mark.
When call from a program, arguments specify the START and END of the
rectangle.

@findex emacspeak-speak-buffer
@kindex C-e b
@item C-e b
@code{emacspeak-speak-buffer}

Speak current buffer contents.  With prefix ARG, speaks the rest of
the buffer from point.  Negative prefix arg speaks from start of
buffer to point.  If voice lock mode is on, the paragraphs in the
buffer are voice annotated first, see command
@code{emacspeak-speak-voice-annotate-paragraphs}.  This provides the
auditory equivalent of @emph{dropped caps} from visual typography.

@findex emacspeak-speak-rest-of-buffer
@kindex C-e n
@item C-e n
@code{emacspeak-speak-rest-of-buffer}

Speak remainder of the buffer starting at point

@findex emacspeak-speak-this-buffer-other-window-display
@kindex C-e /
@item C-e /
@code{emacspeak-speak-this-buffer-other-window-display}

Speak this buffer as displayed in a different frame.  Emacs allows you
to display the same buffer in multiple windows or frames.  These
different windows can display different portions of the buffer.  This
is equivalent to leaving a book open at places at once.  This command
allows you to listen to the places where you have left the book open.
The number used to invoke this command specifies which of the displays
you wish to speak.  Typically you will have two or at most three such
displays open.  The current display is 0, the next is 1, and so on.
Optional argument ARG specifies the display to speak.

@findex emacspeak-speak-this-buffer-previous-display
@kindex C-e @key{LEFT}
@item C-e @key{LEFT}
@code{emacspeak-speak-this-buffer-previous-display}

Speak this buffer as displayed in a `previous' window.  See
documentation for command
@code{emacspeak-speak-this-buffer-other-window-display} for the meaning of
`previous'.

@findex emacspeak-speak-this-buffer-next-display
@kindex C-e @key{RIGHT}
@item C-e @key{RIGHT}
@code{emacspeak-speak-this-buffer-next-display}

Speak this buffer as displayed in a `previous' window.
See documentation for command
@code{emacspeak-speak-this-buffer-other-window-display} for the
meaning of `previous'.

@findex emacspeak-speak-page
@kindex C-e [
@item C-e [
@code{emacspeak-speak-page}

Speak a page.  With prefix ARG, speaks rest of current page.  Negative
prefix arg will read from start of current page to point.  If option
`voice-lock-mode' is on, then it will use any defined personality.

@findex emacspeak-speak-predefined-window
@kindex C-e DIGIT
@item C-e DIGIT
@code{emacspeak-speak-predefined-window}

Speak one of the first 10 windows on the screen.  In general, you'll
never have Emacs split the screen into more than two or three.
Argument ARG determines the 'other' window to speak.  Speaks entire
window irrespective of point.  Semantics of `other' is the same as for
the builtin Emacs command `other-window'.

@findex emacspeak-speak-next-window
@kindex C-e C-n
@item C-e C-n
@code{emacspeak-speak-next-window}

Speak the next window.

@findex emacspeak-speak-previous-window
@kindex C-e C-p
@item C-e C-p
@code{emacspeak-speak-previous-window}

Speak the previous window.

@findex emacspeak-speak-other-window
@item emacspeak-speak-other-window
Speak contents of `other' window.  Speaks entire window irrespective
of point.  Semantics of `other' is the same as for the builtin Emacs
command `other-window'.  Optional argument ARG specifies `other'
window to speak.

@findex emacspeak-owindow-previous-line
@kindex @key{ESCAPE} @key{UP}
@item @key{ESCAPE} @key{UP}
@code{emacspeak-owindow-previous-line}

Move to the next line in the other window and speak it.
Numeric prefix arg COUNT specifies number of lines to move.

@findex emacspeak-owindow-next-line
@kindex @key{ESCAPE} @key{DOWN}
@item @key{ESCAPE} @key{DOWN}
@code{emacspeak-owindow-next-line}

Move to the next line in the other window and speak it.
Numeric prefix arg COUNT can specify number of lines to move.

@findex emacspeak-owindow-scroll-up
@kindex @key{ESCAPE} next
@item @key{ESCAPE} next
@code{emacspeak-owindow-scroll-up}

Scroll up the window that command `other-window' would move to.
Speak the window contents after scrolling.

@findex emacspeak-owindow-scroll-down
@kindex @key{ESCAPE} prior
@item @key{ESCAPE} prior
@code{emacspeak-owindow-scroll-down}

Scroll down  the window that command `other-window' would move to.
Speak the window contents after scrolling.

@findex emacspeak-speak-sexp
@item emacspeak-speak-sexp
Speak current sexp.  With prefix ARG, speaks the rest of the sexp from
point.  Negative prefix arg speaks from start of sexp to point.

@findex emacspeak-speak-spaces-at-point
@kindex C-e meta C-@@
@item C-e meta C-@@
@code{emacspeak-speak-spaces-at-point}
Speak the white space at point.

@end table
@node Speech System


@section Speech System Commands
@include tts.texi

@node Voice-lock
@section Voice Lock Mode

The status of voice lock mode can be toggled on and off in the current
buffer by issuing the command @kbd{C-e d v} (M-x voice-lock-toggle).

Voice-lock is turned on automatically in all buffers that support it
when Emacspeak is started.

Emacspeak can be set to disable voice lock in all of the major modes
that support it. To do so, insert the following statement into your
Emacs initialization file:

@lisp
(global-voice-lock-mode -1)
@end lisp


The characteristics of the different voice personalities used by voice
lock mode vary according to the capabilities of the speech
synthesizer. The definitions applicable to the Dectalk family of
synthesizers are contained in @file{dectalk-voices.el}, which is
supplied as part of the Emacspeak distribution. The Emacspeak
distribution also contains voice definitions for many other
synthesizers.

Using voice lock mode, Emacspeak also supports many of the aural style
properties defined in level 2 of the World Wide Web Consortium's
Cascading Style Sheet specification (see
@url{http://www.w3.org/TR/REC-CSS2/}. Thus, when Emacspeak is running
in conjunction with a cooperating user agent, such as William Perry's
Emacspeak/W3 web browser, the rendering of HTML documents can be
regulated by style sheets. Examples of style rules which employ the
CSS audio properties can be found in the default style sheet which is
supplied in the Emacs/W3 distribution.


@node Status Information
@section Status  Commands


The following commands provide miscellaneous information.
@table @kbd

@findex emacspeak-speak-message-again
@kindex C-e a
@item C-e a
@code{emacspeak-speak-message-again}

Speak the last message from Emacs once again.

@findex emacspeak-speak-mode-line
@kindex C-e m
@item C-e m
@code{emacspeak-speak-mode-line}

Speak the mode-line.

@findex emacspeak-speak-minor-mode-line
@kindex C-e  cap M
@item C-e  cap M
@code{emacspeak-speak-minor-mode-line}

Speak the minor mode-information.

@findex emacspeak-speak-header-line
@kindex C-e SPC
@item C-e SPC
@code{emacspeak-speak-header-line}

Speak the header-line.

@findex emacspeak-speak-window-information
@kindex C-e C-w

@item C-e C-w
@code{emacspeak-speak-window-information}

Speaks information about current windows.

@findex emacspeak-speak-time
@kindex C-e t
@item C-e t
@code{emacspeak-speak-time}

Speak the time.

@findex emacspeak-speak-version
@kindex C-e cap V
@item C-e cap V
@code{emacspeak-speak-version}

Announce version information for running Emacspeak.

@findex emacspeak-speak-buffer-filename
@kindex C-e f
@item C-e f
@code{emacspeak-speak-buffer-filename}

Speak name of file being visited in current buffer.
Speak default directory if invoked in a dired buffer,
or when the buffer is not visiting any file.

@findex emacspeak-speak-help
@kindex C-e h
@item C-e h
@code{emacspeak-speak-help}

Speak help buffer if one present.
With prefix arg, speaks the rest of the buffer from point.
Negative prefix arg speaks from start of buffer to point.

@findex emacspeak-speak-current-kill
@kindex C-e k
@item C-e k
@code{emacspeak-speak-current-kill}

Speak the current kill entry.  This is the text that will be yanked in
by the next @kbd{C-y}.  Prefix numeric arg, COUNT, specifies that the text
that will be yanked as a result of a @kbd{C-y} followed by count-1 @kbd{M-y} be
spoken.  The kill number that is spoken says what numeric prefix arg
to give to command @code{yank}.

@findex emacspeak-view-register
@kindex C-e v
@item C-e v
@code{emacspeak-view-register}

Display the contents of a register, and then speak it.

@findex emacspeak-speak-current-mark
@kindex C-e C-@@
@item C-e C-@@
@code{emacspeak-speak-current-mark}

Speak the line containing the mark.  With no argument, speaks the line
containing the mark @MDash{} this is where `exchange-point-and-mark'
C-x C-x would jump.  Numeric prefix arg 'COUNT' speaks line containing
mark 'n' where 'n' is one less than the number of times one has to
jump using `set-mark-command' to get to this marked position.  The
location of the mark is indicated by an aural highlight achieved by a
change in voice personality.

@findex emacspeak-speak-line-number
@kindex C-e C-l
@item C-e C-l
@code{emacspeak-speak-line-number}

Speak the line number of the current line.

@findex emacspeak-speak-current-column
@kindex C-e =
@item C-e =
@code{emacspeak-speak-current-column}

Speak the current column.


@findex emacspeak-speak-current-percentage
@kindex C-e %
@item C-e %
@code{emacspeak-speak-current-percentage}

Announce the percentage into the current buffer.

@end table
