(Creating Keymaps): Put make-sparse-keymap before make-keymap.

[gnu-emacs] / lispref / text.texi

diff --git a/lispref/text.texi b/lispref/text.texi
index e300b345454da6593f022f98fc172a6ddc198d47..3d6687382505f0aa1968635704c697b5c34a6e2b 100644 (file)
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -207,6 +207,41 @@ This is like @code{buffer-substring}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 

+@defun filter-buffer-substring start end &optional delete
+This function passes the buffer text between @var{start} and @var{end}
+through the filter functions specified by the variable
+@code{buffer-substring-filters}, and returns the value from the last
+filter function.  If @code{buffer-substring-filters} is @code{nil},
+the value is the unaltered text from the buffer, what
+@code{buffer-substring} would return.
+
+If @var{delete} is non-@code{nil}, this function deletes the text
+between @var{start} and @var{end} after copying it, like
+@code{delete-and-extract-region}.
+
+Lisp code should use this function instead of @code{buffer-substring}
+or @code{delete-and-extract-region} when copying into user-accessible
+data structures such as the kill-ring, X clipboard, and registers.
+Major and minor modes can add functions to
+@code{buffer-substring-filters} to alter such text as it is copied out
+of the buffer.
+@end defun
+
+@defvar buffer-substring-filters
+This variable should be a list of functions that accept a single
+argument, a string, and return a string.
+@code{filter-buffer-substring} passes the buffer substring to the
+first function in this list, and the return value of each function is
+passed to the next function.  The return value of the last function is
+used as the return value of @code{filter-buffer-substring}.
+
+As a special convention, point is set to the start of the buffer text
+being operated on (i.e., the @var{start} argument for
+@code{filter-buffer-substring}) before these functions are called.
+
+If this variable is @code{nil}, no filtering is performed.
+@end defvar
+

 @defun buffer-string
 This function returns the contents of the entire accessible portion of
 the current buffer as a string.  It is equivalent to
 @defun buffer-string
 This function returns the contents of the entire accessible portion of
 the current buffer as a string.  It is equivalent to


@@ -1462,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.


@@ -1632,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}.


@@ -1642,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


@@ -2888,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


@@ -3043,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)}


@@ -3448,7 +3529,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


@@ -3480,9 +3561,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


@@ -3493,11 +3574,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