all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#55788: [PATCH] Improve documentation of the raise-sexp command
       [not found] <m1y1ydnuj5.fsf.ref@yahoo.es>
@ 2022-06-04  0:26 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2022-06-04 11:58   ` Lars Ingebrigtsen
  0 siblings, 1 reply; 8+ messages in thread
From: Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-06-04  0:26 UTC (permalink / raw)
  To: 55788

[-- 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


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-04  0:26 ` 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
@ 2022-06-04 11:58   ` Lars Ingebrigtsen
  2022-06-06  7:33     ` Juri Linkov
  0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-04 11:58 UTC (permalink / raw)
  To: Daniel Martín; +Cc: 55788

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-04 11:58   ` Lars Ingebrigtsen
@ 2022-06-06  7:33     ` Juri Linkov
  2022-06-06 10:44       ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Juri Linkov @ 2022-06-06  7:33 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 55788, Daniel Martín

>   "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.





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-06  7:33     ` Juri Linkov
@ 2022-06-06 10:44       ` Eli Zaretskii
  2022-06-06 12:57         ` Lars Ingebrigtsen
  0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-06-06 10:44 UTC (permalink / raw)
  To: Juri Linkov; +Cc: larsi, 55788, mardani29

> 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.






^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-06 10:44       ` Eli Zaretskii
@ 2022-06-06 12:57         ` Lars Ingebrigtsen
  2022-06-06 13:05           ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-06 12:57 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: mardani29, 55788, Juri Linkov

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-06 12:57         ` Lars Ingebrigtsen
@ 2022-06-06 13:05           ` Eli Zaretskii
  2022-06-06 13:13             ` Lars Ingebrigtsen
  0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-06-06 13:05 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: mardani29, 55788, juri

> 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))"





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-06 13:05           ` Eli Zaretskii
@ 2022-06-06 13:13             ` Lars Ingebrigtsen
  2022-06-06 14:11               ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-06 13:13 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: mardani29, 55788, juri

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#55788: [PATCH] Improve documentation of the raise-sexp command
  2022-06-06 13:13             ` Lars Ingebrigtsen
@ 2022-06-06 14:11               ` Eli Zaretskii
  0 siblings, 0 replies; 8+ messages in thread
From: Eli Zaretskii @ 2022-06-06 14:11 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: mardani29, 55788, juri

> 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.





^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2022-06-06 14:11 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <m1y1ydnuj5.fsf.ref@yahoo.es>
2022-06-04  0:26 ` 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
2022-06-04 11:58   ` Lars Ingebrigtsen
2022-06-06  7:33     ` Juri Linkov
2022-06-06 10:44       ` Eli Zaretskii
2022-06-06 12:57         ` Lars Ingebrigtsen
2022-06-06 13:05           ` Eli Zaretskii
2022-06-06 13:13             ` Lars Ingebrigtsen
2022-06-06 14:11               ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.