/[emacs]/emacs/lispref/text.texi
ViewVC logotype

Diff of /emacs/lispref/text.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.98 by rms, Tue Mar 29 21:08:19 2005 UTC revision 1.99 by eliz, Sat Jun 11 13:53:34 2005 UTC
# Line 1667  line won't be broken there. Line 1667  line won't be broken there.
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}.
# Line 1677  It is @code{t} by default. Line 1681  It is @code{t} by default.
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

Legend:
Removed from v.1.98  
changed lines
  Added in v.1.99

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26