X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Fxemacs%2Fabbrevs.texi;fp=man%2Fxemacs%2Fabbrevs.texi;h=e1afef7f30ec7260ed124a62771de1cfc91658d3;hb=6883ee56ec887c2c48abe5b06b5e66aa74031910;hp=0000000000000000000000000000000000000000;hpb=5db996688c255b7f4bbe096f935b10d4c4ab7ade;p=chise%2Fxemacs-chise.git.1 diff --git a/man/xemacs/abbrevs.texi b/man/xemacs/abbrevs.texi new file mode 100644 index 0000000..e1afef7 --- /dev/null +++ b/man/xemacs/abbrevs.texi @@ -0,0 +1,306 @@ + +@node Abbrevs, Picture, Packages, Top +@chapter Abbrevs +@cindex abbrevs +@cindex expansion (of abbrevs) + + An @dfn{abbrev} is a word which @dfn{expands} into some +different text. Abbrevs are defined by the user to expand in specific +ways. For example, you might define @samp{foo} as an abbrev expanding to +@samp{find outer otter}. With this abbrev defined, you would be able to +get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}. + +@findex abbrev-mode +@vindex abbrev-mode + Abbrevs expand only when Abbrev mode (a minor mode) is enabled. +Disabling Abbrev mode does not cause abbrev definitions to be discarded, +but they do not expand until Abbrev mode is enabled again. The command +@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it +turns Abbrev mode on if the argument is positive, off otherwise. +@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is +on when the variable is non-@code{nil}. The variable @code{abbrev-mode} +automatically becomes local to the current buffer when it is set. + + Abbrev definitions can be @dfn{mode-specific}---active only in one major +mode. Abbrevs can also have @dfn{global} definitions that are active in +all major modes. The same abbrev can have a global definition and various +mode-specific definitions for different major modes. A mode-specific +definition for the current major mode overrides a global definition. + + You can define Abbrevs interactively during an editing session. You +can also save lists of abbrev definitions in files and reload them in later +sessions. Some users keep extensive lists of abbrevs that they load in +every session. + + A second kind of abbreviation facility is called the @dfn{dynamic +expansion}. Dynamic abbrev expansion happens only when you give an +explicit command and the result of the expansion depends only on the +current contents of the buffer. @xref{Dynamic Abbrevs}. + +@menu +* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. +* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. +* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. +* Saving Abbrevs:: Saving the entire list of abbrevs for another session. +* Dynamic Abbrevs:: Abbreviations for words already in the buffer. +@end menu + +@node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs +@section Defining Abbrevs + +@table @kbd +@item C-x a g +Define an abbrev to expand into some text before point +(@code{add-global-abbrev}). +@item C-x a l +Similar, but define an abbrev available only in the current major mode +(@code{add-mode-abbrev}). +@item C-x a i g +Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). +@item C-x a i l +Define a word in the buffer as a mode-specific abbrev +(@code{inverse-add-mode-abbrev}). +@item M-x kill-all-abbrevs +After this command, no abbrev definitions remain in effect. +@end table + +@kindex C-x a g +@findex add-global-abbrev + The usual way to define an abbrev is to enter the text you want the +abbrev to expand to, position point after it, and type @kbd{C-x a g} +(@code{add-global-abbrev}). This reads the abbrev itself using the +minibuffer, and then defines it as an abbrev for one or more words +before point. Use a numeric argument to say how many words before point +should be taken as the expansion. For example, to define the abbrev +@samp{foo} as in the example above, insert the text @samp{find outer +otter}, then type @*@kbd{C-u 3 C-x a g f o o @key{RET}}. + + An argument of zero to @kbd{C-x a g} means to use the contents of the +region as the expansion of the abbrev being defined. + +@kindex C-x a l +@findex add-mode-abbrev + The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but +defines a mode-specific abbrev. Mode-specific abbrevs are active only in a +particular major mode. @kbd{C-x a l} defines an abbrev for the major mode +in effect at the time @kbd{C-x a l} is typed. The arguments work the +same way they do for @kbd{C-x a g}. + +@kindex C-x a i g +@findex inverse-add-global-abbrev +@kindex C-x a i l +@findex inverse-add-mode-abbrev + If the text of an abbrev you want is already in the buffer instead of +the expansion, use command @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) +instead of @kbd{C-x a g}, or use @kbd{C-x a i l} +(@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a l}. These commands +are called ``inverse'' because they invert the meaning of the argument +found in the buffer and the argument read using the minibuffer.@refill + + To change the definition of an abbrev, just add the new definition. You +will be asked to confirm if the abbrev has a prior definition. To remove +an abbrev definition, give a negative argument to @kbd{C-x a g} or @kbd{C-x +a l}. You must choose the command to specify whether to kill a global +definition or a mode-specific definition for the current mode, since those +two definitions are independent for one abbrev. + +@findex kill-all-abbrevs + @kbd{M-x kill-all-abbrevs} removes all existing abbrev definitions. + +@node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs +@section Controlling Abbrev Expansion + + An abbrev expands whenever it is in a buffer just before point and you +type a self-inserting punctuation character (@key{SPC}, comma, +etc.@:). Most often an abbrev is used by inserting the abbrev followed +by punctuation. + +@vindex abbrev-all-caps + Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find +outer otter}, @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into +@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the +variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first +of the two expansions).@refill + + Two commands are available to control abbrev expansion: + +@table @kbd +@item M-' +Separate a prefix from a following abbrev to be expanded +(@code{abbrev-prefix-mark}). +@item C-x a e +@findex expand-abbrev +Expand the abbrev before point (@code{expand-abbrev}). +This is effective even when Abbrev mode is not enabled. +@item M-x unexpand-abbrev +Undo last abbrev expansion. +@item M-x expand-region-abbrevs +Expand some or all abbrevs found in the region. +@end table + +@kindex M-' +@findex abbrev-prefix-mark + You may wish to expand an abbrev with a prefix attached. For example, +if @samp{cnst} expands into @samp{construction}, you may want to use it +to enter @samp{reconstruction}. It does not work to type @kbd{recnst}, +because that is not necessarily a defined abbrev. Instead, you can use +the command @kbd{M-'} (@code{abbrev-prefix-mark}) between the prefix +@samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then +type @kbd{M-'}; this inserts a minus sign in the buffer to indicate that +it has done its work. Then insert the abbrev @samp{cnst}. The buffer +now contains @samp{re-cnst}. Now insert a punctuation character to +expand the abbrev @samp{cnst} into @samp{construction}. The minus sign +is deleted at this point by @kbd{M-'}. The resulting text is the +desired @samp{reconstruction}.@refill + + If you actually want the text of the abbrev in the buffer, rather than +its expansion, insert the following punctuation with @kbd{C-q}. Thus, +@kbd{foo C-q -} leaves @samp{foo-} in the buffer. + +@findex unexpand-abbrev + If you expand an abbrev by mistake, you can undo the expansion (replace +the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}. +You can also use @kbd{C-_} (@code{undo}) to undo the expansion; but that +will first undo the insertion of the punctuation character. + +@findex expand-region-abbrevs + @kbd{M-x expand-region-abbrevs} searches through the region for defined +abbrevs, and offers to replace each one it finds with its expansion. +This command is useful if you have typed text using abbrevs but forgot +to turn on Abbrev mode first. It may also be useful together with a +special set of abbrev definitions for making several global replacements at +once. The command is effective even if Abbrev mode is not enabled. + +@node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs +@section Examining and Editing Abbrevs + +@table @kbd +@item M-x list-abbrevs +Print a list of all abbrev definitions. +@item M-x edit-abbrevs +Edit a list of abbrevs; you can add, alter, or remove definitions. +@end table + +@findex list-abbrevs + The output from @kbd{M-x list-abbrevs} looks like this: + +@example +(lisp-mode-abbrev-table) +"dk" 0 "define-key" +(global-abbrev-table) +"dfn" 0 "definition" +@end example + +@noindent +(Some blank lines of no semantic significance, and some other abbrev +tables, have been omitted.) + + A line containing a name in parentheses is the header for abbrevs in a +particular abbrev table; @code{global-abbrev-table} contains all the global +abbrevs, and the other abbrev tables that are named after major modes +contain the mode-specific abbrevs. + + Within each abbrev table, each non-blank line defines one abbrev. The +word at the beginning is the abbrev. The number that appears is the number +of times the abbrev has been expanded. Emacs keeps track of this to help +you see which abbrevs you actually use, in case you want to eliminate +those that you don't use often. The string at the end of the line is the +expansion. + +@findex edit-abbrevs +@kindex C-c C-c (Edit Abbrevs) +@findex edit-abbrevs-redefine + @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev +definitions by editing a list of them in an Emacs buffer. The list has +the format described above. The buffer of abbrevs is called +@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. This mode redefines the +key @kbd{C-c C-c} to install the abbrev definitions as specified in the +buffer. The @code{edit-abbrevs-redefine} command does this. +Any abbrevs not described in the buffer are eliminated when this is +done. + + @code{edit-abbrevs} is actually the same as @code{list-abbrevs}, except +that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs} +merely displays it in another window. + +@node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs +@section Saving Abbrevs + + These commands allow you to keep abbrev definitions between editing +sessions. + +@table @kbd +@item M-x write-abbrev-file +Write a file describing all defined abbrevs. +@item M-x read-abbrev-file +Read such an abbrev file and define abbrevs as specified there. +@item M-x quietly-read-abbrev-file +Similar, but do not display a message about what is going on. +@item M-x define-abbrevs +Define abbrevs from buffer. +@item M-x insert-abbrevs +Insert all abbrevs and their expansions into the buffer. +@end table + +@findex write-abbrev-file + Use @kbd{M-x write-abbrev-file} to save abbrev definitions for use in +a later session. The command reads a file name using the minibuffer and +writes a description of all current abbrev definitions into the +specified file. The text stored in the file looks like the output of +@kbd{M-x list-abbrevs}. + + +@findex read-abbrev-file +@findex quietly-read-abbrev-file +@vindex abbrev-file-name + @kbd{M-x read-abbrev-file} prompts for a file name using the +minibuffer and reads the specified file, defining abbrevs according to +its contents. @kbd{M-x quietly-read-abbrev-file} is the same but does +not display a message in the echo area; it is actually useful primarily +in the @file{.emacs} file. If you give an empty argument to either of +these functions, the file name Emacs uses is the value of the variable +@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. + +@vindex save-abbrevs + Emacs offers to save abbrevs automatically if you have changed any of +them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x +C-c}). Set the variable @code{save-abbrevs} to @code{nil} to inhibit +this feature. + +@findex insert-abbrevs +@findex define-abbrevs + The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are +similar to the previous commands but work on text in an Emacs buffer. +@kbd{M-x insert-abbrevs} inserts text into the current buffer before point, +describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses +the entire current buffer and defines abbrevs accordingly.@refill + +@node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs +@section Dynamic Abbrev Expansion + + The abbrev facility described above operates automatically as you insert +text, but all abbrevs must be defined explicitly. By contrast, +@dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined +automatically from the contents of the buffer, but dynamic abbrev expansion +happens only when you request it explicitly. + +@kindex M-/ +@findex dabbrev-expand +@table @kbd +@item M-/ +Expand the word in the buffer before point as a @dfn{dynamic abbrev}, +by searching in the buffer for words starting with that abbreviation +(@code{dabbrev-expand}). +@end table + + For example, if the buffer contains @samp{does this follow } and you type +@kbd{f o M-/}, the effect is to insert @samp{follow} because that is the +last word in the buffer that starts with @samp{fo}. A numeric argument to +@kbd{M-/} says to take the second, third, etc.@: distinct expansion found +looking backward from point. Repeating @kbd{M-/} searches for an +alternative expansion by looking farther back. After the entire buffer +before point has been considered, the buffer after point is searched. + + Dynamic abbrev expansion is completely independent of Abbrev mode; the +expansion of a word with @kbd{M-/} is completely independent of whether it +has a definition as an ordinary abbrev.