emacspeak 41.0+dfsg-2 / usr / share / doc / emacspeak / FAQ

Emacspeak FAQ -- Frequently Asked Questions
$Id: FAQ 4047 2006-08-11 19:11:17Z tv.raman.tv $
Author: T. V. Raman <raman@cs.cornell.edu>
Copyright (C) 1995 -- 2002,    T. V. Raman  
 All Rights Reserved. 

*Introduction:
This document lists Frequently (and alas not so frequently )
asked questions about using Emacspeak as a full-featured
audio desktop.

* How to use this FAQ:

When running Emacspeak, use command
emacspeak-view-emacspeak-faq bound by default to "C-e F".
This FAQ is structured  with sectional headers at
different levels marked with "*".  Use Emacs" outlining
features to navigate through the structure-- note that when
opened this document automatically turns on outline mode.

* How to contribute to this FAQ:
** Contributing new questions with answers:

New questions with answers should be mailed to the emacspeak
mailing  list with the subject line

FAQ: <question>

where <Question> is a brief one line description of the
question.  The body of the message should contain <Question>
as an outline header, followed by a blank line, followed by
a brief and succinct answer.

If you wish to place the question in a specific section of
the FAQ, indicate this 
before the  "* <Question>" line in the body of your message.

** Contributing updates to an existing question:

Use the same format as above, but say "FAQ:Update" in the
subject line. The "* <Question>" line should match the
section you are contributing an update to.

* Contributing code and patches to Emacspeak:

emacspeak is hosted at sourceforge and you can get access to
the latest  snapshot of the code via anonymous cvs.

If you intend contributing code or patches to emacspeak,

0: first check out the latest working copy from the CVS
   repository,

1: Integrate and test your code in that  checked out
   version,

2: Mail the patch to the emacspeak mailing list.

The easiest way to check out the emacspeak code from  CVS 
is to use CVS from the shell.

