Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

@make(INFO)@Comment[-*-Text-*-]
@Device(INFO)
@Comment<

This is the SCRIBE source from which the INFO file for WORDAB and
the section describing it in the EMACS GUIDE are generated.

Control characters are represented as @CTL[X].

SCRIBE requires two @'s whenever one is wanted.
The SCRIBE "@:" construct must be used when a sentence ends with a
one-letter word.  "@." must be used when a sentence end appears to
occur after an abbreviation.

The SCRIBE constructs @U and @I cannot be used.  Instead, use @XXU and
@XXI for underlining and italicizing.  These do nothing in the INFO version.
Alternatively, use @XXUU and @XXII, which turn into all caps in
the INFO version.

>
@Define(Commands=Description,LeftMargin 16,Indent -8,Spread 0)
@Define(WideCommands=Description,LeftMargin 20,Indent -12,Spread 0)
@Define(DoubleWideCommands=Description,LeftMargin 24,Indent -16,Spread 0)
@Define(GrossCommands=Description,LeftMargin 16,Indent -16,Spread 1)
@Case{draft, ITS <@Textform[CC="C-C",CMC="C-M-C",TAGS=":TAGS"]>}
@Case{draft, Twenex <@Textform[CC="C-Z",CMC="C-M-Z",TAGS="TAGS"]>}

@Comment< These do not work!
@ITS{@Textform[C-C="C-C", C-M-C="C-M-C"]}
@Twenex{@Textform[C-C="C-Z", C-M-C="C-M-Z"]}
	They all get "Textform not at beginning of manuscript">

@style(stringmax=20000)
@String(Filename="WORDAB")

@INFO{@Verbatim{  -*-Text-*-
Don't edit this file! It is produced by SCRIBE from WORDAB.MSS.

This file documents the EMACS Word Abbrev mode.
}}
@Node(Name="Top",	Next="Basic",		Up="(EMACS)Top")

@Chapter[Word Abbreviation Input]
@index{WORDAB}@index{Word Abbrev Mode}@index{Abbrevs}

  Word Abbrev mode allows you to abbreviate text with a
single "word", with EMACS expanding the abbreviation automatically as
soon as you have finished the abbreviation.

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

@index{libraries}@index{minor modes}
  To use this mode, just do M-X Word Abbrev Mode<cr>.  (Another M-X Word
Abbrev Mode<cr> will turn the mode off; it toggles.)

@index{case conversion}
  For example, in writing this documentation we could have defined
"wam" to be an abbreviation for "word abbrev mode".  After typing just
the letters "wam", we see just that, "wam", but if we then finish the
word by typing space or period or any other punctuation, the "wam" is
replaced by (and redisplays as) "word abbrev mode".  If we capitalize
the abbrev, "Wam", the expansion is capitalized: "Word abbrev mode".
If we capitalize the whole abbrev, WAM", each word in the expansion is
capitalized: "Word Abbrev Mode".  In this particular example, though,
we would define "wam" to expand to "Word Abbrev mode" since it is
always to be capitalized that way.

  Thus, typing "I am in wam now" produces "I am in Word Abbrev mode now".

  Word Abbrev mode does not interfere with the use of major modes, such as Text,
Lisp, TECO, PL1, or minor modes, such as Auto Fill.  Those modes (or
the user) may redefine what functions are connected to characters;
this does not hamper Word Abbrev mode. 

@index{major modes}@index{mode abbrevs}@index{global abbrevs}
  There are two kinds of word abbreviations: mode and global.  A mode
word abbrev applies only in one major mode (for instance only in Text
mode), while a global word abbrev applies regardless of major mode.
If some abbrev is defined both as a mode word abbrev for the current
mode and as 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).

@index{abbrev definition lists}

  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).  You can save
them in a file and read them back later.  If you turn off Word Abbrev
mode, abbrevs stop expanding automatically, but their definitions are
remembered in case you turn Word Abbrev mode back on.

