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

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

[Drew Adams]

In Emacs 25, apparently, two additional optional args were added to
`up-list'.  But the doc added for the second of these args is not
understandable, to me.

The doc is identical for the doc string and the manual, so going to
either from the other didn't help me understand.

This is the description of the second new arg:

 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?

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

In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

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

[Noam Postavsky]

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

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

In *scratch*, put cursor inside a string literal, e.g.,

    "point here->.<--"

doing C-M-u will bring you ouside the string in Emacs 25+.  In previous
versions, you get

up-list: Scan error: "Unbalanced parentheses", 205, 1

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Wed, 02 May 2018 20:57:48 -0400
> Cc: 31349@debbugs.gnu.org
> 
> In *scratch*, put cursor inside a string literal, e.g.,
> 
>     "point here->.<--"
> 
> doing C-M-u will bring you ouside the string in Emacs 25+.

"C-M-u" doesn't run up-list, though.

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

[Drew Adams]

> > 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?
> 
> In *scratch*, put cursor inside a string literal, e.g.,
> 
>     "point here->.<--"
> 
> doing C-M-u will bring you ouside the string in Emacs 25+.  In previous
> versions, you get
> 
> up-list: Scan error: "Unbalanced parentheses", 205, 1

Thanks.  (But I guess you meant `C-M-^'.)

But what does moving to the beginning (or end) of a string,
even in the absence of any list, have to do with moving
_up a list_ level?  Why does `up-list' do this now?

OK, from Eli's msg I see that this was discussed.  I guess
I missed that discussion.  Stefan said that this change
was "long overdue", but I don't see why and what this has
to do with moving up list levels.  In the example you gave,
Noam, there's no list involved at all.

(It seems odd, BTW, that Daniel said in that discussion,
about Stefan's suggestion, "Your proposed behavior is a
departure from what we have today."  So is Daniel's
proposal and patch a departure.  And we departed...)

Anyway I was, and still am, really asking about the
_second_ new arg added, NO-SYNTAX-CROSSING.

I can guess that the command now (incompatibly) "moves out
of enclosing strings", based on what is said about new arg
ESCAPE-STRINGS (though it's too bad that we use "escape"
in this sense, since it is usually used to mean escaping
chars etc.).

But what is the doc trying to say about arg NO-SYNTAX-CROSSING?

And why is it that the design gives these two _optional_
args NON-nil values?  That's not very conventional.  (It
can happen, but it's not typical.)

And why this incompatible change, instead of creating a
_new_ command that does what was aimed at (which is, 
apparently, to either move up N list levels or move to
a string/comment beginning/end, plus whatever behavior
is due to NO-SYNTAX-CROSSING?

Even after reading that discussion I don't understand
why was this incompatible change was made.  I don't see
what problem it tries to solve.  And the purpose of
NO-SYNTAX-CROSSING is unclear to me.

And why wasn't this change even called out in NEWS?
(I couldn't find it there, at least.)

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

[Eli Zaretskii]

> Date: Wed, 2 May 2018 17:45:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This is the description of the second new arg:
> 
>  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.

I agree that the doc string could use some clarifications, especially
in the "prefer to break" part and the "list broken across multiple
strings" part.

Also, it seems there's a copy-paste error: both up-list and
backward-up-list talks about going to start of a list, whereas one of
them (up-list, AFAIU) should talk about end of a list.

> Why were these args added?

See this discussion:

  http://lists.gnu.org/archive/html/emacs-devel/2014-04/msg00110.html

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