bug#31349: 27.0; Doc of `up-list'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

>  If NO-SYNTAX-CROSSING is non-'nil' (as it is interactively), prefer to
>  break out of any enclosing string instead of moving to the start of
>  a list broken across multiple strings.  On error, location of point
>  is unspecified.
>
> Looking at the code briefly, it seems to concern not only strings but
> also comments.  If so, shouldn't the description mention that?
>
> At any rate, I don't follow the description.  Can you elaborate, perhaps
> giving an example?  If I understand the behavior then perhaps I can help
> clarify the doc.  Why were these args added?  What use cases do they
> serve?

Apparently the parameters mean exactly what they say.  As a test, do:

"foo (bar|" "zot) yes"

and eval the following two things with point at |:

(up-list nil t nil)
(up-list nil t t)

and observe the difference.  It's somewhat unclear when the nil value of
NO-SYNTAX-CROSSING would be useful, though...  but I see there's no
calls in Emacs with a non-nil ESCAPE-STRINGS, so perhaps just added for
completeness' sake?  (If you're writing Lisp broken across several C
strings, for instance, it might be handy to have a way to get to the end
of a Lisp statement...)

> (It's also not helpful or conventional to put descriptions of all args
> in the same paragraph.)

Now reformatted in Emacs 28.

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