bug#68418: refill-mode interferes with org-mode headlines

bug#68418: refill-mode interferes with org-mode headlines

[Lars Rustand]

Enabling refill-mode in an org-mode buffer results in unwanted behaviour
that interferes with headlines, list items, and possibly other types of
line breaks.

I won't go too deeply into describing it here as it has been described
well in the following bug report on the org-mode mailing list. In that
thread it was suggested that the bug is actually not in org-mode, but
instead in refill-mode.

See the original bug report on the org-mode list here:

https://list.orgmode.org/orgmode/3715730.BJ41AJB0qc@yksi/


I also found a previous thread on this list where it has been discussed:

https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-12/msg01854.html

It seems that the bug was located and the cause was identified, but
nothing more came out of it.

The thread derailed quickly and it seems the problem was ignored because
of personal problems against the author. The fact that some of his
previous bug reports were done to the wrong list does not mean that this
bug should be ignored.

I hope the issue can be taken seriously this time, because it renders
refill-mode unusable in org-mode buffers.

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

merge 68418 52778
thanks

> From: Lars Rustand <rustand.lars@gmail.com>
> Date: Fri, 12 Jan 2024 21:18:51 +0100
> 
> 
> Enabling refill-mode in an org-mode buffer results in unwanted behaviour
> that interferes with headlines, list items, and possibly other types of
> line breaks.
> 
> I won't go too deeply into describing it here as it has been described
> well in the following bug report on the org-mode mailing list. In that
> thread it was suggested that the bug is actually not in org-mode, but
> instead in refill-mode.
> 
> See the original bug report on the org-mode list here:
> 
> https://list.orgmode.org/orgmode/3715730.BJ41AJB0qc@yksi/
> 
> 
> I also found a previous thread on this list where it has been discussed:
> 
> https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-12/msg01854.html
> 
> It seems that the bug was located and the cause was identified, but
> nothing more came out of it.

If a bug isn't picked up by someone who wants or is capable of working
on it, and has time for that, that bug will not be fixed, indeed.
That's one of the downsides of a community-driven project that is
based on volunteers.

> The thread derailed quickly and it seems the problem was ignored because
> of personal problems against the author. The fact that some of his
> previous bug reports were done to the wrong list does not mean that this
> bug should be ignored.
> 
> I hope the issue can be taken seriously this time, because it renders
> refill-mode unusable in org-mode buffers.

This is at least inaccurate, and quite a bit unfair, I'd say: the
thread didn't "derail".  Once the nature of the original report was
established and seemed to point to a problem in refill.el, the
discussion indeed went to a tangent, but no one said that the original
report was invalid or incorrect, or that we don't want to take it
seriously, let alone because the OP had some problems.  It's just a
bug that no one kept working on it.  Which is unfortunate, but it does
happen, since we don't have a way of assigning bugs to developers and
making sure they do fix them.

Anyway, with these tangents aside, coming back to the original report
and its initial analysis by Ihor in bug#52778, viz.:

> > I did some debugging for refill-mode in Org.
> > `refill-post-command-function' calls `refill-fill-paragraph-at', which
> > not only ignores `fill-paragraph-function', but even
> > `fill-forward-paragraph-function'. `forward-paragraph' is hard-coded,
> > I consider to be a bug.
> 
> Let me bump this bug report.
> AFAIU, it belongs to emacs.

