bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

Hello,

According to the documentation, zap-up-to-char allows one to kill up
to, but not including ARGth occurrence of CHAR. No reference is made
to zap-up-to-char in
https://www.gnu.org/software/emacs/manual/html_node/emacs/Killing.html
or https://www.gnu.org/software/emacs/manual/html_node/emacs/Command-Index.html.

It isn't immediately apparent from the documentation on zap-to-char in
the above sections, and also from the source of zap-to-char, that
there exists a way of zapping up to a char without writing this code
manually. I couldn't find any combination of keys, either, to press
after pressing M-z which would result in the same functionality.

It took me quite a while to come across zap-up-to-char. Could
documentation for this function be added to the Emacs manual?

Kind regards,

Justin

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Eli Zaretskii]

> From: Justin Paston-Cooper <paston.cooper@gmail.com>
> Date: Tue, 26 Nov 2019 19:34:37 +0100
> 
> According to the documentation, zap-up-to-char allows one to kill up
> to, but not including ARGth occurrence of CHAR. No reference is made
> to zap-up-to-char in
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Killing.html
> or https://www.gnu.org/software/emacs/manual/html_node/emacs/Command-Index.html.

I see it in Command-Index.html and in Other-Kill-Commands.html, which
is a subsection of "Deletion and Killing".  Not sure why you didn't
see it there.

> Could documentation for this function be added to the Emacs manual?

It's already there, AFAICT.

Thanks.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

I can see zap-to-char mentioned and linked in the above sections, but
not zap-***up***-to-char.

On Tue, 26 Nov 2019 at 20:45, Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Justin Paston-Cooper <paston.cooper@gmail.com>
> > Date: Tue, 26 Nov 2019 19:34:37 +0100
> >
> > According to the documentation, zap-up-to-char allows one to kill up
> > to, but not including ARGth occurrence of CHAR. No reference is made
> > to zap-up-to-char in
> > https://www.gnu.org/software/emacs/manual/html_node/emacs/Killing.html
> > or https://www.gnu.org/software/emacs/manual/html_node/emacs/Command-Index.html.
>
> I see it in Command-Index.html and in Other-Kill-Commands.html, which
> is a subsection of "Deletion and Killing".  Not sure why you didn't
> see it there.
>
> > Could documentation for this function be added to the Emacs manual?
>
> It's already there, AFAICT.
>
> Thanks.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Eli Zaretskii]

> From: Justin Paston-Cooper <paston.cooper@gmail.com>
> Date: Tue, 26 Nov 2019 20:47:54 +0100
> Cc: 38392@debbugs.gnu.org
> 
> I can see zap-to-char mentioned and linked in the above sections, but
> not zap-***up***-to-char.

Sorry, you are right.

This command isn't even in NEWS, so it's completely undocumented.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

What's the decision on this? If positive, should I email a patch, or
is there someone who deals with documentation?

On Tue, 26 Nov 2019 at 21:05, Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Justin Paston-Cooper <paston.cooper@gmail.com>
> > Date: Tue, 26 Nov 2019 20:47:54 +0100
> > Cc: 38392@debbugs.gnu.org
> >
> > I can see zap-to-char mentioned and linked in the above sections, but
> > not zap-***up***-to-char.
>
> Sorry, you are right.
>
> This command isn't even in NEWS, so it's completely undocumented.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Drew Adams]

> not zap-***up***-to-char.

In Isearch we now have `isearch-yank-until-char'.

So we now have two different ways to name something
that deals with text from point forward to, but not
including, the position of some char: "up to" vs
"until".

It would be better to have a single way to name this.

---

Considering that the names `zap-to-char' and
`zap-up-to-char' are so close, and they can be
confused (witness Eli's missing the difference
here, at first), "until" seems a bit better.

On the other hand, "until" has a strong connotation
of time, and a weak one of space/distance.  And "up
to" is pretty clear, if taken apart from "to".

Really, `zap-to-char' should probably be called
`zap-through-char'.  I'd suggest using the terms
"until" (for "up to") and "through" (for zap "to").

In the improvements I suggested for Isearch (bug
#37417, emacs-devel thread "PATCH:
isearch-yank-until-match" and part of thread
"PATCH: isearch-yank-until-char"), I used
"through" for commands that act from point through
some position: `isearch-yank-through-new-match',
`isearch-yank-through-key-move', and
`isearch-yank-through-rec-edit-move'.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

