]> code.delx.au - gnu-emacs/blobdiff - lispref/text.texi
(Garbage Collection): Clarify previous change.
[gnu-emacs] / lispref / text.texi
index 1d4dc0fce8af2d4e18b6df57e13b7207aef8200d..5b9b4259a1c96081b2ddb3d95cffee78dc515308 100644 (file)
@@ -1497,10 +1497,10 @@ of justification.  It can be @code{left}, @code{right}, @code{full},
 follow specified justification style (see @code{current-justification},
 below).  @code{nil} means to do full justification.
 
 follow specified justification style (see @code{current-justification},
 below).  @code{nil} means to do full justification.
 
-If @var{eop} is non-@code{nil}, that means do left-justification if
-@code{current-justification} specifies full justification.  This is used
-for the last line of a paragraph; even if the paragraph as a whole is
-fully justified, the last line should not be.
+If @var{eop} is non-@code{nil}, that means do only left-justification
+if @code{current-justification} specifies full justification.  This is
+used for the last line of a paragraph; even if the paragraph as a
+whole is fully justified, the last line should not be.
 
 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
 whitespace.
 
 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
 whitespace.
@@ -1667,8 +1667,12 @@ line won't be broken there.
 @section Adaptive Fill Mode
 @cindex Adaptive Fill mode
 
 @section Adaptive Fill Mode
 @cindex Adaptive Fill mode
 
-  Adaptive Fill mode chooses a fill prefix automatically from the text
-in each paragraph being filled.
+  When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
+prefix automatically from the text in each paragraph being filled
+rather than using a predetermined value.  During filling, this fill
+prefix gets inserted at the start of the second and subsequent lines
+of the paragraph as described in @ref{Filling}, and in @ref{Auto
+Filling}.
 
 @defopt adaptive-fill-mode
 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
 
 @defopt adaptive-fill-mode
 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
@@ -1677,38 +1681,79 @@ It is @code{t} by default.
 
 @defun fill-context-prefix from to
 This function implements the heart of Adaptive Fill mode; it chooses a
 
 @defun fill-context-prefix from to
 This function implements the heart of Adaptive Fill mode; it chooses a
-fill prefix based on the text between @var{from} and @var{to}.  It does
-this by looking at the first two lines of the paragraph, based on the
-variables described below.
+fill prefix based on the text between @var{from} and @var{to},
+typically the start and end of a paragraph.  It does this by looking
+at the first two lines of the paragraph, based on the variables
+described below.
 @c The optional argument first-line-regexp is not documented
 @c because it exists for internal purposes and might be eliminated
 @c in the future.
 @c The optional argument first-line-regexp is not documented
 @c because it exists for internal purposes and might be eliminated
 @c in the future.
+
+Usually, this function returns the fill prefix, a string.  However,
+before doing this, the function makes a final check (not specially
+mentioned in the following) that a line starting with this prefix
+wouldn't look like the start of a paragraph.  Should this happen, the
+function signals the anomaly by returning @code{nil} instead.
+
+In detail, @code{fill-context-prefix} does this:
+
+@enumerate
+@item
+It takes a candidate for the fill prefix from the first line---it
+tries first the function in @code{adaptive-fill-function} (if any),
+then the regular expression @code{adaptive-fill-regexp} (see below).
+The first non-@code{nil} result of these, or the empty string if
+they're both @code{nil}, becomes the first line's candidate.
+@item
+If the paragraph has as yet only one line, the function tests the
+validity of the prefix candidate just found.  The function then
+returns the candidate if it's valid, or a string of spaces otherwise.
+(see the description of @code{adaptive-fill-first-line-regexp} below).
+@item
+When the paragraph already has two lines, the function next looks for
+a prefix candidate on the second line, in just the same way it did for
+the first line.  If it doesn't find one, it returns @code{nil}.
+@item
+The function now compares the two candidate prefixes heuristically: if
+the non-whitespace characters in the line 2 candidate occur in the
+same order in the line 1 candidate, the function returns the line 2
+candidate.  Otherwise, it returns the largest initial substring which
+is common to both candidates (which might be the empty string).
+@end enumerate
 @end defun
 
 @defopt adaptive-fill-regexp
 @end defun
 
 @defopt adaptive-fill-regexp
-This variable holds a regular expression to control Adaptive Fill mode.
 Adaptive Fill mode matches this regular expression against the text
 starting after the left margin whitespace (if any) on a line; the
 characters it matches are that line's candidate for the fill prefix.
 Adaptive Fill mode matches this regular expression against the text
 starting after the left margin whitespace (if any) on a line; the
 characters it matches are that line's candidate for the fill prefix.
+
+@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+default value.  This matches a number enclosed in parentheses or
+followed by a period, or certain punctuation characters, or any
+sequence of these intermingled with whitespace.  In particular, it
+matches a sequence of whitespace, possibly empty.
 @end defopt
 
 @defopt adaptive-fill-first-line-regexp
 @end defopt
 
 @defopt adaptive-fill-first-line-regexp
