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 - documentation patch Date: Sat, 28 May 2005 19:03:00 +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 1117312556 11572 80.91.229.2 (28 May 2005 20:35:56 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 28 May 2005 20:35:56 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat May 28 22:35:46 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Dc81Q-0006RF-P7 for ged-emacs-devel@m.gmane.org; Sat, 28 May 2005 22:35:05 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Dc85y-0004he-9N for ged-emacs-devel@m.gmane.org; Sat, 28 May 2005 16:39:46 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Dc85F-0004UM-Rd for emacs-devel@gnu.org; Sat, 28 May 2005 16:39:02 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Dc858-0004Qz-Di for emacs-devel@gnu.org; Sat, 28 May 2005 16:38:55 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Dc857-0004OX-05 for emacs-devel@gnu.org; Sat, 28 May 2005 16:38:53 -0400 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1Dc7xt-000706-DI for emacs-devel@gnu.org; Sat, 28 May 2005 16:31:27 -0400 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id TAA00466 for ; Sat, 28 May 2005 19:03:01 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:37835 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:37835 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 * 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)