@Menu{
* Basic::		The most common use of Word Abbrev mode, with
			small numbers of abbrevs (less than 50).

* Advanced::		Customizations, manipulating word abbrev lists
			in various ways, dealing with a large number
			of word abbrevs, what to do if you dump your
			EMACS environment.

* Teco::		Details that extension writers may want to know.
}
@Node(Name="Basic",  Next="Adding",  Prev="Top",  Up="Top")

@Section[Basic Usage]

@index{Word Abbrev Mode}
@WideCommands[

C-X C-A@\Define a mode abbrev for some text before point.

C-X +@\Define a global abbrev for some text before point.

C-X C-H@\Define expansion for mode abbrev before point.

C-X -@\Define expansion for global abbrev before point.

C-M-Space@\Expand abbrev without inserting anything.

M-'@\Mark a prefix to be glued to an abbrev following.

C-X U@\Unexpand the last abbrev, or undo a C-X U.
]

@GrossCommands[

M-X List Word Abbrevs<cr>@\
Shows definitions of all abbrevs.

M-X Edit Word Abbrevs<cr>@\
Lets you edit the definition list directly.

M-X Read Word Abbrev File<filename><cr>@\
Defines word abbrevs from a definition file.

M-X Write Word Abbrev File<filename><cr>@\
Makes a definition file from current abbrev definitions.

Readable Word Abbrev Files@\
Option variable to control abbrev file format.
]

    This section describes the most common use of Word Abbrev
mode.  If you don't read any more than this, you can still use Word
Abbrev mode quite effectively.

    Note that each of the above commands will also work when Word
Abbrev mode is turned off, unlike the automatic expanders (such as Space
or Period), allowing you to manually define and expand abbrevs.  (If
you want to do this, you might also see the M-X Expand Word Abbrevs in
Region command's self-documentation.)

@Menu{
* Adding::		Adding word abbrevs one by one.
* Expanding::		Controlling abbrev expansion.
* Unexpanding::		Undoing or preventing expansions.
* Listing::		Listing current abbrev definitions.
* Editing::		Editing the abbrev definition list to change,
			add, or kill abbrev definitions all at once.
* Saving::		Saving definitions in a file for later.
}

@Node(Name="Adding",	Next="Expanding", Prev="Basic",	  Up="Basic")

@Subsection[Adding Word Abbrevs]
@index{C-X C-A}@index{C-X +}@index{C-X C-H}@index{C-X -}@index{defining abbrevs}
@index{^R Add Mode Word Abbrev}@index{^R Add Global Word Abbrev}
@index{^R Inverse Add Mode Word Abbrev}@index{^R Inverse Add Global Word Abbrev}
@index{echo area}

    C-X C-A (@w[^R Add] Mode Word Abbrev) defines a mode abbrev for the
word before point (this does not include any punctuation between that
word and point, though).  It prints the word before point in the
echo area and asks you for that word's abbreviation.  Type the abbrev
(which you may edit with Rubout and C-U) followed by a
Return.  The abbrev must be a "word": it must contain only letters
and digits; the case of the letters is irrelevant.
If you'd rather define a global abbrev, use C-X + (@w[^R Add]
Global Word Abbrev), which works similarly.

@index{confirmation}@index{redefining abbrevs}

    You can redefine an abbrev with C-X C-A or C-X +.  If the abbrev
already has a definition, it tells you what that was, and asks for
confirmation.

@index{region}@index{numeric argument}@index{argument}

    To define an abbrev for more than one word of text, give C-X C-A or
C-X + a numeric argument:  an argument greater than 0 means the expansion
is that many words before point;  an argument of 0 means to use the region
(between point and mark).  (By using the region specification you can make
an abbrev for any text, not just a sequence of words.)  The message in
the echo area provides you with confirmation of just what the
expansion will be; you might see:

@example[
Text Abbrev for "this is the expansion":
]

    Sometimes you may think you already had an abbrev for some text, use
it, and see that it didn't expand.  In this case, the C-X C-H (@w[^R Inverse]
Add Mode Word Abbrev) or @w[C-X -] (@w[^R Inverse] Add Global Word Abbrev)
commands are helpful:  they ask you to type in an @XXIi[expansion]
rather than an abbrev.  In addition to defining the abbrev, they also
expand it.  If you give them a numeric argument, n, they use the
nth word before point as the abbrev.