Emacspeak comes with a convenience command
`emacspeak-cvs-get-anonymous' that will get the code into
your home directory under ~/cvs-emacspeak/emacspeak

Subsequent invocations of that  command will update this
working copy.

** Coding Guidelines:

Emacspeak is a large system with a consistent coding style.
If you contribute patches, your patches *must* adhere to the coding
conventions used in the rest 
of the Emacspeak code-base.

Here are some of the key coding guidelines:

A) Consistent naming  --study some of the core modules for guidance.
B) Consistent use of CL --Common Lisp 
C) Consistent declaration of dynamic variables via CL macro declare 
D) Clear documentation of user level commands
E) Use package checkdoc to check your coding style.
F) Byte compile your code and make sure it compiles with no warnings or errors.

* How to join the Emacspeak user group:

The Emacspeak mailing list at <emacspeak@cs.vassar.edu> is
run by Greg Priest-Dorman.  Do not send out subscription
requests to the list address; you can subscribe by sending a
message to  <emacspeak-request@cs.vassar.edu> with a
subject line of "subscribe".  To unsubscribe or change your
address send mail to <emacspeak-request@cs.vassar.edu> with
a subject of "unsubscribe" or "help".


* Commonly Reported Problems:

** Emacspeak hits errors under Emacs 20.3:

Make sure you are running Emacs in unibyte mode.  You should
set the shell environment variable EMACS_UNIBYTE *before*
starting Emacs 20.3.

* Switching from a screen-reader to Emacspeak:

Emacspeak provides an audio desktop by speech-enabling Emacs
--it's *not* a screen-reader.

The tips in this section are designed to help the
screen-reader user  in the transition  to using a
speech-enabled environment.

** Why Emacspeak is not a screen-reader:

The short answer is  "Emacspeak builds speech feedback
directly into the applications you use".
This allows the user to focus on the task at hand. 

For a detailed explanation of the speech-enabling approach
versus  screen-readers, see my publications on the WWW site.

You will not use emacspeak productively if you simply start
up Emacs and run only terminal oriented applications such as
pine and lynx inside Emacs --this is *not* what Emacspeak
was designed for.

** How do I run terminal oriented applications?

You should run terminal oriented applications such as pine
or lynx undr emacspeak only as a last option, i.e. there is
no equivalent functionality provided by an Emacs package.
This is because when you run terminal oriented applications
within Emacspeak, emacspeak degenerates into an ordinary 
screen-reader and you lose all the benefits of the
speech-enabling approach.  Further, the speech support for
the Emacs terminal is implemented purely to be a fall-back
option.


** Use M-x term for terminal applications:

If you do find yourself in the situation of having to run
terminal oriented applications such as telnet for logging
into another machine, make sure to use M-x term which brings
up a terminal inside Emacs.
This terminal is fully speech-enabled by Emacspeak.

** What Not To Do:

*** Do not run terminal oriented applications inside a shell
buffer i.e. inside what you get with M-x shell.
Use M-x shell for an interactive shell where you run
command-line utilities like 
Latex,  compiling programs etc.

*** Do not use M-x terminal, M-x rlogin or M-x telnet.

** Running telnet sessions:

If you program or do other intensive computing tasks on
remote machines,   you are better off running Emacspeak on
the remote machine
and having the speech output on your local desktop.

For doing small amounts of work on remote machines, use the
terminal you get with M-x term; alternatively,
you can use the Emacspeak shortcut
emacspeak-eterm-remote-term bound to C-e C-r
to login to a workstation in your local domain.

* Desktop Applications:

 What is the Emacs equivalent of  application XXX?
Note: this list is *not* meant to be exhaustive.
For an overview of all available packages in your Emacs
installation,  use Emacs' built-in package finder invoked
via "C-h p".
** Mail reading:

Use Vm, mh-e or Emacs' builtin rmail.

VM and RMail are speech-enabled by Emacspeak. MH-E is not
speech-enabled, but is completely usable with emacspeak as
is.
Of these packages, VM is not bundled with Emacs, but it's
the mail reader I use.

** Viewing UNIX online man pages:

Use M-x man inside emacs.

** Browsing the WWW:

Use W3 inside Emacs. W3 is not bundled with emacs.

** How do I browse the file-system,  delete or rename files
    etc?

Use Emacs dired for doing complex file operations --this is
in general  more efficient and less error-prone than
doing such operations from a shell.

** How do I maintain appointments?

Use the Emacs calendar.

** How do I read Usenet news?

Use gnus --the Emacs newsreader of choice.
Gnus is bundled with all new versions of emacs.

** How do I author documents?

** HTML for WWW documents:

For documents meant purely for online publication, use
html-helper-mode (not bundled with Emacs)
and create well-structured HTML documents. These documents
can be previewed as you work using the W3 browser.

** XML for structured data:

Use psgml --a powerful SGML/XML package and create
structured data as XML.

** High-quality print documents:

Use LaTeX or any of the  other tools from the TeX family to
produce high-quality visual documents from well-structured
source.
Use Emacs' auctex --a powerful package for authoring and
maintaining La)TeX documents for working with LaTeX; note
that auctex is fully speech-enabled by Emacspeak.

** I want to have a symbolic calculator!

Use the Calc package --described as a poor-man's
Mathematica. Calc is fully speech-enabled by Emacspeak.

**  What spreadsheet applications can I use?

In the past I used sc -- a curses based terminal oriented
spreadsheet inside the Emacs terminal (see the later section
on M-x term).
I have now almost entirely switched over to using dismal --a
spreadsheet package implemented inside Emacs.
The speech-enabled dismal spreadsheet is far more pleasant
to work with than sc inside a terminal.




* Basic Concepts For Working With The Emacspeak Desktop:

The desktop is the work area where you organize the tools of
your trade and the information objects relevant to your
current activities.  In the conventional world of visual
GUI-based computing, these tools and information objects
manifest themselves as a collection of icons organized in a
two-dimensional work-area --this organization is designed to
place frequently used objects within easy reach.

Notice that organizing one's work area in terms of visual
icons arranged in a two-dimensional area where such an
organization is optimized for the available "conversational
gestures" of pointing and clicking is an artifact of visual
interaction.

In the spirit of a truly speech-enabled application,
Emacspeak does not simply provide you spoken access to a
particular presentation of your work environment that was
initially designed with the "sign language" of visual
interaction in mind. Instead, Emacspeak enables you to work
with documents and other information objects in a manner
that is optimized to aural, eyes-free interaction.  A
necessary consequence of this setup is that users accustomed
to the purely visual manifestation of today's electronic
desktop do not immediately perceive the Emacspeak
environment as an electronic desktop.  This section of the
FAQ hopes to introduce you to a work-style that encourages a
different perspective on how one interacts with the computer
in performing day-to-day computing tasks.

The end result in my case has been a marked increase in
personal productivity.

** Objects Making Up The Emacspeak Desktop:

A "buffer" is the basic building block of the Emacs and
hence the Emacspeak desktop.  Any information presented by
Emacs is placed in a "buffer".  For example, when perusing
this FAQ within Emacs, the "file" containing the FAQ is
presented in a "buffer".  All information objects such as
WWW pages, email messages, output from user interaction with
command-line shells etc., are presented by Emacs in
individual "buffers".


Buffers provide a base level of user interaction;
Emacs derives its power by allowing applications to
specialize buffers to enable specific types of
user-interaction that is optimized for 
a specific class of information.

** An Object-Oriented Desktop:

The basic "buffer object" 
can be specialized by Emacs applications to provide optimal
interaction.
This kind of specialization makes the Emacs environment an
object-oriented environment; thus, the basic conversational
gesture of 
"move to the next statement" can be assigned behavior that
is appropriate to the content that the user is currently
navigating.
As an example of such specialization, Emacs provides
"specialized  modes" for working with English text, 
programming languages, markup source e.g. HTML or LaTeX
documents and so on.


** Emacspeak Specializes Aural Interaction Based On Content:

The content-specific user interaction described above is a
very powerful feature of Emacs, and this is where Emacspeak
derives its power.  Traditionally, the ability to create
buffers specialized for working with specific content-types
has been used by the Emacs community to develop versatile
programming environments, messaging applications such as
mail and news readers, and authoring environments.  The
clean design present in all of these Emacs extensions in
terms of separating application functionality from the
user-interface, combined with the availability of the entire
source code making up these packages under the open-source
model has laid the ground-work for developing Emacspeak as
a versatile aural counterpart to the product of years of
software engineering that has been invested by the Emacs
community.  In short, Emacspeak would not exist in its
present shape or form without this prior effort.

** Specialized Aural Interaction:

*** Audio Formatting:

Emacspeak takes advantage of the content-specific knowledge
available within specialized buffers to produce "audio
formatted" output designed to optimize user interaction.
A basic consequence of the above is "voice locking" in
specialized modes; a more interesting consequence is the
implementation of Aural Cascading Style Sheets (ACSS) in
conjunction with the Emacs W3 browser.

*** Structured Navigation:

Emacspeak  also exploits content-specific knowledge to provide
structured navigation of different types of 
electronic content. In many cases, such structured
navigation is an extension of what Emacs provides by
default; in other cases, 
Emacspeak implements the necessary extensions to provide the
level of structural navigation needed to work efficiently in
an eyes-free environment.


Notable among such structured navigation is Emacs' powerful
outline feature. Notice that this FAQ itself takes advantage
of Emacs' outline mode to allow you to easily move through
the various sections.  An example of content-sensitive
navigation is provided by the imenu package which
dynamically creates a "table of contents" based on the
content that is being displayed in a given buffer.

*** Navigating The Desktop:

In addition to navigating individual information objects,
the Emacspeak environment provides speech-enabled navigation
of the various buffers that are currently open on the
Emacspeak desktop via Emacs' built-in list-buffers feature.
Emacs' dired  --directory editor-- for browsing the file
system, along with the new speedbar package 
that combines features from dired and imenu round off the
suite of navigational tools.

*** Everything Is Searchable:

Emacs derives one final advantage from using buffers as the
basic building block for the entire desktop.  Every Emacs
buffer is searchable via a uniform and powerful search
interface.  Emacs' incremental search works efficiently and
consistently to enable you locate "objects" of interest
either within a given document or to locate a given object
from amongst the various objects that are currently open on
the Emacspeak desktop.  This is *very* *powerful* --where a
GUI user is typically limited to quickly locating an object
from a relatively small collection --the size of the
collection being a direct function of available display
real-estate-- the Emacspeak user can typically work with a
far larger collection of objects.
This is well-suited to the eyes-free environment,
where display real-estate has no meaning; so bringing up a
list of currently open buffers and performing an incremental
search to locate a specific buffer
is just as efficient independent of whether you have a few
dozen or a few hundred buffers open.

To illustrate the above, my typical working Emacs session
lasts between two and three weeks-- over that time I
typically accumulate several hundred open buffers holding a
large variety of content ranging from program source code to
email messages and WWW pages.

Ubiquitous search in the eyes-free environment is critical--
as a comparison, when using a conventional, purely visual
WWW browser, users have no means of easily "searching" for
say the "submit" button on a WWW page.  This inability is a
minor annoyance in visual interaction, and the typical
mouse-enabled user *never* uses the find dialog to find a
submit button-- it is simply more efficient to point at the
submit button given the eye's ability to quickly scan the
two-dimensional display.  This luxury is absent in an
eyes-free environment; as a consequence, blind users
confronted by the combination of a visual interface and
screen-reader are typically limited to either tabbing
through all the controls on a WWW page, or using the
sub-optimal find dialog.

* Does Emacspeak Support Synthesizer XXX?

** Software TTS Engines:

Software  Text To Speech (TTS) lets you produce synthetic
speech using a generic sound card.


*** IBM ViaVoice TTS (Outloud):

Emacspeak  supports IBM ViaVoice TTS.

*** Festival:

There is an open source project hosted at SourceForge that
is attempting to  build support for the Festival engine.

*** MBrola: 


Bart Bunting is working on a speech
server using the MBROLA software speech synthesizer.

** Hardware Synthesizers:

The Emacspeak distribution comes with speech servers for the
Dectalk family of synthesizers.  Speech servers for other
synthesizers are available from
<http://www.mv.com/ipusers/vanzandt/> Jim Van Zandt's home
page --thanks Jim!  


* Emacspeak Logo:

Emacspeak now has a visual and auditory logo.

** Visual: A 

picture of Hubbell --Yellow Labrador-- with a bubble coming
out of her mouth saying "Complete Audio Desktop" and the
caption "EMACSPEAK" under her picture; thanks to Hans
Zoebelein for the visual design.  This logo is used on the
Emacspeak WWW site, and is available as an XPM file in the
emacspeak/etc directory for use on graphical desktops.

** Auditory Logo:

Emacspeak.mp3 is a 4 second MP3 file containing the first
few bars of Bach's Toccata And fugue.  The auditory logo is
played as Emacspeak starts up.

* What Is Fenestration?

What does *Fenestration*
as in League Against Forced Fenestration (LAFF) mean?

From the American Heritage Dictionary:
    <REF> fenestration  n.
    1 Archit. The design and placement of windows in a building.
    2 An opening in a structure.
    3 The surgical cutting of an artificial opening from the external auditory canal
    to the labyrinth of the internal ear to restore normal hearing. 


Local variables: 
mode: outline 
paragraph-separate: "[ ]*$"
end: