bug#32047: 26.1; Misleading/confusing text about `C-k' in TUTORIAL

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Cc: 32047@debbugs.gnu.org
> Date: Wed, 11 Jul 2018 15:46:07 -0400
> 
> At 19:12 +0300 on Wednesday 2018-07-11, Eli Zaretskii wrote:
> >
> >> From: nljlistbox2@gmail.com (N. Jackson)
> >> Date: Tue, 03 Jul 2018 21:34:33 -0400
> >> 
> >> 414 >> Move the cursor to the beginning of a line which is not empty.
> >> 415    Then type C-k to kill the text on that line.
> >> 416 >> Type C-k a second time.  You'll see that it kills the Newline
> >> 417    which follows that line.
> >> 418 
> >> 419 Note that a single C-k kills the contents of the line, and a second
> >> 420 C-k kills the line itself, and makes all the other lines move up.  C-k
> >> 421 treats a numeric argument specially: it kills that many lines AND
> >> 422 their contents.  This is not mere repetition.  C-u 2 C-k kills two
> >> 423 lines and their Newlines; typing C-k twice would not do that.
> >> 
> >> The example(s) given in Lines 414 to 417 are correct. But the
> >> sentence beginning on Line 419 is misleading. It is only true
> >> when point is at the beginning of the line.
> >
> > But in this case, point _is_ at the beginning of the line,
> > isn't it?
> 
> No. Well, maybe! If the paragraph beginning at Line 419 is
> talking about the preceding example, then yes, point is at the
> beginning of the line and the first sentence is okay.

It definitely does talk about the example before the text.  That's how
tutorial are written: they show an example, and then talk about that
example.

> My reading of the paragraph was that it was talking about C-k in
> general, not specifically about the preceding example.

I see no reason to assume that.

> A reading borne out by the following sentences about numeric
> arguments which do not feature in the example.

That's another widely accepted methodology in tutorials: after
explaining something simple, build on that to explain more complicated
stuff.  In this case, the _only_ complication is the argument.  The
fact that the text introduces the argument does not mean it is now
talking about C-k in general -- nothing in tutorials is ever general,
unless the text explicitly says so.

> Perhaps this is all that would be needed to make this clear:
> 
>   In the preceding example note that a single C-k ...
> 
> > So I wonder whether it is worth it to complicate the text just
> > for accuracy's sake?
> 
> No, I don't think it makes sense to add any more complication
> here. This is the tutorial, not the documentation, after all.

Indeed.

> In fact, the discussion of C-k is more complicated, I think,
> than anything else in the tutorial, and it might be an
> improvement to drop the discussion of subtle difference in
> behaviour of C-k with numeric arguments -- the actual behaviour
> then is easy to understand when one uses it and it doesn't seem
> that the tutorial is the place to belabour this point.

I actually think that the behavior of C-k with an argument is an
important part of teaching that arguments in Emacs are not always just
repetition.