[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Filling woes - code, documentation and NEWS patches
From: |
Alan Mackenzie |
Subject: |
Re: Filling woes - code, documentation and NEWS patches |
Date: |
Sun, 29 May 2005 19:56:21 +0000 (GMT) |
On Sun, 29 May 2005, Richard Stallman wrote:
> [ A note of corrections to my Doc patch.]
I have incorporated all of these.
>Aside from that, the text is good. Please install the text, correcting
>these little points, and also change the code.
I don't have write access on savannah. Would somebody commit these
patches for me, please.
>Don't forget to change etc/NEWS.
See below.
Here are all three patches: to fill.el, Elisp's text.texi and NEWS.
2005-05-17 Alan Mackenzie <address@hidden>
* fill.el (fill-context-prefix): Try `adaptive-fill-function'
BEFORE `adaptive-fill-regexp' when determining a fill prefix.
(adaptive-file-function): Minor amendment to doc-string.
*** fill-1.175.el Sat May 14 19:51:44 2005
--- fill-1.175.acm.el Tue May 17 19:37:57 2005
***************
*** 114,120 ****
(defcustom adaptive-fill-function nil
"*Function to call to choose a fill prefix for a paragraph, or nil.
! This function is used when `adaptive-fill-regexp' does not match."
:type '(choice (const nil) function)
:group 'fill)
--- 114,120 ----
(defcustom adaptive-fill-function nil
"*Function to call to choose a fill prefix for a paragraph, or nil.
! nil means the function has not determined the fill prefix."
:type '(choice (const nil) function)
:group 'fill)
***************
*** 229,237 ****
;; Also setting first-line-prefix to nil prevents
;; second-line-prefix from being used.
(cond ;; ((looking-at paragraph-start) nil)
((and adaptive-fill-regexp (looking-at adaptive-fill-regexp))
! (match-string-no-properties 0))
! (adaptive-fill-function (funcall adaptive-fill-function))))
(forward-line 1)
(if (< (point) to)
(progn
--- 229,237 ----
;; Also setting first-line-prefix to nil prevents
;; second-line-prefix from being used.
(cond ;; ((looking-at paragraph-start) nil)
+ ((and adaptive-fill-function (funcall
adaptive-fill-function)))
((and adaptive-fill-regexp (looking-at adaptive-fill-regexp))
! (match-string-no-properties 0))))
(forward-line 1)
(if (< (point) to)
(progn
***************
*** 239,249 ****
(setq start (point))
(setq second-line-prefix
(cond ((looking-at paragraph-start) nil) ;Can it happen ? -stef
((and adaptive-fill-regexp
(looking-at adaptive-fill-regexp))
! (buffer-substring-no-properties start (match-end 0)))
! (adaptive-fill-function
! (funcall adaptive-fill-function))))
;; If we get a fill prefix from the second line,
;; make sure it or something compatible is on the first line too.
(when second-line-prefix
--- 239,249 ----
(setq start (point))
(setq second-line-prefix
(cond ((looking-at paragraph-start) nil) ;Can it happen ? -stef
+ ((and adaptive-fill-function
+ (funcall adaptive-fill-function)))
((and adaptive-fill-regexp
(looking-at adaptive-fill-regexp))
! (buffer-substring-no-properties start (match-end 0)))))
;; If we get a fill prefix from the second line,
;; make sure it or something compatible is on the first line too.
(when second-line-prefix
2005-05-29 Alan Mackenzie <address@hidden>
* text.texi: Amplify the description of fill-context-prefix.
*** text-1.98.texi Sat May 14 19:53:50 2005
--- text-1.98.acm.texi Sun May 29 15:03:01 2005
***************
*** 1667,1674 ****
@section Adaptive Fill Mode
@cindex Adaptive Fill mode
! Adaptive Fill mode chooses a fill prefix automatically from the text
! in each paragraph being filled.
@defopt adaptive-fill-mode
Adaptive Fill mode is enabled when this variable is address@hidden
--- 1667,1678 ----
@section Adaptive Fill Mode
@cindex Adaptive Fill mode
! 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 @xref{Filling} and @xref{Auto
! Filling}.
@defopt adaptive-fill-mode
Adaptive Fill mode is enabled when this variable is address@hidden
***************
*** 1677,1714 ****
@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.
@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.
@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.
@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.
@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.
@end defopt
@node Auto Filling
--- 1681,1760 ----
@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},
! 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 address@hidden 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
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.
+
+ The default value of this variable is
+ @address@hidden"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}. 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
! 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 @address@hidden"\\`[ \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 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
*** NEWS-1.1203 Sun May 29 15:09:32 2005
--- NEWS-1.1203.acm Sun May 29 17:10:49 2005
***************
*** 3350,3355 ****
--- 3350,3363 ----
*** The function `insert-string' is now obsolete.
+++
+ ** Filling changes.
+
+ +++
+ *** In determining an adaptive fill prefix, a function in
+ `adaptive-fill-function' is now tried before matching the buffer line
+ against `adaptive-fill-regexp' rather than after it.
+
+ +++
** Atomic change groups.
To perform some changes in the current buffer "atomically" so that
--
Alan Mackenzie (Munich, Germany)