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

[Eli Zaretskii <eliz@gnu.org>]

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