* abbrevs.texi (Abbrevs): Add xref to Creating Symbols when

obarrays are first mentioned.  Define "system abbrev" more
prominently, and add it to the index.
(Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties):
Copyedits.
(Abbrev Expansion): Document abbrev-insert.

2 files changed, 100 insertions, 73 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f07f4ca1cd0..a1dd728e655 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2009-05-13  Chong Yidong  <cyd@stupidchicken.com>
+
+        * abbrevs.texi (Abbrevs): Add xref to Creating Symbols when
+        obarrays are first mentioned.  Define "system abbrev" more
+        prominently, and add it to the index.
+        (Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties):
+        Copyedits.
+        (Abbrev Expansion): Document abbrev-insert.
+
 2009-05-12  Chong Yidong  <cyd@stupidchicken.com>
 
         * frames.texi (Font and Color Parameters): Rename from Color
diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi
index b6544567680..c1eb562d56b 100644
--- a/doc/lispref/abbrevs.texi
+++ b/doc/lispref/abbrevs.texi
@@ -19,20 +19,27 @@ table}.  Each buffer has a local abbrev table, but normally all buffers
 in the same major mode share one abbrev table.  There is also a global
 abbrev table.  Normally both are used.
 
-  An abbrev table is represented as an obarray containing a symbol for
-each abbreviation.  The symbol's name is the abbreviation; its value
-is the expansion; its function definition is the hook function to do
-the expansion (@pxref{Defining Abbrevs}); its property list cell
-typically contains various additional properties such as the use
-count, the number of times the abbreviation has been expanded, or
-whether the abbrev is a so-called ``system'' abbrev defined by a major
-mode rather than by the user (@pxref{Abbrev Properties}).
-
-Because the symbols used for abbrevs are not interned in the usual
+  An abbrev table is represented as an obarray.  @xref{Creating
+Symbols}, for information about obarrays.  Each abbreviation is
+represented by a symbol in the obarray.  The symbol's name is the
+abbreviation; its value is the expansion; its function definition is
+the hook function for performing the expansion (@pxref{Defining
+Abbrevs}); and its property list cell contains various additional
+properties, including the use count and the number of times the
+abbreviation has been expanded (@pxref{Abbrev Properties}).
+
+@cindex system abbrev
+  Certain abbrevs, called @dfn{system abbrevs}, are defined by a major
+mode instead of the user.  A system abbrev is identified by its
+non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}).
+When abbrevs are saved to an abbrev file, system abbrevs are omitted.
+@xref{Abbrev Files}.
+
+  Because the symbols used for abbrevs are not interned in the usual
 obarray, they will never appear as the result of reading a Lisp
 expression; in fact, normally they are never used except by the code
 that handles abbrevs.  Therefore, it is safe to use them in an
-extremely nonstandard way.  @xref{Creating Symbols}.
+extremely nonstandard way.
 
   For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
 Mode, emacs, The GNU Emacs Manual}.
@@ -54,21 +61,20 @@ Mode, emacs, The GNU Emacs Manual}.
 @comment  node-name,  next,  previous,  up
 @section Setting Up Abbrev Mode
 
-  Abbrev mode is a minor mode controlled by the value of the variable
+  Abbrev mode is a minor mode controlled by the variable
 @code{abbrev-mode}.
 
 @defvar abbrev-mode
-A non-@code{nil} value of this variable turns on the automatic expansion
-of abbrevs when their abbreviations are inserted into a buffer.
-If the value is @code{nil}, abbrevs may be defined, but they are not
-expanded automatically.
+If this variable is non-@code{nil}, abbrevs are automatically expanded
+in the buffer.  If the value is @code{nil}, abbrevs may be defined,
+but they are not expanded automatically.
 
 This variable automatically becomes buffer-local when set in any fashion.
 @end defvar
 
 @defvar default-abbrev-mode
