DEMACS - DragonDictate Extension of eMACS. Version 0.8 Jan 1997.
		Written by Thomas Rene Nielsen. (trn@imada.ou.dk)


In recent years the use of speech-recognition systems is becoming more and
more common.   Current systems like DragonDictate are very powerful, but has
been focused primary on dictating normal text. DEMACS is intended to expand
the power of speech-recognition systems;  touching subjects like
cursor-control, programming, editing and more...



Two different  approaches have been used in DEMACS: speech combined with
mouse-pointing (no physical mouse-clicking is needed) and speech alone.
Mouse-clicks will be performed by verbal command (The idea for the
speech-mouse combination, originates from  Nils Klarlund). The combination of
speech and mouse is an attempt to improve the usability of speech-systems.
Some things are actually easier done with the use of mouse, but some people
aren't able to use the mouse at all, so all utilities where a mouse is used,
can be used with speech alone also.



This documentation is in three parts.  The first part, Overview, gives a
general idea of what's included in DEMACS.  The next part, Installation,
runs through the process of installing the utilities.  Part three goes into
depth with the utilities, explaining the use of each function.





Part One - Overview

The following problems are addressed in these utilities:

1.  Cursorcontrol.  Both the more basic control systems, but also more
    intelligent systems.
2.  Editing functions	
3.  Programming shortscuts.  Function skeletons, parsing of identifiers.
4.  Menu-system.  Speech driven menu system.
5.  Various stuff.



1.  Cursorcontrol

Controlling the cursor in the current window, by the use of speech, is one of
the things that should be possible. The basic control of the cursor is fairly
simple. EMACS  already includes functions to move the cursor up and down,
forward and backward over characters and words. Moving to the start and end of
a line is useful too. The possibility to move up or down a given number of
lines can also be handy, so has been included.

To keep down the number of speech commands you can also make functions that
takes a direction but let the number of steps be decided at runtime.


Next comes the ability to move the cursor to parts of the buffer, which aren't
visible in the window. Functions to reach the start and end of the buffer
should be available. Page up and down are pretty obvious for moving in a
small buffer or for moving to positions within one or two pages.  To get to
specific lines within the whole buffer, functions have been made that works
like binary search.  The function 'middle-of-buffer' starts the 'search' and
the functions 'upper part' and 'lower part' allows choosing what part to look
at next, continuing so until the window contains the wanted line.


When using program skeletons, the places to fill in data are usually obvious.
Functions to get to the next  or previous logical place to insert data, could
be very useful.  The 'skip'-function is a try at an intelligent solution of
that problem  (Hopefully).

So far about cursorcontrol in a single window.  Switching between different
frames should be an option also (A frame is a graphical design/frame used to
hold windows).  The most basic approach is to use the next and previous-frame
functions in EMACS.  That is nice as long as there is only one to three
frames. I have used three different approaches in solving this problem. The
first approach allows the user to choose the frame mostly to the South, North,
East or West.  The second approach divides the screen in a 3 by 3 grid.
Choosing, say the Northeast part, will select one of the frames in that part.
A frame even partly in the grid-part will be considered. The third selects the
frames directly (for each frame a 'go-to' function).



2. Editing functions.

Functions for killing and copying words, lines and regions, with the use of
speech alone and speech combined with mouse.



3.  Programming shortscuts.  Function skeletons, parsing of identifiers.

DragonDictate isn't exactly made for programming.  The following functions
have meen made to help a little on that.  Utilities are focused on Lisp, C and
Latex.

A way to improve programming is skeletons for functions.  A given skeleton
inserts the basic form of a Lisp-function.  Example: The Lisp defun skeleton:

(defun  ()
  )

The cursor is placed after the keyword defun, for easy insertion of parameters.
To position the cursor at the next logical place to write, the skip forward and
backward functions have been made.

Function skeletons can speed work up a great deal.  Several are included for
Lisp, C and Latex.

Parsing of identifiers is another programming utility.  The idea is simple;
let a utility collect the function and variable names in a menu-list,
from which the identifiers can be copied. Identifiers can be parsed line by
line, function by function or from the whole buffer at once.



4.  Menu-system.  Speech driven menu system.

A menu system designed for use with speech can be very handy.  The idea is to
keep the overview of a traditional menu system, but to allow selection with
speech alone. A system that allows selection from lists, has been implemented
for Lisp, C and Latex.  A main menu allows selection between groups, resulting
in opening of sub-menus for the chosen groups; in which selection of functions
and macros can be done.



5. Various stuff.

