Re: [PATCH] Fix org-comment-line-break-function

[Richard Lawrence <richard.lawrence@uni-tuebingen.de>]

Tim Cross <theophilusx@gmail.com> writes:

> Well, that is the big question - why was
> org-comment-line-break-function added instead of just using the
> default comment-indent-new-line?

Looking back at commit d58d40f0c864ae3a6d7c66df34769619ad2486c1, I see
this comment was added by Nicolas (still in org.el):

;; `org-auto-fill-function' takes care of auto-filling. It calls
;; `do-auto-fill' only on valid areas with `fill-prefix' shadowed with
;; `org-adaptive-fill-function' value. Internally,
;; `org-comment-line-break-function' breaks the line.

which at least suggests ("Internally, ...") that
org-comment-line-break-function was never intended to be called to break
a comment via a user command like M-j, and was only intended to be
called during filling, in a context where fill-prefix would be set correctly.

In that case, the problem might be that org-setup-filling sets
comment-line-break-function to 'org-comment-line-break-function
(overriding the default value of 'comment-indent-new-line) "globally" in
Org buffers, causing it to be called even when fill-prefix is not
set correctly.

The documentation for (the variable) comment-line-break-function is a
bit confusing:

"Mode-specific function that line breaks and continues a comment.
This function is called during auto-filling when a comment syntax
is defined."

which also suggests that this function will only be called during
filling. But that is clearly not true (even if it once was), since
default-indent-new-line calls it directly.

So maybe org-comment-line-break-function was written under assumptions
that no longer hold?

It might also be worth pointing out here that
org-comment-line-break-function is *almost* a line-for-line copy of part of
default-indent-new-line, except the latter is more careful about
checking that fill-prefix is not nil before calling insert-* on it.

> Until this is determined, I think the only 'safe' approach would be to
> just advise those who are impacted by the M-j issue to set
> comment-line-break-function to comment-indent-new-line and then wait
> to see if someone who has more historical context to comment. 

This is a bit trickier than it sounds, because in Org buffers,
org-setup-filling calls

(setq-local comment-line-break-function 'org-comment-line-break-function)

which will override any global value for comment-line-break-function
(e.g. in your init file).  So you'd have to reset it in Org
buffers locally, via a hook that runs after org-setup-filling.

-- 
Best,
Richard