Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-58

Merge from emacs--devo--0

Patches applied:

 * emacs--devo--0  (patch 239-258)

   - Update from CVS
   - (Ffield_beginning, find_field): Undo change of 2006-04-23.
   - Rcirc patch from Ryan Yeske
   - Merge from gnus--rel--5.10
   - Clean up lisp/gnus/ChangeLog a bit

 * gnus--rel--5.10  (patch 91-98)

   - Merge from emacs--devo--0
   - Update from CVS

6 files changed, 206 insertions, 59 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 48205488ef8..020e667ec16 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,35 @@
+2006-05-01  Richard Stallman  <rms@gnu.org>
+
+        * intro.texi (nil and t): Clarify.
+
+        * variables.texi (File Local Variables): Suggest using booleanp.
+
+2006-05-01  Juanma Barranquero  <lekktu@gmail.com>
+
+        * objects.texi (Type Predicates): Fix typos.
+
+2006-05-01  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * intro.texi (nil and t): Add booleanp.
+
+        * objects.texi (Type Predicates): Add links for booleanp and
+        string-or-null-p.
+
+2006-04-29  Richard Stallman  <rms@gnu.org>
+
+        * modes.texi (Multiline Font Lock): Rename from
+        Multi line Font Lock Elements.  Much clarification.
+        (Font Lock Multiline, Region to Fontify): Much clarification.
+
+2006-04-29  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * variables.texi (File Local Variables): Remove the special case t for
+        safe-local-variable.
+
+2006-04-26  Richard Stallman  <rms@gnu.org>
+
+        * syntax.texi (Parsing Expressions): Minor cleanup.
+
 2006-04-18  Richard Stallman  <rms@gnu.org>
 
         * tips.texi (Coding Conventions): Explain when the package's
@@ -60,7 +92,7 @@
 
 2006-03-25  Karl Berry  <karl@gnu.org>
 
-        * elisp.texi: use @copyright{} instead of (C), and do not indent
+        * elisp.texi: Use @copyright{} instead of (C), and do not indent
         the year list.
 
 2006-03-21  Nick Roberts  <nickrob@snap.net.nz>
@@ -94,7 +126,7 @@
 
         * display.texi (Defining Images): Fix example in
         image-load-path-for-library by not recommending that one binds
-        image-load-path. Just defvar it to placate compiler and only use
+        image-load-path.  Just defvar it to placate compiler and only use
         it if previously defined.
 
 2006-03-14  Bill Wohler  <wohler@newt.com>
@@ -566,11 +598,11 @@
 
 2005-09-26  Chong Yidong  <cyd@stupidchicken.com>
 
-        * errors.texi (Standard Errors): Corrected xrefs.
+        * errors.texi (Standard Errors): Correct xrefs.
 
 2005-09-18  Chong Yidong  <cyd@stupidchicken.com>
 