What about having a class of inclusivity modifiers of the form `C-I
element` (I is isomorphic to set of inclusivities {before, through,
after}), element is either RET for defining inclusivity alone, or a
`regexp RET` for including a certain pattern, similar to C-u, which
would pass an argument to things like C-f, C-b, C-s and do the
appropriate?

On Wed, 27 Nov 2019 at 16:42, Drew Adams <drew.adams@oracle.com> wrote:
>
> > not zap-***up***-to-char.
>
> In Isearch we now have `isearch-yank-until-char'.
>
> So we now have two different ways to name something
> that deals with text from point forward to, but not
> including, the position of some char: "up to" vs
> "until".
>
> It would be better to have a single way to name this.
>
> ---
>
> Considering that the names `zap-to-char' and
> `zap-up-to-char' are so close, and they can be
> confused (witness Eli's missing the difference
> here, at first), "until" seems a bit better.
>
> On the other hand, "until" has a strong connotation
> of time, and a weak one of space/distance.  And "up
> to" is pretty clear, if taken apart from "to".
>
> Really, `zap-to-char' should probably be called
> `zap-through-char'.  I'd suggest using the terms
> "until" (for "up to") and "through" (for zap "to").
>
> In the improvements I suggested for Isearch (bug
> #37417, emacs-devel thread "PATCH:
> isearch-yank-until-match" and part of thread
> "PATCH: isearch-yank-until-char"), I used
> "through" for commands that act from point through
> some position: `isearch-yank-through-new-match',
> `isearch-yank-through-key-move', and
> `isearch-yank-through-rec-edit-move'.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Drew Adams]

> What about having a class of inclusivity modifiers of the form `C-I
> element` (I is isomorphic to set of inclusivities {before, through,
                                                     ^^^^^^
> after}),
  ^^^^^
> element is either RET for defining inclusivity alone, or a
> `regexp RET` for including a certain pattern, similar to C-u, which
> would pass an argument to things like C-f, C-b, C-s and do the
> appropriate?

Just a comment about "before" and "after":

Those terms should be used only if the functionality
really does proceed in a particular buffer direction.

For example, the proposed Isearch commands I
mentioned, which have names with "through", can
work in either forward or backward direction, so
in their case "after" or "before" would be wrong,
for the command name.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

What about near, through and far?

On Wed, 27 Nov 2019 at 17:04, Drew Adams <drew.adams@oracle.com> wrote:
>
> > What about having a class of inclusivity modifiers of the form `C-I
> > element` (I is isomorphic to set of inclusivities {before, through,
>                                                      ^^^^^^
> > after}),
>   ^^^^^
> > element is either RET for defining inclusivity alone, or a
> > `regexp RET` for including a certain pattern, similar to C-u, which
> > would pass an argument to things like C-f, C-b, C-s and do the
> > appropriate?
>
> Just a comment about "before" and "after":
>
> Those terms should be used only if the functionality
> really does proceed in a particular buffer direction.
>
> For example, the proposed Isearch commands I
> mentioned, which have names with "through", can
> work in either forward or backward direction, so
> in their case "after" or "before" would be wrong,
> for the command name.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Drew Adams]

> What about near, through and far?

What about them?

I've already spoken to "through".  How do you
see "near" and "far" fitting into this?

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

