* Filling woes @ 2005-05-17 20:20 Alan Mackenzie 2005-05-19 1:31 ` Stefan Monnier 2005-05-20 21:57 ` Richard Stallman 0 siblings, 2 replies; 9+ messages in thread From: Alan Mackenzie @ 2005-05-17 20:20 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes 2005-05-17 20:20 Filling woes Alan Mackenzie @ 2005-05-19 1:31 ` Stefan Monnier 2005-05-20 21:57 ` Richard Stallman 1 sibling, 0 replies; 9+ messages in thread From: Stefan Monnier @ 2005-05-19 1:31 UTC (permalink / raw) Cc: emacs-devel > 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes 2005-05-17 20:20 Filling woes Alan Mackenzie 2005-05-19 1:31 ` Stefan Monnier @ 2005-05-20 21:57 ` Richard Stallman 2005-05-20 22:20 ` David Kastrup ` (2 more replies) 1 sibling, 3 replies; 9+ messages in thread From: Richard Stallman @ 2005-05-20 21:57 UTC (permalink / raw) Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes 2005-05-20 21:57 ` Richard Stallman @ 2005-05-20 22:20 ` David Kastrup 2005-05-22 1:00 ` Richard Stallman 2005-05-23 22:32 ` Alan Mackenzie 2005-05-28 19:03 ` Filling woes - documentation patch Alan Mackenzie 2 siblings, 1 reply; 9+ messages in thread From: David Kastrup @ 2005-05-20 22:20 UTC (permalink / raw) Cc: Alan Mackenzie, emacs-devel 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes 2005-05-20 22:20 ` David Kastrup @ 2005-05-22 1:00 ` Richard Stallman 0 siblings, 0 replies; 9+ messages in thread From: Richard Stallman @ 2005-05-22 1:00 UTC (permalink / raw) Cc: acm, emacs-devel 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes 2005-05-20 21:57 ` Richard Stallman 2005-05-20 22:20 ` David Kastrup @ 2005-05-23 22:32 ` Alan Mackenzie 2005-05-28 19:03 ` Filling woes - documentation patch Alan Mackenzie 2 siblings, 0 replies; 9+ messages in thread From: Alan Mackenzie @ 2005-05-23 22:32 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes - documentation patch 2005-05-20 21:57 ` Richard Stallman 2005-05-20 22:20 ` David Kastrup 2005-05-23 22:32 ` Alan Mackenzie @ 2005-05-28 19:03 ` Alan Mackenzie 2005-05-29 12:04 ` Richard Stallman 2 siblings, 1 reply; 9+ messages in thread From: Alan Mackenzie @ 2005-05-28 19:03 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes - documentation patch 2005-05-28 19:03 ` Filling woes - documentation patch Alan Mackenzie @ 2005-05-29 12:04 ` Richard Stallman 2005-05-29 19:56 ` Filling woes - code, documentation and NEWS patches Alan Mackenzie 0 siblings, 1 reply; 9+ messages in thread From: Richard Stallman @ 2005-05-29 12:04 UTC (permalink / raw) Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Filling woes - code, documentation and NEWS patches 2005-05-29 12:04 ` Richard Stallman @ 2005-05-29 19:56 ` Alan Mackenzie 0 siblings, 0 replies; 9+ messages in thread From: Alan Mackenzie @ 2005-05-29 19:56 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2005-05-29 19:56 UTC | newest] Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2005-05-17 20:20 Filling woes Alan Mackenzie 2005-05-19 1:31 ` Stefan Monnier 2005-05-20 21:57 ` Richard Stallman 2005-05-20 22:20 ` David Kastrup 2005-05-22 1:00 ` Richard Stallman 2005-05-23 22:32 ` Alan Mackenzie 2005-05-28 19:03 ` Filling woes - documentation patch Alan Mackenzie 2005-05-29 12:04 ` Richard Stallman 2005-05-29 19:56 ` Filling woes - code, documentation and NEWS patches Alan Mackenzie
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).