--- /dev/null
+
+@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.
projects / chise / xemacs-chise.git.1 / blobdiff