From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Filling woes - code, documentation and NEWS patches Date: Sun, 29 May 2005 19:56:21 +0000 (GMT) Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1117398129 18939 80.91.229.2 (29 May 2005 20:22:09 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 29 May 2005 20:22:09 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun May 29 22:21:23 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1DcTrJ-0008Ve-CS for ged-emacs-devel@m.gmane.org; Sun, 29 May 2005 21:54:06 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DcTw2-0005Je-8Y for ged-emacs-devel@m.gmane.org; Sun, 29 May 2005 15:58:58 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1DcTvq-0005IS-SL for emacs-devel@gnu.org; Sun, 29 May 2005 15:58:47 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1DcTvn-0005Gn-Ph for emacs-devel@gnu.org; Sun, 29 May 2005 15:58:44 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DcTvn-0005GN-KZ for emacs-devel@gnu.org; Sun, 29 May 2005 15:58:43 -0400 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1DcTrY-0001cw-1A for emacs-devel@gnu.org; Sun, 29 May 2005 15:54:22 -0400 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id TAA00782 for ; Sun, 29 May 2005 19:56:22 GMT X-Sender: root@acm.acm Original-To: emacs-devel@gnu.org In-Reply-To: X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:37864 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:37864 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 * 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 * 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)