Subject: Re: bug#78816: [PATCH] Add variable `fill-region-as-paragraph-function'

From: Stefan Monnier <[email-masked]>
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