Filling woes

Filling woes

[Alan Mackenzie]

Hi, Emacs!

I wanted to enhance text-mode (for my own use only, not as a
contribution), so that it would recognise a list of items begun by
parenthesized roman numerals as list items, and fill them as below:

(i) The paragraph recognition code should regard each such list item as a
  distinct paragraph, so that M-q and friends leave the paragraph
  structure intact;
(ii) Filling, including the auto-fill variety, should indent the second
  and subsequent lines of a "roman paragraph" by two spaces.

Should be easy, shouldn't it?  Well, yes, but it took me many hours.  I
wasn't able to understand the documentation (Emacs manual's pages "Fill
Prefix", "Adaptive Fill";  Elisp's "Adaptive Fill").  It was too vague
for me to get anything definite out of.  In particular, there was no
clear description of how Emacs determines the fill prefix for a
paragraph; only inadequate disjoint descriptions of the pertinent
variables.  In the end I had to edebugger my way through the filling
code.

And there I found something which I think should be changed:  In the
function `fill-context-prefix' (whose purpose is determining the fill
prefix in the given region (usually a paragraph)), the code first tries
to match the start of a line against `adaptive-fill-regexp' and if it
fails, funcalls `adaptive-fill-function', if non-nil.

This is crazy!  The default value for `adaptive-fiill-regexp' matches the
null string, so if I want to use `adaptive-fill-function', I've got to
somehow clobber this regexp.  Having done that, I would have to
incorporate its functionality into my `adaptive-fill-function'.  YUCK!!!

Surely `adaptive-fill-function' should be tried first.  MUST be tried
first.  Surely?  Or have I missed something significant in the filling
mechanism?

Once I'd put this change into fill.el (see the patch below), I was able
to get the formatting I wanted with this code in my .emacs:

#########################################################################
;; Stuff for formatting "Roman lists" in text-mode
(defconst roman-u (regexp-opt '("i" "ii" "iii" "iv" "v" "vi" "vii" "viii" "ix")))
(defconst roman-t (regexp-opt '("x" "xx" "xxx" "xl" "l" "lx" "lxx" "lxxx" "xc")))
(defconst roman
  (concat "\\(\\(" roman-t "\\)\\(" roman-u "\\)?\\)\\|\\(" roman-u "\\)"))
(defconst p-roman (concat "(\\(" roman "\\))"))
(defconst opt-nl-p-roman (concat "\n?" p-roman )) ; backward-paragraph can go to the blank line before.

(defun roman-adaptive-fill-prefix ()
  "Return a string of 2 spaces iff we're in a \"Roman list\" item."
  (save-excursion
    (forward-line 0)
    (unless (and (looking-at paragraph-start) (not (looking-at paragraph-separate)))
      (backward-paragraph))
    (if (looking-at opt-nl-p-roman) "  ")))

(defun enable-paren-lists ()
  (setq paragraph-start (concat p-roman "\\|" paragraph-start)
        adaptive-fill-function 'roman-adaptive-fill-prefix))

(add-hook 'text-mode-hook 'enable-paren-lists)
#########################################################################

Here is the patch to fill.el.  (I've only tested with the equivalent
patch on 21.3's fill.el, though.)

2005-05-17  Alan Mackenzie  <acm@muc.de>

	* 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

-- 
Alan Mackenzie (Munich, Germany)

Re: Filling woes

[Stefan Monnier]

> This is crazy!  The default value for `adaptive-fiill-regexp' matches the
> null string, so if I want to use `adaptive-fill-function', I've got to
> somehow clobber this regexp.  Having done that, I would have to
> incorporate its functionality into my `adaptive-fill-function'.  YUCK!!!

