bug#55788: [PATCH] Improve documentation of the raise-sexp command

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 608 bytes --]


The documentation of the raise-sexp command is:

  Raise ARG sexps higher up the tree.

I think this description is not very helpful, because it basically
repeats what's already in the command name (but what does "raise"
mean?), and the meaning of "tree" is not clear.  The fact that the
command is not described in the Elisp manual doesn't help either.

I propose to change it to something more descriptive, like:

  Replace the enclosing parenthesis structure with ARG sexps from point.

If you think it's a good improvement to Emacs, you can install the
attached patch with my proposed change.

Thanks.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-of-raise-sexp.patch --]
[-- Type: text/x-patch, Size: 922 bytes --]

From 5d64c8aea06af7586e11f71b546c142c5ed07930 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es>
Date: Sat, 4 Jun 2022 02:20:09 +0200
Subject: [PATCH] Improve documentation of raise-sexp

* lisp/emacs-lisp/lisp.el (raise-sexp): Make the documentation of the
command more useful.
---
 lisp/emacs-lisp/lisp.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/lisp.el b/lisp/emacs-lisp/lisp.el
index ffca0dcf4f..39c286ff3e 100644
--- a/lisp/emacs-lisp/lisp.el
+++ b/lisp/emacs-lisp/lisp.el
@@ -858,7 +858,7 @@ delete-pair
       (delete-char 1))))
 
 (defun raise-sexp (&optional arg)
-  "Raise ARG sexps higher up the tree."
+  "Replace the enclosing parenthesis structure with ARG sexps from point."
   (interactive "p")
   (let ((s (if (and transient-mark-mode mark-active)
                (buffer-substring (region-beginning) (region-end))
-- 
2.34.1

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Lars Ingebrigtsen]

Daniel Martín <mardani29@yahoo.es> writes:

> I propose to change it to something more descriptive, like:
>
>   Replace the enclosing parenthesis structure with ARG sexps from point.

I don't think that really explains a lot more than the current doc
string.

But there's no need to be terse here, and in a case like this, an
example explains more than any text could, so I've changed the doc
string to this in Emacs 29 now:

  "Raise ARG sexps higher up the tree.
This means that the ARGth enclosing form will be deleted and
replaced with the form that follows point.

For instance, if you have:

  (let ((foo 2))
    (progn
      (setq foo 3)
      (zot)
      (+ foo 2)))

and point is before (zot), `M-x raise-sexp' will give you

  (let ((foo 2))
    (zot))"


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Juri Linkov]

>   "Raise ARG sexps higher up the tree.
> This means that the ARGth enclosing form will be deleted and
> replaced with the form that follows point.
>
> For instance, if you have:
>
>   (let ((foo 2))
>     (progn
>       (setq foo 3)
>       (zot)
>       (+ foo 2)))
>
> and point is before (zot), `M-x raise-sexp' will give you
>
>   (let ((foo 2))
>     (zot))"

It seems that new docstring suggests that `M-2 M-x raise-sexp' will give

  (zot)

whereas really it will give

  (let ((foo 2))
    (zot)
    (+ foo 2))

since ARG is the number of sexps that follow point and that will be raised.

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Eli Zaretskii]

> Cc: 55788@debbugs.gnu.org, Daniel Martín <mardani29@yahoo.es>
> From: Juri Linkov <juri@linkov.net>
> Date: Mon, 06 Jun 2022 10:33:25 +0300
> 
> >   "Raise ARG sexps higher up the tree.
> > This means that the ARGth enclosing form will be deleted and
> > replaced with the form that follows point.
> >
> > For instance, if you have:
> >
> >   (let ((foo 2))
> >     (progn
> >       (setq foo 3)
> >       (zot)
> >       (+ foo 2)))
> >
> > and point is before (zot), `M-x raise-sexp' will give you
> >
> >   (let ((foo 2))
> >     (zot))"
> 
> It seems that new docstring suggests that `M-2 M-x raise-sexp' will give
> 
>   (zot)
> 
> whereas really it will give
> 
>   (let ((foo 2))
>     (zot)
>     (+ foo 2))
> 
> since ARG is the number of sexps that follow point and that will be raised.

Right.  Is the below better?

    Raise ARG sexps one level higher up the tree.

  This function removes the sexp enclosing the form which follows
  point, and then re-inserts ARG sexps following point, thus raising
  them one level up.

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Right.  Is the below better?
>
>     Raise ARG sexps one level higher up the tree.
>
>   This function removes the sexp enclosing the form which follows
>   point, and then re-inserts ARG sexps following point, thus raising
>   them one level up.

Much better.  But perhaps ARG should be renamed to NUM or something to
make things clearer.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Juri Linkov <juri@linkov.net>,  55788@debbugs.gnu.org,  mardani29@yahoo.es
> Date: Mon, 06 Jun 2022 14:57:44 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Right.  Is the below better?
> >
> >     Raise ARG sexps one level higher up the tree.
> >
> >   This function removes the sexp enclosing the form which follows
> >   point, and then re-inserts ARG sexps following point, thus raising
> >   them one level up.
> 
> Much better.  But perhaps ARG should be renamed to NUM or something to
> make things clearer.

Like this?

  (defun raise-sexp (&optional n)
    "Raise N sexps one level higher up the tree.

  This function removes the sexp enclosing the form which follows
  point, and then re-inserts N sexps following point, thus raising
  those N sexps one level up.

  Interactively, N is the numeric prefix argument, and defaults to 1.

  For instance, if you have:

    (let ((foo 2))
      (progn
	(setq foo 3)
	(zot)
	(+ foo 2)))

  and point is before (zot), \\[raise-sexp] will give you

    (let ((foo 2))
      (zot))"

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Like this?
>
>   (defun raise-sexp (&optional n)
>     "Raise N sexps one level higher up the tree.
>
>   This function removes the sexp enclosing the form which follows
>   point, and then re-inserts N sexps following point, thus raising
>   those N sexps one level up.
>
>   Interactively, N is the numeric prefix argument, and defaults to 1.

Yup, looks good.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55788: [PATCH] Improve documentation of the raise-sexp command

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: juri@linkov.net,  55788@debbugs.gnu.org,  mardani29@yahoo.es
> Date: Mon, 06 Jun 2022 15:13:56 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Like this?
> >
> >   (defun raise-sexp (&optional n)
> >     "Raise N sexps one level higher up the tree.
> >
> >   This function removes the sexp enclosing the form which follows
> >   point, and then re-inserts N sexps following point, thus raising
> >   those N sexps one level up.
> >
> >   Interactively, N is the numeric prefix argument, and defaults to 1.
> 
> Yup, looks good.

Thanks, installed.