[Emacs-diffs] /srv/bzr/emacs/trunk r107494: Checked lispref/abbrevs.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107494
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-03-03 18:45:04 -0800
message:
  Checked lispref/abbrevs.texi
  
  * doc/lispref/abbrevs.texi: Small copyedits throughout.
  (Abbrev Mode): Remove this section, folding it into the top-level.
  (Abbrev Tables): Don't mention irrelevant return values.
  (Abbrev Expansion): Add cross-ref for wrapper hooks.
  (Standard Abbrev Tables): Emacs Lisp mode now has its own table.
  (Abbrev Table Properties): Update nil :regexp description.
  
  * lisp/abbrev.el (copy-abbrev-table, abbrev-table-p)
  (abbrev-minor-mode-table-alist, define-abbrev, abbrev-insert)
  (expand-abbrev, define-abbrev-table): Doc fixes.
  
  * admin/FOR-RELEASE: Related markup.
modified:
  admin/FOR-RELEASE
  doc/emacs/abbrevs.texi
  doc/lispref/ChangeLog
  doc/lispref/abbrevs.texi
  doc/lispref/elisp.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  lisp/ChangeLog
  lisp/abbrev.el

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-03-03 22:13:28 +0000
+++ b/admin/FOR-RELEASE 2012-03-04 02:45:04 +0000
@@ -180,7 +180,7 @@
 
 ** Check the Lisp manual.
 
-abbrevs.texi      
+abbrevs.texi      rgm
 advice.texi       cyd
 anti.texi         
 back.texi

=== modified file 'doc/emacs/abbrevs.texi'
--- a/doc/emacs/abbrevs.texi    2012-01-19 07:21:25 +0000
+++ b/doc/emacs/abbrevs.texi    2012-03-04 02:45:04 +0000
@@ -60,7 +60,8 @@
 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 the editing session.  You
+  You can define abbrevs interactively during the editing session,
+irrespective of whether Abbrev mode is enabled.  You
 can also save lists of abbrev definitions in files for use in later
 sessions.  Some users keep extensive lists of abbrevs that they load
 in every session.

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-03 22:13:28 +0000
+++ b/doc/lispref/ChangeLog     2012-03-04 02:45:04 +0000
@@ -1,3 +1,12 @@
+2012-03-04  Glenn Morris  <address@hidden>
+
+       * abbrevs.texi: Small copyedits throughout.
+       (Abbrev Mode): Remove this section, folding it into the top-level.
+       (Abbrev Tables): Don't mention irrelevant return values.
+       (Abbrev Expansion): Add cross-ref for wrapper hooks.
+       (Standard Abbrev Tables): Emacs Lisp mode now has its own table.
+       (Abbrev Table Properties): Update nil :regexp description.
+
 2012-03-03  Glenn Morris  <address@hidden>
 
        * internals.texi: Change @appendix section commands to @section.

=== modified file 'doc/lispref/abbrevs.texi'
--- a/doc/lispref/abbrevs.texi  2012-01-19 07:21:25 +0000
+++ b/doc/lispref/abbrevs.texi  2012-03-04 02:45:04 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990-1994, 1999, 2001-2012  Free Software 
Foundation, Inc.
address@hidden Copyright (C) 1990-1994, 1999, 2001-2012 Free Software 
Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/abbrevs
 @node Abbrevs, Processes, Syntax Tables, Top
@@ -37,14 +37,15 @@
   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.
+that handles abbrevs.  Therefore, it is safe to use them in a
+nonstandard way.
 
-  For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
-Mode, emacs, The GNU Emacs Manual}.
+  If the minor mode Abbrev mode is enabled, the buffer-local variable
address@hidden is address@hidden, and abbrevs are automatically
+expanded in the buffer.  For the user-level commands for abbrevs, see
address@hidden,, Abbrev Mode, emacs, The GNU Emacs Manual}.
 
 @menu