[-- Attachment #1: Type: text/plain, Size: 1146 bytes --]

Sorry for my terrible reading comprehension.

I suppose you’re saying that exactly two ‘inclusivities’ suffice: ‘up
to/until’ and 'through' in your case, which makes complete sense.

I have found that both 'up to' and 'until' are still ambiguous, for
instance when trying to agree on a date with someone. This ambiguity might
carry over to the Emacs world, where a user might not know that there is
another distinct inclusivity called 'through'. 'up to' and 'until' can mean
either 'inclusive' or 'exclusive', this seemingly depending on the phase of
the Moon. I still use the words 'inclusive' and 'exclusive' to confirm. I
hope that at least programmers don't find that silly. Of course, there is
an existing precedent of 'up to', 'until', 'through' and 'to'.

Regardless of the naming, wouldn’t an inclusivity modifier over the set of
two inclusivities be a nice thing to have?

On Wed, 27 Nov 2019 at 17:45, Drew Adams <drew.adams@oracle.com> wrote:

> > What about near, through and far?
>
> What about them?
>
> I've already spoken to "through".  How do you
> see "near" and "far" fitting into this?
>

[-- Attachment #2: Type: text/html, Size: 1799 bytes --]

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Drew Adams]

> I suppose you’re saying that exactly two ‘inclusivities’ suffice: ‘up to/until’ and 'through' in your case, which makes complete sense.

I wasn't speaking to what might suffice.  I was just
pointing out that we use `up-to' for zapping and `until' for searching - and we mean the same thing by them.  And I mentioned `through' as a possible name for including the final char. 

> I have found that both 'up to' and 'until' are still ambiguous, for instance when trying to agree on a date with someone. This ambiguity might carry over to the Emacs world, where a user might not know that there is another distinct inclusivity called 'through'. 'up to' and 'until' can mean either 'inclusive' or 'exclusive', this seemingly depending on the phase of the Moon. I still use the words 'inclusive' and 'exclusive' to confirm. I hope that at least programmers don't find that silly. Of course, there is an existing precedent of 'up to', 'until', 'through' and 'to'.

Yes, the terms are ambiguous.  If we use consistent
names and the doc is clear then I don't think there's
a problem in practice.  But yes, in conversation,
and particularly with dates/times, people can need
to discuss a bit to be sure to be on the same page.

> Regardless of the naming, wouldn’t an inclusivity modifier over the set of two inclusivities be a nice thing to have?

No idea.  Modifier where?  Here we're talking about
function names.  I don't think we need to or should
add such a thing to the names.

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Justin Paston-Cooper]

[-- Attachment #1: Type: text/plain, Size: 2001 bytes --]

On Wed, 27 Nov 2019 at 22:46, Drew Adams <drew.adams@oracle.com> wrote:

> > I suppose you’re saying that exactly two ‘inclusivities’ suffice: ‘up
> to/until’ and 'through' in your case, which makes complete sense.
>
> I wasn't speaking to what might suffice.  I was just
> pointing out that we use `up-to' for zapping and `until' for searching -
> and we mean the same thing by them.  And I mentioned `through' as a
> possible name for including the final char.


>
> > I have found that both 'up to' and 'until' are still ambiguous, for
> instance when trying to agree on a date with someone. This ambiguity might
> carry over to the Emacs world, where a user might not know that there is
> another distinct inclusivity called 'through'. 'up to' and 'until' can mean
> either 'inclusive' or 'exclusive', this seemingly depending on the phase of
> the Moon. I still use the words 'inclusive' and 'exclusive' to confirm. I
> hope that at least programmers don't find that silly. Of course, there is
> an existing precedent of 'up to', 'until', 'through' and 'to'.
>
> Yes, the terms are ambiguous.  If we use consistent
> names and the doc is clear then I don't think there's
> a problem in practice.  But yes, in conversation,
> and particularly with dates/times, people can need
> to discuss a bit to be sure to be on the same page.


Fair enough.


>
> > Regardless of the naming, wouldn’t an inclusivity modifier over the set
> of two inclusivities be a nice thing to have?
>
> No idea.  Modifier where?  Here we're talking about
> function names.  I don't think we need to or should
> add such a thing to the names.


> The idea was that there could be a key combination entered before commands
related to movement, killing, searching and so on which would pass an
argument to those commands determining their inclusivity. Similar to the
idea behind T and t in viper-mode. Not sure how it would tie in with the
numerical argument, though.

[-- Attachment #2: Type: text/html, Size: 2831 bytes --]

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Phil Sainty]

Eli wrote:
> I'm not sure we should have it in the manual.  The fact that you
> wanted it doesn't yet mean it's useful enough to have in the manual.
> 
> Does anyone else have an opinion?

Mentioning only one of the two commands just seems arbitrary,
so I think it should be either "both" or "neither" for the sake
of consistency.

I think the manual should mention both of them, and that their
docstrings should probably mention one another as well, so that
users can learn about these alternatives more easily.


-Phil

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Lars Ingebrigtsen]

Phil Sainty <psainty@orcon.net.nz> writes:

> I think the manual should mention both of them, and that their
> docstrings should probably mention one another as well, so that
> users can learn about these alternatives more easily.

Yup.  Both variants seem equally useful (that is, not really  :-)).

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

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Yup.  Both variants seem equally useful (that is, not really  :-)).

FWIW, I use zap-up-to-char almost every day.  Try it!  You might like
it, and end up being a weirdo like me.  ;-)

Best regards,
Stefan Kangas

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> FWIW, I use zap-up-to-char almost every day.  Try it!  You might like
> it, and end up being a weirdo like me.  ;-)

I'm very set in my "move the point around and kill the region" ways.  :-)

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

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Eli Zaretskii]

> Date: Thu, 28 Nov 2019 13:45:20 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> 
> Eli wrote:
> > I'm not sure we should have it in the manual.  The fact that you
> > wanted it doesn't yet mean it's useful enough to have in the manual.
> > 
> > Does anyone else have an opinion?
> 
> Mentioning only one of the two commands just seems arbitrary,
> so I think it should be either "both" or "neither" for the sake
> of consistency.
> 
> I think the manual should mention both of them, and that their
> docstrings should probably mention one another as well, so that
> users can learn about these alternatives more easily.

Thanks, done (I only added the reference to the doc string of
zap-to-char, though).

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Stefan Kangas]

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

> In Isearch we now have `isearch-yank-until-char'.
>
> So we now have two different ways to name something
> that deals with text from point forward to, but not
> including, the position of some char: "up to" vs
> "until".
>
> It would be better to have a single way to name this.
>
> ---
>
> Considering that the names `zap-to-char' and
> `zap-up-to-char' are so close, and they can be
> confused (witness Eli's missing the difference
> here, at first), "until" seems a bit better.
>
> On the other hand, "until" has a strong connotation
> of time, and a weak one of space/distance.  And "up
> to" is pretty clear, if taken apart from "to".
>
> Really, `zap-to-char' should probably be called
> `zap-through-char'.  I'd suggest using the terms
> "until" (for "up to") and "through" (for zap "to").

FWIW, I think `zap-until-char' and `zap-through-char' would be less
clear than the current names.

I agree with the point about consistency.  It would be better then to
rename `isearch-yank-until-char' to `isearch-yank-up-to-char' instead
of renaming the old commands, I think.

Best regards,
Stefan Kangas

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Drew Adams]