@index{killing abbrevs}

    You can kill abbrevs (cause them to no longer expand) by giving a
negative numeric argument to C-X C-A or @w[C-X +].  For instance, to kill the
global abbrev "foo" type @w[C-U -] @w[C-X +] foo<cr>.

@Node(Name="Expanding",	Next="Unexpanding", Prev="Adding",  Up="Basic")

@Subsection[Controlling Abbrev Expansion]
@index{C-M-Space}@index{^R Abbrev Expand Only}@index{M-'}@index{^R Word Abbrev Prefix Mark}
@index{expanding abbrevs}@index{capitalization}
@index{Expand Word Abbrevs in Region}
@index{WORDAB All Caps}

    When an abbrev expands, the capitalization of the expansion is
determined by the capitalization of the abbrev:  If the abbrev is all
lowercase, the expansion is as defined.  If the abbrev's first letter is
uppercase, the expansion's first letter is too.  If the abbrev is all
uppercase, there are two possibilities:  if the expansion is a single
word, it is all-uppercased;  otherwise, each of its words
has its first letter uppercased (such as for use in a title).
(If you don't like this distinction between single-word and
multi-word expansions, set the variable WORDAB All Caps to 1.
Then an all-uppercase abbrev will always result in an all-uppercase
expansion.)

    Abbrevs normally expand when you type some punctuation character;  the
abbrev expands and the punctuation character is inserted.  There are other
ways of expanding abbrevs:  C-M-Space (@w[^R Abbrev] Expand Only) causes
the abbrev just before point to be expanded without inserting any other
character.  C-M-Space will expand abbrevs even if Word Abbrev mode is
currently off; this can be useful if the system is slow, and you just
want to manually expand a few abbrevs.
M-' (@w[^R Word] Abbrev Prefix Mark) allows you to "glue" an
abbrev onto any prefix:  suppose you have the abbrev "comm" for
"committee", and wish to insert @w["intercommittee "]; type "inter", M-' (you
will now see "inter-"), and then @w["comm "];  @w["inter-comm "] becomes
@w["intercommittee "].  M-X Expand Word Abbrevs in Region checks each
word in the region and offers to expand each word abbrev found;  for
more details see its self-documentation.  (It is similar to the M-X
Query Replace command.)

@Node(Name="Unexpanding", Next="Listing", Prev="Expanding", Up="Basic")

@Subsection[Unexpanding Abbrevs]
@index{unexpanding abbrevs}

    C-X U (@w[^R Unexpand] Last Word) "unexpands" the last abbrev's
expansion, replacing the last expansion with the abbrev that caused
it.  If any auto-filling was done because of the expansion (you had
Auto Fill mode on), that too is undone.  If you type another C-X U,
the first one is "undone" and the abbrev is expanded again.  Only the
last expansion can be undone.  Sometimes you may find that C-X U
unexpands an abbrev later than the one you're looking at.  In this
case, do another C-X U and go back and manually correct the earlier
expansion.

@index{preventing abbrev expansion}@index{C-Q}

    If you know beforehand that a word will expand, and want to prevent
it, you can simply "quote" the punctuation character with C-Q.  For example,
typing "comm", a C-Q, and then "." gives "comm." without expanding.

@Node(Name="Listing", Next="Editing", Prev="Unexpanding", Up="Basic")

@Subsection[Listing Abbrevs]
@index{List Word Abbrevs}

  M-X List Word Abbrevs<cr> shows all currently defined abbrevs.  An
abbrev "foo" that expands to "this is an abbrev" in Text mode and has been
expanded 3 times, is listed as:

@example[
foo:    (Text)  3       "this is an abbrev"
]

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

