X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/8e669bbd42c254c32e3fffa489f4d97d48d9bd76..67ec7f41d043a895556e581b6d035fa4906dabd1:/lispref/text.texi diff --git a/lispref/text.texi b/lispref/text.texi index 1d4dc0fce8..5b9b4259a1 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -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. -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. @@ -1667,8 +1667,12 @@ line won't be broken there. @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}. @@ -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 -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 @@ -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 -@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 @@ -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 -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)} @@ -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. +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)} @@ -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 -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 @@ -3515,9 +3565,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 @@ -3528,11 +3578,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