@c $Id: documents.texi,v 15.0 2001/11/20 20:05:31 raman Exp $
@node Document Authoring
@section Document Authoring 

The Emacspeak environment provides a rich collection of structured
document authoring tools.  These are well-suited for working in an
eyes-free environment --you clearly do not want to use a @b{What You See
Is What You Get} (WYSIWYG) authoring tool if you cannot see what you're
getting.  Structure-based authoring tools allow you to focus on the act
of content creation, leaving the minutiae of visual layout to the
computer.



@menu
* Creating Well-formatted Documents::   Authoring Content.
* Search replace and spell check::   Fixing errors.
@end menu

@node Creating Well-formatted Documents
@subsection Creating Well-formatted Documents


Before authoring a document, decide its primary audience 
if the document contains relatively simple content e.g., no mathematical
equations etc. 
and is primarily targetted at the WWW,  you are probably better off
using HTML.
You can create well-structured HTML documents with the help of package 
@code{html-helper-mode} available from 
@code{ftp://ftp.reed.edu/pub/src/html-helper-mode.tar.gz}.
Package @code{html-helper-mode} is speech-enabled by Emacspeak to
provide auditory icons, structured navigation and outlines, as well as
voice locking for audio formatted feedback as you work.


If the document being authored is more complex, you are usually better
off creating it in LaTeX.
Note that LaTeX documents can be converted to HTML either via package
@code{tth} or package @code{latex2html} --both available on the WWW.

The TeX family of typesetting languages  is suitable for producing 
well-formatted documents in an eyes-free environment.
Unlike WYSIWYG environments, 
the author  of a TeX or LaTeX document works with the content of the
document, leaving it to the formatting system (TeX) 
to format the document for good visual presentation.

The auctex package is an Emacs extension that facilitates authoring and
maintaining structured documents in TeX and LaTeX.  Package
@code{bibtex} facilitates maintainance and use of @code{bibtex}
bibliography databases.  The Texinfo package allows creation of software
documentation that is suitable for both printing as well as online
viewing as hypertext.  Emacspeak speech-enables packages @code{auctex},
@code{bibtex} and @code{texinfo} to provide convenient spoken feedback
as you create and compile documents. For details on using these
packages, see their accompanying online info documentation.  

The most recent version of package @code{auctex} is always available by
ftp at @code{ftp://ftp.iesd.auc.dk/pub/emacs-lisp/auctex.tar.gz}.
Packages @code{bibtex} and  @code{texinfo} are part of the standard Emacs distribution.

As the document preparation system of choice, Emacspeak supports a
fluent speech-enabled interface
to editing and formatting LaTeX documents.
This interface is provided
by speech-enabling  @emph{auctex} mode. 

Mode @emph{auctex} provides efficient keyboard shortcuts for
inserting and maintaining LaTeX markup as a document is being
authored.
All of these editing commands provide succinct auditory
feedback when used with Emacspeak.
The syntax coloring provided by this mode is extended to provide @emph{
  voice locking}
--- consequently, Emacspeak uses different voices to speak the
embedded markup to set it apart from the content.

Mode @emph{auctex} can be used to create empty document templates and
to insert document content
at the appropriate places in the template.
The mode also enables structured 
navigation of the document as it is
being edited.  Emacspeak speech-enables these template creation and
structured navigation commands to produce auditory icons and succinct
spoken feedback.  For example, while editing, the user can quickly
browse through the sections of the document and have each section
title spoken.  Document elements such as paragraphs and bulleted lists
can be manipulated as logical units.  These features are especially
relevant  in an eyes-free environment where the user needs to select
logical parts of the document without having to point at portions of a
visual display.


Finally, Emacs supports creating and maintaining SGML and XML documents.
Emacs comes with a fairly simple @code{sgml-mode}
--in addition, package @code{psgml} provides sophisticated parsing and
validation facilities for working with SGML and XML documents.
Package @code{psgml} can be downloaded from
@code{http://w4.lns.cornell.edu/public/COMP/info/psgml/psgml_toc.html}.

@node Search replace and spell check
@subsection Searching, Replacing, And Spell Checking

Incremental search, a process by which the system prompts the user for a
search string and moves the selection to the next available match while
allowing the user to add more characters to the search string, is the
search technique of choice amongst most Emacs users.  As the system
successively finds each match and provides the user the option of
continuing the search.  Incremental search is a more complex instance of
traditional search interaction because in addition to either stopping or
continuing the search, the user can modify the current search in a
number of ways including specifying a longer (or shorter)
search string.

All of the user commands available during incremental search are
documented in the online Emacs info manual.  These are speech-enabled by
Emacspeak to provide spoken prompts as the dialogue begins; auditory
icons indicate a search hit or search miss as the search progresses.
Along with auditory icons @emph{search-hit} and @emph{search-miss} the
user also hears the current line spoken, and in the case of a search
hit, the matching text is @emph{aurally} highlighted by using the
standard audio formatting technique of changing voice characteristic.
This feedback proves extremely effective when the search pattern appears
several times on a single line; the user is unambiguously cued to the
current match.


Search and replace actions are an extension to the basic
conversational gestures of  a search dialogue.
In addition to specifying a search string,
the user also specifies a replacement string.
On the Emacspeak desktop, this functionality is provided by
command @emph{query-replace}.  The
speech-enabled version of this interaction prompts the user for the
search and replacement texts.  The 
auditory feedback during the interactive search and replacement
process parallels that described in the case of incremental search.
Audio formatting to indicate the occurrence that is about to be
replaced proves an effective means of avoiding erroneous modifications
to the text being edited.  As an example, consider using command @emph{
  query-replace} to locate and replace the second occurrence of 
  @b{foo} with @b{bar} in the text
 
   @samp{Do not change this fool, but change this food.}
 
  When the search matches the first occurrence of @b{foo}
 in word @emph{fool}, the aural highlighting helps the user in
 answering ``no'' in response to question ``should this occurrence be
 replaced''.  In addition to allowing the user to supply a
 simple ``yes or no'' answer for each match, command @emph{
   query-replace} also allows the user to specify a number of other
 valid answers as described  in the online Emacs documentation.


@unnumbered  Spell Checking

A more complex instance of conversational gesture ``search and
replace'' is exhibited by standard spell checking dialogues.  Spell
checking differs from the search and replace dialogue described above
in that the search and replacement text is guessed by the system based
on an available dictionary.  Words that are not found in the
dictionary are flagged as potential spelling errors, and the system
offers an interactive search and replace dialogue for each of these
possible errors.  During this dialogue, the system successively selects
each occurrence of the possibly erroneous word and offers a set of
possible replacements.  Unlike in the case of simple search and
replace, more than one possible replacement string is offered, since a
potential spelling error can be corrected by more than one word
appearing in the dictionary.

In the visual interface, such spell checking dialogues are realized by
displaying the available choices in a pop-up window
and allowing the user to pick a correction
Once a correction is selected, the user is offered the choice of
interactively  replacing the erroneous word with the correction.

The spell checking interface on the Emacspeak desktop is speech-enabled
to provide fluent auditory feedback.  The visual interface parallels
that described above and is provided by package @code{ispell} which is
part of the standard Emacs distribution.  Emacspeak provides a spoken 
prompt that is composed of the line
containing the possibly erroneous word (which is aurally highlighted to
set it apart from the rest of the text on that line) and the available
corrections.  Each correction is prefixed with a number that the user
can use to select it.  Once a correction is selected, the interaction
continues with the query and replace interaction described earlier.  The
speech interface to the spell checker is as fluent as the visual
interface.  Notice that Emacspeak users do not need to concern
themselves with the details of the visual display such as ``the
corrections are displayed in a window at the top of the screen''.


In addition to the standard spell checker described above, newer
versions of Emacs include an ``on-the-fly'' spell checker that flags
erroneous words as they are typed.
Emacspeak speech-enables package @code{flyspell} so that such erroneous
words are aurally highlighted.