diff options
Diffstat (limited to 'devdocs/elisp/adaptive-fill.html')
| -rw-r--r-- | devdocs/elisp/adaptive-fill.html | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/devdocs/elisp/adaptive-fill.html b/devdocs/elisp/adaptive-fill.html new file mode 100644 index 00000000..cd0a39fb --- /dev/null +++ b/devdocs/elisp/adaptive-fill.html @@ -0,0 +1,25 @@ + <h3 class="section">Adaptive Fill Mode</h3> <p>When <em>Adaptive Fill Mode</em> 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 <a href="filling">Filling</a>, and in <a href="auto-filling">Auto Filling</a>. </p> <dl> <dt id="adaptive-fill-mode">User Option: <strong>adaptive-fill-mode</strong> +</dt> <dd><p>Adaptive Fill mode is enabled when this variable is non-<code>nil</code>. It is <code>t</code> by default. </p></dd> +</dl> <dl> <dt id="fill-context-prefix">Function: <strong>fill-context-prefix</strong> <em>from to</em> +</dt> <dd> +<p>This function implements the heart of Adaptive Fill mode; it chooses a fill prefix based on the text between <var>from</var> and <var>to</var>, typically the start and end of a paragraph. It does this by looking at the first two lines of the paragraph, based on the variables described below. </p> <p>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</code> instead. </p> <p>In detail, <code>fill-context-prefix</code> does this: </p> <ol> <li> It takes a candidate for the fill prefix from the first line—it tries first the function in <code>adaptive-fill-function</code> (if any), then the regular expression <code>adaptive-fill-regexp</code> (see below). The first non-<code>nil</code> result of these, or the empty string if they’re both <code>nil</code>, becomes the first line’s candidate. </li> +<li> 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</code> below). </li> +<li> 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</code>. </li> +<li> 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). </li> +</ol> </dd> +</dl> <dl> <dt id="adaptive-fill-regexp">User Option: <strong>adaptive-fill-regexp</strong> +</dt> <dd> +<p>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. </p> <p>The default value matches whitespace with certain punctuation characters intermingled. </p> +</dd> +</dl> <dl> <dt id="adaptive-fill-first-line-regexp">User Option: <strong>adaptive-fill-first-line-regexp</strong> +</dt> <dd> +<p>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</code>. If it doesn’t, <code>fill-context-prefix</code> replaces the candidate with a string of spaces of the same width as it. </p> <p>The default value of this variable is <code>"\\`[ \t]*\\'"</code>, 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. </p> +</dd> +</dl> <dl> <dt id="adaptive-fill-function">User Option: <strong>adaptive-fill-function</strong> +</dt> <dd><p>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</code>, meaning it has failed to determine a prefix. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Adaptive-Fill.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Adaptive-Fill.html</a> + </p> +</div> |