@example[
gfoo:           11      "this is a global abbrev"
]

  Note that any use of the double-quote character (") inside an expansion
is doubled, to distinguish the use of " from the "s that surround the
whole expansion.  Thus if the global abbrev 'helpc' expands to
'the "Help" character', it is listed as:

@example[
helpc:		3	"the ""Help"" character"
]

@Node(Name="Editing", Next="Saving",  Prev="Listing", Up="Basic")

@Subsection[Editing the Definition List]
@index{Edit Word Abbrevs}@index{defining abbrevs}@index{killing abbrevs}
@index{recursive editing level}@index{abbrev definition lists}

  M-X Edit Word Abbrevs places you in a recursive editing level,
editing the current word abbrev definition list.  The abbrevs appear
in the same format used by M-X List Word Abbrevs.  When you exit (via @CMC[]),
the current word abbrevs are redefined from 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 editing level, all
previously-defined word abbrevs are killed, and the edited list is used to
define new abbrevs.  Typing C-] (Abort Recursive Edit) aborts Edit
Word Abbrevs, without killing or redefining any abbrevs.

@Node(Name="Saving",		Prev="Editing",	  Up="Basic")

@Subsection[Saving Abbrev Definitions]
@index{Write Word Abbrev File}@index{Read Word Abbrev File}
@index{saving abbrevs}@index{abbrev definition files}
@index{Save Word Abbrevs}@index{exiting EMACS}
@ITS[@index{WORDAB DEFNS}@index{C-X C-C}]
@Twenex[@index{WORDAB.DEFNS}@index{C-X C-Z}]

    M-X Write Word Abbrev File<filename><cr> writes an "abbrev
definition file" which contains the definitions of all the abbrevs in
your EMACS now.  M-X Read Word Abbrev File<filename><cr> reads in
such a file and defines the abbrevs.  (Other abbrevs already
defined are not affected unless the file redefines them.)
If you don't supply a filename, the last file you used in either of
these commands is used again, originally defaulting to
@ITS[WORDAB DEFNS]@Twenex[WORDAB.DEFNS].  With these two commands, you
can save the abbrevs you defined in one EMACS and restore them in
another EMACS another day.  If you want abbrevs to be automatically
saved when you exit EMACS (with @ITS[C-X C-C]@Twenex[C-X C-Z] (^R
Return to Superior)), set the option variable Save Word Abbrevs to 1.
(They are saved only if the definitions have changed.)


@index{Readable Word Abbrev Files}
    The format of the definition file is designed for fast loading, not
ease of human readability.  (But if you have to, you can figure it out
enough to read or even edit it.)  If you want M-X Write Word Abbrev File
to write a human-readable version instead, set the option Readable Word
Abbrev Files to 1.  (M-X Read Word Abbrev File will be able to read
this format, but not as fast.)

@index{init files}@index{EVARS files}
    If you have an EVARS file, you might want to put the following
lines into it in order to turn on Word Abbrev mode, have your
abbrev definition file automatically read when EMACS starts up, and
enable automatic exit-saving:

@example{
*: 1 MM Word Abbrev Mode
@ITS[*: MM Read Word Abbrev FileWORDAB DEFNS]
@Twenex[*: MM Read Word Abbrev FileWORDAB.DEFNS]
Save Word Abbrevs:1
}

    Or if you have an init file, use the following Teco code:

@example{
1 MM Word Abbrev Mode
@ITS[MM Read Word Abbrev FileWORDAB DEFNS]
@Twenex[MM Read Word Abbrev FileWORDAB.DEFNS]
1uSave Word Abbrevs
}

@Node(Name="Advanced",	Next="Alternatives",  Previous="Basic", Up="Top")

@Section[Advanced Usage]

    The use of Word Abbrev mode as discussed in the previous section
suffices for most users.  However, some users who use Word Abbrev
mode a lot or have highly tailored environments may desire more
flexibility or need more power to handle extreme situations than the
basic commands provide.

@Menu{
* Alternatives::	Various other ways of doing basic things and
			ways of customizing Word Abbrev mode.
* Lists::		Commands for manipulating definition lists.
* Many::		Dealing with a huge number of abbrevs.
* Dumping::		What to do if you dump out your EMACS
			environment for fast startups.
}

@Node(Name="Alternatives", Next="Lists", Prev="Advanced", Up="Advanced")

@Subsection[Alternatives and Customizations]

@index{customization}@index{init files}@index{EVARS files}

