emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Filling woes


From: Alan Mackenzie
Subject: Re: Filling woes
Date: Mon, 23 May 2005 22:32:17 +0000 (GMT)


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)







reply via email to

[Prev in Thread] Current Thread [Next in Thread]