diff options
Diffstat (limited to 'devdocs/elisp/filling.html')
| -rw-r--r-- | devdocs/elisp/filling.html | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/devdocs/elisp/filling.html b/devdocs/elisp/filling.html new file mode 100644 index 00000000..20db8230 --- /dev/null +++ b/devdocs/elisp/filling.html @@ -0,0 +1,54 @@ + <h3 class="section">Filling</h3> <p><em>Filling</em> means adjusting the lengths of lines (by moving the line breaks) so that they are nearly (but no greater than) a specified maximum width. Additionally, lines can be <em>justified</em>, which means inserting spaces to make the left and/or right margins line up precisely. The width is controlled by the variable <code>fill-column</code>. For ease of reading, lines should be no longer than 70 or so columns. </p> <p>You can use Auto Fill mode (see <a href="auto-filling">Auto Filling</a>) to fill text automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly. </p> <p>Most of the commands in this section return values that are not meaningful. All the functions that do filling take note of the current left margin, current right margin, and current justification style (see <a href="margins">Margins</a>). If the current justification style is <code>none</code>, the filling functions don’t actually do anything. </p> <p>Several of the filling functions have an argument <var>justify</var>. If it is non-<code>nil</code>, that requests some kind of justification. It can be <code>left</code>, <code>right</code>, <code>full</code>, or <code>center</code>, to request a specific style of justification. If it is <code>t</code>, that means to use the current justification style for this part of the text (see <code>current-justification</code>, below). Any other value is treated as <code>full</code>. </p> <p>When you call the filling functions interactively, using a prefix argument implies the value <code>full</code> for <var>justify</var>. </p> <dl> <dt id="fill-paragraph">Command: <strong>fill-paragraph</strong> <em>&optional justify region</em> +</dt> <dd> +<p>This command fills the paragraph at or after point. If <var>justify</var> is non-<code>nil</code>, each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Paragraphs.html#Paragraphs">Paragraphs</a> in <cite>The GNU Emacs Manual</cite>. </p> <p>When <var>region</var> is non-<code>nil</code>, then if Transient Mark mode is enabled and the mark is active, this command calls <code>fill-region</code> to fill all the paragraphs in the region, instead of filling only the current paragraph. When this command is called interactively, <var>region</var> is <code>t</code>. </p> +</dd> +</dl> <dl> <dt id="fill-region">Command: <strong>fill-region</strong> <em>start end &optional justify nosqueeze to-eop</em> +</dt> <dd> +<p>This command fills each of the paragraphs in the region from <var>start</var> to <var>end</var>. It justifies as well if <var>justify</var> is non-<code>nil</code>. </p> <p>If <var>nosqueeze</var> is non-<code>nil</code>, that means to leave whitespace other than line breaks untouched. If <var>to-eop</var> is non-<code>nil</code>, that means to keep filling to the end of the paragraph—or the next hard newline, if <code>use-hard-newlines</code> is enabled (see below). </p> <p>The variable <code>paragraph-separate</code> controls how to distinguish paragraphs. See <a href="standard-regexps">Standard Regexps</a>. </p> +</dd> +</dl> <dl> <dt id="fill-individual-paragraphs">Command: <strong>fill-individual-paragraphs</strong> <em>start end &optional justify citation-regexp</em> +</dt> <dd> +<p>This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented with spaces, the filled paragraph will remain indented in the same fashion. </p> <p>The first two arguments, <var>start</var> and <var>end</var>, are the beginning and end of the region to be filled. The third and fourth arguments, <var>justify</var> and <var>citation-regexp</var>, are optional. If <var>justify</var> is non-<code>nil</code>, the paragraphs are justified as well as filled. If <var>citation-regexp</var> is non-<code>nil</code>, it means the function is operating on a mail message and therefore should not fill the header lines. If <var>citation-regexp</var> is a string, it is used as a regular expression; if it matches the beginning of a line, that line is treated as a citation marker. </p> <p>Ordinarily, <code>fill-individual-paragraphs</code> regards each change in indentation as starting a new paragraph. If <code>fill-individual-varying-indent</code> is non-<code>nil</code>, then only separator lines separate paragraphs. That mode can handle indented paragraphs with additional indentation on the first line. </p> +</dd> +</dl> <dl> <dt id="fill-individual-varying-indent">User Option: <strong>fill-individual-varying-indent</strong> +</dt> <dd><p>This variable alters the action of <code>fill-individual-paragraphs</code> as described above. </p></dd> +</dl> <dl> <dt id="fill-region-as-paragraph">Command: <strong>fill-region-as-paragraph</strong> <em>start end &optional justify nosqueeze squeeze-after</em> +</dt> <dd> +<p>This command considers a region of text as a single paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as filling when <var>justify</var> is non-<code>nil</code>. </p> <p>If <var>nosqueeze</var> is non-<code>nil</code>, that means to leave whitespace other than line breaks untouched. If <var>squeeze-after</var> is non-<code>nil</code>, it specifies a position in the region, and means that whitespace other than line breaks should be left untouched before that position. </p> <p>In Adaptive Fill mode, this command calls <code>fill-context-prefix</code> to choose a fill prefix by default. See <a href="adaptive-fill">Adaptive Fill</a>. </p> +</dd> +</dl> <dl> <dt id="justify-current-line">Command: <strong>justify-current-line</strong> <em>&optional how eop nosqueeze</em> +</dt> <dd> +<p>This command inserts spaces between the words of the current line so that the line ends exactly at <code>fill-column</code>. It returns <code>nil</code>. </p> <p>The argument <var>how</var>, if non-<code>nil</code> specifies explicitly the style of justification. It can be <code>left</code>, <code>right</code>, <code>full</code>, <code>center</code>, or <code>none</code>. If it is <code>t</code>, that means to follow specified justification style (see <code>current-justification</code>, below). <code>nil</code> means to do full justification. </p> <p>If <var>eop</var> is non-<code>nil</code>, that means do only left-justification if <code>current-justification</code> specifies full justification. This is used for the last line of a paragraph; even if the paragraph as a whole is fully justified, the last line should not be. </p> <p>If <var>nosqueeze</var> is non-<code>nil</code>, that means do not change interior whitespace. </p> +</dd> +</dl> <dl> <dt id="default-justification">User Option: <strong>default-justification</strong> +</dt> <dd><p>This variable’s value specifies the style of justification to use for text that doesn’t specify a style with a text property. The possible values are <code>left</code>, <code>right</code>, <code>full</code>, <code>center</code>, or <code>none</code>. The default value is <code>left</code>. </p></dd> +</dl> <dl> <dt id="current-justification">Function: <strong>current-justification</strong> +</dt> <dd> +<p>This function returns the proper justification style to use for filling the text around point. </p> <p>This returns the value of the <code>justification</code> text property at point, or the variable <code>default-justification</code> if there is no such text property. However, it returns <code>nil</code> rather than <code>none</code> to mean “don’t justify”. </p> +</dd> +</dl> <dl> <dt id="sentence-end-double-space">User Option: <strong>sentence-end-double-space</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, a period followed by just one space does not count as the end of a sentence, and the filling functions avoid breaking the line at such a place. </p> +</dd> +</dl> <dl> <dt id="sentence-end-without-period">User Option: <strong>sentence-end-without-period</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, a sentence can end without a period. This is used for languages like Thai, where sentences end with a double space but without a period. </p></dd> +</dl> <dl> <dt id="sentence-end-without-space">User Option: <strong>sentence-end-without-space</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, it should be a string of characters that can end a sentence without following spaces. </p></dd> +</dl> <dl> <dt id="fill-separate-heterogeneous-words-with-space">User Option: <strong>fill-separate-heterogeneous-words-with-space</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, two words of different kind (e.g., English and CJK) will be separated with a space when concatenating one that is in the end of a line and the other that is in the beginning of the next line for filling. </p></dd> +</dl> <dl> <dt id="fill-paragraph-function">Variable: <strong>fill-paragraph-function</strong> +</dt> <dd> +<p>This variable provides a way to override the filling of paragraphs. If its value is non-<code>nil</code>, <code>fill-paragraph</code> calls this function to do the work. If the function returns a non-<code>nil</code> value, <code>fill-paragraph</code> assumes the job is done, and immediately returns that value. </p> <p>The usual use of this feature is to fill comments in programming language modes. If the function needs to fill a paragraph in the usual way, it can do so as follows: </p> <div class="example"> <pre class="example">(let ((fill-paragraph-function nil)) + (fill-paragraph arg)) +</pre> +</div> </dd> +</dl> <dl> <dt id="fill-forward-paragraph-function">Variable: <strong>fill-forward-paragraph-function</strong> +</dt> <dd><p>This variable provides a way to override how the filling functions, such as <code>fill-region</code> and <code>fill-paragraph</code>, move forward to the next paragraph. Its value should be a function, which is called with a single argument <var>n</var>, the number of paragraphs to move, and should return the difference between <var>n</var> and the number of paragraphs actually moved. The default value of this variable is <code>forward-paragraph</code>. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Paragraphs.html#Paragraphs">Paragraphs</a> in <cite>The GNU Emacs Manual</cite>. </p></dd> +</dl> <dl> <dt id="use-hard-newlines">Variable: <strong>use-hard-newlines</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, the filling functions do not delete newlines that have the <code>hard</code> text property. These hard newlines act as paragraph separators. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Hard-and-Soft-Newlines.html#Hard-and-Soft-Newlines">Hard and Soft Newlines</a> in <cite>The GNU Emacs Manual</cite>. </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/Filling.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Filling.html</a> + </p> +</div> |