Re: Filling woes - code, documentation and NEWS patches

[Alan Mackenzie <acm@muc.de>]

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)