Subject: Re: bug#78561: [PATCH] Add semantic linefeed support for paragraph filling

From: Roi Martin <[email-masked]>
Date: Sun, 15 Jun 2025 11:56:06 +0200

Eli Zaretskii <[email-masked]> writes:

>> From: Roi Martin <[email-masked]>
>> Cc: [email-masked]
>> Date: Sun, 15 Jun 2025 11:12:49 +0200
>> 
>> Eli Zaretskii <[email-masked]> writes:
>> 
>> > Neither, AFAIU?  Those two are commands, not fill-paragraph functions.
>> > They don't implement the protocol defined for fill-paragraph
>> > functions.
>> 
>> It should be possible to use `fill-paragraph-semlf' as
>> `fill-paragraph-function'.
>> 
>> It takes a JUSTIFY argument, which is required by:
>> 
>>   (funcall function justify)
>> 
>> in the specific case in `fill-paragraph' ("2. Try
>> fill-paragraph-function.").
>> 
>>   ;; 2. Try fill-paragraph-function.
>>   (and (not (eq fill-paragraph-function t))
>>             (or fill-paragraph-function
>>                 (and (minibufferp (current-buffer))
>>                      (= 1 (point-min))))
>>             (let ((function (or fill-paragraph-function
>>                                 ;; In the minibuffer, don't count
>>                                 ;; the width of the prompt.
>>                                 'fill-minibuffer-function))
>>                   ;; If fill-paragraph-function is set, it probably
>>                   ;; takes care of comments and stuff.  If not, it
>>                   ;; will have to set fill-paragraph-handle-comment
>>                   ;; back to t explicitly or return nil.
>>                   (fill-paragraph-handle-comment nil)
>>                   (fill-paragraph-function t))
>>               (funcall function justify)))
>> 
>> It also returns a non-nil value to avoid executing the following cases
>> in `fill-paragraph'.
>> 
>> Is there anything missing?
>
> The doc string of fill-paragraph-function says:
>
>   If the function returns nil, then ‘fill-paragraph’ does its normal work.
>   A value of t means explicitly "do nothing special".
>
> By contrast, the doc string of fill-paragraph-semlf says:
>
>   Return the `fill-prefix' used for filling.
>
> Maybe the doc string is inaccurate, but if it's accurate, then its
> return value is not what's expected from fill-paragraph-function.  Or
> what did I miss?

No, you are right.

I decided to return `fill-prefix' in `fill-paragraph-semlf' because it
seemed to have the same effect as returning t, based on the code I
attached previously.  Also, returning `fill-paragraph' seemed more
useful.  But, you are right, the contract mentions nil and t explicitly.

Then, what's better?  Should we remove the following paragraph from the
doc string of `fill-paragraph-semlf'?

  You can use this function as the value of ‘fill-paragraph-function’, so
  ‘fill-paragraph’ and other filling commands will use it.

Or should we return t in `fill-paragraph-semlf'?

Also, what does "do nothing special" mean exactly?

        Roi