-* Abbrev Mode::                 Setting up Emacs for abbreviation.
 * Tables: Abbrev Tables.        Creating and working with abbrev tables.
 * Defining Abbrevs::            Specifying abbreviations and their expansions.
 * Files: Abbrev Files.          Saving abbrevs in files.
@@ -56,22 +57,7 @@
                                 Which properties have which effect.
 @end menu
 
address@hidden Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
address@hidden  node-name,  next,  previous,  up
address@hidden Setting Up Abbrev Mode
-
-  Abbrev mode is a minor mode controlled by the variable
address@hidden
-
address@hidden abbrev-mode
-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.
address@hidden defopt
-
address@hidden Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
address@hidden Abbrev Tables, Defining Abbrevs, Abbrevs, Abbrevs
 @section Abbrev Tables
 
   This section describes how to create and manipulate abbrev tables.
@@ -90,14 +76,15 @@
 
 @defun clear-abbrev-table abbrev-table
 This function undefines all the abbrevs in @var{abbrev-table}, leaving
-it empty.  It always returns @code{nil}.
+it empty.
address@hidden Don't see why this needs saying.
address@hidden It always returns @code{nil}.
 @end defun
 
 @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}.
+table containing the same abbrev definitions.  It does @emph{not} copy
+any property lists; only the names, values, and functions.
 @end defun
 
 @defun define-abbrev-table tabname definitions &optional docstring &rest props
@@ -106,8 +93,7 @@
 abbrevs in the table according to @var{definitions}, a list of
 elements of the form @code{(@var{abbrevname} @var{expansion}
 address@hidden address@hidden)}.  These elements are passed as
-arguments to @code{define-abbrev}.  The return value is always
address@hidden
+arguments to @code{define-abbrev}.  @c The return value is always @code{nil}.
 
 The optional string @var{docstring} is the documentation string of the
 variable @var{tabname}.  The property list @var{props} is applied to
@@ -115,7 +101,7 @@
 
 If this function is called more than once for the same @var{tabname},
 subsequent calls add the definitions in @var{definitions} to
address@hidden, rather than overriding the entire original contents.
address@hidden, rather than overwriting the entire original contents.
 (A subsequent call only overrides abbrevs explicitly redefined or
 undefined in @var{definitions}.)
 @end defun
@@ -128,7 +114,7 @@
 @defun insert-abbrev-table-description name &optional human
 This function inserts before point a description of the abbrev table
 named @var{name}.  The argument @var{name} is a symbol whose value is an
-abbrev table.  The return value is always @code{nil}.
+abbrev table.  @c The return value is always @code{nil}.
 
 If @var{human} is address@hidden, the description is human-oriented.
 System abbrevs are listed and identified as such.  Otherwise the
@@ -146,7 +132,7 @@
 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}
address@hidden and specify @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
@@ -177,12 +163,12 @@
 to insert the self-inserting input character that triggered the
 expansion.  If @var{hook} returns address@hidden in this case, that
 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.
+returns @code{nil}, @code{expand-abbrev} (or @code{abbrev-insert})
+also returns @code{nil}, as if expansion had not really occurred.
 
 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
+This is so that some commands will offer to save the abbrevs.  It
 does not do this for a system abbrev, since those aren't saved anyway.
 @end defun
 
@@ -202,7 +188,8 @@
 abbrev tables with the same contents.  Therefore, you can load the file
 with @code{load} (@pxref{How Programs Do Loading}).  However, the
 function @code{quietly-read-abbrev-file} is provided as a more
-convenient interface.
+convenient interface.  Emacs automatically calls this function at
+startup.
 
   User-level facilities such as @code{save-some-buffers} can save
 abbrevs in a file automatically, under the control of variables
@@ -216,17 +203,18 @@
 This function reads abbrev definitions from a file named @var{filename},
 previously written with @code{write-abbrev-file}.  If @var{filename} is
 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
-used.  @code{save-abbrevs} is set to @code{t} so that changes will be
-saved.
+used.
 
