-*-Text-*-
This file documents the EMACS Word Abbrev Mode.

Node: Top,	Next: Intro,		Up: (EMACS)Top

    Word Abbrev Mode allows the EMACS user to abbreviate text with a
single "word", with EMACS expanding the abbreviation automatically as
soon as you have finished the abbreviation, with control over
capitalization of the expanded string.

    Abbrevs are also useful for correcting commonly misspelled or
mistyped words (e.g. "thier" could expand to "their"), and for
uppercasing words like "EMACS" (abbrev "emacs" could expand to
"EMACS").

    To use this mode, load the WORDAB library and then do MM Word
Abbrev Mode$$:

	MM Load Library$WORDAB$$
	MM Word Abbrev Mode$$

	0 MM Word Abbrev Mode$$ turns the mode off.

    For example, in writing this doumentation I could have defined
"wam" to be an abbreviation for "word abbrev mode".  After only
typing the letters "wam", I see just that, "wam", but if I then
finish the word by typing space or period or any of the text
break-characters, the "wam" is replaced by (and redisplays as) "word
abbrev mode".  If I capitalize the abbrev, "Wam", the expansion is
capitalized: "Word abbrev mode".  If I capitalize the whole abbrev,
WAM", each word in the expansion is capitalized: "Word Abbrev Mode".
In this particular example, though, I would define "wam" to expand to
"Word Abbrev Mode" since it is always to be capitalized.

    Thus, I can type "I am in wam now" and end up with "I
am in Word Abbrev Mode now".

    Word Abbrev Mode can interface with other modes, e.g. Text, LISP,
TECO, Auto Fill, PL1.  Those modes (or the user) may redefine what
functions are to be called by characters;  that will not interfere
with Word Abbrev Mode.

* Menu:

* Intro::			An introduction to Word Abbrev Mode.

* Kinds::			There are two kinds of abbrevs:
				Global word abbrevs are active in all modes.
				Mode word abbrevs are active in one mode.

* Defining::			You can add or delete abbrevs as you
				think of them, define many at once
				from a list, file a list of abbrev
				definitions, and edit the current
				definitions.

* Listing::			MM List Word Abbrevs$ lists currently
				defined abbrevs.

* Unexpanding::			Correcting an expansion that you
				didn't want.

* Expansions::			Expansions can be capitalized;  prefixes and
				suffixes can be "glued" on.


* Entry/Exit::			MM Word Abbrev Mode, user hooks.


* Other Modes::			Word Abbrev Mode tries to interface
				gracefully to other modes without interfering.
				Text break characters like space, return,
				!@#$%^&*()-_+=,.<>/? etc.  cause expansion of
				abbreviations, unless otherwise specified.
				In addition, they will do whatever they would
				do if you weren't in Word Abbrev Mode.

Node: Intro,	Next: Kinds,	Previous: Top,	  Up: Top

    Word Abbrev Mode is useful for abbreviating commonly-used or long words
or expressions, both to save typing and to avoid mispellings.  The mode is
designed to appeal both to fast and slow typists.  It is also designed to be
used in modes other than Text;  for instance, LISP programmers could define
abbreviations for long function names.

    There are two kinds of word abbreviations: mode and global.  A mode word
abbrev will cause expansion in only one mode, while a global word abbrev will
cause expansion in all modes.  If some abbrev is both a mode word abbrev for
the current mode and a global word abbrev, the mode word abbrev expansion
takes precedence.

    For instance, you might want an abbrev "foo" for "find outer otter" in
TEXT mode, an abbrev "foo" for "FINAGLE-OPPOSING-OPINIONS" in LISP, and an
abbrev "foo" for "meta-syntactic variable" in any other mode (the global word
abbrev).

    MM Word Abbrev Mode$ will enter Word Abbrev Mode and set up some
characters for handling abbreviations and expansions:

