X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9bf6d576a798f47ab6c0716335ed13c7fa90196f..171920a66145032a61fab9458ec6104000ff8dd8:/lispref/text.texi diff --git a/lispref/text.texi b/lispref/text.texi index 0e636d4ba5..3d66873825 100644 --- 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 +@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 @@ -1228,6 +1263,16 @@ relocated due to deletion of surrounding text, and that it moved @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 @@ -1452,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. -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. @@ -1480,6 +1525,17 @@ does not count as the end of a sentence, and the filling functions 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 @@ -1598,19 +1654,25 @@ becomes buffer-local when set in any fashion. @end defvar @defvar fill-nobreak-predicate -This variable gives major modes a way to specify not to break a line at -certain places. Its value should be a function. This function is -called during filling, with no arguments and with point located at the -place where a break is being considered. If the function returns -non-@code{nil}, then the line won't be broken there. +This variable gives major modes a way to specify not to break a line +at certain places. Its value should be a list of functions, but a +single function is also supported for compatibility. Whenever filling +considers breaking the line at a certain place in the buffer, it calls +each of these functions with no arguments and with point located at +that place. If any of the functions returns non-@code{nil}, then the +line won't be broken there. @end defvar @node Adaptive Fill @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}. @@ -1619,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 -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 @@ -2617,9 +2720,9 @@ list. @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 @@ -2865,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 -@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 @@ -2884,7 +2988,7 @@ Strictly speaking, @code{font-lock-face} is not a built-in text property; rather, it is implemented in Font Lock mode using @code{char-property-alias-alist}. @xref{Examining Properties}. -This property is new in Emacs 21.4. +This property is new in Emacs 22.1. @item mouse-face @kindex mouse-face @r{(text property)} @@ -3020,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 -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)} @@ -3425,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 -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 @@ -3457,9 +3561,9 @@ The action code is always @code{t}. 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 @@ -3470,11 +3574,11 @@ action code. 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 @@ -4223,8 +4327,6 @@ disabled; none of them run. This affects all the hook variables described above in this section, as well as the hooks attached to certain special text properties (@pxref{Special Properties}) and overlay properties (@pxref{Overlay Properties}). - -This variable is available starting in Emacs 21. @end defvar @ignore