-This function does not display any messages.  It returns @code{nil}.
+As the name implies, this function does not display any messages.
address@hidden It returns @code{nil}.
 @end defun
 
 @defopt save-abbrevs
 A address@hidden value for @code{save-abbrevs} means that Emacs should
-offer the user to save abbrevs when files are saved.  If the value is
address@hidden, Emacs saves the abbrevs without asking the user.
address@hidden specifies the file to save the abbrevs in.
+offer to save abbrevs (if any have changed) when files are saved.  If
+the value is @code{silently}, Emacs saves the abbrevs without asking
+the user.  @code{abbrev-file-name} specifies the file to save the
+abbrevs in.
 @end defopt
 
 @defvar abbrevs-changed
@@ -254,7 +242,7 @@
 
 @defun abbrev-symbol abbrev &optional table
 This function returns the symbol representing the abbrev named
address@hidden  The value returned is @code{nil} if that abbrev is not
address@hidden  It returns @code{nil} if that abbrev is not
 defined.  The optional second argument @var{table} is the 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
@@ -263,8 +251,8 @@
 
 @defun abbrev-expansion abbrev &optional table
 This function returns the string that @var{abbrev} would expand into (as
-defined by the abbrev tables used for the current buffer).  If
address@hidden is not a valid abbrev, the function returns @code{nil}.
+defined by the abbrev tables used for the current buffer).  It returns
address@hidden if @var{abbrev} is not a valid abbrev.
 The optional argument @var{table} specifies the abbrev table to use,
 as in @code{abbrev-symbol}.
 @end defun
@@ -274,7 +262,7 @@
 follow an abbrev, this command does nothing.  The command returns the
 abbrev symbol if it did expansion, @code{nil} otherwise.
 
-If the abbrev symbol has a hook function which is a symbol whose
+If the abbrev symbol has a hook function that is a symbol whose
 @code{no-self-insert} property is address@hidden, and if the hook
 function returns @code{nil} as its value, then @code{expand-abbrev}
 returns @code{nil} even though expansion did occur.
@@ -346,14 +334,14 @@
 @end defvar
 
 @defvar abbrev-expand-functions
-This is a special hook run @emph{around} the @code{expand-abbrev}
-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.
+This is a wrapper hook (@pxref{Running Hooks}) run around the
address@hidden 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
 
   The following sample code shows a simple use of
@@ -361,8 +349,7 @@
 mode for editing certain files in which lines that start with @samp{#}
 are comments.  You want to use Text mode abbrevs for those lines.  The
 regular local abbrev table, @code{foo-mode-abbrev-table} is
-appropriate for all other lines.  Then you can put the following code
-in your @file{.emacs} file.  @xref{Standard Abbrev Tables}, for the
+appropriate for all other lines.  @xref{Standard Abbrev Tables}, for the
 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
 
 @smallexample
@@ -419,14 +406,16 @@
 @end defvar
 
 @defvar lisp-mode-abbrev-table
-This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
+This is the local abbrev table used in Lisp mode.  It is the parent
+of the local abbrev table used in Emacs Lisp mode.  @xref{Abbrev Table
+Properties}.
 @end defvar
 
 @node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, 
Abbrevs
 @section Abbrev Properties
 
 Abbrevs have properties, some of which influence the way they work.
-You can provide them as arguments to @code{define-abbrev} and you can
+You can provide them as arguments to @code{define-abbrev}, and
 manipulate them with the following functions:
 
 @defun abbrev-put abbrev prop val
@@ -467,8 +456,7 @@
 
 Like abbrevs, abbrev tables have properties, some of which influence
 the way they work.  You can provide them as arguments to
address@hidden and you can manipulate them with the
-functions:
address@hidden, and manipulate them with the functions:
 
 @defun abbrev-table-put table prop val
 Set the property @var{prop} of abbrev table @var{table} to value @var{val}.
@@ -484,8 +472,8 @@
 @table @code
 @item :enable-function
 This is like the @code{:enable-function} abbrev property except that
-it applies to all abbrevs in the table and is used even before trying
-to find the abbrev before point so it can dynamically modify the
+it applies to all abbrevs in the table.  It is used before even trying
+to find the abbrev before point, so it can dynamically modify the
 abbrev table.
 
 @item :case-fixed
@@ -494,15 +482,16 @@
 
 @item :regexp
 If address@hidden, this property is a regular expression that
-indicates how to extract the name of the abbrev before point before
+indicates how to extract the name of the abbrev before point, before
 looking it up in the table.  When the regular expression matches
 before point, the abbrev name is expected to be in submatch 1.
-If this property is @code{nil}, @code{expand-function} defaults to
address@hidden"\\<\\(\\w+\\)\\W"}.  This property allows the use of abbrevs
-whose name contains characters of non-word syntax.
+If this property is @code{nil}, the default is to use
address@hidden and @code{forward-word} to find the name.  This
+property allows the use of abbrevs whose name contains characters of
+non-word syntax.
 
 @item :parents