^X ^A:
	Add a new mode abbrev, which will expand into the word
	before point.  Type the abbrev followed by a return.  (You
	can edit a little with rubout.)  The abbrev must not contain
	any break characters (just letters and digits).  If you give
	^X ^A an non-0 argument, N, the abbrev will expand into the
	N words before point.  A 0 argument means expand into the
	text between MARK and point.  A negative argument means kill
	the abbrev typed -- it will no longer cause any expansions.

^X +:
	Add a new global abbrev, which will expand into the word before
	point.  ^X + interprets its argument in the same way ^X ^A does.

^X U:
	"Unexpand" -- change the last expansion that occurred back to its
	abbreviation.  Thus, if you typed something that you didn't want to
	expand, but which did, type ^X U.  E.g. if you type "foo." and it
	expands to "fooooo.", typing ^X U will restore "foo.".

	If you know ahead of time that "foo." will expand, and you don't want
	it to, you can quote the text break character which terminates "foo"
	with ^Q (type "foo^Q.").

Meta-':
	If you have an abbrev "com" for "committee", and wish to write
	"intercommittee.", you can separate the prefix "inter" from the
	abbrev "com" by meta-', which will mark the end of the prefix with a
	hyphen, so you have "inter-".  Then type "com", getting "inter-com"; 
	when "com." expands, it will note that a prefix has been marked, and
	glue it on to the expansion, eliminating the hyphen, ending with
	"intercommittee." as desired.  Thus, you just type "inter", meta-',
	"com.".




Listing Word Abbreviations:

    MM List Word Abbrevs$ will list the abbreviations currently in use, both
global and mode, which might include:

ab:	(Text)	3	"abbrev"

which identifies "ab" as a mode abbrev for "abbrev" in Text mode,
used 3 times.  You might also see something like:

aw:		2	"always"

which identifies "aw" as a global abbrev for "always", used twice.


Changing Word Abbreviations:

    You can redefine any abbrev simply by using ^X ^A or ^X + to define the
same abbrev.  However, if you want to do a fair amount of redefining and/or
killing at once, you can use MM Edit Word Abbrevs$, which will put you into a
recursive ^R mode editing the abbrev definition list (the same format as MM
List Word Abbrevs prints).  This can be useful for changing several abbrevs
from mode to global word abbrevs, for instance (editing out the "(...)" mode
specifications).

    Some people like to define word abbrevs from a command:
    MM Make Word Abbrev$foo$find outer otter$TEXT$ makes "foo" expand
to "find outer otter" in TEXT mode. Using "*" in place of "TEXT"
causes "foo" to expand in all modes.


Saving Word Abbreviations:

    After adding or redefining word abbrevs, you can save the
definition list by using MM Write Word Abbrev File$<filename>$.  (If
you don't specify a filename, the last one you specified, or WORDAB DEFNS
if none, is used.)

    Later, e.g. in a new EMACS, you can define those same word
abbrevs by MM Read Word Abbrev File$<filename>$.

**********

    Now that you've finished the introduction, I suggest that you
try Word Abbrev Mode out a bit, rather than reading more of this
INFO just now.  Later, after you've got a feel for the mode, and
perhaps have some questions, you can come back to INFO and get more
details from the other nodes.  To try it out, just do:
	MM Load Library$WORDAB$
	MM Word Abbrev Mode$

Node: Kinds,	Next: Defining,	  Previous: Intro,	Up: Top

    There are two kinds of abbrevs: mode and global.  Mode word abbrevs are
effective in only one mode, global word abbrevs in all modes.  Abbrevs are
defined by EMACS variables:

	$X <abbrev> <modename> Abbrev$  for a mode abbrev, and
	$X <abbrev> * Abbrev$  for a global abbrev.

    The variable contains the expansion string.  Thus if the variable
$X longt Text Abbrev$ contains the string "Long Winded Thesis Title", then
in Text mode "longt" will expand to "Long Winded Thesis Title".  If the
variable $X hufpuf * Abbrev$ contains the string "Much Longer Thesis
Title Which Can't Even Fit On A TR Cover's Side", then in any mode (unless
overridden by a mode abbrev) "hufpuf" will expand to....

    The variable's "comment" (all variables can have comments
