procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of filling and justification commands

Browse source 
* doc/lispref/text.texi (Filling):
* lisp/textmodes/fill.el (fill-region-as-paragraph)
(default-justification, set-justification, justify-current-line):
Clarify "canonicalization" of spaces and the meaning of
justification styles.  (Bug#54047)
(set-justification-left, set-justification-right)
(set-justification-full): Improve wording of doc strings.
This commit is contained in:
Eli Zaretskii 2022-02-18 09:47:44 +02:00
parent 9fd396e4d0
commit 1e4b04c540
2 changed files with 34 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

5
doc/lispref/text.texi
View file

@ -1670,8 +1670,9 @@ filling when @var{justify} is non-@code{nil}.
If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
other than line breaks untouched. If @var{squeeze-after} is other than line breaks untouched. If @var{squeeze-after} is
non-@code{nil}, it specifies a position in the region, and means don't non-@code{nil}, it specifies a position in the region, and means
canonicalize spaces before that position. that whitespace other than line breaks should be left untouched before
that position.
In Adaptive Fill mode, this command calls @code{fill-context-prefix} to In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
choose a fill prefix by default. @xref{Adaptive Fill}. choose a fill prefix by default. @xref{Adaptive Fill}.

47
lisp/textmodes/fill.el
View file

@ -648,20 +648,27 @@ The break position will be always after LINEBEG and generally before point."
(defun fill-region-as-paragraph (from to &optional justify (defun fill-region-as-paragraph (from to &optional justify
nosqueeze squeeze-after) nosqueeze squeeze-after)
"Fill the region as one paragraph. "Fill the region as if it were a single paragraph.
It removes any paragraph breaks in the region and extra newlines at the end, This command removes any paragraph breaks in the region and
indents and fills lines between the margins given by the extra newlines at the end, and indents and fills lines between the
`current-left-margin' and `current-fill-column' functions. margins given by the `current-left-margin' and `current-fill-column'
\(In most cases, the variable `fill-column' controls the width.) functions. (In most cases, the variable `fill-column' controls the
It leaves point at the beginning of the line following the paragraph. width.) It leaves point at the beginning of the line following the
region.
Normally performs justification according to the `current-justification' Normally, the command performs justification according to
function, but with a prefix arg, does full justification instead. the `current-justification' function, but with a prefix arg, it
does full justification instead.
From a program, optional third arg JUSTIFY can specify any type of When called from Lisp, optional third arg JUSTIFY can specify any
justification. Fourth arg NOSQUEEZE non-nil means not to make spaces type of justification; see `default-justification' for the possible
between words canonical before filling. Fifth arg SQUEEZE-AFTER, if non-nil, values.
means don't canonicalize spaces before that position. Optional fourth arg NOSQUEEZE non-nil means not to make spaces
between words canonical before filling.
Fifth arg SQUEEZE-AFTER, if non-nil, should be a buffer position; it
means canonicalize spaces only starting from that position.
See `canonically-space-region' for the meaning of canonicalization
of spaces.
Return the `fill-prefix' used for filling. Return the `fill-prefix' used for filling.
@ -1104,6 +1111,10 @@ space does not end a sentence, so don't break a line there."
(defcustom default-justification 'left (defcustom default-justification 'left
"Method of justifying text not otherwise specified. "Method of justifying text not otherwise specified.
Possible values are `left', `right', `full', `center', or `none'. Possible values are `left', `right', `full', `center', or `none'.
The values `left' and `right' mean lines are lined up at,
respectively, left or right margin, and ragged at the other margin.
`full' means lines are lined up at both margins. `center' means each
line is centered. `none' means no justification or centering.
The requested kind of justification is done whenever lines are filled. The requested kind of justification is done whenever lines are filled.
The `justification' text-property can locally override this variable." The `justification' text-property can locally override this variable."
:type '(choice (const left) :type '(choice (const left)
@ -1133,6 +1144,7 @@ However, it returns nil rather than `none' to mean \"don't justify\"."
(defun set-justification (begin end style &optional whole-par) (defun set-justification (begin end style &optional whole-par)
"Set the region's justification style to STYLE. "Set the region's justification style to STYLE.
This commands prompts for the kind of justification to use. This commands prompts for the kind of justification to use.
See `default-justification' for the possible values and their meaning.
If the mark is not active, this command operates on the current paragraph. If the mark is not active, this command operates on the current paragraph.
If the mark is active, it operates on the region. However, if the If the mark is active, it operates on the region. However, if the
beginning and end of the region are not at paragraph breaks, they are beginning and end of the region are not at paragraph breaks, they are
@ -1184,7 +1196,8 @@ If the mark is not active, this applies to the current paragraph."
(defun set-justification-left (b e) (defun set-justification-left (b e)
"Make paragraphs in the region left-justified. "Make paragraphs in the region left-justified.
This means they are flush at the left margin and ragged on the right. This means lines are flush (lined up) at the left margin and ragged
on the right.
This is usually the default, but see the variable `default-justification'. This is usually the default, but see the variable `default-justification'.
If the mark is not active, this applies to the current paragraph." If the mark is not active, this applies to the current paragraph."
(interactive (list (if mark-active (region-beginning) (point)) (interactive (list (if mark-active (region-beginning) (point))
@ -1193,7 +1206,8 @@ If the mark is not active, this applies to the current paragraph."
(defun set-justification-right (b e) (defun set-justification-right (b e)
"Make paragraphs in the region right-justified. "Make paragraphs in the region right-justified.
This means they are flush at the right margin and ragged on the left. This means lines are flush (lined up) at the right margin and ragged
on the left.
If the mark is not active, this applies to the current paragraph." If the mark is not active, this applies to the current paragraph."
(interactive (list (if mark-active (region-beginning) (point)) (interactive (list (if mark-active (region-beginning) (point))
(if mark-active (region-end) (point)))) (if mark-active (region-end) (point))))
@ -1201,7 +1215,7 @@ If the mark is not active, this applies to the current paragraph."
(defun set-justification-full (b e) (defun set-justification-full (b e)
"Make paragraphs in the region fully justified. "Make paragraphs in the region fully justified.
This makes lines flush on both margins by inserting spaces between words. This makes lines be lined up on both margins by inserting spaces between words.
If the mark is not active, this applies to the current paragraph." If the mark is not active, this applies to the current paragraph."
(interactive (list (if mark-active (region-beginning) (point)) (interactive (list (if mark-active (region-beginning) (point))
(if mark-active (region-end) (point)))) (if mark-active (region-end) (point))))
@ -1236,7 +1250,8 @@ If the mark is not active, this applies to the current paragraph."
Normally does full justification: adds spaces to the line to make it end at Normally does full justification: adds spaces to the line to make it end at
the column given by `current-fill-column'. the column given by `current-fill-column'.
Optional first argument HOW specifies alternate type of justification: Optional first argument HOW specifies alternate type of justification:
it can be `left', `right', `full', `center', or `none'. it can be `left', `right', `full', `center', or `none'; for their
meaning, see `default-justification'.
If HOW is t, will justify however the `current-justification' function says to. If HOW is t, will justify however the `current-justification' function says to.
If HOW is nil or missing, full justification is done by default. If HOW is nil or missing, full justification is done by default.
Second arg EOP non-nil means that this is the last line of the paragraph, so Second arg EOP non-nil means that this is the last line of the paragraph, so