Word-pad
The word-pad is used to hold often used words, which isn't included in the
DragonDictate speech data-base.  Call 'insert-word-pad' to add the word under
the cursor to the word-pad. 'delete-word-pad' removes the word under the
cursor from word-pad. You can save different word-pads for each application
with save-word-pad and load with load-word-pad. Open list with
'open-word-pad'. 'clear-word-pad' clears the whole word-pad. Selection from the
word-pad is done with mouse-clicking or other selection functions ([get n] or
[select it]). Words selected is copied to the kill-ring. 

No space mode.
Used to suppress DragonDictate's automatic insertion of spaces after words.
Useful for programming. Spaces can still be made manually.


To make the utility pack more complete, the following areas of EMACS use has
also been include:

Mail. Writing, reading ...: [CC], [compose mail], [delete message],
[edit message], [first message], [forward mail], [mail header],
[mail signature], [mail subject], [next message], [previous message],
[read mail], [reply mail], [send mail], [undelete message].

Directory. Basic moving around and deletion of files. [delete flag],
[delete the flagged], [find file], [file list], [remove delete] (removes the
delete flag) , [up directory].

Mouse-clicks.  I use the Danish names of Donald Duck's three nephews as
names for the three mouse buttons. [rip], [rap], [rup], and [rip rip] for
double click on button one.

Shifting between EMACS modes. [Lisp-mode], [c-mode], [text-mode], [latex-mode].

Quitting stuff: [quit emacs], [quit quit] = (Ctrl+g) = keyboard-quit  and
[quit all] = (ESC+Esc+Esc) = keyboard-escape-quit.


And a few more functions that won't be mentioned here.

Notice that DEMACS is meant as a basis on which the user can build. The user
still has to add hers/his more specific functions.










Part two - Installation
The package consist of this textfile,
demacs.dcm, demacs.ddx, emacs,
general.el, lisp-mode.el, c-mode.el, latex-mode.el,
speak-list.el, filelist.el, undo.el, word-pad.el
c.dat, lisp.dat, latex.dat, undo.dat,
default.pad.
You will need these files, so keep them together.

First you must make a few changes to you '.emacs' file.  Just insert the
'load' instructions below.

Remember to change the paths to reflect your system.

(load-file "c:/utils/emacs-19.34/general.el")
(load-file "c:/utils/emacs-19.34/lisp-mode.el")
(load-file "c:/utils/emacs-19.34/c-mode.el")
(load-file "c:/utils/emacs-19.34/latex-mode.el")
(load-file "c:/utils/emacs-19.34/speak-list.el")
(load-file "c:/utils/emacs-19.34/filelist.el")
(load-file "c:/utils/emacs-19.34/undo.el")
(load-file "c:/utils/emacs-19.34/word-pad.el")

The above lines installs the whole utility pack.


Feel free to include only the parts of the utilities, that fit your needs, but
notice that 'general.el' holds some general definitions used by the other
utilities. These should be available.

The following is a list of what can be found in the files:
lisp-mode.el: skeleton forms for Lisp, Lisp skip functions, Lisp parser
functions, Lisp menu system.
c-mode.el: C skeleton forms, C skip functions, C parser functions, C menu
system.
latex-mode.el: Latex skeleton forms, latex skip functions, latex menu system.
speak-list.el: speak-list window.
filelist.el: filelist menu list.
undo.el: undo activated with 'Choose 10'. See below.
word-pad.el: word-pad system.
general.el: all other stuff. General skeleton forms, general functions calling
the more specifik functions,....


Setting specific paths and modes
generel.el: The modes which the mode specific functions shall react on, can be
set in 'c-modes', 'lisp-modes' and 'tex-modes'.

lisp-mode.el: The path to the lisp menu data file(lisp.dat) should be set in
'lisp-filename'. Positions and sizes for the lisp-frames can be set.

c-mode.el: The path to the C menu data file(c.dat) should be set in
'c-filename'. Positions and sizes for the c-frames can be set.

latex-mode.el: The path to the latex menu data file(latex.dat) should be set in
'latex-filename'. Positions and sizes for the latex-frames can be
set.

speak-list.el: The path to the demacs.dcm or demacs.ddx file should be set in
'speaklist-file'. Positions and sizes for the speaklist-frames can be set.

filelist.el: Positions and sizes for the filelist-frames can be set.

undo.el: The path to the undo file(undo.dat) should be set in 'undo-filename'.

word-pad.el: The path to the default word-pad file(default.pad) should be set
in 'word-pad-default-filename'.



