From: Alan Mackenzie <acm@muc.de>
Subject: Re: Filling woes - documentation patch
Date: Sat, 28 May 2005 19:03:00 +0000 (GMT) [thread overview]
Message-ID: <Pine.LNX.3.96.1050528185000.457A-100000@acm.acm> (raw)
In-Reply-To: <E1DZFUb-0003yK-Gy@fencepost.gnu.org>
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)
next prev parent reply other threads:[~2005-05-28 19:03 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` Alan Mackenzie [this message]
2005-05-29 12:04 ` Filling woes - documentation patch Richard Stallman
2005-05-29 19:56 ` Filling woes - code, documentation and NEWS patches Alan Mackenzie
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Pine.LNX.3.96.1050528185000.457A-100000@acm.acm \
--to=acm@muc.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.