-In a one-line paragraph, if the candidate fill prefix matches this
-regular expression, or if it matches @code{comment-start-skip}, then it
-is used---otherwise, spaces amounting to the same width are used
-instead.
-
-However, the fill prefix is never taken from a one-line paragraph
-if it would act as a paragraph starter on subsequent lines.
+Used only in one-line paragraphs, this regular expression acts as an
+additional check of the validity of the one available candidate fill
+prefix: the candidate must match this regular expression, or match
+@code{comment-start-skip}.  If it doesn't, @code{fill-context-prefix}
+replaces the candidate with a string of spaces ``of the same width''
+as it.
+
+The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which
+matches only a string of whitespace.  The effect of this default is to
+force the fill prefixes found in one-line paragraphs always to be pure
+whitespace.
 @end defopt
 
 @defopt adaptive-fill-function
 You can specify more complex ways of choosing a fill prefix
 automatically by setting this variable to a function.  The function is
 @end defopt
 
 @defopt adaptive-fill-function
 You can specify more complex ways of choosing a fill prefix
 automatically by setting this variable to a function.  The function is
-called when @code{adaptive-fill-regexp} does not match, with point after
-the left margin of a line, and it should return the appropriate fill
-prefix based on that line.  If it returns @code{nil}, that means it sees
-no fill prefix in that line.
+called with point after the left margin (if any) of a line, and it
+must preserve point.  It should return either ``that line's'' fill
+prefix or @code{nil}, meaning it has failed to determine a prefix.
 @end defopt
 
 @node Auto Filling
 @end defopt
 
 @node Auto Filling
@@ -2923,7 +2968,8 @@ A cons cell of the form @code{(foreground-color . @var{color-name})} or
 just the foreground color or just the background color.
 
 @code{(foreground-color . @var{color-name})} is equivalent to
 just the foreground color or just the background color.
 
 @code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+specifying @code{(:foreground @var{color-name})}, and likewise for the
+background.
 @end itemize
 
 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
 @end itemize
 
 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
@@ -3078,8 +3124,8 @@ that character a non-@code{nil} @var{cursor} text property.
 @item pointer
 @kindex pointer @r{(text property)}
 This specifies a specific pointer shape when the mouse pointer is over
 @item pointer
 @kindex pointer @r{(text property)}
 This specifies a specific pointer shape when the mouse pointer is over
-this text or image.  See the variable @var{void-area-text-pointer}
-for possible pointer shapes.
+this text or image.  @xref{Pointer Shape}, for possible pointer
+shapes.
 
 @item line-spacing
 @kindex line-spacing @r{(text property)}
 
 @item line-spacing
 @kindex line-spacing @r{(text property)}
@@ -3106,6 +3152,10 @@ particular modification hook function appears on several characters
 being modified by a single primitive, you can't predict how many times
 the function will be called.
 
 being modified by a single primitive, you can't predict how many times
 the function will be called.
 
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
 @item insert-in-front-hooks
 @itemx insert-behind-hooks
 @kindex insert-in-front-hooks @r{(text property)}
 @item insert-in-front-hooks
 @itemx insert-behind-hooks
 @kindex insert-in-front-hooks @r{(text property)}
@@ -3483,7 +3533,7 @@ buffer.
 graphical applications use @key{Mouse-1} for following links.  For
 compatibility, @key{Mouse-1} follows links in Emacs too, when you
 click on a link quickly without moving the mouse.  The user can
 graphical applications use @key{Mouse-1} for following links.  For
 compatibility, @key{Mouse-1} follows links in Emacs too, when you
 click on a link quickly without moving the mouse.  The user can
-customize this behaviour through the variable
+customize this behavior through the variable
 @code{mouse-1-click-follows-link}.
 
   To define text as a link at the Lisp level, you should bind the
 @code{mouse-1-click-follows-link}.
 
   To define text as a link at the Lisp level, you should bind the
@@ -3515,9 +3565,9 @@ The action code is always @code{t}.
 
 For example, here is how Info mode handles @key{Mouse-1}:
 
 
 For example, here is how Info mode handles @key{Mouse-1}:
 
-@example
+@smallexample
 (define-key Info-mode-map [follow-link] 'mouse-face)
 (define-key Info-mode-map [follow-link] 'mouse-face)
-@end example
+@end smallexample
 
 @item a function
 If the condition is a valid function, @var{func}, then a position
 
 @item a function
 If the condition is a valid function, @var{func}, then a position
@@ -3528,11 +3578,11 @@ action code.
 For example, here is how pcvs enables @key{Mouse-1} to follow links on
 file names only:
 
 For example, here is how pcvs enables @key{Mouse-1} to follow links on
 file names only:
 
-@example
+@smallexample
 (define-key map [follow-link]
   (lambda (pos)
 (define-key map [follow-link]
   (lambda (pos)
-    (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
-@end example
+    (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
 
 @item anything else
 If the condition value is anything else, then the position is inside a
 
 @item anything else
 If the condition value is anything else, then the position is inside a