-This property holds the list of tables from which to inherit
+This property holds a list of tables from which to inherit
 other abbrevs.
 
 @item :abbrev-table-modiff

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-03-02 02:54:47 +0000
+++ b/doc/lispref/elisp.texi    2012-03-04 02:45:04 +0000
@@ -1186,7 +1186,6 @@
 
 Abbrevs and Abbrev Expansion
 
-* Abbrev Mode::             Setting up Emacs for abbreviation.
 * Abbrev Tables::           Creating and working with abbrev tables.
 * Defining Abbrevs::        Specifying abbreviations and their expansions.
 * Abbrev Files::            Saving abbrevs in files.

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-03-02 02:54:47 +0000
+++ b/doc/lispref/vol1.texi     2012-03-04 02:45:04 +0000
@@ -1208,7 +1208,6 @@
 
 Abbrevs and Abbrev Expansion
 
-* Abbrev Mode::             Setting up Emacs for abbreviation.
 * Abbrev Tables::           Creating and working with abbrev tables.
 * Defining Abbrevs::        Specifying abbreviations and their expansions.
 * Abbrev Files::            Saving abbrevs in files.

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-03-02 02:54:47 +0000
+++ b/doc/lispref/vol2.texi     2012-03-04 02:45:04 +0000
@@ -1207,7 +1207,6 @@
 
 Abbrevs and Abbrev Expansion
 
-* Abbrev Mode::             Setting up Emacs for abbreviation.
 * Abbrev Tables::           Creating and working with abbrev tables.
 * Defining Abbrevs::        Specifying abbreviations and their expansions.
 * Abbrev Files::            Saving abbrevs in files.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-03-04 00:15:34 +0000
+++ b/lisp/ChangeLog    2012-03-04 02:45:04 +0000
@@ -1,3 +1,9 @@
+2012-03-04  Glenn Morris  <address@hidden>
+
+       * abbrev.el (copy-abbrev-table, abbrev-table-p)
+       (abbrev-minor-mode-table-alist, define-abbrev, abbrev-insert)
+       (expand-abbrev, define-abbrev-table): Doc fixes.
+
 2012-03-03  Lars Magne Ingebrigtsen  <address@hidden>
 
        * mail/emacsbug.el (report-emacs-bug-hook): Look at the value of

=== modified file 'lisp/abbrev.el'
--- a/lisp/abbrev.el    2012-02-29 15:05:42 +0000
+++ b/lisp/abbrev.el    2012-03-04 02:45:04 +0000
@@ -1,6 +1,6 @@
 ;;; abbrev.el --- abbrev mode commands for Emacs -*- lexical-binding: t -*-
 
-;; Copyright (C) 1985-1987, 1992, 2001-2012  Free Software Foundation, Inc.
+;; Copyright (C) 1985-1987, 1992, 2001-2012 Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
 ;; Keywords: abbrev convenience