describing what they are for) is used to meter the usage of the
abbrev:  the "comment" is a string representing the number of times
the abbrev has expanded.  (E.g. it might be the string "4".)  This
usage-count is shown by MM List Word Abbrevs$ and saved by MM Write
Word Abbrev File$, so that when the saved word abbrev definitions are
used to define abbrevs, the usage-counts start off where they were
before.

    The command Sort Word Abbrevs will reorder a word abbrev
definition list (in the buffer) so that the most frequently used
abbrevs are listed first, rather than in alphabetical order.

    Since abbrevs are just variables, you can make any abbrev local to a
buffer or file, or use MM Variable Apropos$ to list just those abbrevs that
contain some pattern (e.g. to list just the Text mode abbrevs, you could do:
MM Variable Apropos$ Text Abbrev$, just the globals: MM Variable Ap$* Ab$).

Node: Defining,	    Next: Listing,	Previous: Kinds,	Up: Top

    Word abbrevs can be defined one at a time (adding them as you
think of them), or many at a time (from a definition list).  Word
abbrev definitions, being EMACS variables, will stay around even if
you're not in Word Abbrev Mode at the moment.

    Word abbrevs can be killed either singly, by editing the current
definition list, or by MM Kill All Word abbrevs$.

    Here is a summary of the word abbrev defining commands.  "+n"
refers to an explicit argument which is positive, "-n" an explicit
argument which is negative:

   ^X ^A:	Define a mode abbrev for the word before point.
+n ^X ^A:	Define a mode abbrev for the n words before point.
-n ^X ^A:	Kill specified abbrev.

   ^X +:	Define a global abbrev for the word before point.
+n ^X +:	Define a global abbrev for the n words before point.
-n ^X +:	Kill specified abbrev.

MM Define Word Abbrevs:	  Define word abbrevs from list in buffer.
MM Make Word Abbrev:      Define one word abbrev from command's arguments.
MM Edit Word Abbrevs:	  Edit word abbrev definitions in a ^R mode.
MM Kill All Word Abbrevs: No word abbrevs are defined after this.

* Menu:		More details about (re)defining word abbrevs.

* Add One::		^X ^A will define an abbrev that expands only
			in one mode (a mode abbrev).  ^X +  will
			define an abbrev that expands in all modes (a
			global abbrev).  MM Make Word Abbrev is a
			command to define one abbrev.

* Kill One::		^X ^A with a negative argument will kill a
			mode abbrev.  ^X + with a negative argument
			will kill a global abbrev.

* Define Many::		MM Define Word Abbrevs$ will add many abbrev
			definitions from a list in the buffer.

* Edit::		MM Edit Word Abbrevs$ allows editing of the
			current word abbrevs in a recursive ^R mode.

* Local Definitions::	Word abbrevs can be made local to a buffer or file.

Node: Add One,	Next: Kill One,		Up: Defining

    ^X ^A (^R Add Mode Word Abbrev) and ^X + (^R Add Global Word
Abbrev) define one abbrev, which will expand to n words before point,
or the region.  The argument specification determines the expansion
string:

	No argument given:  expansion string starts with word before
	point and continues to point.

	Positive argument n given:  expansion string starts with nth
	word before point, and continues to point.

	Zero argument given:  expansion string is the region (between
	pont and MARK).

    There is one exception to the above expansion string specification:

	If FS ^R Mark$ is set, the expansion string is all text
	between point and FS ^R Mark$.  Note that the standard EMACS
	environment does not set FS ^R Mark$.  FS ^R Mark$ is a Teco
	mark, and is volatile:  after setting it, it stays defined
	only as long as you do not edit (i.e. you can only move).

    ^X ^A and ^X + will print the specified expansion string at the