@GrossCommands[
M-X Make Word Abbrev<abbrev><expansion><mode><cr>

M-X Kill All Word Abbrevs<cr>

M-X Make These Characters Expand<characters><cr>

M-X Attach Word Abbrev Keyboard Macro

^R Kill Mode Word Abbrev

^R Kill Global Word Abbrev

Only Global Abbrevs@\
Set this option if you only use globals.

Additional Abbrev Expanders@\
Variable for adding a few more expanders.

WORDAB Ins Chars@\
Variable for replacing entire set of expanders.
]

@index{C-X C-A}@index{C-X +}@index{Make Word Abbrev}
@index{mode abbrevs}@index{global abbrevs}
@index{^R Add Mode Word Abbrev}@index{^R Add Global Word Abbrev}
@index{^R Inverse Add Mode Word Abbrev}
@index{^R Inverse Add Global Word Abbrev}

    The basic commands for defining a new mode abbrev, C-X C-A (^R
Add Mode Word Abbrev) and C-X C-H (@w[^R Inverse] Add Mode Word Abbrev),
work only in the current mode.  A more general command is M-X Make
Word Abbrev which takes three string arguments:  the first is the
abbrev, the second is the expansion, and the third is the mode (such as
"Text").  This command can also define global abbrevs, by providing
"*" as the mode name.

@index{killing abbrevs}@index{Kill All Word Abbrevs}

    M-X Kill All Word Abbrevs<cr> is a very quick way of killing every
abbrev currently defined.  After this command, no abbrev will expand.
(A slower but more careful way is with M-X Edit Word Abbrevs.)

@index{^R Kill Mode Word Abbrev}@index{^R Kill Global Word Abbrev}
@index{Set Key}@index{init files}@index{EVARS files}

    The functions ^R Kill Mode Word Abbrev and ^R Kill Global Word
Abbrev exist, but are not connected to any commands by default.
If you find having to specify negative arguments to
C-X C-A (@w[^R Add] Mode Word Abbrev) and C-X + (@w[^R Add] Global Word
Abbrev) inconvenient, you should connect
these functions to commands.
(@XNote(File="EMACS", Node="MMArcana", Name="Set Key").  Or
@XNote(File="EMACS", Node="Init").)

@index{C-X +}@index{C-X -}@index{mode abbrevs}@index{global abbrevs}
@index{^R Add Global Word Abbrev}@index{^R Inverse Add Global Word Abbrev}
@index{killing abbrevs}@index{Kill All Word Abbrevs}
@index{Only Global Abbrevs}@index{Word Abbrev Mode}

    If you prefer to use only global abbrevs then you should set the
option variable Only Global Abbrevs to 1.  You can do this after or
before turning on Word Abbrev mode; it makes no difference.  This
causes the global abbrev definers which would otherwise be on
@w[C-X +] (@w[^R Add] Global Word Abbrev) and @w[C-X -]
(@w[^R Inverse] Add Global Word Abbrev) to be on the easier to type
characters C-X C-A and C-X C-H.  In addition, the checking done
whenever you type an expander character (a punctuation character) is
about three times faster for the no-expansion case, which is what
happens most of the time.

@index{expander characters}@index{Make These Characters Expand}
@index{Additional Abbrev Expanders}@index{WORDAB Ins Chars}

    Normally, the following characters cause expansion (followed by
whatever they would normally do were Word Abbrev mode off; such as,
insert themselves): !~@@#;$%^&*-_=+[]()\|:`"{},<.>'/? and Space,
Return, Linefeed, and Tab.  You can, however, specify additional characters to
cause expansion (digits, for instance, or greek letters on keyboards
with Top-keys).  M-X Make These Characters Expand<characters><cr>
adds the characters in the string argument to the list of expanders.
Alternatively, you can set the
variable Additional Abbrev Expanders to contain the string of
characters.  (This is particularly useful in an init or EVARS file.)
If you wish to completely replace the set of characters
that cause expansion, set the variable WORDAB Ins Chars in your init
file.  @XNote(File="EMACS", Node="init"), for details on setting
variables in init and EVARS files.