> > In Isearch we now have `isearch-yank-until-char'.
> >
> > So we now have two different ways to name something
> > that deals with text from point forward to, but not
> > including, the position of some char: "up to" vs
> > "until".
> >
> > It would be better to have a single way to name this.
> >
> > ---
> >
> > Considering that the names `zap-to-char' and
> > `zap-up-to-char' are so close, and they can be
> > confused (witness Eli's missing the difference
> > here, at first), "until" seems a bit better.
> >
> > On the other hand, "until" has a strong connotation
> > of time, and a weak one of space/distance.  And "up
> > to" is pretty clear, if taken apart from "to".
> >
> > Really, `zap-to-char' should probably be called
> > `zap-through-char'.  I'd suggest using the terms
> > "until" (for "up to") and "through" (for zap "to").
> 
> FWIW, I think `zap-until-char' and `zap-through-char' would be less
> clear than the current names.
> 
> I agree with the point about consistency.  It would be better then to
> rename `isearch-yank-until-char' to `isearch-yank-up-to-char' instead
> of renaming the old commands, I think.

No objection from me.

Consistency can help in general, but it's not an
imperative.  More important than global consistency
is local consistency (e.g. within Isearch, don't use
more than one way to name the same thing).

It's probably too late to change `zap-to-char', but
I think that `through' is clearer than `to', when
the char is included.  `zap-through-char' would be
clearer, and it's confusing to have both `-to-' and
`-up-to-'.

(There currently is no Isearch yank command that has
"through" semantics, but I added a couple in my code
and in the patch I submitted for bug #37417.)

bug#38392: zap-up-to-char should appear in "Deletion and Killing" Emacs info section and "Command Index"

[Eli Zaretskii]

> From: Justin Paston-Cooper <paston.cooper@gmail.com>
> Date: Wed, 27 Nov 2019 11:11:24 +0100
> Cc: 38392@debbugs.gnu.org
> 
> What's the decision on this? If positive, should I email a patch, or
> is there someone who deals with documentation?

I'm not sure we should have it in the manual.  The fact that you
wanted it doesn't yet mean it's useful enough to have in the manual.

Does anyone else have an opinion?