> Surely `adaptive-fill-function' should be tried first.  MUST be tried
> first.  Surely?  Or have I missed something significant in the filling
> mechanism?

I'd tend to agree.  I remember going through similar steps at some point,
and also wondering who came up with the idea of only checking
adaptive-fill-function as a last resort.  What was he thinking?


        Stefan

Re: Filling woes

[Richard Stallman]

I agree it would be better to try adaptive-fill-function first.  If it
returns nil, the code should proceed to try the appropriate regexp.

As regards documenting precisely how these variables are used,
that is hard because the code details were designed based
on heuristics.

Re: Filling woes

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> I agree it would be better to try adaptive-fill-function first.  If
> it returns nil, the code should proceed to try the appropriate
> regexp.

This is a very incompatible change, since adaptive-fill-function's
return value previously carried no meaning.

While the current scheme appears braindead, we could make it somewhat
saner in a compatible way by allowing adaptive-fill-regexp to be nil,
in which case adaptive-fill-function would get called unconditionally.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Filling woes

[Richard Stallman]

    This is a very incompatible change, since adaptive-fill-function's
    return value previously carried no meaning.

Looking at the code, I think you're mistaken.  adaptive-fill-function
returns the string to use as the prefix, or nil.'

The change *is* incompatible, for a different reason.
It would cause adaptive-fill-function to be called in situations
where now it would not be called.  And adaptive-fill-function could
override matching adaptive-fill-regexp.

This can't break anything in Emacs because nothing in Emacs uses
adaptive-fill-function.  It could break some user Lisp code, though.
Pretest is when we are likely to find out about this; mostly users
would change their code.  So if we are going to make this change,
there's no harm doing it now.

However, it could be a good idea to first ask users who use
adaptive-fill-function to tell us how they use it, before deciding
whether to change anything here.

    While the current scheme appears braindead, we could make it somewhat
    saner in a compatible way by allowing adaptive-fill-regexp to be nil,
    in which case adaptive-fill-function would get called unconditionally.

That is how it works now.

Re: Filling woes

[Alan Mackenzie]

On Fri, 20 May 2005, Richard Stallman wrote:

>I agree it would be better to try adaptive-fill-function first.  If it
>returns nil, the code should proceed to try the appropriate regexp.

Thanks!

>As regards documenting precisely how these variables are used,
>that is hard because the code details were designed based
>on heuristics.

Nevertheless, even given that constraint, I found the documentation so
vague as to be nearly useless.  And even if the vagueness were tidied up,
and each variable were clearly defined, I'm not sure that would be enough
help in achieving the type of filling I might want.  In the end, I could
only work out what everything meant by reading the fine source code.

In what follows, I'm not being an obnoxious pedant tearing apart what
isn't specified with lawyers' precision.  I'm reconstructing the
frustration I encountered trying to understand it.  Give me a few days,
and I'll try and submit a patch fixing what I think is wrong.

The following comments apply to the Elisp Manual's "Adaptive Fill" page:

>    Adaptive Fill mode chooses a fill prefix automatically from the text
>    in each paragraph being filled.

Is this fill prefix for the current line, every line in the paragraph or
every line but the first?  What I think is missing is a sentence along
the lines "Having chosen this prefix, adaptive fill then uses it as
describe in @xref{Filling} and @xref{auto-filling}."

>  - Function: fill-context-prefix from to
>    This function implements the heart of Adaptive Fill mode; it
>    chooses a fill prefix based on the text between FROM and TO.  It
>    does this by looking at the first two lines of the paragraph,
>    based on the variables described below.

"based on" is too vague.  What if there aren't yet two lines in the
paragraph?  (Yes, I know an answer, of a sort, is in the Emacs manual,
but surely it should be here too (or instead)).  What is missing here is
which ORDER these variables are used in.  What happens when, for example,
adaptive-fill-regexp and adaptive-fill-first-line-regexp disagree for the
prefix in a one-liner paragraph?

And how about saying FROM and TO are usually (always?) the boundaries of
the current paragraph?

>  - User Option: adaptive-fill-regexp
>    This variable holds a regular expression to control Adaptive Fill
>    mode. ....

GET RID OF THAT FIRST SENTENCE!!  It's content-free and patronising.

>    Adaptive Fill mode matches this regular expression against
>    the text starting after the left margin whitespace (if any) on a
>    line; .....

Which line?  The first line or the second (if any)?  Or both, one after
the other?

>    the characters it matches are that line's candidate for the fill
>    prefix.

Ah... So presumably it tries both lines - at least sometimes.  Which one
does it try first?  When does it try both?  Which one wins when they
disagree?

Missing here is also a statement that the default for this regexp matches
a sequence of whitespace and punctuation characters, including matching
the empty string. 

> - User Option: adaptive-fill-first-line-regexp
    In a one-line paragraph, if the candidate fill prefix matches this
    regular expression, or if it matches `comment-start-skip', then it
    is used--otherwise, spaces amounting to the same width are used
    instead.