bottom of the screen, unless it is too long, in which case the first
and last several letters of the expansion are printed.  E.g. you
might see:

	Text Abbrev for "this is the expansion":
or	Global Abbrev for "here is another...":

    Type the abbrev for that expansion, followed by a return.  You
can edit a little with rubout, control-U (to erase everything typed),
and control-G (to abort the abbrev definition).  The abbrev must not
contain any break characters (just letters and digits -- it must be a
"word").

    If you are causing an existing abbrev to be redefined, you will
be told of the old expansion, and asked for confirmation:  type "yes"
followed by return if you want to change the abbrev.  Anything else
followed by return means no change.

    If the abbrev is already defined as you are now specifying, you
will be told.  The usage-count for the abbrev is left as it was, so
this becomes a no-op.


    MM Make Word Abbrev$foo$find outer otter$TEXT$
will define "foo" to expand automatically to "find outer otter" when
in TEXT mode.  If the third string argument is null, the current mode
is used.  If the third string argument is "*", a global abbrev is
defined:
    MM Make Word Abbrev$foo$find outer otter$$  -- for current mode,
    MM Make Word Abbrev$foo$find outer otter$*$ -- for global.

Node: Kill One,	  Next: Define Many,	Previous: Add One,   Up: Defining

    ^X ^A (^R Add Mode Word Abbrev) and ^X + (^R Add Global Word
Abbrev) can also be used to kill a single word abbrev (mode or
global, respectively).  Just give them a negative argument, and type
the abbrev to kill.

    The character-commands ^R Kill Mode Word Abbrev, and ^R Kill
Global Word Abbrev exist, but are not attached to any characters or
^X-commands by default.  If you want to avoid specifying negative
arguments to ^X ^A and ^X +, you should attach these commands to
characters.  For instance, if you wanted to put the kill-mode-abbrev
command on Control-Meta-W and kill-global-abbrev on Meta-W, you
should go into mini-buffer and type:

	m.m ^R Kill Mode Word Abbrev$ u...^RW
	m.m ^R Kill Global Word Abbrev$ u..^RW $$

(The "..^R" means "Meta-", and the "...^R" means "Control-Meta-", in
Teco.)

Node: Define Many,	Next: Edit,	Previous: Kill One,   Up: Defining

    MM Read Word Abbrev File$<filename>$ will define all abbrevs
listed in the specified file.  If no filename is given, it defaults
to the last one used by Read Word Abbrev File or Write Word Abbrev
File.  The format of the file is the same as what MM List Word
Abbrevs$ prints, and is described below.

    MM Write Word Abbrev File$<filename>$ will write a file with the
definitions of all current abbrevs.  The filename defaults like that
for MM Read Word Abbrev File.



    If you want a lower-level handle:

    MM Define Word Abbrevs$ will define abbrevs from a definition
list in the buffer.

    MM Insert Word Abbrevs$ will insert into the buffer a definition
list for the current abbrevs.



    The format for word abbrev definition lists is:

	<deflist> ::= null | <1def> CRLF <deflist>
	<1def>	  ::= <abbrev> : <white> <optionals> <white> " <expansion> "
	<optionals> ::= <optmode> <white> <optcount>
	<optmode> ::= null | ( <modename> )
	<optcount> ::= null | <usage-count>

    <White> refers to spaces and tabs.  There can be no colons in an
abbrev, though there can be quotes in the expansion.  If <optmode> is
null, then the abbrev is to be global;  otherwise it is for the mode named.

Node: Edit,   Next: Local Definitions,  Previous: Define Many,  Up: Defining

    MM Edit Word Abbrevs$ will place you in a recursive ^R mode,
editing the current word abbrev definition list.  When that ^R mode
is exited (via C-M-C, or ^C^C), the current word abbrevs will be
redefined by the edited definition list:  any abbrevs that have been
deleted from the list are killed, new ones added to the list are
defined, and old ones changed are modified.

    In effect, after exiting the Edit Word Abbrev ^R mode, all
