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 Date: Mon, 23 May 2005 22:32:17 +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 1116887373 8433 80.91.229.2 (23 May 2005 22:29:33 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 23 May 2005 22:29:33 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue May 24 00:29:24 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1DaLP7-000587-Vp for ged-emacs-devel@m.gmane.org; Tue, 24 May 2005 00:28:10 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DaLSf-0000Vm-9I for ged-emacs-devel@m.gmane.org; Mon, 23 May 2005 18:31:49 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1DaLR9-0007bP-Fg for emacs-devel@gnu.org; Mon, 23 May 2005 18:30:15 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1DaLR2-0007YN-QO for emacs-devel@gnu.org; Mon, 23 May 2005 18:30:10 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DaLR2-0007Y1-M8 for emacs-devel@gnu.org; Mon, 23 May 2005 18:30:08 -0400 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1DaLOr-0001MI-D8 for emacs-devel@gnu.org; Mon, 23 May 2005 18:27:54 -0400 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id WAA00481 for ; Mon, 23 May 2005 22:32:18 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:37525 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:37525 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 does this 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)