@INFO{
    Word abbrev hooks are a (very) experimental mechanism: a Teco
program or keyboard macro can be specified to execute just after a
particular abbrev expands.  See the self-documentation of the M-X
Attach Word Abbrev Keyboard Macro command; Teco programmers should
describe the @w[& Attach] Word Abbrev Hook subroutine.
}

@Node(Name="Lists", Next="Many", Prev="Alternatives", Up="Advanced")

@Subsection[Manipulating Definition Lists]

@index{abbrev definition lists}
@index{List Word Abbrevs}@index{Insert Word Abbrevs}@index{Define Word Abbrevs}

    One reason you might want to manipulate the definition lists
is to provide more structure to the definition environment than just
the mode vs. global structure provided normally, such as to group together in
a file those abbrevs pertaining to one topic.

    M-X Insert Word Abbrevs<cr> inserts into the buffer a list of
the current word abbrev definitions, in the format that M-X List Word
Abbrevs uses.  M-X Insert Word Abbrevs<string><cr> inserts some
of the abbrevs' definitions;  @Note(Name="Many Abbrevs", Node="Many"), for
details.

    M-X Define Word Abbrevs<cr> defines a set of word abbrevs from
a definition list in the buffer.  There should be nothing else besides
the definition list in the buffer; or, if there is, you must
narrow the buffer to just the definition list.
@XNote(File="EMACS", Node="Narrowing").


@Node(Name="Many", Next="Dumping", Prev="Lists", Up="Advanced")

@Subsection[Dealing with Many Abbrevs]
@index{List Word Abbrevs}@index{Insert Word Abbrevs}
@index{abbrev definition lists}

    Some users build up a very large number of abbrevs.  This
causes a couple of problems:  First, defining all those abbrevs
when EMACS starts up can become too slow; this problem is discussed in
the next section.  Second, the commands that deal with the entire
definition list become unwieldy.

@index{quoting}@index{C-Q}

    M-X List Word Abbrevs<string><cr> shows you the definitions of
just the abbrev definitions containing <string> (in the abbrev, in the
mode, or in the expansion).  The argument is actually a TECO search
string (@XNote(Name="TECO search strings", Node="TECOsearch",
File="EMACS").).  If you want to see the abbrevs which contain either
<string1> @XXI[or] <string2>, separate the strings with a @CTL[O];
to see abbrev definitions containing either "defn" or "wab", do
M-X List Word Abbrevsdefn@CTL[O]wab<cr>.

@index{C-U}@index{argument}@index{numeric argument}

    You can provide M-X List Word Abbrevs with an argument to
control whether the filtering string applies to just the abbrev (C-U
1), just the expansion (C-U 2), just the mode (C-U 4), or any
combination (the sum).  C-U 3 M-X List Word Abbrevslisp<cr>
will match "lisp" against abbrevs and expansions, but not modes.

    M-X Insert Word Abbrevs<string><cr> works similarly, but
inserts the list into the buffer instead of typing it out.

@Node(Name="Dumping", Next="Teco", Prev="Many", Up="Advanced")

@Subsection[Dumped EMACS Environments]
@index{dumped environments}@index{incremental abbrev definition files}
@index{abbrev definition files}
@index{Read Incremental Word Abbrev File}@index{Read Word Abbrev File}
@index{Write Incremental Word Abbrev File}@index{Write Word Abbrev File}

