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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 19 Jun 2025 08:40:38 +0300

> From: Stefan Monnier <[email-masked]>
> Cc: [email-masked],  Marcin Borkowski <[email-masked]>,
>   [email-masked],  [email-masked]
> 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.