[PATCH] Enhance the use of prefix arguments when filling text

[PATCH] Enhance the use of prefix arguments when filling text

[Phil Sainty]

[-- Attachment #1: Type: text/plain, Size: 1730 bytes --]

This patch enables the use of a numeric prefix argument to select a
one-time `fill-column' value, over-riding the value for that call.

It takes effect before the main fill loop in `fill-region-as-paragraph'
(which is ultimately used by all the other fill commands), by which time
the likes of `emacs-lisp-docstring-fill-column' have already been dealt
with, and won't clobber the prefix value.

A prefix argument of `-' now means "un-fill" (turning multiple lines
into a single long line), by using most-positive-fixnum as the
fill-column for that call.

All fill commands accept a JUSTIFY argument, and at present a prefix
argument of any kind always simply means JUSTIFY is 'full. As that
interactive behaviour is implemented independently by each command,
this patch necessarily changes the interactive argument handling for
each fill command, to prevent them from justifying when we are just
setting a fill column.

With the patch, negative numeric arguments now mean JUSTIFY using the
specified fill column.

In all cases a plain C-u still means (only) JUSTIFY.

A new user option `fill-interactive-prefix-type' determines whether or
not the new behaviour is used.  There is a setting to revert to the
original behaviour (where any prefix argument means JUSTIFY), and also
a hybrid setting to combine the old and new behaviours in a practical
manner.

This initial patch addresses only the commands in fill.el itself, but
changes for other fill commands ought to follow a similar pattern.

The patch is also missing documentation changes to the modified commands
and to the info manuals, but I'm sending it as-is for review of the
general idea and implementation.

The patch was rolled against the emacs-25 branch.


-Phil


[-- Attachment #2: 0001-Enhance-use-of-prefix-arguments-when-filling-text.patch --]
[-- Type: text/x-patch, Size: 6302 bytes --]

From acbbc93a4efb33850dbe5e7a42c4c237962fe354 Mon Sep 17 00:00:00 2001
From: Phil Sainty <psainty@orcon.net.nz>
Date: Sat, 12 Nov 2016 22:31:53 +1300
Subject: [PATCH] Enhance the use of prefix arguments when filling text

* lisp/textmodes/fill.el (fill-region-as-paragraph): Modify fill-column
locally, based on the interactive prefix argument.
(fill-interactive-prefix-type): New user option.
(fill-interactive-column, fill-interactive-justify-arg): New functions.
(fill-region-as-paragraph, fill-paragraph, fill-region,
fill-nonuniform-paragraphs, fill-individual-paragraphs): Change how
interactive JUSTIFY argument is calculated.
---
 lisp/textmodes/fill.el | 94 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 88 insertions(+), 6 deletions(-)

diff --git a/lisp/textmodes/fill.el b/lisp/textmodes/fill.el
index 100e2a2..788546a 100644
--- a/lisp/textmodes/fill.el
+++ b/lisp/textmodes/fill.el
@@ -618,6 +618,87 @@ fill-indent-to-left-margin
     (indent-line-to (current-left-margin))
     (put-text-property beg (point) 'face 'default)))
 
+(defcustom fill-interactive-prefix-type 'column-and-justify
+  "Determines how fill commands interpret a prefix argument.
+
+Under the default `column-and-justify' setting, a plain C-u
+argument sets the JUSTIFY argument; a positive numeric argument
+specifies `fill-column' for the duration of the command; a
+negative numeric argument specifies both a `fill-column' value
+and JUSTIFY together; and a plain `-' argument causes the text to
+be 'un-filled' into a single line.  Temporary fill-column values
+are displayed in the echo area.  A numeric prefix argument of
+zero does not modify the fill-column, but also causes the current
+value to be displayed.
+
+The `justify' setting is the original behaviour, where any prefix
+argument simply means JUSTIFY.
+
+The `hybrid' setting behaves like `column-and-justify' with the
+exception of single-digit numeric arguments, which mean JUSTIFY.
+Because fill-columns of less than 10 are unlikely to be useful,
+this setting provides the new features while still enabling the
+use of a numeric prefix argument to mean JUSTIFY for users who
+were used to doing that."
+  :type '(choice (const :tag "Fill-column and/or justify" column-and-justify)
+		 (const :tag "Justify only" justify)
+		 (const :tag "Hybrid" hybrid))
+  :safe 'symbolp
+  :group 'fill)
+
+(defun fill-interactive-justify-arg ()
+  "Determine the JUSTIFY argument for the current fill command
+based on the interactive `current-prefix-arg', and the user
+option `fill-interactive-prefix-type'.
+
+Called in the interactive forms of fill commands.
+
+Returns either 'full or nil in all cases."
+  (cond
+   ;; column-and-justify
+   ((eq fill-interactive-prefix-type 'column-and-justify)
+    (if (or (consp current-prefix-arg)
+	    (and (integerp current-prefix-arg)
+		 (< current-prefix-arg 0)))
+	'full))
+   ;; hybrid
+   ((eq fill-interactive-prefix-type 'hybrid)
+    (if (or (consp current-prefix-arg)
+	    (and (integerp current-prefix-arg)
+		 (< current-prefix-arg 10)))
+	'full))
+   ;; justify
+   ((eq fill-interactive-prefix-type 'justify)
+    (if current-prefix-arg 'full))))
+
+(defun fill-interactive-column (col)
+  "Return column COL, modified based on the current prefix arg
+and the user option `fill-interactive-prefix-type'.
+
+`fill-region-as-paragraph' let-binds `fill-column' to this value."
+  (cond
+   ;; justify (do nothing; ignore remaining conditions)
+   ((eq fill-interactive-prefix-type 'justify))
+   ;; un-fill
+   ((eq current-prefix-arg '-)
+    (setq col most-positive-fixnum)
+    (message "Un-filling"))
+   ;; column-and-justify
+   ((and (eq fill-interactive-prefix-type 'column-and-justify)
+	 (integerp current-prefix-arg))
+    (unless (eq 0 current-prefix-arg)
+      (setq col (abs current-prefix-arg)))
+    (message "Using fill column %d" col))
+   ;; hybrid
+   ((and (eq fill-interactive-prefix-type 'hybrid)
+	 (integerp current-prefix-arg)
+	 (or (> current-prefix-arg 9)
+	     (< current-prefix-arg 0)))
+    (setq col (abs current-prefix-arg))
+    (message "Using fill column %d" col)))
+  ;; return the column, possibly unchanged.
+  col)
+
 (defun fill-region-as-paragraph (from to &optional justify
 				      nosqueeze squeeze-after)
   "Fill the region as one paragraph.
@@ -642,7 +723,7 @@ fill-region-as-paragraph
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (region-beginning) (region-end)
-		       (if current-prefix-arg 'full))))
+		       (fill-interactive-justify-arg))))
   (unless (memq justify '(t nil none full center left right))
     (setq justify 'full))
 
@@ -726,7 +807,8 @@ fill-region-as-paragraph
 
 	;; This is the actual filling loop.
 	(goto-char from)
-	(let (linebeg)
+	(let ((fill-column (fill-interactive-column fill-column))
+	      linebeg)
 	  (while (< (point) to)
 	    (setq linebeg (point))
 	    (move-to-column (current-fill-column))
@@ -803,7 +885,7 @@ fill-paragraph
 region, instead of just filling the current paragraph."
   (interactive (progn
 		 (barf-if-buffer-read-only)
-		 (list (if current-prefix-arg 'full) t)))
+		 (list (fill-interactive-justify-arg) t)))
   (or
    ;; 1. Fill the region if it is active when called interactively.
    (and region transient-mark-mode mark-active
@@ -1023,7 +1105,7 @@ fill-region
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (region-beginning) (region-end)
-		       (if current-prefix-arg 'full))))
+		       (fill-interactive-justify-arg))))
   (unless (memq justify '(t nil none full center left right))
     (setq justify 'full))
   (let ((start-point (point-marker))
@@ -1383,7 +1465,7 @@ fill-nonuniform-paragraphs
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (region-beginning) (region-end)
-		       (if current-prefix-arg 'full))))
+		       (fill-interactive-justify-arg))))
   (let ((fill-individual-varying-indent t))
     (fill-individual-paragraphs min max justifyp citation-regexp)))
 
@@ -1413,7 +1495,7 @@ fill-individual-paragraphs
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (region-beginning) (region-end)
-		       (if current-prefix-arg 'full))))
+		       (fill-interactive-justify-arg))))
   (save-restriction
     (save-excursion
       (goto-char min)
-- 
2.8.3

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Eli Zaretskii]

> From: Phil Sainty <psainty@orcon.net.nz>
> Date: Sun, 13 Nov 2016 00:21:08 +1300
> 
> This patch enables the use of a numeric prefix argument to select a
> one-time `fill-column' value, over-riding the value for that call.

Thanks.  A few comments below.

> +(defcustom fill-interactive-prefix-type 'column-and-justify
> +  "Determines how fill commands interpret a prefix argument.

We use a different style when describing user options.  Something like

  How fill commands interpret the prefix argument.

> +Under the default `column-and-justify' setting, a plain C-u

Please use \\[universal-argument] instead of a literal "C-u", for
those who rebind the command.

> +are displayed in the echo area.  A numeric prefix argument of
> +zero does not modify the fill-column, but also causes the current
> +value to be displayed.                    ^^^^

That "also" is redundant and is better removed, IMO.

> +The `hybrid' setting behaves like `column-and-justify' with the
> +exception of single-digit numeric arguments, which mean JUSTIFY.
> +Because fill-columns of less than 10 are unlikely to be useful,
> +this setting provides the new features while still enabling the
> +use of a numeric prefix argument to mean JUSTIFY for users who
> +were used to doing that."

So why isn't the default 'hybrid'?  It sounds like a more
backward-compatible setting to me.

> +(defun fill-interactive-justify-arg ()
> +  "Determine the JUSTIFY argument for the current fill command
> +based on the interactive `current-prefix-arg', and the user
> +option `fill-interactive-prefix-type'.

The first line of a doc string should be a complete sentence.  You can
then augment it by describing the details later in the doc string.
The first line should include the main intent of the command, because
it's the only one that's displayed by the likes of "M-x apropos".

> +Returns either 'full or nil in all cases."
                  ^^^^^
`full'

> +(defun fill-interactive-column (col)
> +  "Return column COL, modified based on the current prefix arg
> +and the user option `fill-interactive-prefix-type'.

Again, the first line should be a full sentence.

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Phil Sainty]

On 13/11/16 00:55, Eli Zaretskii wrote:
> A few comments below.

I'll make these changes for the next revision, thanks.

> So why isn't the default 'hybrid'?  It sounds like a more
> backward-compatible setting to me.

Yes indeed, but it's also a weird setting in that different numbers
have completely different meanings, so I was a bit loathe to make it
the default.  It's not a very intuitive use of the 0-9 numeric prefix
unless you already know why it works that way.

My thinking was that people who tended to use, say, M-1 M-q to
justify text would immediately notice the change and quickly find
their way to the new option by looking at C-h k M-q (docstrings not
yet updated in this patch) or the NEWS file, and quickly rectify
the situation one way or another; whereas for everyone else it seemed
nicer to me if the default behaviour was the more consistent one.

I don't feel too strongly about it, so I'm perfectly happy to make
the hybrid setting the default if people think it's for the best.


-Phil

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Eli Zaretskii]

> From: Phil Sainty <psainty@orcon.net.nz>
> Date: Sun, 13 Nov 2016 23:33:39 +1300
> 
> > So why isn't the default 'hybrid'?  It sounds like a more
> > backward-compatible setting to me.
> 
> Yes indeed, but it's also a weird setting in that different numbers
> have completely different meanings, so I was a bit loathe to make it
> the default.  It's not a very intuitive use of the 0-9 numeric prefix
> unless you already know why it works that way.
> 
> My thinking was that people who tended to use, say, M-1 M-q to
> justify text would immediately notice the change and quickly find
> their way to the new option by looking at C-h k M-q (docstrings not
> yet updated in this patch) or the NEWS file, and quickly rectify
> the situation one way or another; whereas for everyone else it seemed
> nicer to me if the default behaviour was the more consistent one.
> 
> I don't feel too strongly about it, so I'm perfectly happy to make
> the hybrid setting the default if people think it's for the best.

I don't feel strongly, either, and will probably never use this
feature anyway.  So let's see if there's someone else who thinks
'hybrid' is a better default.

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Noam Postavsky]

On Sun, Nov 13, 2016 at 10:15 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Phil Sainty <psainty@orcon.net.nz>
>> Date: Sun, 13 Nov 2016 23:33:39 +1300
>>
>> > So why isn't the default 'hybrid'?  It sounds like a more
>> > backward-compatible setting to me.
>>
>> Yes indeed, but it's also a weird setting in that different numbers
>> have completely different meanings, so I was a bit loathe to make it
>> the default.  It's not a very intuitive use of the 0-9 numeric prefix
>> unless you already know why it works that way.
>>
>> My thinking was that people who tended to use, say, M-1 M-q to
>> justify text would immediately notice the change and quickly find
>> their way to the new option by looking at C-h k M-q (docstrings not
>> yet updated in this patch) or the NEWS file, and quickly rectify
>> the situation one way or another; whereas for everyone else it seemed
>> nicer to me if the default behaviour was the more consistent one.
>>
>> I don't feel too strongly about it, so I'm perfectly happy to make
>> the hybrid setting the default if people think it's for the best.
>
> I don't feel strongly, either, and will probably never use this
> feature anyway.  So let's see if there's someone else who thinks
> 'hybrid' is a better default.
>

I can't say that I would use this feature much, but 'hybrid' sounds
like the better default to me. Consistency is nice, but in this case
it's not an especially helpful consistency, since filling with such a
tiny width would be very rare.

RE: [PATCH] Enhance the use of prefix arguments when filling text

[Herring, Davis]

> In all cases a plain C-u still means (only) JUSTIFY.

This seems sufficient (and sufficiently obvious) to avoid having to have the user option at all.  (But maybe someone (on QWERTY) is using M-1 M-q to justify?)

Davis

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Phil Sainty]

On 13/11/16 06:21, Herring, Davis wrote:
>> In all cases a plain C-u still means (only) JUSTIFY.
> 
> This seems sufficient (and sufficiently obvious) to
> avoid having to have the user option at all. (But maybe
> someone (on QWERTY) is using M-1 M-q to justify?)

Yes, that's the reason for the new user option -- I want
to ensure that people can retain the behaviour they're
used to.  Personally I never need to justify text; but if
there are people who do so very regularly, it's entirely
possible that they're using the M-<n> style of numeric
prefix, simply because it's slightly easier to type that
then to have to switch modifier keys after typing C-u.

Furthermore, (info "(emacs) Fill Commands") currently
says: "A numeric argument to ‘M-q’ tells it to "justify"
the text as well as filling it" -- the "numeric" detail
is really unnecessary, but it did give me even more reason
to ensure that this behaviour could be retained.


-Phil

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Stefan Monnier]

FWIW, I rarely need to force a particular one-time fill-column, whereas I'd
regularly appreciate being able to force a particular one-time fill prefix.


        Stefan


>>>>> "Phil" == Phil Sainty <psainty@orcon.net.nz> writes:

> This patch enables the use of a numeric prefix argument to select a
> one-time `fill-column' value, over-riding the value for that call.

> It takes effect before the main fill loop in `fill-region-as-paragraph'
> (which is ultimately used by all the other fill commands), by which time
> the likes of `emacs-lisp-docstring-fill-column' have already been dealt
> with, and won't clobber the prefix value.

> A prefix argument of `-' now means "un-fill" (turning multiple lines
> into a single long line), by using most-positive-fixnum as the
> fill-column for that call.

> All fill commands accept a JUSTIFY argument, and at present a prefix
> argument of any kind always simply means JUSTIFY is 'full. As that
> interactive behaviour is implemented independently by each command,
> this patch necessarily changes the interactive argument handling for
> each fill command, to prevent them from justifying when we are just
> setting a fill column.

> With the patch, negative numeric arguments now mean JUSTIFY using the
> specified fill column.

> In all cases a plain C-u still means (only) JUSTIFY.

> A new user option `fill-interactive-prefix-type' determines whether or
> not the new behaviour is used.  There is a setting to revert to the
> original behaviour (where any prefix argument means JUSTIFY), and also
> a hybrid setting to combine the old and new behaviours in a practical
> manner.

> This initial patch addresses only the commands in fill.el itself, but
> changes for other fill commands ought to follow a similar pattern.

> The patch is also missing documentation changes to the modified commands
> and to the info manuals, but I'm sending it as-is for review of the
> general idea and implementation.

> The patch was rolled against the emacs-25 branch.


> -Phil

Re: [PATCH] Enhance the use of prefix arguments when filling text

[Phil Sainty]

On 13/11/16 07:53, Stefan Monnier wrote:
> FWIW, I rarely need to force a particular one-time fill-column, whereas I'd
> regularly appreciate being able to force a particular one-time fill prefix.

I'll look into adding this.

Given the limitations on prefix arg values, I think I'd be restricted
to using "C-u C-u" for this.

That could mean "prompt for the fill-prefix, and use the default column
and justify values", but it might be more useful to instead make it
prompt for *everything* -- justify, fill-column, fill-prefix, and maybe
left-margin too.

The default value would be provided in each case, so you could just RET
your way past the ones you didn't want to change.

How does that sound?


-Phil

Re: [PATCH] Enhance the use of prefix arguments when filling text

[John Wiegley]

>>>>> "SM" == Stefan Monnier <monnier@iro.umontreal.ca> writes:

SM> FWIW, I rarely need to force a particular one-time fill-column, whereas
SM> I'd regularly appreciate being able to force a particular one-time fill
SM> prefix.

I would use one-time fill-column far more often (to fill quotations within
e-mails so that they have a larger right margin than the surrounding text),
but I'd also have use for a one-time fill-prefix too.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2