-*-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$$. (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$$. ********** 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$ for a mode abbrev, and $X * 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$$ 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$$ 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: ::= null | <1def> CRLF <1def> ::= : " " ::= ::= null | ( ) ::= null | refers to spaces and tabs. There can be no colons in an abbrev, though there can be quotes in the expansion. If 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