On Sun, 04 May 2025 08:05:23 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <stephen.berman@gmx.net>
>> Cc: 78021@debbugs.gnu.org,  drew.adams@oracle.com
>> Date: Sun, 04 May 2025 00:31:08 +0200
>> 
>> Thanks, I've made the changes you suggested.  If that now completes this
>> revision of the Electric Pair mode documentation for the Emacs manual,
>> should I go ahead and install it to emacs-30, or would you prefer to
>> wait for improvements to the corresponding doc strings in
>> electric-pair.el, and have all the doc changes installed as one
>> changeset?  If the latter, I'll make a patch for review as soon as I
>> can.
>
> I'd prefer a single patch with all the documentation changes for this
> mode.

I've now finished the patch and attached it.  On rereading my changes
for the Emacs manual I realized that my use of the terms "matching" and
"of the same type" was confusing (and confused); Drew drew attention to
that upthread but I misconstrued it then.  I've adjusted the text
accordingly (mainly in the description of
`electric-pair-preserve-balance') and also replaced the infelicitous
"unmatched" with "unpaired".  In electric-pair.el I tried to clarify and
improve not just the doc strings of the user options documented in the
manual but also a number of others that I found unclear.  I also added
text to the Commentary section, corrected several typos and in one case
reformatted overlong lines of code.

If you agree with these changes I'll push them to emacs-30, using the
ChangeLog entry below as the commit message.

Steve Berman

Improve Electric Pair mode documentation (bug#78021)

* doc/emacs/programs.texi (Matching): Clarify and improve
documentation of Electric Pair mode.

* lisp/elec-pair.el: Improve description in header line.  Add text
and a reference to the Emacs user manual in the Commentary section.
(electric-pair-skip-self, electric-pair-inhibit-predicate)
(electric-pair-preserve-balance)
(electric-pair-delete-adjacent-pairs)
(electric-pair-open-newline-between-pairs)
(electric-pair-skip-whitespace)
(electric-pair-skip-whitespace-function)
(electric-pair-analyze-conversion)
(electric-pair--skip-whitespace)
(electric-pair-text-syntax-table, electric-pair-syntax-info)
(electric-pair--insert, electric-pair--syntax-ppss)
(electric-pair--balance-info)
(electric-pair-inhibit-if-helps-balance)
(electric-pair-skip-if-helps-balance)
(electric-pair-open-newline-between-pairs-psif)
(electric-pair-mode): Clarify and improve doc strings and some comments.
(electric-pair-post-self-insert-function): Restructure doc string
to shorten overlong first line, and reformat overlong lines of code.