\input texinfo
@setfilename./emacspeak.info
@settitle Emacspeak User's Manual
@ifinfo
$Id: emacspeak.texinfo,v 1.26 1995/08/02 23:55:09 raman Exp $
@end ifinfo 
@iftex
@finalout
@end iftex
@c @setchapternewpage odd
@c @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % for printing in double space
@end tex
@ifinfo
This file documents  Emacspeak, a speech interface to Emacs. 

Copyright (C) 1994, Digital Equipment Corporation
All Rights Reserved. 
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo
@c
@titlepage
@sp 6
@center @titlefont{Emacspeak User's Manual}
@sp 4
@center First Edition, Emacspeak Version 4.2A 
@sp 6
@center Digital Equipment Corporation 
@page
@ignore
@vskip 0pt plus 1filll
@end ignore

COPYRIGHT NOTICE 

Copyright (c) Digital Equipment Corporation, 1993, 1994, 1995.
All Rights reserved. Unpublished rights reserved under the 
copyright laws of the United States. Copyright is claimed in 
the computer program and user interface thereof. 

The software contained on this media is proprietary to and 
embodies the confidential technology of Digital Equipment 
Corporation. Possession, use, duplication or dissemination of 
the software and media is authorized only pursuant to a valid
written license from Digital Equipment Corporation. 

The name of Digital Equipment Corporation may not be used to endorse or 
promote products derived from this software without specific prior 
written permission. All other rights reserved.

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED 
WARRANTIES, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 
Digital assumes no responsibility AT ALL for the use or reliability of 
this software.

@itemize 
@item
 USE, DUPLICATION OR DISCLOSURE BY THE U.S. GOVERNMENT IS SUBJECT TO  
@item
 RESTRICTIONS AS SET FORTH IN SUBPARAGRAPH (c) DFARS 252.227-7013, 
@item
 OR IN FAR 52.227-19 OR IN 52.227-14 ALT III, AS APPLICABLE
@end itemize 
@end titlepage
@page

@ifinfo 
@node Top, Introduction, (dir), (dir)
@comment node-name, next,          previous, up

This manual documents Emacspeak, a speech interface to Emacs.  The
manual is divided into the following chapters.

@menu
* Introduction::                What exactly is Emacspeak?
* Synthesizers Supported::      The speech synthesizers Emacspeak
supports.
* Installation:: Retrieving and installing Emacspeak.
* Basic Usage::                 Basic movement and usage of Emacspeak.
* Compatibility::               Reading mail,
* Advanced Features::           For experts, hackers, and other weird people. 
* Future Directions::           What is planned for Emacspeak.
* Programming Interface::       Extending  emacspeak.
* Acknowledgements::            The people who made Emacspeak happen. 
Indices:
* Concept Index::               Menus of concepts. 
* Key Index::                   Menus of command keys and their references
* Command Index::               Menus of commands and their references
* Variable Index::              Menus of variables and their references

 --- The Detailed Node Listing ---

Synthesizers Supported 

* Dectalk Express ::            The portable Dectalk Express.
* Software Dectalk::            Dectalk in software on DECALPHA
* Dectalk MultiVoice::          Older Dectalks

Basic Usage
* Movement::                    Moving around in an Emacs buffer
* Action::                      Taking actions in a Emacspeak buffer 
                                (reading, changing state, ... )
* Miscellaneous::               Miscellaneous keybindings

Advanced Features

* Hooks::                       
* Other Variables::             

Internals of Emacspeak

* Global Variables::            
* Data Structures::             
* Miscellaneous Functions::     
@end menu

@end ifinfo

@node Introduction, Synthesizers Supported, Top, Top
@chapter  Introduction
@cindex Screen-Reading

Emacspeak is an Emacs subsystem that allows the user to
get feedback using synthesized speech. 

Screen reading programs allow a visually impaired user to get feedback
using synthesized speech. Such programs have been commercially available
for well over a decade. Most of them run on PC's under DOS, and there
are now a few screen-readers for the Windows platform.  However,
screen-readers for the UNIX environment have been conspicuous in their
absence.@refill 

This means that most visually impaired computer users face the
additional handicap of being DOS-impaired --- a far more serious
problem.@refill 

Emacspeak is an emacs subsystem that provides basic speech access 
functionality.  Emacspeak will always have the shortcoming that it will
only work under Emacs.  This said, there is very little that cannot be
done inside Emacs, so it's not a real shortcoming. 

Emacspeak does have a significant advantage: since it runs inside Emacs, a
structure-sensitive, fully customizable editor, Emacspeak often has more
context-specific information about what it is speaking than its commercial
counterparts.  In this sense, Emacspeak is not a ``screenreader'', it is a
subsystem that produces speech output.  A traditional screen-reader speaks the
content of the screen, leaving it to the user to interpret the visually
laid-out information.  Emacspeak, on the other hand, treats speech as a
first-class output modality; it speaks the information in a manner that is
easy to comprehend when listening.  @refill 

This initial version provides a basic speech subsystem for Emacs; using Emacs'
power and flexibility, it has proven  straightforward to add modules that customize how
things are spoken, e.g. depending on the major/minor mode of a given buffer.
Note that the basic speech functionality provided by Emacspeak is sufficient to use
most Emacs packages effectively; adding package-specific customizations makes
the interaction much smoother.  This is because package-specific extensions can
take advantage of the current context. 
Emacspeak currently comes with speech extensions for several popular
Emacs subsystems and editing modes.

@enumerate
@item
 W3 for surfing the WWW.
 @item
 VM For reading and replying to email.
 @item
 Gnus  for reading Usenet news.
 @item
Calendar for maintaining appointments etc.
@item
auctex for editing TeX and LaTeX.
@item
Dired for navigating a file system.
@item
 C and C++ editing extensions.
 @item
Calc for working with the Emacs Calculator.
@item
Info for listening to online documentation.
@item
Folding for using Emacs as a structured folding editor.
@item
Tempo a package that allows for editing templates.
This extension makes html-helper-mode speech friendly.
@item
Ispell for spell checking files.
@item
Eterm for launching terminal based programs.
This extension enables you to login to another system and get spoken
feedback,
as well as running programs that can only be run from the shell.
Note: eterm is a new improved terminal emulator by Perl Bothner
(bothner@@cygnus.com)
@item
Buffer-menu for navigating through the list of currently open buffers.
@item
Comint for command interpreters running in an inferior process. 
@end enumerate

In addition, other editing modes like Perl and TCL modes work fluently
with emacspeak
Emacspeak.

 Emacs-19's font-locking facilities are extended to the speech
output as well; for instance, a user can customize the system to have
different types of text spoken using different kinds of voices (speech
fonts).
Currently, this feature is used to provide ``voice locking`` for many
popular editing modes like c-mode, tcl-mode, perl-mode, emacs-lisp-mode
etc. 
 @refill 

The basic concepts used by Emacspeak are simple; all of the Emacs cursor
movement commands as well as the various input-output functions are
adapted to provide speech feedback.  Hence, a user can just use Emacs as
he normally would; Emacspeak works behind the scene to give audio
feedback in addition to updating the screen. @refill 



@node Synthesizers Supported, Installation, Introduction, Top
@comment current, next, previous, top 
@chapter Synthesizers Supported 
Emacspeak currently supports the DECtalk software (using dtk-mme). 

@menu
* DECtalk Software::            Dectalk in software on DECALPHA
@end menu


@node  DECtalk Software, Synthesizers Supported
@comment  node-name,  next,  previous,  up
@unnumberedsec DECtalk Software 


The DECtalk Software is a Dectalk Speech Synthesizer that runs in
software on the Digital UNIX workstations.  This software library allows user 
applications to produce synthesized speech.

To use the DECtalk Software with Emacspeak, you need to:
@itemize @bullet
@item Install DECtalk Software on your workstation.
@end itemize
@itemize 
@item
The following two items are performed automatically with @code{emacspeak}.  
These items enable you to add your own executable and shell program. 
@end itemize
@itemize @bullet
@item Set the environment variable @var{DTK_SH}
to the pathname to the dtk-mme executable. 
@item Set the environment variable @var{DTK_PROGRAM}
to "dtk-soft". 
@end itemize





@node Installation, Basic Usage, Synthesizers Supported, Top
 @comment node-name, next, previous, up
@chapter Installation
    This chapter  of the manual deals with getting, configuring, compiling, and
installing @i{Emacspeak}.

@ifinfo
@menu
* Quick Installation:: Default installation process.
* Configuring and Installing Emacspeak::  Configuring and Installing Emacspeak 
                                         and its associated files
* Starting Up:: How you run it.
@end menu
@end ifinfo 


@node Quick Installation, Configuring and Installing Emacspeak, Retrieving Emacspeak, Installation
@comment node-name, next, previous, up
@unnumberedsec Quick Installation

Here are the quick installation instructions.
See the next section for detailed installation instructions.

@itemize 
@item
 Look over the Makefile and edit site-specific variables.
@item
 Type @samp{make config} to configure the sources for your site.
@item
 Type @samp{make emacspeak} to compile the files.
@item
 Run it by doing one of:
@itemize
@item
  Start Emacs as follows:
   @example
emacs -l <emacspeak-dir>/emacspeak-setup.el -l ~/.emacs
@end example
@item
Add the line
@example
(load-file "<emacspeak-dir>/emacspeak-setup.el")
@end example
to the top of your .emacs file.
@item
 Run the shell script emacspeak.sh
found in the directory <emacspeak-dir>
@end itemize
In the above, <emacspeak-dir> refers to the directory where you unpacked
the sources. 
@end  itemize


@node  Configuring and Installing Emacspeak, Starting Up, Quick Installation, Installation
@comment  node-name,  next,  previous,  up
@unnumberedsec Configuring and Installing Emacspeak

Note: You need GNU Emacs 19 (19.23 or later) for using Emacspeak.
Emacspeak may work with other flavors of Emacs19, e.g. @code{xemacs}, but it
has not been tried. 

Decide where you want the Emacspeak elisp files.  Most Unix packages are
unpacked and compiled in one directory, and then the executable,
documentation, and data files are installed in the appropriate system
directories.  However, Emacspeak elisp byte-compiled files are
conventionally left in the same directory as the source files.  One
reasonable choice would be @file{/usr/local/lib/emacs/site-lisp/emacspeak}. 

Once you have decided on the appropriate directory, copy it from 
@file{/usr/opt/DTKEMSRT420/Macros/}.

@itemize 
@item The directory prefix for installation.  The default is @file{/usr/local},
so the executable file @file{dtk-mme} goes to @file{/usr/local/bin}.  
To change this, edit the line defining @var{prefix}.
@end itemize

Configure the source files by typing @samp{make config}.  

Next, compile the elisp files by typing 
@example
make emacspeak
@end example
Finally, install the executable files by typing 
@example
make install
@end example

The driver program can also be specified at run time by 
setting the shell environment variable @var{DTK_PROGRAM}. Note: This is the 
default value.
Examples: If using @code{csh} or @code{tcsh} 
@example
setenv DTK_PROGRAM "dtk-soft"
@end example
@noindent if using @code{sh} or @code{bash}
@example
DTK_PROGRAM=dtk-soft
export DTK_PROGRAM
@end example

You can always set this variable from a running Emacs session by
executing the Emacs setenv command.

@node Starting Up, ,  Configuring and Installing Emacspeak,  Installation
@comment  node-name,  next,  previous,  up
@unnumberedsec Starting Emacspeak

To use emacspeak you can do one of the following:

@itemize 
@item Add the line
 @example 
 (load-file (expand-file-name "@var{emacspeak_dir}/emacspeak-setup.el"))
 @end example 
to the start of your @file{.emacs} file.
This will start emacspeak every time you use Emacs.
(This might not be a good idea if a sighted person often uses your account.)
@item Alternatively, define @code{emacspeak} as an alias.  
If you use @code{csh} or @code{tcsh}:
@example
alias emacspeak "emacs -q -l @var{emacspeak_dir}/emacspeak-setup.el -l $HOME/.emacs"
@end example
@noindent If you use @code{bash} (the default under linux):
@example
alias emacspeak="emacs -q -l @var{emacspeak_dir}/emacspeak-setup.el -l $HOME/.emacs"
@end example
@noindent This could go into the system-wide initilization file (@file{/etc/profile})
or in the personal initialization file (in @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile})
Note: in all of the above you should of course replace @var{emacspeak_dir}
with your site-specific value 
@item Use the @code{emacspeak.sh} shell script which is equivalent to the above
alias, and is created during the above installation procedure.
@end itemize

