[Emacs-diffs] emacs/doc/lispref ChangeLog abbrevs.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/05/13 01:26:47

Modified files:
        doc/lispref    : ChangeLog abbrevs.texi 

Log message:
        * 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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.273&r2=1.274
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/abbrevs.texi?cvsroot=emacs&r1=1.7&r2=1.8

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.273
retrieving revision 1.274
diff -u -b -r1.273 -r1.274
--- ChangeLog   12 May 2009 03:31:58 -0000      1.273
+++ ChangeLog   13 May 2009 01:26:47 -0000      1.274
@@ -1,3 +1,12 @@
+2009-05-13  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * frames.texi (Font and Color Parameters): Rename from Color

Index: abbrevs.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/abbrevs.texi,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- abbrevs.texi        25 Jan 2009 12:10:53 -0000      1.7
+++ abbrevs.texi        13 May 2009 01:26:47 -0000      1.8
@@ -19,20 +19,27 @@
 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}).
+  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}).
+
address@hidden 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
address@hidden @code{:system} property (@pxref{Abbrev Properties}).
+When abbrevs are saved to an abbrev file, system abbrevs are omitted.
address@hidden Files}.
 
-Because the symbols used for abbrevs are not interned in the usual
+  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 @@
 @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 address@hidden 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 address@hidden, 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 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.
address@hidden is a property list that is applied to the new table
 (@pxref{Abbrev Table Properties}).
 @end defun
 
address@hidden abbrev-table-p table
-Return address@hidden is @var{table} is an abbrev table.
address@hidden abbrev-table-p object
+This function returns a address@hidden value if @var{object} is an
+abbrev table.
 @end defun
 
address@hidden clear-abbrev-table table
-This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty.  It always returns @code{nil}.
address@hidden 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
 
address@hidden 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.
address@hidden 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 @@
 @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.
-
address@hidden 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
address@hidden (@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
address@hidden is normally the desired expansion (a string), or
address@hidden to undefine the abbrev.  If it is anything but a string or
address@hidden, then the abbreviation ``expands'' solely by running
address@hidden
+abbrev in an abbrev table.
+
+  When a major mode defines a system abbrev, it should call
address@hidden 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.
+
address@hidden define-abbrev abbrev-table name expansion &optional hook &rest 
props
+This function defines an abbrev named @var{name}, in
address@hidden, 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.
+
address@hidden 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
 address@hidden, then it is called with no arguments after the abbrev is
@@ -177,11 +186,10 @@
 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 @@
 
 @defvar abbrevs-changed
 This variable is set address@hidden 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 @@
 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 @@
 returns @code{nil} even though expansion did occur.
 @end deffn
 
address@hidden 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 address@hidden, 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.
address@hidden 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 @@
 
 @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 @@
 
 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 @@
 @code{define-abbrev}.
 
 @item :system
-If address@hidden, this property marks the abbrev as a ``system''
-abbrev.  Such abbrevs will not be saved to @var{abbrev-file-name}.
+If address@hidden, this property marks the abbrev as a system abbrev.
+Such abbrevs are not saved (@pxref{Abbrev Files}).
 
 @item :enable-function
 If address@hidden, this property should be a function of no