bug#30502: 26.0.91; electric-pair-mode documentation

bug#30502: 26.0.91; electric-pair-mode documentation

[Charles A. Roelli]

When you turn on electric-pair-mode from emacs -q, then select a
region and type an opening delimeter like "(", the region is
surrounded by the "(" and ")" characters, the mark is deactivated, and
point is left after the opening delimeter.  This should be documented.
(I searched for documentation but have not found any.)

Also, this functionality requires transient-mark-mode to be on.  Are
there any equivalent "wrapping" commands for use when
transient-mark-mode is off?  If not, maybe we should add some.

bug#30502: 26.0.91; electric-pair-mode documentation

[Eli Zaretskii]

> Date: Sat, 17 Feb 2018 17:07:53 +0100
> From: charles@aurox.ch (Charles A. Roelli)
> 
> When you turn on electric-pair-mode from emacs -q, then select a
> region and type an opening delimeter like "(", the region is
> surrounded by the "(" and ")" characters, the mark is deactivated, and
> point is left after the opening delimeter.  This should be documented.
> (I searched for documentation but have not found any.)

Which part of this is undocumented?  Did you see the description of
Electric pair mode in the "Matching" node of the user manual?

> Also, this functionality requires transient-mark-mode to be on.

I don't see it.  I can turn off transient-mark-mode, and the feature
still works.  Maybe I don't understand what you mean by "this
functionality"?

Thanks.

bug#30502: 26.0.91; electric-pair-mode documentation

[Charles A. Roelli]

> Date: Sat, 17 Feb 2018 18:21:16 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> CC: 30502@debbugs.gnu.org
> Reply-to: Eli Zaretskii <eliz@gnu.org>
> 
> > Date: Sat, 17 Feb 2018 17:07:53 +0100
> > From: charles@aurox.ch (Charles A. Roelli)
> > 
> > When you turn on electric-pair-mode from emacs -q, then select a
> > region and type an opening delimeter like "(", the region is
> > surrounded by the "(" and ")" characters, the mark is deactivated, and
> > point is left after the opening delimeter.  This should be documented.
> > (I searched for documentation but have not found any.)
> 
> Which part of this is undocumented?  Did you see the description of
> Electric pair mode in the "Matching" node of the user manual?

Yes, I did.  The node does not mention anything about automatically
inserting a matching delimeter at the mark when the region is active
and a delimeter character is typed.  For example, it could say,

Whenever you insert an opening delimiter, the matching closing
delimiter is automatically inserted as well (at the mark, if the
region is active), leaving point between the two.

instead of,

Whenever you insert an opening delimiter, the matching closing
delimiter is automatically inserted as well, leaving point between the
two.

> > Also, this functionality requires transient-mark-mode to be on.
> 
> I don't see it.  I can turn off transient-mark-mode, and the feature
> still works.  Maybe I don't understand what you mean by "this
> functionality"?

By "this functionality" I mean auto-inserting a matching delimeter at
the mark when a delimeter character is typed, when electric-pair-mode
is on.  The region has to be active for this to work, therefore
transient-mark-mode must be on (even if temporarily).  I suggest
adding a command that wraps point and mark with some given delimeters,
regardless of whether the region is active.

bug#30502: 26.0.91; electric-pair-mode documentation

[Eli Zaretskii]

> Date: Sat, 17 Feb 2018 17:51:45 +0100
> From: charles@aurox.ch (Charles A. Roelli)
> CC: 30502@debbugs.gnu.org
> 
> The node does not mention anything about automatically
> inserting a matching delimeter at the mark when the region is active
> and a delimeter character is typed.

Thanks, I documented that now.  In the doc string of the mode as well.

> By "this functionality" I mean auto-inserting a matching delimeter at
> the mark when a delimeter character is typed, when electric-pair-mode
> is on.  The region has to be active for this to work, therefore
> transient-mark-mode must be on (even if temporarily).  I suggest
> adding a command that wraps point and mark with some given delimeters,
> regardless of whether the region is active.

We have "C-u C-x C-x" that turns on transient-mark-mode temporarily.
Isn't that enough?  If not, the issue is general, not specific to this
mode.

bug#30502: 26.0.91; electric-pair-mode documentation

[Charles A. Roelli]

> Date: Sat, 17 Feb 2018 19:31:42 +0200
> From: Eli Zaretskii <eliz@gnu.org>
>
> Thanks, I documented that now.  In the doc string of the mode as well.

Thanks a lot for the improvement.  With that, I'll close this bug.

> > By "this functionality" I mean auto-inserting a matching delimeter at
> > the mark when a delimeter character is typed, when electric-pair-mode
> > is on.  The region has to be active for this to work, therefore
> > transient-mark-mode must be on (even if temporarily).  I suggest
> > adding a command that wraps point and mark with some given delimeters,
> > regardless of whether the region is active.
> 
> We have "C-u C-x C-x" that turns on transient-mark-mode temporarily.
> Isn't that enough?  If not, the issue is general, not specific to this
> mode.

"C-u C-x C-x" does work well enough, but Emacs normally also provides
commands that explicitly do some subset of what a region-aware command
would do in the same situation.  For example, if you want to comment
out the region with transient-mark-mode switched off, you can either
type:

C-u C-x C-x [exchange-point-and-mark]
M-; [comment-dwim]

or more memorably, clearly, and without moving point,

M-x comment-region RET

I like having both options available, but the latter is preferable IMO.
Hence we could have some command that would be used like,

M-x wrap-region RET ( RET

to wrap a region explicitly.