GNU bug report logs - #78816
[PATCH] Add variable `fill-region-as-paragraph-function'

Previous Next

To reply to this bug, email your comments to 78816 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add variable `fill-region-as-paragraph-function'
Date: Tue, 17 Jun 2025 12:52:01 +0200

[Message part 1 (text/plain, inline)]

Tags: patch

Right now it is not possible to customize how the `fill-region' function
fills text.  This patch adds a new variable named
`fill-region-as-paragraph-function' that allows to override the default
behavior.

For more details, see the discussion in Bug#78561.

[0001-Add-variable-fill-region-as-paragraph-function.patch (text/x-patch, attachment)]

Message #8 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: 78816 <at> debbugs.gnu.org
Subject: Re: bug#78816: Acknowledgement ([PATCH] Add variable
 `fill-region-as-paragraph-function')
Date: Tue, 17 Jun 2025 12:59:30 +0200

[Message part 1 (text/plain, inline)]

Please, find attached a new version of the patch.  It adds the bug
number to the commit message and it also adds a missing white space
after period.  Sorry for the noise.

[0001-Add-variable-fill-region-as-paragraph-function.patch (text/x-patch, attachment)]

Message #11 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: eliz <at> gnu.org, Marcin Borkowski <mbork <at> mbork.pl>, 78816 <at> debbugs.gnu.org,
 juri <at> linkov.net
Subject: Re: bug#78816: [PATCH] Add variable
 `fill-region-as-paragraph-function'
Date: Tue, 17 Jun 2025 18:07:24 -0400

> --- a/doc/emacs/text.texi
> +++ b/doc/emacs/text.texi
> @@ -607,6 +607,15 @@ Fill Commands
>  deletes any blank lines within the region, so separate blocks of text
>  end up combined into one block.
>  
> +@vindex fill-region-as-paragraph-function
> +  The variable @code{fill-region-as-paragraph-function} provides a way
> +to override how the function @code{fill-region} fills text.  Its value
> +should be a function, which is called with the arguments @var{from},
> +@var{to}, @var{justify} and @var{nosqueeze}, defined by
> +@code{fill-region-as-paragraph}.  It should return the
> +@code{fill-prefix} used for filling.  The default value of this variable
> +is @code{fill-region-as-paragraph}.

Does it need to be in the Emacs manual also?  I have the impression that
it belongs only in the ELisp manual.

> +@defvar fill-region-as-paragraph-function
> +This variable provides a way to override how the function
> +@code{fill-region} fills text.

I don't think this should be specific to `fill-region`.  E.g. it should
also affect `fill-paragraph` and any other user of
`fill-region-as-paragraph`.  IOW, I'd say something like "... how
functions like @code{fill-region} fill text."

> Its value should be a function, which is
> +called with the arguments @var{from}, @var{to}, @var{justify} and
> +@var{nosqueeze}, defined by @code{fill-region-as-paragraph}.  It should
> +return the @code{fill-prefix} used for filling.  The default value of
> +this variable is @code{fill-region-as-paragraph}.
> +@end defvar

[ I think "fill prefix" above is used in a "generic" sense (e.g. it may
  be chosen without using the `fill-prefix` variable), so I'm not sure
  `@code` is warranted for it.  ]

> +(defvar fill-region-as-paragraph-function 'fill-region-as-paragraph
                                            ^^^
                                             #'

> +  "Function to fill the region as if it were a single paragraph.
> +It is called with the arguments FROM, TO, JUSTIFY and NOSQUEEZE, defined
> +by `fill-region-as-paragraph'. It should return the `fill-prefix' used
> +for filling.")

Please use two spaces after the ".".
Better yet, use semlf-style filling here.  🙂

> @@ -1095,7 +1104,7 @@ fill-region
>  	    (goto-char beg))
>  	(if (and (>= (point) initial) (< (point) end))
>  	    (setq fill-pfx
> -		  (fill-region-as-paragraph (point) end justify nosqueeze))
> +		  (funcall fill-region-as-paragraph-function (point) end justify nosqueeze))

I think I'd leave this alone and instead do

    (defun fill-region-as-paragraph (&rest args)
      (apply fill-region-as-paragraph-function args))

and rename `fill-region-as-paragraph` as `fill-region-as-paragraph-default`.


        Stefan

Message #14 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: eliz <at> gnu.org, Marcin Borkowski <mbork <at> mbork.pl>, 78816 <at> debbugs.gnu.org,
 juri <at> linkov.net
