Trailing-Edge
-
PDP-10 Archives
-
mit_emacs_170_teco_1220
-
info/wordab.info
There are no other files named wordab.info in the archive.
-*-Text-*-
Don't edit this file! It is produced by SCRIBE from WORDAB.MSS.
This file documents the EMACS Word Abbrev mode.
WORDAB Node: Top, Up: (EMACS)Top, Next: Basic
Word Abbreviation Input
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 ("thier" could expand to "their"), and for uppercasing words like
"EMACS" (abbrev "emacs" could expand to "EMACS").
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.)
For example, in writing this documentation I could have defined "wam" to
be an abbreviation for "word abbrev mode". After typing just the
letters "wam", I see just that, "wam", but if I 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 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 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.
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).
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 not
lost.
Word abbrevs can be killed, either singly or by editing the current
definition list.
* 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.
WORDAB Node: Basic, Previous: Top, Up: Top, Next: Adding
Basic Usage
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.
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.
WORDAB Node: Adding, Previous: Basic, Up: Basic, Next: Expanding
Adding Word Abbrevs
C-X C-A (^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
+ (^R Add Global Word Abbrev), which works similarly.
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.
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:
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 (^R Inverse
Add Mode Word Abbrev) or C-X - (^R Inverse Add Global Word Abbrev)
commands are helpful: they ask you to type in an 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.
You can kill abbrevs (cause them to no longer expand) by giving a
negative numeric argument to C-X C-A or C-X +. For instance, to kill
the global abbrev "foo" type C-U - C-X + foo<cr>.
WORDAB Node: Expanding, Previous: Adding, Up: Basic, Next: Unexpanding
Controlling Abbrev Expansion
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).
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 (^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-' (^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 "intercommittee ";
type "inter", M-' (you will now see "inter-"), and then "comm ";
"inter-comm " becomes "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.)
WORDAB Node: Unexpanding, Previous: Expanding, Up: Basic, Next: Listing
Unexpanding Abbrevs
C-X U (^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.
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.
WORDAB Node: Listing, Previous: Unexpanding, Up: Basic, Next: Editing
Listing 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:
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:
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:
helpc: 3 "the ""Help"" character"
WORDAB Node: Editing, Previous: Listing, Up: Basic, Next: Saving
Editing the Definition List
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 C-M-Z), 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.
WORDAB Node: Saving, Previous: Editing, Up: Basic
Saving Abbrev Definitions
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 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 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.)
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.)
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:
*: 1 MM Word Abbrev Mode
*: MM Read Word Abbrev FileWORDAB.DEFNS
Save Word Abbrevs:1
Or if you have an init file, use the following Teco code:
1 MM Word Abbrev Mode
MM Read Word Abbrev FileWORDAB.DEFNS
1uSave Word Abbrevs
WORDAB Node: Advanced, Up: Top, Next: Alternatives
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.
WORDAB Node: Alternatives, Previous: Advanced, Up: Advanced, Next: Lists
Alternatives and Customizations
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.
The basic commands for defining a new mode abbrev, C-X C-A (^R Add Mode
Word Abbrev) and C-X C-H (^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.
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.)
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 (^R Add Mode Word
Abbrev) and C-X + (^R Add Global Word Abbrev) inconvenient, you should
connect these functions to characters. (*Note Set Key: (EMACS)MMArcana.
Or *Note Init: (EMACS)Init.)
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 C-X + (^R Add Global
Word Abbrev) and C-X - (^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.
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, 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. *Note
init: (EMACS)init, for details on setting variables in init and EVARS
files.
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 &
Attach Word Abbrev Hook subroutine.
WORDAB Node: Lists, Previous: Alternatives, Up: Advanced, Next: Many
Manipulating Definition Lists
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 Many Abbrevs: 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. *Note Narrowing: (EMACS)Narrowing.
WORDAB Node: Many, Previous: Lists, Up: Advanced, Next: Dumping
Dealing with Many Abbrevs
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.
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 (*Note
TECO search strings: (EMACS)TECOsearch.). If you want to see the
abbrevs which contain either <string1> or <string2>, separate the
strings with a ; to see abbrev definitions containing either "defn" or
"wab", do M-X List Word Abbrevsdefnwab<cr>.
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.
WORDAB Node: Dumping, Previous: Many, Up: Advanced, Next: Teco
Dumped EMACS Environments
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.
*Note Dumping: (CONV), for more details about dumping environments.)
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 SINCE the environment was dumped out. A file
which contains only these new abbrev's definitions is called an
"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 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).
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 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 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.
WORDAB Node: Teco, Previous: Advanced, Up: Top
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.
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 (^R Add Mode Word Abbrev), check to
see if the volatile TECO mark, fs^RMark, is set; if it is, then the
region between point and fs^RMark is used as the expansion. The
intention is to provide a mechanism for simple but safe expansion
marking. *Note FS Flags: (EMACS)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 & 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 1fsMode Change to cause expansions to be redefined.