Subject: Re: [PATCH v2] lisp: Introduce a `lisp-fill-paragraph-as-displayed' variable.

From: Maxim Cournoyer <[email-masked]>
Date: Tue, 21 Jan 2025 11:43:27 +0900

Hi,

Eli Zaretskii <[email-masked]> writes:

[...]

>> * lisp/emacs-lisp/lisp-mode.el (lisp-fill-paragraph-as-displayed): New
>> variable.
>> (lisp-fill-paragraph): Honor it, by avoiding the logic narrow to strings
>> before applying fill-paragraph.
>> * test/lisp/emacs-lisp/lisp-mode-tests.el
>> (lisp-fill-paragraph-respects-fill-column): Test it.
>> (lisp-fill-paragraph-docstring-boundaries): New test, as a safeguard to
>> avoid regressions.
>
> Please format these entries according to our conventions, mostly
> regarding the line length (it should be at most 69 columns, preferably
> no more than 64.

Done.  It's odd that when using magit there's no easy way to have this
this set by default (it defaults to use the text-mode major mode).  I've
M-x log-edit-mode in the edit buffer to get the .dir-locals.el
preferences applied.

>> -;; Copyright (C) 1985-1986, 1999-2024 Free Software Foundation, Inc.
>> +;; Copyright (C) 1985-1986, 1999-2025 Free Software Foundation, Inc.
>
> Please rebase on the current master branch, where the copyright years
> were already updated.

Done.

>> +(defvar lisp-fill-paragraph-as-displayed nil
>> +  "This variable can be set to true to fill paragraphs as displayed in the
>> +buffer, preserving surrounding context such as the leading indentation.
>> +This is useful if respecting `fill-column' is more important than
>> +preventing surrounding code from being filled, and makes
>> +`lisp-fill-paragraph' behave as it used to in Emacs 27 and prior
>> +versions.")
>
> The first line of a doc string should be a single full sentence.
> (This is because the various apropos commands show only the first
> line.)
>
> More importantly, I think this doc string should describe the main use
> case for which the default behavior is tuned: filling Emacs Lisp doc
> strings, with their special treatment of the first line.

I expound the docstring to add more information w.r.t. to the default
behavior of `lisp-fill-paragraph'.  I hope it addresses your comment.

I'll send v3 shortly.

-- 
Thanks,
Maxim