bug#51032: 29.0.50; Choices for blink-matching-paren

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 5 Oct 2021 17:23:22 -0400
> Cc: Arash Esbati <arash@gnu.org>, 51032@debbugs.gnu.org
> 
> > I wonder if the documentation is correct.  The off-screen position of an
> > open paren is shown in the echo area when the variable is non-nil and
> > not 'jump-offscreen (and of course the open paren is off-screen).
> >
> > I don't see how 'show is treated differently than t.
> 
> Yup, there is no particular behavior associated with `show'.
> 
> Valid choices here include nil, t, `jump', and `jump-offscreen', and
> while the last one will move the cursor off screen, t and jump will only
> show the position in the echo area.

And 'show' (or 'foo', or any other non-nil value) does NOT show the
matching paren in the echo area when that position is off-screen?  It
does here, FWIW.

>  (defcustom blink-matching-paren t
>    "Non-nil means show matching open-paren when close-paren is inserted.
> -If t, highlight the paren.  If `jump', briefly move cursor to its
> -position.  If `jump-offscreen', move cursor there even if the
> -position is off screen.  With any other non-nil value, the
> -off-screen position of the opening paren will be shown in the
> -echo area."
> +In addition, if the opening paren is not visible on screen, show
> +its position in the echo area.
> +
> +The valid values are:
> +
> +  nil               Disable.
> +  non-nil           Highlight the opening paren.
> +  `jump'            Briefly move cursor to its position.
                                              ^^^
What does "its" there allude to?

> +  `jump-offscreen'  Briefly move cursor to its position,

Likewise.

> +                    even if the opening paren is not on screen."

This doesn't update the choices, which is what the original bug report
was about.  And I think the new doc string is incomplete, because you
removed the information about showing matches that are far away in the
echo-area.