I could only get meaning from this paragraph with excessive effort.  And
having struggled to its meaning, it's not clear why this user option
needs to exist at all.

"this regular expression" is too far away from
"adaptive-fill-first-line-regexp" to be instantly recognisable as
referring to it.

In "or if it matches ...." it takes too much effort to work out that "it"
means the candidate prefix, not the regular expression.

In "..., then it is used", what is "it"?  There are three semantic
possibilities - again, it's too much hassle to work out which one ("the
candidate fill prefix") makes sense.

"--otherwise, ...." - Which <if> does this <else> match?  I don't think
it's "In a one-line paragraph" - more likely it's the combination of the
two following "if"s.   "...spaces amounting to the same width ...." -
same as what? - "... are used .." - used for what, exactly?  The fill
prefix for the first line?  The fill prefix for the entire paragraph?  Or
for the second line onwards?

>   However, the fill prefix is never taken from a one-line paragraph
>   if it would act as a paragraph starter on subsequent lines.

"it"?  How about "if that prefix would cause subsequent lines to become
paragraph starting lines themselves", or something like that?

>    - User Option: 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 `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. ....

"Appropriate" for what?  Appropriate for the current line, the entire
current paragraph, or line two onwards?  Is the function called with
point after the left margin of the first line, the second line, or what?
Must the function preserve point?  (Yes, it must.)

>    If it returns `nil', that means it sees no fill prefix in that line.

This is ambiguous - it should say either "it hasn't determined a fill
prefix from that line" or "that line/paragraph doesn't contain a usable
prefix".  I think the former is meant here.

-- 
Alan Mackenzie (Munich, Germany)

Re: Filling woes - documentation patch

[Alan Mackenzie]

Hi, Richard, Hi, Emacs!

On Fri, 20 May 2005, Richard Stallman wrote:

>I agree it would be better to try adaptive-fill-function first.  If it
>returns nil, the code should proceed to try the appropriate regexp.

OK.  The enclosed patch assumes this.

>As regards documenting precisely how these variables are used,
>that is hard because the code details were designed based
>on heuristics.

Too damn right, it's hard!  Nevertheless, I've made the attempt.  While
this patch isn't perfect, I think it's an improvement nevertheless.

2005-05-28  Alan Mackenzie  <acm@muc.de>

	* 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	Sat May 28 18:47:33 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 non-@code{nil}.
--- 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 non-@code{nil}.
***************
*** 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,1759 ----
  
  @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 the paragraph being filled.  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
  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
+ @w{@samp{"[ \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 @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 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

-- 
Alan Mackenzie (Munich, Germany)

Re: Filling woes - documentation patch

[Richard Stallman]

      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 the paragraph being filled.  It does

"end of a paragraph" would be more correct.

    + In detail, @code{fill-context-prefix} does this:

You need a blank line.  Constructs such as @enumerate are always
preceded by a blank line.

    + @enumerate
    + @item
    + It takes a candidate for the fill prefix from the first line - it

A dash is writen as `---' with no space around it.

Aside from that, the text is good.  Please install the text, correcting
these little points, and also change the code.

Don't forget to change etc/NEWS.

Re: Filling woes - code, documentation and NEWS patches

[Alan Mackenzie]

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  <acm@muc.de>

	* 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  <acm@muc.de>

	* 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 non-@code{nil}.
--- 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 non-@code{nil}.
***************
*** 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 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
  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
+ @w{@samp{"[ \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 @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 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)