Using any one of these methods will:

@itemize 
@item Add the Emacspeak code directory to the load-path.
@item Load the relevant libraries.
@item Start up Emacspeak.
@end itemize


@node Basic Usage, Compatibility, Installation, Top
@comment node-name, next, previous, up
@chapter Basic Usage

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

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

@ifinfo 
@menu
* Movement::                    Moving around in an Emacs buffer
* Action::                      Taking actions in a Emacspeak buffer 
                                (reading, changing state, ... )
* Miscellaneous::               Miscellaneous keybindings
@end menu
@end ifinfo


@node Movement, Action, Basic Usage, Basic Usage
@unnumberedsec Movement

All of the normal Emacs movement commands will speak the relevant
information after moving.
Here are some of the cursor movement functions that have  been speech
enabled.
Note that this list only enumerates a few of these speech enabled
commands;
the purpose of emacspeak is to speech-enable all of emacs and provide
you spoken feedback as you work.
Thus, this list is here only as a representative example of the kind of
speech-enabling extensions Emacspeak  provides.

@table @kbd
@item C-n
@itemx M-x next-line
@itemx @key{down}
@findex  next-line 
@kindex C-n 
Speaks line moved to.

@item C-p
@itemx M-x previous-line
@itemx @key{up}
@findex previous-line 
@kindex C-p
Speaks line moved to.

