@c $Id$
@node Structured Editing
@section Structured Editing And Templates

Editing documents based on the inherent structure present in the
electronic encoding can be very efficient when using spoken
interaction.  We described mode @emph{ auctex} --- a specialized
interface to authoring LaTeX documents as a special instance of such
structured editing in @pxref{Document Authoring}.

The Emacspeak desktop allows the user to efficiently author and
maintain an electronic document based either on the
structure present in the
markup (as in the case of mode auctex) or on special outlining
constructs that allow the user to impose a desired logical structure
on the document.  This section describes the effect of speech-enabling
such editing tools and points out the advantages in using these in a
speech oriented interface.

Template-based authoring --- a technique that allows the user to create
a document by inserting contents into appropriate positions in a
predefined template--- goes hand in hand with such structured editing.
Finally, structured editing can vastly simplify the creation and
maintenance of structured data, for example, the data present in a UNIX
password file.  Such data files are in fact nothing more than a
collection of database records, where each record (or line) consists of
a set of fields delimited by a special character.  Maintaining such
files without exploiting the underlying structure often tends to be
error prone.  We describe editing modes that can exploit such record
structure to provide a fluent editing interface.  Finally, we outline a
speech-enabled interface to a spreadsheet application as a complex
instance of such structured data editing.




@menu
* Outline Editing ::             Editing and navigating outlines.
* Template-based Authoring::     Creating and Filling Templates.
* Maintaining Structured Data::   Structured Data.
@end menu

@node Outline Editing
@subsection Outline Editing

All of the various outline editing interfaces on the Emacs desktop
allow the user to @emph{ hide} or @emph{ show}
the contents at the different levels of a possibly nested tree
structure.
   Components of this tree structure can be
manipulated as a unit, e.g.,
entire subtrees can be deleted or copied.
Outline editing thus provides an efficient means of obtaining quick
overviews of a document.

The visual interface displays such hidden content as a series of
ellipses following the visible outline heading.  Emacspeak produces
auditory icon @emph{ ellipses} when
speaking such outline headings.

The basic @emph{ outline mode} allows the user to specify the syntax
and level of outline header lines as a regular expression.  This
simple technique can be used to advantage in the structured navigation
of large electronic texts such as those available on the Internet from
online book projects such as project Gutenberg and the Internet
Wiretap.  For example, when this feature is activated while reading
the electronic text of a Shakespearean play, the different acts can be
recognized as separate nodes in the logical structure of the document.
The user can then hide the document body with a single keystroke,
navigate the outline headings to find a particular act, and have that
portion rendered either visually or aurally.  Hiding an outline level
produces auditory icon @emph{ close-object}; exposing a hidden level
produces auditory icon @emph{ open-object}.
For details on using mode @code{outline}, see the relevant section of
the online Emacs info manual.

The basic outline facility described above is applicable to all
content being edited or browsed on the Emacspeak desktop.  In
addition, Emacspeak has  other specialized outline editing
modes such as  @emph{ folding mode} that provide extended
outlining facilities.  In mode
@emph{ folding}, the user can create
(possibly nested) @emph{ folds} --- logical containers of content
that are delimited by a special @emph{ fold mark}.  The fold mark is
typically a text string that is chosen based on the type of content
that is being manipulated.  Thus, when @emph{ folding} a C~program
source file, fold marks are created from C~comments.  The user can
@emph{ open} or @emph{ close} any or all folds in a document, and
these actions
are accompanied by auditory icons @emph{ open-object}
and @emph{ close-object}.  By entering a fold, all editing actions are
restricted to the contents of that fold; this proves a simple yet
convenient way of constraining editing actions such as search and
replace to specific portions of large documents.
Folds can be manipulated as a unit and can be deleted, copied or moved.

Mode @emph{ folding} proves especially effective in maintaining large
software modules.  The technique can be used to advantage by creating
folds for different sections in a module and by further placing each
function appearing in a particular %
section in a fold of its
own.  Complex functions can themselves be folded into sections where
each section reflects a different stage in the algorithm implemented
by that function.  Thus, the technique of folding can be used as an
effective aid in @emph{ literate} programming.  I typically write
software modules by first creating an outline structure using folds
that reflect the various components of that module. Next, I populate
each fold with the function signatures and documentation for the
functions in each section.  When I am satisfied with the overall
architecture of the module, I fill in the function skeletons with
actual program code.  This technique is used extensively in
maintaining  the  Emacspeak code base.


@node Template-based Authoring
@subsection Template-based Authoring


Emacspeak supports two powerful template-based authoring subsystems that
enable the user to quickly create and fill in templates.  @emph{ Dmacro}
(short for ``dynamic macros'') allows the user to define and invoke
template-based macros that are specialized for creating different types
of content.  For example, when programming in C, the user can invoke
dynamic macros that insert skeletons of standard C constructs with a few
keystrokes.  This form of editing has numerous advantages in creating
consistently structured code when developing large software modules.
Emacspeak speech-enables mode @emph{ dmacro} to provide succinct spoken
feedback as templates are created and filled.  The user invokes @emph{
dmacro} via command @emph{ insert dmacro}, which is typically bound to a
single key.  This results in a dialogue where the user is prompted to
pick one of the dynamic macros available in the current context.  If the
users choice can be uniquely completed, that completion is spoken;
otherwise, the list of possible completions based on the available
partial input is spoken, accompanied by auditory icon @emph{ help}.

An alternative template-editing facility is provided by mode  @emph{ tempo}
This mode is designed to  be used in creating
template-based editing tools for specific markup languages; a good
example is mode @emph{ html-helper},
a  mode for creating and updating HTML documents for
publishing on the WWW (see @pxref{Document Authoring}).

@node Maintaining Structured Data
@subsection Maintaining Structured Data


Consider the following entry from file @code{ /etc/passwd}
on my laptop.

@samp{aster:KoUxwQ2:501:100:Aster Labrador:/home/aster:/bin/bash}

 File @code{ /etc/passwd} is a simple instance of a text file
that stores structured data records as a series of fields delimited by
a special character. Each item in the file acquires @emph{
  meaning} from the @emph{ position}  in which it  occurs   for
example, the fifth field contains the @b{ user name}, Aster Labrador.
More generally, structured data where each field in a record has @emph{
  meaning} is found throughout the desktop in applications ranging
from entries in a rolodex to rows in a spreadsheet.

Typically, users do not directly edit the stored representation of the
data. Instead, application front-ends provide a more human-centric
(and hopefully less error prone) user interface for modifying and
maintaining the data. Thus, spreadsheet applications present the data
as a two dimensional table that is automatically updated to reflect
changes in the underlying data. The two dimensional table is perhaps
the most commonly found visual front-end to structured data tables
with row and column headers prove a succinct way of implicitly
displaying the @emph{ meaning} along with the @emph{value} of the
fields making up each data record.