previously-defined word abbrevs are killed, and the edited list is
used to define new abbrevs.

    Typing ^G will abort the Edit Word Abbrev ^R mode, without
killing or redefining any abbrevs.

Node: Local Definitions,	Previous: Edit,		Up: Defining

    Word abbrevs can be made local to one buffer, or one file, since
the abbrevs are implemented as EMACS variables.

    To have an abbrev local to a file, the last page of the file must
contain a "Local Modes" specification.  For full documentation on how
files can have local variables and modes, see the INFO documentation
on EMACS, under the "Local Modes" section.  As an example, consider a
TJ6 source file.  At the end of the file, following a form-feed (^L),
you might have:

.comment Local Modes:
.comment Mode:Text
.comment Mode:Auto Fill
.comment X foo * Abbrev:this is an abbrev
.comment X oof * Abbrev:this is too
.comment End:

    The ".comment"s force TJ6 to ignore these lines, while the "Local
Modes:" and "End:" tell EMACS that these are local mode and variable
specifications.  These lines say that a buffer containing this file
should be put into Text and Auto Fill modes, that "foo" is a global
abbrev for "this is an abbrev", and that "oof" is a global abbrev for
"this is too".

Node: Listing,	    Next: Unexpanding,	    Previous: Defining,	    Up: Top

    MM List Word Abbrevs$ will list all currently defined word
abbrevs.  An abbrev "foo" that expands to "this is an abbrev" in TEXT
mode and has been expanded 3 times, will be listed by:

foo:	(Text)	3	"this is an abbrev"

    An abbrev "gfoo" which expands to "this is a global abbrev" in
all modes, expanded 11 times, will be listed by:

gfoo:		11	"this is a global abbrev"


    Abbrevs that are local to a buffer other than the currently
selected one are not listed.

Node: Unexpanding,    Next: Expansions,     Previous: Listing,    Up: Top

    If you discover that a word expanded when you didn't mean it to
be an abbrev, you can "unexpand" it to its original word by ^X U (the
^R-command ^R Unexpand Last Word).  You can unexpand even if you have
typed past the end of the expansion.  However, unexpand is not a
stack mechanism:  only the last expansion can be unexpanded.

    As an example, assume that "v" expands to "very".  You mean to
type the phrase "the velocity v is..." but at that point you see
"the velocity very is".  Type ^X U, and you have "the velocity v is",
with the cursor after "is" where you want it.

    Any line break or new-comment starting that happened because of
the expansion is undone, leaving you with the abbrev as originally
typed.  E.g. if "mev" expands to "million electron volts", and you
are typing a LISP program:

(defun foo (a b)					;mev subr is used.

The "mev" is a subroutine name, so you want precisely "mev", but get:

(defun foo (a b)					;million
							;electron
							;volts subr
							;is used.

So, with the cursor after "used.", type ^X U, and get back to:

(defun foo (a b)					;mev subr
							;is used.

The cursor is still after "used.", as desired.

Node: Expansions,   Next: Entry/Exit,   Previous: Unexpanding,  Up: Top

    There are three expand functions: ^R Expand And Self-Insert,
^R Expand And Call Old Character, and ^R Expand Only.  All three
check the word (if any) before point, expanding it if it is an
abbrev.  They differ in what action they take after trying to expand:

    ^R Expand Only (C-M-Space) will do nothing after expanding,
allowing you to type a suffix for instance.

    ^R Expand And Call Old Char will do whatever the character did
outside of Word Abbrev Mode.  For instance, if you had ^R LISP ) on
the character ")" before setting Word Abbrev Mode, then after
trying to expand, ")" will show you the matching "(".

    ^R Expand And Self-Insert will insert its character.

    Both ^R Expand And Call Old Character, and ^R Expand And
Self-Insert will inhibit expansion if given an explicit argument.  If
you know ahead of time that a word will expand, and you want to avoid
this, you can give the character following the word an argument, as
opposed to typing ^X U to unexpand the unwanted expansion.  Thus, if
"foo" expands to "this here", and you want to type "foo bar", you
could type either:
	foo bar^XU	(let it expand, then unexpand)
or	foo$1 bar	(inhibit expanding by giving Space an
			 argument of 1)


    If ^R Mark Word Abbrev Prefix (Meta-') has marked a prefix for
the expanded abbrev, the prefix will be "glued" on to the expansion
by deleting the "-" that ^R Mark Word Abbrev Prefix used to separate
prefix and abbrev.  Thus, if "expn" expands to "expansion" and you
want "preexpansion", type:
	pre$'expn	(which will look like "pre-expn" before it expands)


    If the first letter of the abbrev is capitalized, then the first
letter of the expansion is capitalized.  If all letters of the abbrev
are capitalized, then the first letter of each word of the expansion
is capitalized.

Node: Entry/Exit,   Next: Other Modes,	 Previous: Expansions,	Up: Top

Entering Word Abbrev Mode:

    MM Word Abbrev Mode$$  (Or non-zero argument.)

    The default action is to define the following character-commands:
	^X ^A runs ^R Add Mode Word Abbrev,
	^X +  runs ^R Add Global Word Abbrev,
	M-'   runs ^R Mark Word Abbrev Prefix,
	C-M-Space runs ^R Expand Only, and
        ^XU   runs ^R Unexpand Last Word.

    However, if the variable $Word Abbrev Hook$ exists, its contents
will be executed, allowing the user to put the above commands on
whatever characters he or she desires.

    After defining the above commands, or calling $Word Abbrev Hook$,
the text break characters are defined to cause expansions.  Each of
the following chars:

	~@#;$%^&*()-_=+[]\|:'"{},<.>/?, Space, Return, Tab, Excl

will run ^R Expand And Self-Insert, or ^R Expand And Call Old Character.
You can inhibit redefinition of any of the above characters by putting them
into the variable $Untouched By Word Abbrev$.  E.g. if you do not want the
characters "-", "_", and "=" to run expansion commands, put the string "-_="
into $Untouched By Word Abbrev$.


Exiting Word Abbrev Mode:

    0 MM Word Abbrev Mode$ will take you out of Word Abbrev Mode, and restore
all break characters to non-expanding commands.  Again, if $Word Abbrev Hook$
exists, it will be called.  Its argument is the zero for exiting Word Abbrev
Mode, and non-zero for entering.

    Exiting Word Abbrev Mode will not cause the definitions of abbrevs to be
lost;  it will just render them inactive.

Node: Other Modes,	Previous: Entry/Exit,		Up: Top

    Word Abbrev Mode tries hard to interface gracefully to other modes, such
as Auto Fill, LISP, Text, TECO, Auto Save, etc.  While in Word Abbrev Mode
you can change the other modes, and things should work out ok.  If the mode
changing commands redefine any of the characters that Word Abbrev Mode uses,
that will be spotted and Word Abbrev Mode will put ^R Expand And Call Old
Character on that redefined character:  it will first expand, then go do
whatever the mode wanted it to do.

    This observation of character-redefinition happens when the subroutine
& Set Mode Line is called.  This is called whenever a buffer is switched, or
a mode is changed.  If you manually redefine a character, say by doing:
	m.m ^R LISP )$ u^R) $$
then Word Abbrev Mode will not notice the change, since & Set Mode Line has
not yet been called.  Thus ")" will not cause expansions.  However, if you
later change modes or buffers, the change will be noticed, and ")" will start
expanding abbrevs as well as showing the matching "(".  To force Word Abbrev
Mode to notice your manual redefinition, just do:
	mm & Set Mode Line$$

    You can specify to Word Abbrev Mode that it should not redefine
certain characters, by including those characters in the variable
$Untouched By Word Abbrev$.  The following characters will be
redefined to cause expansions unless they are in that variable:

    ~@#;$%^&*()-_=+[]\|:'"{},<.>/?, Space, Return, Tab, Excl

