Revision: miles@gnu.org--gnu-2005/emacs--unicode--0--patch-61

Merge from emacs--cvs-trunk--0

Patches applied:

 * emacs--cvs-trunk--0  (patch 353-357)

   - Update from CVS

4 files changed, 134 insertions, 60 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 6077deea9bb..6742080bd03 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,32 @@
+2005-06-09  Kim F. Storm  <storm@cua.dk>
+
+        * searching.texi (Entire Match Data): Explain new `reseat' argument to
+        match-data and set-match-data.
+
+2005-06-08  Richard M. Stallman  <rms@gnu.org>
+
+        * searching.texi (Entire Match Data): Clarify when match-data
+        returns markers and when integers.
+
+        * display.texi (Defining Faces): Explain that face name should not
+        end in `-face'.
+
+        * modes.texi (Mode Line Data): Minor cleanup.
+        (Customizing Keywords): Node split out of Search-based Fontification.
+        Add example of using font-lock-add-keywords from a hook.
+        Clarify when MODE should be non-nil, and when nil.
+
+2005-06-06  Richard M. Stallman  <rms@gnu.org>
+
+        * modes.texi (Mode Line Data): Explain what happens when the car
+        of a list is a void symbol.
+        (Search-based Fontification): Explain MODE arg to
+        font-lock-add-keywords and warn about calls from major modes.
+
+2005-06-08  Juri Linkov  <juri@jurta.org>
+
+        * display.texi (Standard Faces): Add `shadow' face.
+
 2005-05-29  Luc Teirlinck  <teirllm@auburn.edu>
 
         * modes.texi (Major Mode Conventions): A derived mode only needs
diff --git a/lispref/display.texi b/lispref/display.texi
index 7b4db373f63..87520fb4d4f 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -1775,6 +1775,11 @@ This face forces use of a particular fixed-width font.
 This face forces use of a particular variable-width font.  It's
 reasonable to customize this to use a different variable-width font, if
 you like, but you should not make it a fixed-width font.
+
+@item shadow
+@kindex shadow @r{(face name)}
+This face is used for making the text less noticeable than the
+surrounding ordinary text.
 @end table
 
 @defvar show-trailing-whitespace
@@ -1790,14 +1795,15 @@ end of a line.
   The way to define a new face is with @code{defface}.  This creates a
 kind of customization item (@pxref{Customization}) which the user can
 customize using the Customization buffer (@pxref{Easy Customization,,,
-emacs, The GNU Emacs Manual}).
+emacs, The GNU Emacs Manual}).  
 
 @defmac defface face spec doc [keyword value]...
-This declares @var{face} as a customizable face that defaults according
-to @var{spec}.  You should not quote the symbol @var{face}.  The
+This declares @var{face} as a customizable face that defaults
+according to @var{spec}.  You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant).  The
 argument @var{doc} specifies the face documentation.  The keywords you
-can use in @code{defface} are the same ones that are meaningful in both
-@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+can use in @code{defface} are the same as in @code{defgroup} and
+@code{defcustom} (@pxref{Common Keywords}).
 
 When @code{defface} executes, it defines the face according to
 @var{spec}, then uses any customizations that were read from the
diff --git a/lispref/modes.texi b/lispref/modes.texi
index f8c1ae82a4e..2366fca5b96 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1650,13 +1650,13 @@ properties specified by @var{props} to the result.  The argument
 @var{value}.  (This feature is new as of Emacs 22.1.)
 
 @item (@var{symbol} @var{then} @var{else})
-A list whose first element is a symbol that is not a keyword specifies a
-conditional.  Its meaning depends on the value of @var{symbol}.  If the
-value is non-@code{nil}, the second element, @var{then}, is processed
-recursively as a mode-line element.  But if the value of @var{symbol} is
-@code{nil}, the third element, @var{else}, is processed recursively.
-You may omit @var{else}; then the mode-line element displays nothing if
-the value of @var{symbol} is @code{nil}.
+A list whose first element is a symbol that is not a keyword specifies
+a conditional.  Its meaning depends on the value of @var{symbol}.  If
+@var{symbol} has a non-@code{nil} value, the second element,
+@var{then}, is processed recursively as a mode-line element.
+Otherwise, the third element, @var{else}, is processed recursively.
+You may omit @var{else}; then the mode-line element displays nothing
+if the value of @var{symbol} is @code{nil} or void.
 
 @item (@var{width} @var{rest}@dots{})
 A list whose first element is an integer specifies truncation or
@@ -2319,6 +2319,7 @@ Search-based fontification happens second.
 @menu
 * Font Lock Basics::            Overview of customizing Font Lock.
 * Search-based Fontification::  Fontification based on regexps.
+* Customizing Keywords::        Customizing search-based fontification.
 * Other Font Lock Variables::   Additional customization facilities.
 * Levels of Font Lock::         Each mode can define alternative levels
                                   so that the user can select more or less.
@@ -2624,19 +2625,27 @@ Non-@code{nil} means that regular expression matching for the sake of
 @code{font-lock-keywords} should be case-insensitive.
 @end defvar
 
-You can use @code{font-lock-add-keywords} to add additional
+@node Customizing Keywords
+@subsection Customizing Search-Based Fontification
+
+  You can use @code{font-lock-add-keywords} to add additional
 search-based fontification rules to a major mode, and
 @code{font-lock-remove-keywords} to removes rules.
 
 @defun font-lock-add-keywords mode keywords &optional append
-This function adds highlighting @var{keywords} for @var{mode}.  The
-argument @var{keywords} should be a list with the same format as the
-variable @code{font-lock-keywords}.  @var{mode} should be a symbol,
-the major mode command name, such as @code{c-mode}.  When Font Lock
-mode is turned on in @var{mode}, it adds @var{keywords} to
-@code{font-lock-keywords}.  @var{mode} can also be @code{nil}; the
-highlighting @var{keywords} are immediately added to
-@code{font-lock-keywords} in the current buffer in that case.
+This function adds highlighting @var{keywords}, for the current buffer
+or for major mode @var{mode}.  The argument @var{keywords} should be a
+list with the same format as the variable @code{font-lock-keywords}.
+
+If @var{mode} is a symbol which is a major mode command name, such as
+@code{c-mode}, the effect is that enabling Font Lock mode in
+@var{mode} will add @var{keywords} to @code{font-lock-keywords}.
+Calling with a non-@code{nil} value of @var{mode} is correct only in
+your @file{~/.emacs} file.
+
+If @var{mode} is @code{nil}, this function adds @var{keywords} to
+@code{font-lock-keywords} in the current buffer.  This way of calling
+@code{font-lock-add-keywords} is usually used in mode hook functions.
 
 By default, @var{keywords} are added at the beginning of
 @code{font-lock-keywords}.  If the optional argument @var{append} is
@@ -2645,7 +2654,29 @@ By default, @var{keywords} are added at the beginning of
 non-@code{nil} value, they are added at the end of
 @code{font-lock-keywords}.
 
-For example:
+Some modes provide specialized support you can use in additional
+highlighting patterns.  See the variables
+@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
+@code{objc-font-lock-extra-types} and
+@code{java-font-lock-extra-types}, for example.
+
+@strong{Warning:} major mode functions must not call
+@code{font-lock-add-keywords} under any circumstances, either directly
+or indirectly, except through their mode hooks.  (Doing so would lead
+to incorrect behavior for some minor modes.)  They should set up their
+rules for search-based fontification by setting
+@code{font-lock-keywords}.
+@end defun
+
+@defun font-lock-remove-keywords mode keywords
+This function removes @var{keywords} from @code{font-lock-keywords}
+for the current buffer or for major mode @var{mode}.  As in
+@code{font-lock-add-keywords}, @var{mode} should be a major mode
+command name or @code{nil}.  All the caveats and requirments for
+@code{font-lock-add-keywords} apply here too.
+@end defun
+
+  For example, this code
 
 @smallexample
 (font-lock-add-keywords 'c-mode
@@ -2653,30 +2684,23 @@ For example:
    ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
 @end smallexample
 
+@noindent
 adds two fontification patterns for C mode: one to fontify the word
 @samp{FIXME}, even in comments, and another to fontify the words
 @samp{and}, @samp{or} and @samp{not} as keywords.
 
-Some modes have specialized support for additional patterns.  See the
-variables @code{c-font-lock-extra-types},
-@code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types}
-and @code{java-font-lock-extra-types}, for example.
-@end defun
-
-@defun font-lock-remove-keywords mode keywords
-This function removes highlighting @var{keywords} for @var{mode}.  As
-in @code{font-lock-add-keywords}, @var{mode} should be a major mode
-command name or @code{nil}.  If @code{nil}, the highlighting
-@var{keywords} are immediately removed in the current buffer.
-@end defun
+@noindent
+That example affects only C mode proper.  To add the same patterns to
+C mode @emph{and} all modes derived from it, do this instead:
 
-@strong{Warning:} Only use a non-@code{nil} @var{mode} argument when
-you use @code{font-lock-add-keywords} or
-@code{font-lock-remove-keywords} in your @file{.emacs} file.  When you
-use these functions from a Lisp program (such as a minor mode), we
-recommend that you use @code{nil} for @var{mode} (and place the call
-on a hook) to avoid subtle problems due to the details of the
-implementation.
+@smallexample
+(add-hook 'c-mode-hook
+ (lambda ()
+  (font-lock-add-keywords nil
+   '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+     ("\\<\\(and\\|or\\|not\\)\\>" .
+      font-lock-keyword-face)))))
+@end smallexample
 
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 1f4a82d3f1f..15037068dd2 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -1485,13 +1485,14 @@ character of the buffer counts as 1.)
   The functions @code{match-data} and @code{set-match-data} read or
 write the entire match data, all at once.
 
-@defun match-data &optional integers reuse
-This function returns a newly constructed list containing all the
-information on what text the last search matched.  Element zero is the
-position of the beginning of the match for the whole expression; element
-one is the position of the end of the match for the expression.  The
-next two elements are the positions of the beginning and end of the
-match for the first subexpression, and so on.  In general, element
+@defun match-data &optional integers reuse reseat
+This function returns a list of positions (markers or integers) that
+record all the information on what text the last search matched.
+Element zero is the position of the beginning of the match for the
+whole expression; element one is the position of the end of the match
+for the expression.  The next two elements are the positions of the
+beginning and end of the match for the first subexpression, and so on.
+In general, element
 @ifnottex
 number 2@var{n}
 @end ifnottex
@@ -1508,15 +1509,13 @@ number {\mathsurround=0pt $2n+1$}
 @end tex
 corresponds to @code{(match-end @var{n})}.
 
-All the elements are markers or @code{nil} if matching was done on a
-buffer and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}.   If @var{integers} is
-non-@code{nil}, then the elements are integers or @code{nil}, even if
-matching was done on a buffer.  In that case, the buffer itself is
-appended as an additional element at the end of the list
-to facilitate complete restoration of the match data.  Also,
-@code{match-beginning} and
-@code{match-end} always return integers or @code{nil}.
+Normally all the elements are markers or @code{nil}, but if
+@var{integers} is non-@code{nil}, that means to use integers instead
+of markers.  (In that case, the buffer itself is appended as an
+additional element at the end of the list, to facilitate complete
+restoration of the match data.)  If the last match was done on a
+string with @code{string-match}, then integers are always used,
+since markers can't point into a string.
 
 If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
 @code{match-data} stores the match data in @var{reuse}.  That is,
@@ -1524,8 +1523,16 @@ If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
 have the right length.  If it is not long enough to contain the match
 data, it is extended.  If it is too long, the length of @var{reuse}
 stays the same, but the elements that were not used are set to
-@code{nil}.  The purpose of this feature is to avoid producing too
-much garbage, that would later have to be collected.
+@code{nil}.  The purpose of this feature is to reduce the need for
+garbage collection.
+
+If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
+are reseated to point to nowhere, and if the value is @code{evaporate},
+the markers are put back on the free list.
+
+@strong{Warning:} When @code{evaporate} is specified for @var{reseat},
+no other references to the markers on the @var{reuse} list; otherwise,
+Emacs may crash during the next garbage collection.
 
 As always, there must be no possibility of intervening searches between
 the call to a search function and the call to @code{match-data} that is
@@ -1542,7 +1549,7 @@ intended to access the match data for that search.
 @end example
 @end defun
 
-@defun set-match-data match-list
+@defun set-match-data match-list &optional reseat
 This function sets the match data from the elements of @var{match-list},
 which should be a list that was the value of a previous call to
 @code{match-data}.  (More precisely, anything that has the same format
@@ -1551,6 +1558,14 @@ will work.)
 If @var{match-list} refers to a buffer that doesn't exist, you don't get
 an error; that sets the match data in a meaningless but harmless way.
 
+If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
+are reseated to point to nowhere, and if the value is @code{evaporate},
+the markers are put back on the free list.
+
+@strong{Warning:} When @code{evaporate} is specified for @var{reseat},
+no other references to the markers on the @var{match-list} list; otherwise,
+Emacs may crash during the next garbage collection.
+
 @findex store-match-data
 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
 @end defun