Subject: Re: bug#16074: 24.3.50; enhancement request: Remove "pop" from command names & doc for `C-(u|x) C-SPC'

From: Juri Linkov <[email-masked]>
Date: Sun, 25 Aug 2019 23:09:45 +0300

>> >> Yes, renaming here seems like a good idea.
>> >
>> > How about the attached patch?
>>
>> I think that looks like the correct solution.
>
> It doesn't address the problem for the `mark-ring',
> does it?  My impression was that it addresses it
> only for `global-mark-ring'.  The local `mark-ring'
> is used much more often than the `global-mark-ring',
> and its doc is probably accessed much more often.
>
> For example -
>
> This part of `C-h k C-SPC' is wrong:
>
>  With prefix argument (e.g., C-u C-SPC), jump to the mark,
>  and set the mark from position popped off the local mark
>                                 ^^^^^^^^^^
>  ring (this does not affect the global mark ring).
>  ...
>
>  If 'set-mark-command-repeat-pop' is non-nil, repeating
>  the C-SPC command with no prefix argument pops the next
>  position off the local (or global) mark ring and jumps there.
>
>  With C-u C-u as prefix argument, unconditionally set
>  mark where point is, even if 'set-mark-command-repeat-pop'
>  is non-nil.
>
> And the doc & name of option `set-mark-command-repeat-pop'
> are wrong (plus, the line lengths are screwy):
>
>  Non-nil means repeating C-SPC after popping mark
>  pops it again.
>  That means that C-u C-SPC C-SPC
>  will pop the mark twice, and
>  C-u C-SPC C-SPC C-SPC
>  will pop the mark three times.
>
> And the doc & name of function `pop-to-mark-command'
> are wrong:
>
>  Jump to mark, and pop a new position for mark off the ring.
>
> A position is NOT popped off the ring.  That's what's
> wrong with all of these.  Likewise, the doc in the
> manuals.
>
> The enhancement request is to fix this wrong
> terminology wrt BOTH `global-mark-ring' and
> `mark-ring'.

And `yank' doesn't yank, and `kill' doesn't kill literally.
What is the most important is that docstrings should describe
the behavior in all details.  The name is more a matter of taste.