Undo
To make the undo part work with a2x, a few changes have to be done. 
If using a2x, you should make sure that none of the a2x-undo pairs, are the
same as in undo.dat, to avoid double undoing.  Another important thing is to
include the '-b' flag in the call to a2x. The 'b' flag means that a2x won't
convert backspace characters to del characters. The undo needs backspaces to
work.

Unfortunately a backspace-character has the same key-sequence as the
'ctrl-h' key-sequence.  This key-sequence calls the emacs help function.
To make the undo work, I had to move this sequence.  The 'undo.el' file
moves the help to 'meta-h', instead.

Notice that the undo only works with these versions of DragonDictate that
generates backspace characters for all deletion of errors.  The newer versions
of DragonDictate only generates backspace characters for correction of plain
text.  Users of the newer versions, will have to do with [undo that] and
[undo only]. Don't load the 'undo.el' file in EMACS startup.


Binding the functions
The next thing to do is binding the functions to DragonDictate words.  This is
usually done with the DragonDictate command 'add-word', followed by a call to
the EMACS function.  Example:

	add-word "[file list]" {Esc}xopen-file-list{Enter}

Look in the 'emacs.dcm/ddx' file, to see how I use the commands. The demacs.dcm
and demacs.ddx files includes more functions than described here. These are
normal EMACS functions which have been included to form a more complete set
of functions. 


A remark to the functions that depends on the mode of EMACS: the mode used is
the mode of the current window. That means switching to a window with another
mode will influence the working of these functions. The alternative is to
always use the mode of the window top-left in the main-frame; this alternative
has not been implemented. Therefore make sure to be in the main window when
activating mode specific functions.







Part three - Function description

This chapter contains a list of the utility functions in DEMACS. For each
function the following information will be given: function name, DragonDictate
word connected with function(shown with the usual [] brackets) and a general
description of the working of function.




BASIC SKELETON FORMS

insert-remark, [make remark], inserts a skeleton for a remark in Lisp, C or
Latex.  The form of the remark depends on current mode.
The underlying functions are:
c-remark
lisp-remark
tex-remark

paren-body, [paren], inserts paren-pair, positioning cursor between parens.
Underlying Lisp function: lisp-paren.

single-quotes, [single quotes], inserts single-quotes-pair, positioning cursor
between quotes.

quote-body, [quote], inserts normal or latex quote-pair, depending on EMACS
mode. Underlying functions: tex-quotes, normal-quotes

brace-body, [brace], inserts brace-pair.

bracket-body, [bracket], inserts bracket-pair.



CURSOR CONTROL
Standard cursor control: [up 1-5, 10, 20], [down 1-5, 10, 20],
[left 1-5, 10, 20, 50],  [right 1-5, 10, 20, 50]. 

cursor-list-select, [select it], used to select from menu-lists.

get-list-entry, [get 1] - [get 15], also used to select from menu-lists.


several-lines-up, [up lines], asks for number of lines to go up.

several-lines-down, [down lines], asks for number of lines to go down.

start-of-buffer, [start of buffer], goes to start of buffer.

start-of-line, [start of line], goes to start of line.

And their standard EMACS counterparts: [end-of-buffer] [end-of-line].


buffer-part (num), [part 1] - [part 9], to understand this function, imagine
that the buffer is divided in 10 parts.  Part 0 is reached with
'start-of-buffer', [part 1] goes to the start of the next part,[part 2] the
next, and so on.


skip-forward, [skip forward], tries to position the cursor at the next
logical place to write, depending on the current mode.

skip-backward, [skip backward], like skip-forward but backward.

The following functions are programming specific skip functions. They are
available for users who don't want EMACS to decide what skip function to use.
The more global skip functions calls the specific ones, depending on EMACS
mode.
c-skip-forward
c-skip-backward
lisp-skip-forward
lisp-skip-backward
tex-skip-forward
tex-skip-backward


nice-newline, [nice newline], makes newline.  Doesn't move text after cursor
on current line to new line. That is; allows shift to the next line, from the
middle of the current line, without disturbing the current line.


'Manual binary search'. For scrolling the buffers. The middle-of-buffer goes
to the middle of the current buffer, counting lines and prepares the buffer
for at kind of manual binary search. It sets the bounds for the search to the
top of the buffer and the end of the buffer. upper-part will move to the
middle line, between upper bound and the current cursor position. Lower bound
will be set to the cursor-position before running upper-part. And os on ...
Similar with lower-part : middle line between current cursor line and lower
bound and upper bound set to cursor pos, before running command. Used for
quickly zero'ing in on a wanted line. The idea for this one, comes from Peter
Kornerup.