@GrossCommands[
M-X Write Word Abbrev File<filename><cr>@\
Writes a file of all abbrev definitions, before dumping.

M-X Read Word Abbrev File<filename><cr>@\
Reads file of abbrev definitions at init-time.

M-X Write Incremental Word Abbrev File<filename><cr>@\
Writes a file of abbrev definitions changed since dumping.

M-X Read Incremental Word Abbrev File<filename><cr>@\
Reads file of changed abbrev definitions at startup-time.
]

    Some users with highly customized EMACS environments (their init files
take a long time to run) "dump out" their environments, in effect creating
another EMACS-like program (the "dump") which starts up much faster.  (For
instance, 1.7 cpu seconds instead of 70.5 cpu seconds.
@INFONote(Name="MKDUMP", File="MKDUMP"), for details about a simple
method of dumping environments.
@INFONote(Name="Dumping", File="CONV"), for details about more
general environment dumping.)  Since the dumped environment
contains word abbrev definitions, a dumped environment with hundreds of
abbrevs can start just as quickly as if it had none.  (But reading all these
abbrevs with M-X Read Word Abbrev File in the init file originally took a long
time.)  For these users it is important, at dump-startup time,
to read in only those abbrevs which were changed or defined @XXII[since] the
environment was dumped out.  A file which contains only these new abbrev's
definitions is called an @dfn[incremental word abbrev file].  (It also can
specify that certain abbrevs are to be killed if they were defined when the
environment was dumped out, but subsequently killed.)

    The startup for the dump should use the Read Incremental Word Abbrev File
function instead of Read Word Abbrev File.  It takes the filename as a string
argument, which defaults to @ITS[INCABS >]@Twenex[INCABS..0].  The command M-X
Write Incremental Word Abbrev File<filename><cr> writes such a file,
writing out those abbrevs more recent than the dump (ones read by
Read Incremental Word Abbrev File and ones defined in the current editing
session).

@index{Save Word Abbrevs}@index{exiting EMACS}

    Setting Save Word Abbrevs to -1 will cause an incremental abbrev
file to be automatically written, if necessary, when EMACS is exited.

    When you want to dump out a new EMACS, first create a new, complete
word abbrev definition file using M-X Write Word Abbrev File.  This
file now has @XXII[all] abbrevs in it, and you can thus delete any
incremental definition files you have.  Then start up the new EMACS
from scratch, using the init file, and dump it.  (The init file in
general should call Read Word Abbrev File and then @XXI[also] call Read
Incremental Word Abbrev File, just in case there are both kinds of
files around.  The startup calls only Read Incremental Word Abbrev
File.)  Note that these functions will return without error if their
files don't exist, as a convenience.

@Node(Name="Teco",	  Prev="Advanced",	Up="Top")

@Section[Teco Details for Extension Writers]

    This section documents some details that users programming
extensions may need to know, in order to interact properly with Word
Abbrev mode operation or to build upon it.

@index{hooks}@index{WORDAB Setup Hook}@index{Word Abbrev Hook}
@index{C-X C-A}@index{C-X C-H}@index{C-X +}@index{C-X -}
@index{M-'}@index{C-M-Space}@index{C-X U}

    The
variable WORDAB Setup Hook, if non-0, is executed when the WORDAB
library is loaded and sets itself up.  (M-X Word Abbrev Mode<cr> in
the default EMACS environment auto-loads the WORDAB library.)  If
there is no hook, the normal key connections (C-X C-A, C-X U, etc@.)
are made;  if there is a hook, it must do the connections.

    The variable Word Abbrevs Modified is non-0 when abbrev
definitions have changed.  This is used to signal the abbrev-saving
mechanism.

    The abbrev definers, such as C-X C-A (@w[^R Add] Mode Word Abbrev), check
to see if the volatile TECO mark, @w[FS ^R] Mark, is set; if it is, then
the region between point and @w[FS ^R] Mark is used as the expansion.  The
intention is to provide a mechanism for simple but safe expansion
marking.  @XNote(Name="FS Flags", File="EMACS", Node="FS Flags").

    Finally, the general way that Word Abbrev mode works is this: at
certain times, when characters are likely to have been reconnected, a Word
Abbrev mode subroutine looks at each of the expander characters to see
if they are running an expander or have been reconnected.  If they don't
have expanders, they are connected to an expander function (which
first checks for expansion and then calls the "old" function, what the
character was connected to before).  The problem is that it is not really
possible to efficiently catch all the times that characters of interest are
reconnected.  So, as a good guess, Word Abbrev mode looks at these characters
when the @w[& Set] Mode Line function is called.  This happens when major
or minor modes change, when buffer switching happens, and when Set Key
is used.  These are the standard times that connections are changed.
However, the extension writer must be careful about reconnecting expander
characters.  If an extension might do this, it should do 1FS Mode
Change to cause expansions to be redefined.