@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2000, 2001, 2004, 2005
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
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
@var{adjustment} character positions. Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.
+@item (apply @var{funname} . @var{args})
+This is an extensible undo item, which is undone by calling
+@var{funname} with arguments @var{args}.
+
+@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
+This is an extensible undo item, which records a change limited to the
+range @var{beg} to @var{end}, which increased the size of the buffer
+by @var{delta}. It is undone by calling @var{funname} with arguments
+@var{args}.
+
@item nil
This element is a boundary. The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
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.
avoid breaking the line at such a place.
@end defopt
+@defopt sentence-end-without-period
+If this variable is non-@code{nil}, a sentence can end without a
+period. This is used for languages like Thai, where sentences end
+with a double space but without a period.
+@end defopt
+
+@defopt sentence-end-without-space
+If this variable is non-@code{nil}, it should be a string of
+characters that can end a sentence without following spaces.
+@end defopt
+
@defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
@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}.
@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.
+
+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
-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.
+
+@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
-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
-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 defun
@defun remove-list-of-text-properties start end list-of-properties &optional object
-Like @code{remove-list-properties} except that
+Like @code{remove-text-properties} except that
@var{list-of-properties} is a list property names only, not an
-alternating list of property values.
+alternating list of property names and values.
@end defun
@defun set-text-properties start end props &optional object
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
@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)}
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)}
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
For example, here is how Info mode handles @key{Mouse-1}:
-@example
+@smallexample
(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
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)
- (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