I now have second thoughts about this.  fill-paragraph-function is
used by fill-paragraph, whereas refill.el calls
fill-region-as-paragraph.  fill-region-as-paragraph cannot possibly
call fill-paragraph-function, because the latter is not supposed to be
able to fill more than a single paragraph.  The doc string of
fill-paragraph-function actually says so:

  (defvar fill-paragraph-function nil
    "Mode-specific function to fill a paragraph, or nil if there is none.
  If the function returns nil, then `fill-paragraph' does its normal work.
  A value of t means explicitly \"do nothing special\".
  Note: This only affects `fill-paragraph' and not `fill-region'
  nor `auto-fill-mode', so it is often better to use some other hook,
  such as `fill-forward-paragraph-function'.")

Am I missing something?

If my analysis is correct, then to move forward with this bug, we
could either:

  . add a fill-region-function, make fill-region-as-paragraph call it,
    and then make Org set this function to something appropriate
  . modify refill.el to use fill-forward-paragraph-function instead of
    a literal forward-paragraph

I tried the latter (patch below), but I don't know if that gives
good-enough results, as I don't use Org intensively enough, and
certainly don't use refill-mode.  Can you try the patch below and
report back?

diff --git a/lisp/textmodes/refill.el b/lisp/textmodes/refill.el
index 937a8ed..22f67bc 100644
--- a/lisp/textmodes/refill.el
+++ b/lisp/textmodes/refill.el
@@ -106,10 +106,10 @@ refill-fill-paragraph-at
     ;; FIXME: forward-paragraph seems to disregard `use-hard-newlines',
     ;; leading to excessive refilling and wrong choice of fill-prefix.
     ;; might be a bug in my paragraphs.el.
-    (forward-paragraph)
+    (fill-forward-paragraph 1)
     (skip-syntax-backward "-")
     (let ((end (point))
-	  (beg (progn (backward-paragraph) (point)))
+	  (beg (progn (fill-forward-paragraph -1) (point)))
 	  (obeg (overlay-start refill-ignorable-overlay))
 	  (oend (overlay-end refill-ignorable-overlay)))
       (unless (> beg pos)      ;Don't fill if point is outside the paragraph.

bug#68418: refill-mode interferes with org-mode headlines

[Lars Rustand]

Eli Zaretskii <eliz@gnu.org> writes:

> I tried the latter (patch below), but I don't know if that gives
> good-enough results, as I don't use Org intensively enough, and
> certainly don't use refill-mode.  Can you try the patch below and
> report back?

Thanks for the patch! This does indeed seem to have fixed the problems I
was having. I don't really use Org very intensely myself, so there could
be cases that I have missed.

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Lars Rustand <rustand.lars@gmail.com>
> Cc: Rudolf Adamkovič <salutis@me.com>
> Date: Sat, 13 Jan 2024 10:01:27 +0100
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I tried the latter (patch below), but I don't know if that gives
> > good-enough results, as I don't use Org intensively enough, and
> > certainly don't use refill-mode.  Can you try the patch below and
> > report back?
> 
> Thanks for the patch! This does indeed seem to have fixed the problems I
> was having. I don't really use Org very intensely myself, so there could
> be cases that I have missed.

Thanks for testing.  I will wait for Rudolf to chime in, and will
install this if no problems are reported with the patch.

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> Cc: 68418@debbugs.gnu.org, salutis@me.com
> Date: Sat, 13 Jan 2024 11:16:14 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Lars Rustand <rustand.lars@gmail.com>
> > Cc: Rudolf Adamkovič <salutis@me.com>
> > Date: Sat, 13 Jan 2024 10:01:27 +0100
> > 
> > 
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> > > I tried the latter (patch below), but I don't know if that gives
> > > good-enough results, as I don't use Org intensively enough, and
> > > certainly don't use refill-mode.  Can you try the patch below and
> > > report back?
> > 
> > Thanks for the patch! This does indeed seem to have fixed the problems I
> > was having. I don't really use Org very intensely myself, so there could
> > be cases that I have missed.
> 
> Thanks for testing.  I will wait for Rudolf to chime in, and will
> install this if no problems are reported with the patch.

No further comments within 2 weeks, so I've now installed that patch
on the master branch.

I'm not closing the bug, since the changes I installed evidently don't
fix all the issues refill.el has in Org buffers.

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> > I did some debugging for refill-mode in Org.
>> > `refill-post-command-function' calls `refill-fill-paragraph-at', which
>> > not only ignores `fill-paragraph-function', but even
>> > `fill-forward-paragraph-function'. `forward-paragraph' is hard-coded,
>> > I consider to be a bug.
>> 
>> Let me bump this bug report.
>> AFAIU, it belongs to emacs.
>
> I now have second thoughts about this.  fill-paragraph-function is
> used by fill-paragraph, whereas refill.el calls
> fill-region-as-paragraph.  fill-region-as-paragraph cannot possibly
> call fill-paragraph-function, because the latter is not supposed to be
> able to fill more than a single paragraph.  The doc string of
> fill-paragraph-function actually says so:
>
>   (defvar fill-paragraph-function nil
>     "Mode-specific function to fill a paragraph, or nil if there is none.
>   If the function returns nil, then `fill-paragraph' does its normal work.
>   A value of t means explicitly \"do nothing special\".
>   Note: This only affects `fill-paragraph' and not `fill-region'
>   nor `auto-fill-mode', so it is often better to use some other hook,
>   such as `fill-forward-paragraph-function'.")
>
> Am I missing something?

No. This indeed makes sense.
`fill-paragraph-function' is not even passed the region to fill, so it
has no way to know what it is supposed to fill and should determine the
paragraph boundaries by itself.

> If my analysis is correct, then to move forward with this bug, we
> could either:
>
>   . add a fill-region-function, make fill-region-as-paragraph call it,
>     and then make Org set this function to something appropriate

This is a bit tangent, but the current design of filling feels chaotic -
we have configurable fill-paragraph-function and
fill-forward-paragraph-function, while `fill-region-as-paragraph' is
hard-coded.  And forward-paragraph relies upon regexps...

It looks like the notion of paragraph when filling is designed to be
different compared to the notion of paragraph in `forward-paragraph'.
Is there any reason for such difference?

>   . modify refill.el to use fill-forward-paragraph-function instead of
>     a literal forward-paragraph
>
> I tried the latter (patch below), but I don't know if that gives
> good-enough results, as I don't use Org intensively enough, and
> certainly don't use refill-mode.  Can you try the patch below and
> report back?
>
> diff --git a/lisp/textmodes/refill.el b/lisp/textmodes/refill.el
> index 937a8ed..22f67bc 100644
> --- a/lisp/textmodes/refill.el
> +++ b/lisp/textmodes/refill.el
> @@ -106,10 +106,10 @@ refill-fill-paragraph-at
>      ;; FIXME: forward-paragraph seems to disregard `use-hard-newlines',
>      ;; leading to excessive refilling and wrong choice of fill-prefix.
>      ;; might be a bug in my paragraphs.el.
> -    (forward-paragraph)
> +    (fill-forward-paragraph 1)
>      (skip-syntax-backward "-")
>      (let ((end (point))
> -	  (beg (progn (backward-paragraph) (point)))
> +	  (beg (progn (fill-forward-paragraph -1) (point)))

This looks like an improvement. Also, it appears to fix the original
reproducer.

However, there will still be a problem, even with the proposed patch, in
the following scenario:

1. emacs -Q
2. Open a new org file
* Heading <point> :tag:
3. M-x refill-mode
4. Keep typing
* Heading alksjd alkjasd asldkj asdlkj aslldkj aslkdj asldkj
  asldkj <point>:tag:

See how the heading is split into multiple lines.

This happens because refill-mode uses `fill-region-as-paragraph', which
is impossible to configure by major modes.
As the above example demonstrates, not everything is safe to fill
without breaking the markup.

A similar problem appears in `fill-region' - it completely disregards
`fill-paragraph-function' and always calls `fill-region-as-paragraph'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: Lars Rustand <rustand.lars@gmail.com>, Rudolf Adamkovič
>  <salutis@me.com>, 68418@debbugs.gnu.org
> Date: Sat, 13 Jan 2024 13:28:16 +0000
> 
> This is a bit tangent, but the current design of filling feels chaotic -
> we have configurable fill-paragraph-function and
> fill-forward-paragraph-function, while `fill-region-as-paragraph' is
> hard-coded.  And forward-paragraph relies upon regexps...
> 
> It looks like the notion of paragraph when filling is designed to be
> different compared to the notion of paragraph in `forward-paragraph'.
> Is there any reason for such difference?

I don't know.

> This looks like an improvement. Also, it appears to fix the original
> reproducer.
> 
> However, there will still be a problem, even with the proposed patch, in
> the following scenario:
> 
> 1. emacs -Q
> 2. Open a new org file
> * Heading <point> :tag:
> 3. M-x refill-mode
> 4. Keep typing
> * Heading alksjd alkjasd asldkj asdlkj aslldkj aslkdj asldkj
>   asldkj <point>:tag:
> 
> See how the heading is split into multiple lines.
> 
> This happens because refill-mode uses `fill-region-as-paragraph', which
> is impossible to configure by major modes.
> As the above example demonstrates, not everything is safe to fill
> without breaking the markup.
> 
> A similar problem appears in `fill-region' - it completely disregards
> `fill-paragraph-function' and always calls `fill-region-as-paragraph'.

So you think the patch I posted should not be installed, and we should
wait for a more thorough solution?

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> This looks like an improvement. Also, it appears to fix the original
>> reproducer.
>> 
>> However, there will still be a problem, even with the proposed patch, in
>> the following scenario:
> ...
> So you think the patch I posted should not be installed, and we should
> wait for a more thorough solution?

I believe that your patch is good - it improves the situation and makes
refill-mode more consistent with fill.el (by honouring
`fill-forward-paragraph-function').

However, more general problem with fill.el design will remain. Although,
emacs-devel might be more suitable place to discuss the Emacs design -
see my other email - https://yhetil.org/emacs-devel/87frz5kux7.fsf@localhost/

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: rustand.lars@gmail.com, salutis@me.com, 68418@debbugs.gnu.org
> Date: Sat, 13 Jan 2024 13:56:13 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> This looks like an improvement. Also, it appears to fix the original
> >> reproducer.
> >> 
> >> However, there will still be a problem, even with the proposed patch, in
> >> the following scenario:
> > ...
> > So you think the patch I posted should not be installed, and we should
> > wait for a more thorough solution?
> 
> I believe that your patch is good - it improves the situation and makes
> refill-mode more consistent with fill.el (by honouring
> `fill-forward-paragraph-function').

OK.

Is it possible that Org's fill-forward-paragraph-function needs some
improvements, btw?

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> I believe that your patch is good - it improves the situation and makes
>> refill-mode more consistent with fill.el (by honouring
>> `fill-forward-paragraph-function').
>
> OK.
>
> Is it possible that Org's fill-forward-paragraph-function needs some
> improvements, btw?

May you please elaborate?
Some improvements can be made most of the time, but you seem to have
something specific in mind.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: rustand.lars@gmail.com, salutis@me.com, 68418@debbugs.gnu.org
> Date: Sat, 13 Jan 2024 15:26:50 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Is it possible that Org's fill-forward-paragraph-function needs some
> > improvements, btw?
> 
> May you please elaborate?
> Some improvements can be made most of the time, but you seem to have
> something specific in mind.

I mean the problem with refill-mode that you described in

  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68418#19

Is it possible to fix that by some improvements to
fill-forward-paragraph-function used by Org?

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

> I mean the problem with refill-mode that you described in
>
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68418#19
>
> Is it possible to fix that by some improvements to
> fill-forward-paragraph-function used by Org?

I doubt so. The only idea that is coming to my mind is to make Org
mode's `fill-forward-paragraph-function' not move anywhere when not on
paragraph - this will prevent refill-mode from filling anything but Org
paragraphs.

However, this idea will not work because:
1. It will cause infinite loop in `fill-region' that is also using
   `fill-forward-paragraph-function', but expects it to move somewhere.

2. Make it impossible to implement custom filling for non-paragraphs, as
   we do for source blocks (by delegating to source block major mode),
   tables, and comments.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: salutis@me.com, 68418@debbugs.gnu.org, rustand.lars@gmail.com
> Date: Sat, 13 Jan 2024 18:37:23 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I mean the problem with refill-mode that you described in
> >
> >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68418#19
> >
> > Is it possible to fix that by some improvements to
> > fill-forward-paragraph-function used by Org?
> 
> I doubt so. The only idea that is coming to my mind is to make Org
> mode's `fill-forward-paragraph-function' not move anywhere when not on
> paragraph - this will prevent refill-mode from filling anything but Org
> paragraphs.

Is the problem in your example what fill-forward-paragraph-function
does, or is the problem elsewhere in refill-fill-paragraph-at and/or
refill-post-command-function?  IOW, can you tell which part(s) of
refill.el fail to DTRT in an Org buffer?  I don't know enough about
all the peculiarities of the Org format to tell what should be fixed
in that case, let alone how.

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> > Is it possible to fix that by some improvements to
>> > fill-forward-paragraph-function used by Org?
>> 
>> I doubt so. The only idea that is coming to my mind is to make Org
>> mode's `fill-forward-paragraph-function' not move anywhere when not on
>> paragraph - this will prevent refill-mode from filling anything but Org
>> paragraphs.
>
> Is the problem in your example what fill-forward-paragraph-function
> does, or is the problem elsewhere in refill-fill-paragraph-at and/or
> refill-post-command-function?  IOW, can you tell which part(s) of
> refill.el fail to DTRT in an Org buffer?  I don't know enough about
> all the peculiarities of the Org format to tell what should be fixed
> in that case, let alone how.

AFAIU, the problem is in

(if use-hard-newlines
		    (fill-region oend end arg)
		  (fill-region-as-paragraph oend end arg))

Both `fill-region' and `fill-region-as-paragraph' do not respect
`fill-paragraph-function' and always act the same once the region
boundaries are identified regardless of the major mode.

`fill-region-as-paragraph' does not respect it as per docstring and
refill mode should probably not call `fill-region-as-paragraph'. The
branching for `use-hard-newlines' should belong to text-mode, IMHO.

`fill-region' does not respect `fill-paragraph-function' for the reasons
I do not understand.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: salutis@me.com, 68418@debbugs.gnu.org, rustand.lars@gmail.com
> Date: Sat, 13 Jan 2024 19:13:56 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Is the problem in your example what fill-forward-paragraph-function
> > does, or is the problem elsewhere in refill-fill-paragraph-at and/or
> > refill-post-command-function?  IOW, can you tell which part(s) of
> > refill.el fail to DTRT in an Org buffer?  I don't know enough about
> > all the peculiarities of the Org format to tell what should be fixed
> > in that case, let alone how.
> 
> AFAIU, the problem is in
> 
> (if use-hard-newlines
> 		    (fill-region oend end arg)
> 		  (fill-region-as-paragraph oend end arg))
> 
> Both `fill-region' and `fill-region-as-paragraph' do not respect
> `fill-paragraph-function' and always act the same once the region
> boundaries are identified regardless of the major mode.

We already agreed that fill-region-as-paragraph cannot use
fill-paragraph-function, right?  So what should
fill-region-as-paragraph do in order to behave more correctly in Org
buffers?  IOW, what are the specific problems in
fill-region-as-paragraph that break it in Org buffers?  (I presume
that use-hard-newlines is nil in these cases, so fill-paragraph is
currently not relevant.)

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

> We already agreed that fill-region-as-paragraph cannot use
> fill-paragraph-function, right?  So what should
> fill-region-as-paragraph do in order to behave more correctly in Org
> buffers?  IOW, what are the specific problems in
> fill-region-as-paragraph that break it in Org buffers?  (I presume
> that use-hard-newlines is nil in these cases, so fill-paragraph is
> currently not relevant.)

`fill-region-as-paragraph' itself is not a problem.
The problem is that calling `fill-region-as-paragraph' directly does not
make sense in Org buffers - it will break the markup.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#68418: refill-mode interferes with org-mode headlines

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: salutis@me.com, 68418@debbugs.gnu.org, rustand.lars@gmail.com
> Date: Sat, 13 Jan 2024 19:33:55 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > We already agreed that fill-region-as-paragraph cannot use
> > fill-paragraph-function, right?  So what should
> > fill-region-as-paragraph do in order to behave more correctly in Org
> > buffers?  IOW, what are the specific problems in
> > fill-region-as-paragraph that break it in Org buffers?  (I presume
> > that use-hard-newlines is nil in these cases, so fill-paragraph is
> > currently not relevant.)
> 
> `fill-region-as-paragraph' itself is not a problem.
> The problem is that calling `fill-region-as-paragraph' directly does not
> make sense in Org buffers - it will break the markup.

You are basically saying that refill-mode makes no sense in Org
buffers, right?  If fill-region-as-paragraph cannot be factored and/or
provide hooks for Org to customize it, then Org users should be told
not to use refill-mode in Org buffers.

bug#68418: refill-mode interferes with org-mode headlines

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> `fill-region-as-paragraph' itself is not a problem.
>> The problem is that calling `fill-region-as-paragraph' directly does not
>> make sense in Org buffers - it will break the markup.
>
> You are basically saying that refill-mode makes no sense in Org
> buffers, right?  If fill-region-as-paragraph cannot be factored and/or
> provide hooks for Org to customize it, then Org users should be told
> not to use refill-mode in Org buffers.

No. refill-mode could make use of `fill-paragraph-function' rather than
calling `fill-region-as-paragraph' directly.

Look at the docstring:

(defun refill-fill-paragraph-at (pos &optional arg)
  "Like `fill-paragraph' at POS, but don't delete whitespace at paragraph end."

If `refill-fill-paragraph-at' is "like fill-paragraph", how come it does
not respect `fill-paragraph-function'?
If the goal is to preserve the whitespace at paragraph end, that
whitespace could be stored and re-applied after calling `fill-paragraph'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>