1667 |
@section Adaptive Fill Mode |
@section Adaptive Fill Mode |
1668 |
@cindex Adaptive Fill mode |
@cindex Adaptive Fill mode |
1669 |
|
|
1670 |
Adaptive Fill mode chooses a fill prefix automatically from the text |
When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill |
1671 |
in each paragraph being filled. |
prefix automatically from the text in each paragraph being filled |
1672 |
|
rather than using a predetermined value. During filling, this fill |
1673 |
|
prefix gets inserted at the start of the second and subsequent lines |
1674 |
|
of the paragraph as described in @ref{Filling}, and in @ref{Auto |
1675 |
|
Filling}. |
1676 |
|
|
1677 |
@defopt adaptive-fill-mode |
@defopt adaptive-fill-mode |
1678 |
Adaptive Fill mode is enabled when this variable is non-@code{nil}. |
Adaptive Fill mode is enabled when this variable is non-@code{nil}. |
1681 |
|
|
1682 |
@defun fill-context-prefix from to |
@defun fill-context-prefix from to |
1683 |
This function implements the heart of Adaptive Fill mode; it chooses a |
This function implements the heart of Adaptive Fill mode; it chooses a |
1684 |
fill prefix based on the text between @var{from} and @var{to}. It does |
fill prefix based on the text between @var{from} and @var{to}, |
1685 |
this by looking at the first two lines of the paragraph, based on the |
typically the start and end of a paragraph. It does this by looking |
1686 |
variables described below. |
at the first two lines of the paragraph, based on the variables |
1687 |
|
described below. |
1688 |
@c The optional argument first-line-regexp is not documented |
@c The optional argument first-line-regexp is not documented |
1689 |
@c because it exists for internal purposes and might be eliminated |
@c because it exists for internal purposes and might be eliminated |
1690 |
@c in the future. |
@c in the future. |
1691 |
|
|
1692 |
|
Usually, this function returns the fill prefix, a string. However, |
1693 |
|
before doing this, the function makes a final check (not specially |
1694 |
|
mentioned in the following) that a line starting with this prefix |
1695 |
|
wouldn't look like the start of a paragraph. Should this happen, the |
1696 |
|
function signals the anomaly by returning @code{nil} instead. |
1697 |
|
|
1698 |
|
In detail, @code{fill-context-prefix} does this: |
1699 |
|
|
1700 |
|
@enumerate |
1701 |
|
@item |
1702 |
|
It takes a candidate for the fill prefix from the first line---it |
1703 |
|
tries first the function in @code{adaptive-fill-function} (if any), |
1704 |
|
then the regular expression @code{adaptive-fill-regexp} (see below). |
1705 |
|
The first non-@code{nil} result of these, or the empty string if |
1706 |
|
they're both @code{nil}, becomes the first line's candidate. |
1707 |
|
@item |
1708 |
|
If the paragraph has as yet only one line, the function tests the |
1709 |
|
validity of the prefix candidate just found. The function then |
1710 |
|
returns the candidate if it's valid, or a string of spaces otherwise. |
1711 |
|
(see the description of @code{adaptive-fill-first-line-regexp} below). |
1712 |
|
@item |
1713 |
|
When the paragraph already has two lines, the function next looks for |
1714 |
|
a prefix candidate on the second line, in just the same way it did for |
1715 |
|
the first line. If it doesn't find one, it returns @code{nil}. |
1716 |
|
@item |
1717 |
|
The function now compares the two candidate prefixes heuristically: if |
1718 |
|
the non-whitespace characters in the line 2 candidate occur in the |
1719 |
|
same order in the line 1 candidate, the function returns the line 2 |
1720 |
|
candidate. Otherwise, it returns the largest initial substring which |
1721 |
|
is common to both candidates (which might be the empty string). |
1722 |
|
@end enumerate |
1723 |
@end defun |
@end defun |
1724 |
|
|
1725 |
@defopt adaptive-fill-regexp |
@defopt adaptive-fill-regexp |
|
This variable holds a regular expression to control Adaptive Fill mode. |
|
1726 |
Adaptive Fill mode matches this regular expression against the text |
Adaptive Fill mode matches this regular expression against the text |
1727 |
starting after the left margin whitespace (if any) on a line; the |
starting after the left margin whitespace (if any) on a line; the |
1728 |
characters it matches are that line's candidate for the fill prefix. |
characters it matches are that line's candidate for the fill prefix. |
1729 |
|
|
1730 |
|
The default value of this variable is |
1731 |
|
@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}. This |
1732 |
|
matches a number enclosed in parentheses or followed by a period, |
1733 |
|
or certain punctuation characters, or any sequence of these |
1734 |
|
intermingled with whitespace. In particular, it matches a sequence of |
1735 |
|
whitespace, possibly empty. |
1736 |
@end defopt |
@end defopt |
1737 |
|
|
1738 |
@defopt adaptive-fill-first-line-regexp |
@defopt adaptive-fill-first-line-regexp |
1739 |
In a one-line paragraph, if the candidate fill prefix matches this |
Used only in one-line paragraphs, this regular expression acts as an |
1740 |
regular expression, or if it matches @code{comment-start-skip}, then it |
additional check of the validity of the one available candidate fill |
1741 |
is used---otherwise, spaces amounting to the same width are used |
prefix: the candidate must match this regular expression, or match |
1742 |
instead. |
@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} |
1743 |
|
replaces the candidate with a string of spaces ``of the same width'' |
1744 |
However, the fill prefix is never taken from a one-line paragraph |
as it. |
1745 |
if it would act as a paragraph starter on subsequent lines. |
|
1746 |
|
The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which |
1747 |
|
matches only a string of whitespace. The effect of this default is to |
1748 |
|
force the fill prefixes found in one-line paragraphs always to be pure |
1749 |
|
whitespace. |
1750 |
@end defopt |
@end defopt |
1751 |
|
|
1752 |
@defopt adaptive-fill-function |
@defopt adaptive-fill-function |
1753 |
You can specify more complex ways of choosing a fill prefix |
You can specify more complex ways of choosing a fill prefix |
1754 |
automatically by setting this variable to a function. The function is |
automatically by setting this variable to a function. The function is |
1755 |
called when @code{adaptive-fill-regexp} does not match, with point after |
called with point after the left margin (if any) of a line, and it |
1756 |
the left margin of a line, and it should return the appropriate fill |
must preserve point. It should return either ``that line's'' fill |
1757 |
prefix based on that line. If it returns @code{nil}, that means it sees |
prefix or @code{nil}, meaning it has failed to determine a prefix. |
|
no fill prefix in that line. |
|
1758 |
@end defopt |
@end defopt |
1759 |
|
|
1760 |
@node Auto Filling |
@node Auto Filling |