middle-of-buffer, [middle of buffer], goes to the line in the middle of the
buffer.  Also used to initiate the 'binary search' cursor positioning system.

upper-part, [upper part], will do the upper part of a manual binary search.

lower-part, [lower part], will do the lower part of a manual binary search.




FRAME SELECTION

goto-next-frame, [next frame], cycles to the next frame, using EMACS order of
frames(by using next-frame).

goto-previous-frame, [previous frame], cycles to the next frame, using EMACS
order of frames(by using previous-frame).

go-mainframe, [go main], goes to the starting frame.

go-function-frame, [go function frame], goes to Lisp or C function frame,
depending on EMACS mode.

go-var-frame, [go var frame], goes to Lisp or C var frame,
depending on EMACS mode.

go-file-list, [go file list], goes to filelist frame.

go-speak-list, [go speak list], goes to speaklist frame.

go-word-pad, [go word pad], goes to wordpad frame.


go-main-menu-frame, [go main menu], goes to the main menu frame, in Lisp, C or
Latex, depending on EMACS mode.

go-sub-menu-frame, [go sub menu], goes to the sub menu frame, in Lisp, C or
Latex, depending on EMACS mode.

The following functions are the specific functions called by the two more
generel functions above.
go-latex-main-frame, [go latex main], goes to the latex main frame.
go-latex-sub-frame, [go latex sub], goes to the latex sub frame.
go-c-main-frame, [go c main], goes to the c main frame.
go-c-sub-frame, [go c sub], goes to the c sub frame.
go-lisp-main-frame, [go lisp main], goes to the lisp main frame.
go-lisp-sub-frame, [go lisp sub], goes to the lisp sub frame.


frame-west, [west frame], selects the west most frame.

frame-north, [north frame], selects the north most frame.

frame-east, [east frame], selects the east most frame.

frame-south, [south frame], selects the south most frame.

get-frame (num), [upper left frame], [upper frame],[upper right frame],
[left frame], [middle frame], [right frame],
[lower left frame], [lower frame], [lower right frame], imagine that the
screen is divided into 3x3 parts.  Frames can now be chosen by selecting the
part that the frame is in.  Frames even partly in a screen part will be
considered.  Multiple frames in the same screen part can be selected by
repeatedly choosing the same screen part.




EDITING STUFF

delete-word, [kill word], deletes word under cursor.

copy-word, [copy word], copies the word under mouse-pointer to cursor position.

copy-between, [copy between], copies region between mouse-pointer and cursor to
kill-ring.

copy-region, [copy region], copies region between mark and cursor to kill-ring.

kill-mark-region, [kill region], kills region between mark and cursor.
Confirmation in the form of a 'enter-key'-click is required.

kill-between, [kill between], kills region between mouse-pointer and cursor.
Confirmation in the form of a 'enter-key'-click is required.

paste, [paste that], inserts from kill-ring at cursor position.  Can paste
functions too. function-paste does the function pasting stuff.

[set mark], normal EMACS set mark function.



C SKELETONS. I have included most of Simon Crosby's C-skeletons and has made
a few of my own.
c-main, [c main], makes main skeleton.

c-for-loop, [for loop], for-loop for C.

c-conditional, [make conditional], 'if' for C. [make conditional] actually
calls the polymorph funktion make-conditional,  which decides whether to use a
C conditional or a Lisp conditional.

c-do-while, [do while], do-while skeleton. [do while] actually calls
the polymorph funktion make-do-while,  which decides whether to use a C
do-while or a Lisp do-while.

c-while-do, [while do], while-do skeleton. [while do] actually calls
the polymorph funktion make-while-do,  which decides whether to use a C
while-do or a Lisp while-do.

c-block, [c block], sets up braces.

c-switch, [c switch], makes a switch skeleton form.

c-new-case, [c new case], inserts more cases for a switch statement.




LISP SKELETONS.
lisp-make-defun, [make defun], inserts defun skeleton.

lisp-make-setq, [setq], makes setq skeleton.

let-selection, [let], a try for an 'intelligent' function.  Inserts a Lisp
'let' skeleton in Lisp mode and a normal 'let' word in all other modes.
Underlying function is: lisp-make-let.

lisp-make-alist, [alist], inserts a alist skeleton.

lisp-make-alist-part, [alist part], inserts a alist part.

lisp-conditional, [make conditional], 'if'. [make conditional] actually
calls the polymorph funktion make-conditional,  which decides whether to use a
C conditional or a Lisp conditional.

lisp-do-while, [do while], do-while skeleton. [do while] actually calls
the polymorph funktion make-do-while,  which decides whether to use a C
do-while or a Lisp do-while.