-This is the value of @code{abbrev-mode} for buffers that do not override it.
-This is the same as @code{(default-value 'abbrev-mode)}.
+This is the value of @code{abbrev-mode} for buffers that do not
+override it.  It is the same as @code{(default-value 'abbrev-mode)}.
 @end defvar
 
 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
@@ -77,26 +83,27 @@ This is the same as @code{(default-value 'abbrev-mode)}.
   This section describes how to create and manipulate abbrev tables.
 
 @defun make-abbrev-table &rest props
-This function creates and returns a new, empty abbrev table---an obarray
-containing no symbols.  It is a vector filled with zeros.  @var{props}
-is a property list that is applied to the new table
+This function creates and returns a new, empty abbrev table---an
+obarray containing no symbols.  It is a vector filled with zeros.
+@var{props} is a property list that is applied to the new table
 (@pxref{Abbrev Table Properties}).
 @end defun
 
-@defun abbrev-table-p table
-Return non-@code{nil} is @var{table} is an abbrev table.
+@defun abbrev-table-p object
+This function returns a non-@code{nil} value if @var{object} is an
+abbrev table.
 @end defun
 
-@defun clear-abbrev-table table
-This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty.  It always returns @code{nil}.
+@defun clear-abbrev-table abbrev-table
+This function undefines all the abbrevs in @var{abbrev-table}, leaving
+it empty.  It always returns @code{nil}.
 @end defun
 
-@defun copy-abbrev-table table
-This function returns a copy of abbrev table @var{table}---a new
-abbrev table that contains the same abbrev definitions.  The only
-difference between @var{table} and the returned copy is that this
-function sets the property lists of all copied abbrevs to 0.
+@defun copy-abbrev-table abbrev-table
+This function returns a copy of @var{abbrev-table}---a new abbrev
+table containing the same abbrev definitions.  There is one difference
+between the contents of @var{abbrev-table} and the returned copy: all
+abbrevs in the latter have their property lists set to @code{nil}.
 @end defun
 
 @defun define-abbrev-table tabname definitions &optional docstring &rest props
@@ -140,28 +147,30 @@ to add these to @var{name} separately.)
 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
 @comment  node-name,  next,  previous,  up
 @section Defining Abbrevs
+
   @code{define-abbrev} is the low-level basic function for defining an
-abbrev in a specified abbrev table.  When major modes predefine standard
-abbrevs, they should call @code{define-abbrev} and specify a @code{t} for
-the @code{:system} property.
-Be aware that any saved non-``system'' abbrevs are 
-restored at startup, i.e. before some major modes are loaded.  Major modes
-should therefore not assume that when they are first loaded their abbrev
-tables are empty.
-
-@defun define-abbrev table name expansion &optional hook &rest props
-This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}, with properties
-@var{props} (@pxref{Abbrev Properties}).  The return value is @var{name}.
-The @code{:system} property in @var{props} is treated specially here:
-if it has the value @code{force}, then it will overwrite an existing
-definition even for a non-``system'' abbrev of the same name.
-
-The argument @var{name} should be a string.  The argument
-@var{expansion} is normally the desired expansion (a string), or
-@code{nil} to undefine the abbrev.  If it is anything but a string or
-@code{nil}, then the abbreviation ``expands'' solely by running
-@var{hook}.
+abbrev in an abbrev table.
+
+  When a major mode defines a system abbrev, it should call
+@code{define-abbrev} and specify a @code{t} for the @code{:system}
+property.  Be aware that any saved non-``system'' abbrevs are restored
+at startup, i.e. before some major modes are loaded.  Therefore, major
+modes should not assume that their abbrev tables are empty when they
+are first loaded.
+
+@defun define-abbrev abbrev-table name expansion &optional hook &rest props
+This function defines an abbrev named @var{name}, in
+@var{abbrev-table}, to expand to @var{expansion} and call @var{hook},
+with properties @var{props} (@pxref{Abbrev Properties}).  The return
+value is @var{name}.  The @code{:system} property in @var{props} is
+treated specially here: if it has the value @code{force}, then it will
+overwrite an existing definition even for a non-``system'' abbrev of
+the same name.
+
+@var{name} should be a string.  The argument @var{expansion} is
+normally the desired expansion (a string), or @code{nil} to undefine
+the abbrev.  If it is anything but a string or @code{nil}, then the
+abbreviation ``expands'' solely by running @var{hook}.
 
 The argument @var{hook} is a function or @code{nil}.  If @var{hook} is
 non-@code{nil}, then it is called with no arguments after the abbrev is
@@ -177,11 +186,10 @@ inhibits insertion of the character.  By contrast, if @var{hook}
 returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
 if expansion had not really occurred.
 
-Normally the function @code{define-abbrev} sets the variable
+Normally, @code{define-abbrev} sets the variable
 @code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
 (This is so that some commands will offer to save the abbrevs.)  It
-does not do this for a ``system'' abbrev, since those won't be saved
-anyway.
+does not do this for a system abbrev, since those aren't saved anyway.
 @end defun
 
 @defopt only-global-abbrevs
@@ -229,12 +237,12 @@ offer the user to save abbrevs when files are saved.  If the value is
 
 @defvar abbrevs-changed
 This variable is set non-@code{nil} by defining or altering any
-abbrevs (except ``system'' abbrevs).  This serves as a flag for
-various Emacs commands to offer to save your abbrevs.
+abbrevs (except system abbrevs).  This serves as a flag for various
+Emacs commands to offer to save your abbrevs.
 @end defvar
 
 @deffn Command write-abbrev-file &optional filename
-Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
+Save all abbrev definitions (except system abbrevs), for all abbrev
 tables listed in @code{abbrev-table-name-list}, in the file
 @var{filename}, in the form of a Lisp program that when loaded will
 define the same abbrevs.  If @var{filename} is @code{nil} or omitted,
@@ -254,9 +262,9 @@ use for communication.
 This function returns the symbol representing the abbrev named
 @var{abbrev}.  The value returned is @code{nil} if that abbrev is not
 defined.  The optional second argument @var{table} is the abbrev table
-to look it up in.  If @var{table} is @code{nil}, this function tries
-first the current buffer's local abbrev table, and second the global
-abbrev table.
+in which to look it up.  If @var{table} is @code{nil}, this function
+tries first the current buffer's local abbrev table, and second the
+global abbrev table.
 @end defun
 
 @defun abbrev-expansion abbrev &optional table
@@ -278,6 +286,16 @@ function returns @code{nil} as its value, then @code{expand-abbrev}
 returns @code{nil} even though expansion did occur.
 @end deffn
 
+@deffn abbrev-insert abbrev &optional name start end
+This function inserts the abbrev expansion of @code{abbrev}, replacing
+the text between @code{start} and @code{end}.  If @code{start} is
+omitted, it defaults to point.  @code{name}, if non-@code{nil}, should
+be the name by which this abbrev was found (a string); it is used to
+figure out whether to adjust the capitalization of the expansion.  The
+function returns @code{abbrev} if the abbrev was successfully
+inserted.
+@end deffn
+
 @deffn Command abbrev-prefix-mark &optional arg
 This command marks the current location of point as the beginning of
 an abbrev.  The next call to @code{expand-abbrev} will use the text
@@ -335,11 +353,11 @@ has already been unexpanded.  This contains information left by
 
 @defvar abbrev-expand-functions
 This is a special hook run @emph{around} the @code{expand-abbrev}
-function.  Functions on this hook are called with a single argument
-which is a function that performs the normal abbrev expansion.
-The hook function can hence do anything it wants before and after
-performing the expansion.  It can also choose not to call its argument
-and thus override the default behavior, or it may even call it
+function.  Each function on this hook is called with a single
+argument: a function that performs the normal abbrev expansion.  The
+hook function can hence do anything it wants before and after
+performing the expansion.  It can also choose not to call its
+argument, thus overriding the default behavior; or it may even call it
 several times.  The function should return the abbrev symbol if
 expansion took place.
 @end defvar
@@ -415,18 +433,18 @@ This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
 
 Abbrevs have properties, some of which influence the way they work.
 You can provide them as arguments to @code{define-abbrev} and you can
-manipulate them with the functions:
+manipulate them with the following functions:
 
 @defun abbrev-put abbrev prop val
-Set the property @var{prop} of abbrev @var{abbrev} to value @var{val}.
+Set the property @var{prop} of @var{abbrev} to value @var{val}.
 @end defun
 
 @defun abbrev-get abbrev prop
-Return the property @var{prop} of abbrev @var{abbrev}, or @code{nil}
-if the abbrev has no such property.
+Return the property @var{prop} of @var{abbrev}, or @code{nil} if the
+abbrev has no such property.
 @end defun
 
-The following properties have special meaning:
+The following properties have special meanings:
 
 @table @code
 @item :count
@@ -435,8 +453,8 @@ been expanded.  If not explicitly set, it is initialized to 0 by
 @code{define-abbrev}.
 
 @item :system
-If non-@code{nil}, this property marks the abbrev as a ``system''
-abbrev.  Such abbrevs will not be saved to @var{abbrev-file-name}.
+If non-@code{nil}, this property marks the abbrev as a system abbrev.
+Such abbrevs are not saved (@pxref{Abbrev Files}).
 
 @item :enable-function
 If non-@code{nil}, this property should be a function of no