@@ -81,7 +81,8 @@
     (clear-abbrev-table (symbol-value tablesym))))
 
 (defun copy-abbrev-table (table)
-  "Make a new abbrev-table with the same abbrevs as TABLE."
+  "Make a new abbrev-table with the same abbrevs as TABLE.
+Does not copy property lists."
   (let ((new-table (make-abbrev-table)))
     (mapatoms
      (lambda (symbol)
@@ -447,6 +448,7 @@
     table))
 
 (defun abbrev-table-p (object)
+  "Return non-nil if OBJECT is an abbrev table."
   (and (vectorp object)
        (numberp (abbrev-table-get object :abbrev-table-modiff))))
 
@@ -472,7 +474,8 @@
 (defvar abbrev-minor-mode-table-alist nil
   "Alist of abbrev tables to use for minor modes.
 Each element looks like (VARIABLE . ABBREV-TABLE);
-ABBREV-TABLE is active whenever VARIABLE's value is non-nil.")
+ABBREV-TABLE is active whenever VARIABLE's value is non-nil.
+ABBREV-TABLE can also be a list of abbrev tables.")
 
 (defvar fundamental-mode-abbrev-table
   (let ((table (make-abbrev-table)))
@@ -548,6 +551,12 @@
  special one, which does not expand in the usual way but only
  runs HOOK.
 
+If HOOK is a non-nil symbol with a non-nil `no-self-insert' property,
+it can control whether the character that triggered abbrev expansion
+is inserted.  If such a HOOK returns non-nil, the character is not
+inserted.  If such a HOOK returns nil, then so does `abbrev-insert'
+\(and `expand-abbrev'), as if no abbrev expansion had taken place.
+
 PROPS is a property list.  The following properties are special:
 - `:count': the value for the abbrev's usage-count, which is incremented each
   time the abbrev is used (the default is zero).
@@ -746,7 +755,9 @@
 If non-nil, WORDSTART is the place where to insert the abbrev.
 If WORDEND is non-nil, the abbrev replaces the previous text between
 WORDSTART and WORDEND.
-Return ABBREV if the expansion should be considered as having taken place."
+Return ABBREV if the expansion should be considered as having taken place.
+The return value can be influenced by a `no-self-insert' property;
+see `define-abbrev' for details."
   (unless name (setq name (symbol-name abbrev)))
   (unless wordstart (setq wordstart (point)))
   (unless wordend (setq wordend wordstart))
@@ -811,7 +822,8 @@
 (defun expand-abbrev ()
   "Expand the abbrev before point, if there is an abbrev there.
 Effective when explicitly called even when `abbrev-mode' is nil.
-Returns the abbrev symbol, if expansion took place."
+Returns the abbrev symbol, if expansion took place.  (The actual
+return value is that of `abbrev-insert'.)"
   (interactive)
   (run-hooks 'pre-abbrev-expand-hook)
   (with-wrapper-hook abbrev-expand-functions ()
@@ -934,9 +946,11 @@
   abbreviations.
 - `:case-fixed' non-nil means that abbreviations are looked up without
   case-folding, and the expansion is not capitalized/upcased.
-- `:regexp' describes the form of abbrevs.  It defaults to 
\\=\\<\\(\\w+\\)\\W* which
-  means that an abbrev can only be a single word.  The submatch 1 is treated
-  as the potential name of an abbrev.
+- `:regexp' is a regular expression that specifies how to extract the
+  name of the abbrev before point.  The submatch 1 is treated
+  as the potential name of an abbrev.  If :regexp is nil, the default
+  behavior uses `backward-word' and `forward-word' to extract the name
+  of the abbrev, which can therefore only be a single word.
 - `:enable-function' can be set to a function of no argument which returns
   non-nil if and only if the abbrevs in this table should be used for this
   instance of `expand-abbrev'."