@item M-f
@itemx M-x forward-word
@findex forward-word 
@kindex M-f 
Speaks word moved to.
Places point on the first character of the next work, rather than on the space
preceding it

@item M-b
@itemx M-x backward-word
@findex backward-word 
@kindex M-b
Speaks word moved to.

@item M-C-f
@itemx M-x forward-sexp
@findex forward-sexp 
@kindex M-C-f 
Speaks sexp moved to.
If the sexp spans more than a line, only the first line is spoken. 

@item M-C-b
@itemx M-x backward-sexp
@findex backward-sexp 
@kindex M-C-b
Speaks sexp moved to.
If the sexp spans more than a line, only the first line is spoken. 

@item M-<
@item M-x beginning-of-buffer
@findex beginning-of-buffer
@kindex M-<
Speaks line moved to.

@item M->
@itemx M-x end-of-buffer
@findex end-of-buffer 
@kindex M->
Speaks line moved to.

@item M-m
@itemx M-x back-to-indentation
@findex back-to-indentation 
@kindex M-m
Speaks entire current line. 
A useful way of hearing the current line. 
@end table

For a complete list of the functions that have been advised, see file
@file{emacspeak-advice.el}.


@node Action, Miscellaneous, Movement, Basic Usage
@unnumberedsec Action