Subject: Re: bug#78816: [PATCH] Add variable
 `fill-region-as-paragraph-function'
Date: Wed, 18 Jun 2025 01:34:26 +0200

[Message part 1 (text/plain, inline)]

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> I think I'd leave this alone and instead do
>
>     (defun fill-region-as-paragraph (&rest args)
>       (apply fill-region-as-paragraph-function args))
>
> and rename `fill-region-as-paragraph` as `fill-region-as-paragraph-default`.

Done.  However, I kept the parameters and the doc string in
`fill-region-as-paragraph', so almost nothing changed from the user
perspective.

Thanks for the review!  I've attached a new version of the patch.

       Roi

[0001-Add-variable-fill-region-as-paragraph-function.patch (text/x-patch, attachment)]

Message #17 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: eliz <at> gnu.org, Marcin Borkowski <mbork <at> mbork.pl>, 78816 <at> debbugs.gnu.org,
 juri <at> linkov.net
Subject: Re: bug#78816: [PATCH] Add variable
 `fill-region-as-paragraph-function'
Date: Wed, 18 Jun 2025 15:58:24 -0400

> Done.  However, I kept the parameters and the doc string in
> `fill-region-as-paragraph', so almost nothing changed from the user
> perspective.
>
> Thanks for the review!  I've attached a new version of the patch.

LGTM.  Eli?


        Stefan

Message #20 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: juri <at> linkov.net, mbork <at> mbork.pl, jroi.martin <at> gmail.com,
 78816 <at> debbugs.gnu.org
Subject: Re: bug#78816: [PATCH] Add variable
 `fill-region-as-paragraph-function'
Date: Thu, 19 Jun 2025 08:40:38 +0300

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: 78816 <at> debbugs.gnu.org,  Marcin Borkowski <mbork <at> mbork.pl>,
>   eliz <at> gnu.org,  juri <at> linkov.net
> Date: Wed, 18 Jun 2025 15:58:24 -0400
> 
> > Done.  However, I kept the parameters and the doc string in
> > `fill-region-as-paragraph', so almost nothing changed from the user
> > perspective.
> >
> > Thanks for the review!  I've attached a new version of the patch.
> 
> LGTM.  Eli?

I have a problem with the documentation of the functions and commands
we had before, which can now be overridden by the new
fill-region-as-paragraph-function.  The documentation was basically
left unaltered as to what filling does, with just a single sentence,
at the end of a very long doc string, saying that
fill-region-as-paragraph-function could change the behavior.  But the
truth is that such a function can completely change the result and
invalidate the description in the doc string; in particular, the
function which implements semantic line-feeds does exactly that.

So at the very least, the doc strings should:

 . mention the fill-region-as-paragraph-function early on
 . say that the rest of the description is about the default function,
   mentioning its symbol

I also think some minimal addition to the user manual is in order, to
the effect that the manual describes the default filling style, while
the major mode or the user could change it via
fill-region-as-paragraph-function.

Message #23 received at 78816 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: mbork <at> mbork.pl, 78816 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#78816: [PATCH] Add variable
 `fill-region-as-paragraph-function'
Date: Thu, 19 Jun 2025 19:45:57 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> I have a problem with the documentation of the functions and commands
> we had before, which can now be overridden by the new
> fill-region-as-paragraph-function.  The documentation was basically
> left unaltered as to what filling does, with just a single sentence,
> at the end of a very long doc string, saying that
> fill-region-as-paragraph-function could change the behavior.  But the
> truth is that such a function can completely change the result and
> invalidate the description in the doc string; in particular, the
> function which implements semantic line-feeds does exactly that.
>
> So at the very least, the doc strings should:
>
>  . mention the fill-region-as-paragraph-function early on
>  . say that the rest of the description is about the default function,
>    mentioning its symbol
>
> I also think some minimal addition to the user manual is in order, to
> the effect that the manual describes the default filling style, while
> the major mode or the user could change it via
> fill-region-as-paragraph-function.

Please, find attached a new version of the patch with the following
changes:

- In the user manual, I added a reference to
  `fill-region-as-paragraph-function'.  I also made explicit that the
  `fill-region-as-paragraph' behavior described by the manual
  corresponds to the default implementation.
- In the Emacs Lisp reference, I made explicit that the behavior
  described for `fill-region-as-paragraph' corresponds to the default
  implementation.
- Moved the original docstring of `fill-region-as-paragraph' to
  `fill-region-as-paragraph-default' given that it describes its
  specific behavior.
- I used the docstring of `fill-region-as-paragraph' to describe the
  general purpose of the command and the expected arguments.  I also
  moved the mention to `fill-region-as-paragraph-function' to the
  beginning of the docstring.
- I noticed that, after my previous patches, `fill-region-as-paragraph'
  was not a command anymore.  Now it is a command again.

        Roi

[0001-Add-variable-fill-region-as-paragraph-function.patch (text/x-patch, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.