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

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

[N. Jackson]

At around Line 419 of the Emacs tutorial there are two
statements which are not strictly correct, which might
potentially cause confusion.

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.

Likewise the sentence beginning in Line 420 and the sentence
beginning in Line 422 ("C-u 2 C-k kills...") about using `C-k'
with a numeric argument are misleading in the same way -- the
writer is assuming that point was at the beginning of a line
without telling the reader of the assumption.

[In my opinion, what gets the text into trouble is that it
starts talking about `C-k' killing lines, when what it really
does (despite its name `kill-line') is kill from point to the
end of a line, except when point is at the end of a line when it
deletes the Newline separating the line from the following line
(if any). This is made clear in the examples in Lines 414 to 417
and then confuddled in the paragraph at Line 419.

To really kill lines one needs `kill-whole-line'. Whereas
`kill-line' is best thought of as "kill to end of line".]


In GNU Emacs 26.1 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.22.26)
 of 2018-05-28 built on moondust.localdomain
Windowing system distributor 'Fedora Project', version 11.0.11906000
System Description:	Fedora release 27 (Twenty Seven)

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

[Eli Zaretskii]

> 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?
So I wonder whether it is worth it to complicate the text just for
accuracy's sake?

What do others think?

Thanks.

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

[Filipp Gunbin]

On 11/07/2018 19:12 +0300, 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?
> So I wonder whether it is worth it to complicate the text just for
> accuracy's sake?
>
> What do others think?

I think the doc is clear and cannot see what's so special about the
beginning of line..

Maybe an example would help.

Filipp

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

[N. Jackson]

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.

My reading of the paragraph was that it was talking about C-k in
general, not specifically about the preceding example. A reading
borne out by the following sentences about numeric arguments
which do not feature in the example.

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.

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.

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

[N. Jackson]

At 22:14 +0300 on Wednesday 2018-07-11, Filipp Gunbin wrote:
>
>>> 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.

> I think the doc is clear

This is not the documentation of C-k, it is the Emacs Tutorial.

> and cannot see what's so special about the beginning of line..

Perhaps you did not read the OP [1]. There's nothing special
about the beginning of the line when using C-k to kill the rest
of the line, but when C-k is used to "kill the contents of the
line" -- as it is in the example -- then point must be at the
beginning of the line.

The writer of the Tutorial makes an assumption that point is at
the beginning of the line without telling the reader of that
assumption.


[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32047#5

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.

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

[Filipp Gunbin]

On 11/07/2018 16:45 -0400, N. Jackson wrote:

> Perhaps you did not read the OP [1]. There's nothing special
> about the beginning of the line when using C-k to kill the rest
> of the line, but when C-k is used to "kill the contents of the
> line" -- as it is in the example -- then point must be at the
> beginning of the line.
>
> The writer of the Tutorial makes an assumption that point is at
> the beginning of the line without telling the reader of that
> assumption.
>
>
> [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32047#5

Ah, it's about "contents of the whole line" vs. "contents of the line
from point to end of line".

Anyway, I'd read that "Note that a single C-k..." as an additional note
about the actions the user just did, so there is context.  Otherwise,
it'd start just with "A single C-k...".

Filipp

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

[N. Jackson]

At 21:34 -0400 on Tuesday 2018-07-03, N. Jackson wrote:
>
> At around Line 419 of the Emacs tutorial there are two
> statements which are not strictly correct, which might
> potentially cause confusion.

Hmm... well if no one agrees with me about this, perhaps the
potential confusion is only in my imagination.

I only reported this because I had just gone through the
Tutorial from beginning to end (after not looking at it for
eight years) -- so I felt that I was almost looking at it with
fresh eyes -- and everything in it seemed good to me except this
one paragraph.

[The only other fault that I found with it is that I felt that
it goes almost, but not quite, far enough to teach a new user
"how to fish".]

So if no one else chimes in with an opinion in the next few
weeks, this bug can probably best be closed so that it doesn't
clutter up the bug tracker.

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

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Date: Thu, 12 Jul 2018 16:09:40 -0400
> 
> [The only other fault that I found with it is that I felt that
> it goes almost, but not quite, far enough to teach a new user
> "how to fish".]

Please elaborate on this, I don't think I understand what that means
in practice.

Thanks.