-        * display.texi (Defining Images): Updated documentation for
+        * display.texi (Defining Images): Update documentation for
         `image-load-path'.
 
 2005-09-17  Richard M. Stallman  <rms@gnu.org>
diff --git a/lispref/intro.texi b/lispref/intro.texi
index b2294be4c2d..7e1b6155b35 100644
--- a/lispref/intro.texi
+++ b/lispref/intro.texi
@@ -163,7 +163,7 @@ person reading this manual, are thought of as ``the programmer'' and are
 addressed as ``you''.  ``The user'' is the person who uses Lisp
 programs, including those you write.
 
-@cindex fonts
+@cindex fonts in this manual
   Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
 Names that represent metasyntactic variables, or arguments to a function
 being described, are formatted like this: @var{first-number}.
@@ -187,14 +187,14 @@ readers.  After the Lisp reader has read either @samp{()} or @samp{nil},
 there is no way to determine which representation was actually written
 by the programmer.
 
-  In this manual, we use @code{()} when we wish to emphasize that it
-means the empty list, and we use @code{nil} when we wish to emphasize
+  In this manual, we write @code{()} when we wish to emphasize that it
+means the empty list, and we write @code{nil} when we wish to emphasize
 that it means the truth value @var{false}.  That is a good convention to use
 in Lisp programs also.
 
 @example
 (cons 'foo ())                ; @r{Emphasize the empty list}
-(not nil)                     ; @r{Emphasize the truth value @var{false}}
+(setq foo-flag nil)           ; @r{Emphasize the truth value @var{false}}
 @end example
 
 @cindex @code{t}, uses of
@@ -212,6 +212,11 @@ to use them as constants in a program.  An attempt to change their
 values results in a @code{setting-constant} error.  @xref{Constant
 Variables}.
 
+@defun booleanp object
+Return non-nil iff @var{object} is one of the two canonical boolean
+values: @code{t} or @code{nil}.
+@end defun
+
 @node Evaluation Notation
 @subsection Evaluation Notation
 @cindex evaluation notation
diff --git a/lispref/modes.texi b/lispref/modes.texi
index b33424a58be..9e55ca847fc 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -2336,8 +2336,6 @@ Search-based fontification happens second.
 * Font Lock Basics::            Overview of customizing Font Lock.
 * Search-based Fontification::  Fontification based on regexps.
 * Customizing Keywords::        Customizing search-based fontification.
-* Region to Fontify::           Controlling which region gets refontified
-                                  after a buffer change.
 * 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.
@@ -2347,6 +2345,8 @@ Search-based fontification happens second.
 * Syntactic Font Lock::         Fontification based on syntax tables.
 * Setting Syntax Properties::   Defining character syntax based on context
                                   using the Font Lock mechanism.
+* Multiline Font Lock::         How to coerce Font Lock into properly
+                                  highlighting multiline constructs.
 @end menu
 
 @node Font Lock Basics
@@ -2623,16 +2623,9 @@ this value of @code{font-lock-keywords} is used in a buffer.
 Its value should have one of the forms described in this table.
 @end table
 
-@vindex font-lock-multiline
 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
-to match text which spans lines; this does not work reliably.  While
-@code{font-lock-fontify-buffer} handles multi-line patterns correctly,
-updating when you edit the buffer does not, since it considers text one
-line at a time.  If you have patterns that typically only span one
-line but can occasionally span two or three, such as
-@samp{<title>...</title>}, you can ask Font Lock to be more careful by
-setting @code{font-lock-multiline} to @code{t}.  But it still will not
-work in all cases.
+to match text which spans lines; this does not work reliably.
+For details, see @xref{Multiline Font Lock}.
 
 You can use @var{case-fold} in @code{font-lock-defaults} to specify
 the value of @code{font-lock-keywords-case-fold-search} which says
@@ -2718,36 +2711,6 @@ C mode @emph{and} all modes derived from it, do this instead:
       font-lock-keyword-face)))))
 @end smallexample
 
-@node Region to Fontify
-@subsection Region to Fontify after a Buffer Change
-
-  When a buffer is changed, the region that Font Lock refontifies is by
-default the smallest sequence of whole lines that spans the change.
-While this works well most of the time, sometimes it doesn't---for
-example, when a buffer change has changed the syntactic meaning of text
-on an earlier line.
-
-You can enlarge (or even reduce) the region to fontify by setting either
-of the following variables:
-
-@defvar font-lock-extend-region-function
-This buffer-local variable is either @code{nil} or is a function that
-determines the region to fontify, which Emacs then calls after each
-buffer change.
-
-The function is given three parameters, the standard @var{beg},
-@var{end}, and @var{old-len} from after-change-functions (@pxref{Change
-Hooks}).  It should return either a cons of the beginning and end buffer
-positions (in that order) of the region to fontify, or @code{nil} (which
-directs the caller to fontify the default region).  This function need
-not preserve point or the match-data, but must preserve the current
-restriction.  The region it returns may start or end in the middle of a
-line.
-
-Since this function is called after every buffer change, it should be
-reasonably fast.
-@end defvar
-
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
 
@@ -2981,8 +2944,8 @@ value returns @code{font-lock-comment-face} for comments and
 
 This can be used to highlighting different kinds of strings or
 comments differently.  It is also sometimes abused together with
-@code{font-lock-syntactic-keywords} to highlight elements that span
-multiple lines, but this is too obscure to document in this manual.
+@code{font-lock-syntactic-keywords} to highlight constructs that span
+multiple lines, but this is too esoteric to document here.
 
 Specify this variable using @var{other-vars} in
 @code{font-lock-defaults}.
@@ -3052,6 +3015,145 @@ Major modes normally set this variable with @var{other-vars} in
 @code{font-lock-defaults}.
 @end defvar
 
+@node Multiline Font Lock
+@subsection Multiline Font Lock Constructs
+@cindex multiline font lock
+
+  Normally, elements of @code{font-lock-keywords} should not match
+across multiple lines; that doesn't work reliably, because Font Lock
+usually scans just part of the buffer, and it can miss a multi-line
+construct that crosses the line boundary where the scan starts.  (The
+scan normally starts at the beginning of a line.)
+
+  Making elements that match multiline constructs work properly has
+two aspects: correct @emph{identification} and correct
+@emph{rehighlighting}.  The first means that Font Lock finds all
+multiline constructs.  The second means that Font Lock will correctly
+rehighlight all the relevant text when a multiline construct is
+changed---for example, if some of the text that was previously part of
+a multiline construct ceases to be part of it.  The two aspects are
+closely related, and often getting one of them to work will appear to
+make the other also work.  However, for reliable results you must
+attend explicitly to both aspects.
+
+  There are two ways to ensure correct identification of multiline
+constructs:
+
+@itemize
+@item
+Place a @code{font-lock-multiline} or @code{jit-lock-defer-multiline}
+property on the construct when it is added to the buffer.
+@item
+Use @code{font-lock-fontify-region-function} hook to extend the scan
+so that the scanned text never starts or ends in the middle of a
+multiline construct.
+@end itemize
+
+  There are three ways to do rehighlighting of multiline constructs:
+
+@itemize
+@item
+Place a @code{font-lock-multiline} property on the construct.  This
+will rehighlight the whole construct if any part of it is changed.  In
+some cases you can do this automatically by setting the
+@code{font-lock-multiline} variable.
+@item
+Use @code{jit-lock-contextually}.  This will only rehighlight the part
+of the construct that follows the actual change, and will do it after
+a short delay.  This only works if the highlighting of the various
+parts of your multiline construct never depends on text in subsequent
+lines.  Since @code{jit-lock-contextually} is activated by default,
+this can be an attractive solution.
+@item
+Place a @code{jit-lock-defer-multiline} property on the construct.
+This works only if @code{jit-lock-contextually} is used, but it can
+handle the case where highlighting depends on subsequent lines.
+@item
+@end itemize
+
+@menu
+* Font Lock Multiline::         Marking multiline chunks with a text property
+* Region to Fontify::           Controlling which region gets refontified
+                                  after a buffer change.
+@end menu
+
+@node Font Lock Multiline
+@subsubsection Font Lock Multiline
+
+  One way to ensure reliable rehighlighting of multiline Font Lock
+constructs is to put on the text property @code{font-lock-multiline}.
+It should be present and non-@code{nil} for text that is part of a
+multiline construct.
+
+  When Font Lock is about to highlight a range of text, it first
+extends the boundaries of the range as necessary so that they do not
+fall within text marked with the @code{font-lock-multiline} property.
+Then it removes any @code{font-lock-multiline} properties from the
+range, and highlights it.  The highlighting specification (mostly
+@code{font-lock-keywords}) must reinstall this property each time,
+whenever it is appropriate.
+
+  @strong{Warning:} don't use the @code{font-lock-multiline} property
+on large ranges of text, because that will make rehighlighting slow.
+
+@defvar font-lock-multiline
+If the @code{font-lock-multiline} variable is set to @code{t}, Font
+Lock will try to add the @code{font-lock-multiline} property
+automatically on multiline constructs.  This is not a universal
+solution, however, since it slows down Font Lock somewhat.  It can
+miss some multiline constructs, or make the property larger or smaller
+than necessary.
+
+For elements whose @var{matcher} is a function, the function should
+ensure that submatch 0 covers the whole relevant multiline construct,
+even if only a small subpart will be highlighted.  It is often just as
+easy to add the @code{font-lock-multiline} property by hand.
+@end defvar
+
+  The @code{font-lock-multiline} property is meant to ensure proper
+refontification; it does not automatically identify new multiline
+constructs.  Identifying the requires that Font-Lock operate on large
+enough chunks at a time.  This will happen by accident on many cases,
+which may give the impression that multiline constructs magically work.
+If you set the @code{font-lock-multiline} variable non-@code{nil},
+this impression will be even stronger, since the highlighting of those
+constructs which are found will be properly updated from then on.
+But that does not work reliably.
+
+  To find multiline constructs reliably, you must either manually
+place the @code{font-lock-multiline} property on the text before
+Font-Lock looks at it, or use
+@code{font-lock-fontify-region-function}.
+
+@node Region to Fontify
+@subsubsection Region to Fontify after a Buffer Change
+
+  When a buffer is changed, the region that Font Lock refontifies is
+by default the smallest sequence of whole lines that spans the change.
+While this works well most of the time, sometimes it doesn't---for
+example, when a change alters the syntactic meaning of text on an
+earlier line.
+
+  You can enlarge (or even reduce) the region to fontify by setting
+one the following variables:
+
+@defvar font-lock-extend-region-function
+This buffer-local variable is either @code{nil} or a function for
+Font-Lock to call to determine the region to scan and fontify.
+
+The function is given three parameters, the standard @var{beg},
+@var{end}, and @var{old-len} from after-change-functions
+(@pxref{Change Hooks}).  It should return either a cons of the
+beginning and end buffer positions (in that order) of the region to
+fontify, or @code{nil} (which means choose the region in the standard
+way).  This function needs to preserve point, the match-data, and the
+current restriction.  The region it returns may start or end in the
+middle of a line.
+
+Since this function is called after every buffer change, it should be
+reasonably fast.
+@end defvar
+
 @node Desktop Save Mode
 @section Desktop Save Mode
 @cindex desktop save mode
diff --git a/lispref/objects.texi b/lispref/objects.texi
index 93848cffe09..5665e5beee6 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -1779,6 +1779,12 @@ with references to further information.
 
 @item windowp
 @xref{Basic Windows, windowp}.
+
+@item booleanp
+@xref{nil and t, booleanp}.
+
+@item string-or-null-p
+@xref{Predicates for Strings, string-or-null-p}.
 @end table
 
   The most general way to check the type of an object is to call the
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 7297f6b9104..1575ebeb850 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -672,7 +672,9 @@ the parse:
 
 @enumerate 0
 @item
-The depth in parentheses, counting from 0.
+The depth in parentheses, counting from 0.  @strong{Warning:} this can
+be negative if there are more close parens than open parens between
+the start of the defun and point.
 
 @item
 @cindex innermost containing parentheses
diff --git a/lispref/variables.texi b/lispref/variables.texi
index d97848549c0..5b4b779448e 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1778,13 +1778,13 @@ measures to prevent this.
 
 @cindex safe local variable
   You can specify safe values for a variable with a
-@code{safe-local-variable} property.  If the property is @code{t},
-setting that variable in a file is always considered safe, regardless
-of the value used.  If the property is a function of one argument,
-then any value is safe if the function returns non-@code{nil} given
-that value.  Many commonly encountered file variables standardly have
-@code{safe-local-variable} properties, including @code{fill-column},
-@code{fill-prefix}, and @code{indent-tabs-mode}.
+@code{safe-local-variable} property.  The property has to be
+a function of one argument; any value is safe if the function
+returns non-@code{nil} given that value.  Many commonly encountered
+file variables standardly have @code{safe-local-variable} properties,
+including @code{fill-column}, @code{fill-prefix}, and
+@code{indent-tabs-mode}.  For boolean-valued variables that are safe,
+use @code{booleanp} as the property value.
 
 @defopt safe-local-variable-values
 This variable provides another way to mark some variable values as