lisp-while-do, [while do], while-do skeleton. [while do] actually calls
the polymorph funktion make-while-do,  which decides whether to use a C
while-do or a Lisp while-do.



LATEX SKELETONS.
The following functions are various latex skeleton functions.
latex-enviroment, [latex enviro], asks for enviroment name and creates
enviroment form.

latex-flushright, [latex flushright], inserts a flushright form.

latex-document, [latex document], inserts a latex document form.

The following are Latex skeleton functions. 
latex-inline
latex-displayed
latex-emphasize-text
latex-number-range
latex-subscript
latex-superscript
latex-interval-open-open, makes a (, ) form. Positioning cursor before the ','.
latex-interval-open-closed, a (, ] form.
latex-interval-closed-open, a [, ) form.
latex-interval-closed-closed, a [, ] form.




VARIOUS MENUES AND LISTS.

The following functions opens programming-language specific menus, that allows
the user to select macros. Macros are selected by mouse-clicking, [get n] or
[select it] (The menuframe has to be the active one for the speakcommands to
work.) You can place the macros in logical groups.  The files '.dat' extension
are the data files.  Take a look at these files. Instructions for how to
format the data files are given in the files. Back to the menu system: In the
main menu you can select groups.  This will open another window, from which
you select macros.  The macro is placed in the kill-ring, for pasting.  The
user can select function-forms from the menu too. When you run 'paste', the
function will activate. Only a few macros have been included in the data file.
It's up to you to fill them. The menues are closed by another call to the
function that opened them.

open-main-list, [main menu], open one of the menus below, depending on mode.
c-open-main-list
lisp-open-main-list
latex-open-main-list


open-file-list, [file list], opens a list of the ten most recently used files.
A file will be made the current buffer if selected.  Call function again to
close window with list.


open-speak-list, [speak list], This function opens a list of the available
speak-commands found in your DragonDictate dcom or ddx-file.  

The following functions are identifier parsing functions for Lisp and C,
that this, they collect the function and variable names and gather them in a
list.  The list can be viewed in a seperate window.  The mode of EMACS will
decide what kind of parsing to do (Lisp or C). The identifiers can be selected
for copying(placed in the kill ring).  Select by mouseclicking or by the use of
'cursor-list-select' or 'get-list-entry'.

collect-function, [collect function], erases former identifier list and
collects all identifiers in the function indicated by the cursor.

collect-identifiers, [collect ident], collects identifiers starting from
cursor position and until end of current logical line.

clear-identifiers, [clear ident], clears the identifier list.

open-identifier-list, [ident list], opens the identifier lists, both the
variable and function list.  Call again to close list windows.

open-var-identifier-list, [var list], opens variable list window. Call again
to close list window.

open-function-identifier-list, [function list], opens function list window.
Call again to close list window.

collect-all-identifiers-buffer, [collect all], collects all identifiers in the
whole buffer.


The following functions are used to parse c-code and are actually the ones
called by the more general parsing functions described above.
clear-c-identifiers
collect-c-identifiers
open-c-var-list
open-c-function-list
collect-all-c-identifiers-buffer


The following functions are used to parse lisp-code and are actually the ones
called by the more general parsing functions described above.
lisp-clear-identifiers
lisp-collect-defun-only
lisp-collect-identifiers
open-var-list
open-defun-list
lisp-collect-all-identifiers-buffer


Wordpad.
Remember to run open-word-pad or load-word-pad once first to specify what pad
to use.

insert-word-pad, [insert word-pad], inserts word under cursor in word-pad.

delete-word-pad, [delete word-pad], deletes word under cursor from word-pad.

open-word-pad, [word-pad], opens the word-pad window.  Selection in window
will copy word to kill-ring. Call again to close window.

save-word-pad, [save word-pad], saves current word-pad, asking for filename.

clear-word-pad, [clear word-pad], clears whole word-pad.

load-word-pad (filename), [load word-pad], asks for filename to load.




STUFF
no-space-mode, [no space mode], toggle to activate/deactivate.  When activated
DragonDictate's automatic insertion of spaces will be suppressed and so will
other spaces.  Spaces can be manually made using:
space-bar, [space key].




UNDO
undo-dragondictate, bound to the backspaces of [Choose 10].
For normal undo use [undo that] and [undo last]. [undo that] inserts a space
after undoing. [undo last] is the normal EMACS undo.





Hope you will find some of my utilities useful.  Please let me know your
thoughts about my work, bugs and stuff.


		Thomas Rene Nielsen
		trn@imada.ou.dk