While typing in an Emacs buffer, hitting space  speaks  the recently typed
word.  Under Emacs19, use @code{load-library ret completion ret} for loading
the completion package.  

The standard Emacs I/O functions have also been advised to speak.
All forms of completion, including minibuffer 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
@item
 Emacspeak commands for listening to chunks of information.
 The names of these  commands all start with the common prefix @code{emacspeak-}.
 All Emacspeak commands are bound to the keymap @var{emacspeak-keymap} and are accessed with the key @kbd{Control e}@footnote{
 Control 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{Control-e l}.
 If for some reason you wish to use some key other than @kbd{control-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{Control-e}@footnote{d is mnemonic for Dectalk.}.
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{Control 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{Control-h Control-e}

 @node Miscellaneous,  , Action, Basic Usage
@unnumberedsec Miscellaneous

Reading without moving point: 

The following commands allow you to listen to information without moving
point (point is emacs terminology for the editing cursor).

Emacspeak uses @kbd{C-e} as a prefix-key.  Note: In all of the
following, a prefix arg (conventionally @key{C-u}) will read the "rest
of the unit" and a negative prefix arg (conventionally @key{C-u -}) will
read the initial part of the unit before point.  As an example, given
the sexp @code{emacspeak-speak-sexp} with point on the @code{-}
preceding the @code{speak}, @dfn{emacspeak-speak-speak} will say:

  @itemize
   @item @code{emacspeak-speak-region} with no prefix-arg.
    @item @code{speak-region}
 with a positive prefix-arg.
  @item @code{emacs} with a negative prefix arg.
 @end itemize

Note: For a better way of reading the beginning and or rest of a line
etc, see the extended Emacspeak reading commands such as
@code{emacspeak-speak-line-interactively}.

 
@table @kbd
@item C-el
@item M-x emacspeak-speak-line
@findex   emacspeak-speak-line 
@kindex C-el 
Speaks  current line.

@item C-e @key{up}
@itemx M-x emacspeak-read-next-line
@findex   emacspeak-read-next-line 
@kindex C-e @key{up}
Speaks previous line (without moving point).
Numeric prefix arg can specify offset relative to current line. (Useful
in shell buffers to quickly look at the output. )

@item C-e @key{down}
@itemx M-x emacspeak-read-next-line
@findex   emacspeak-read-next-line 
@kindex C-e @key{down}
Speaks next line (without moving point).
Numeric prefix arg can specify offset relative to current line.  (Useful
in shell buffers to quickly look at the output.)

@item C-e .
@itemx M-x emacspeak-speak-sentence
@findex   emacspeak-speak-sentence 
@kindex C-e .
Speaks current sentence. 

@item C-e '
@itemx M-x emacspeak-speak-sexp
@findex   emacspeak-speak-sexp 
@kindex C-e' 
Speaks current sexp. 

@item C-e w
@itemx M-x emacspeak-speak-word
@findex   emacspeak-speak-word 
@kindex C-e w
Speaks current word.

@item C-e c
@itemx M-x emacspeak-speak-char
@findex   emacspeak-speak-char 
@kindex C-e c 
Speaks current char.

@item C-e r
@itemx M-x emacspeak-speak-region
@findex   emacspeak-speak-region
@kindex  C-e r
Speaks current region.

@item C-e b
@itemx M-x emacspeak-speak-buffer 
@findex   emacspeak-speak-buffer 
@kindex C-e b 
Speaks current buffer.

@item C-e h
@itemx M-x emacspeak-speak-help
@findex   emacspeak-speak-help
@kindex C-e h
Speaks current help buffer if present.

@item C-e C-i
@itemx M-x emacspeak-speak-completions
@findex   emacspeak-speak-completions 
@kindex C-e C-i  
Speaks possible completions if any listed. 
@end table

The following commands provide miscellaneous information.
@table @kbd
@item C-e v
@itemx M-x emacspeak-speak-version
@findex   emacspeak-speak-version 
@kindex C-e v
Identifies current version of Emacspeak. 

@item C-e t
@itemx M-x emacspeak-speak-time
@findex   emacspeak-speak-time 
@kindex C-e t
Speaks date and time.

@item C-e m
@itemx M-x emacspeak-speak-mode-line
@findex   emacspeak-speak-mode-line
@kindex C-e m
Speaks concise mode-line. Only major mode information is spoken.

@item C-e M
@item C-e h
@itemx M-x emacspeak-speak-help
@findex   emacspeak-speak-help
@kindex C-e h
Speaks help buffer.

@itemx M-x emacspeak-speak-minor-mode-line
@findex   emacspeak-speak-minor-mode-line
@kindex C-e M
Speaks minor mode information.

@end table

@node Compatibility, Advanced Features, Basic Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Compatibility with Emacs subsystems 

Write one node for each subsystem, e.g. vm, gnus, ...@refill 
Note: emacspeak already works with these subsystems, writing additional
modules will customize how things get spoken.

@node Advanced Features, Future Directions, Compatibility, Top
@comment  node-name,  next,  previous,  up
@chapter Advanced Features

@ifinfo 
@menu
* Hooks::                       
@end menu
@end ifinfo

@node Hooks, Other Variables, Advanced Features, Advanced Features
@unnumberedsec Hooks
@cindex Hooks
These are the various hooks you can use to customize some of Emacspeaks
behavior.  They are arranged in the order in which they would
happen. 

@var{dtk-startup-hook} specifies a list of
functions to run after starting the speech system. You can set the
speech-device state, e.g. speech-rate etc in this hook. 

@var{emacspeak-startup-hook} is run after Emacspeak has been started up.

@node  Acknowledgements, Concept Index, Programming Interface, Top
@comment  node-name,  next,  previous,  up
@chapter Acknowledgements
Emacspeak was developed by T.V. Raman, and would not have come about without input from the following people:@refill 

Dave Wecker who goaded me into writing this package.

Hans Chalupsky  whose advice package makes Emacspeak work.


@bye
