bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs "file"; capitalize Dired. Four other trivial TUTORIAL patches

[Stefan Kangas]

Hi Jorge,

First, I'd like to congratulate you on writing your first patch to a
free software project.  Let's hope we see many more.

"Jorge" <jorge+list@disroot.org> writes:

> January 31, 2020 6:29 AM, "Eli Zaretskii" <eliz@gnu.org> wrote:
>
>> (This is yet another reason why introducing buffers before they are
>> described in the tutorial might be a step in the wrong direction.)
>
> I understand.  I only disambiguated buffer vs file after the BUFFERS
> section.
>
>> Bottom line: I think in this case accuracy is less important than
>> providing an introduction to Emacs usage that is as free from
>> complexities as practically possible.
>
> I understand.  However, if the user learns too much inaccuracy, she can
> be confused later when she tries to consult docstrings or the Info
> manual, because (IIRC) these use technical terminology.
[...]
> So I've made a second attempt.  I don't want to waste your time with my
> OCD, so if after analyzing the second attempt you decide to just apply
> the parts you agree with (even if just the capitalization fix at the
> end: "dired" -> "Dired") and proceed to discuss the other trivial patches
> (and I can open separate bug reports for them if you wish), I'm OK with
> that.

Thanks.  Please see my comments below.

> diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
> index a7017336a7..536351c582 100644
> --- a/etc/tutorials/TUTORIAL
> +++ b/etc/tutorials/TUTORIAL
> @@ -662,13 +662,15 @@ There are many C-x commands.  Here is a list of the 
> ones you have learned:
>  
>       C-x C-f         Find file
>       C-x C-s         Save file
> -     C-x s           Save some buffers
> +     C-x s           Save some files

I think this change is good, and more consistent with what we already have.

>       C-x C-b         List buffers
>       C-x b           Switch buffer
>       C-x C-c         Quit Emacs
>       C-x 1           Delete all but one window
>       C-x u           Undo
>  
> +(Technically, C-x C-s is "save-buffer" and C-x s is save-some-buffers.)

I agree with Eli that we should probably avoid introducing the concept
of buffers here.  Even if we would want to introduce it, the suggested
text is much too terse.

> -When you have made changes in a file, but you have not saved them yet,
[...]
> +When you have made changes in a file (technically, to its buffer), but

Same comment as above.

> -You already know what the filename means--it is the file you have
> -found. 
[...]
> +You already know what "TUTORIAL" means--it is the current file's name
> +(technically it is the buffer's name, but, when you are editing a file,
> +by default that is the file's name).

I don't understand the need for this change.  Perhaps it's a matter of
taste, but I think I prefer the original.

> -If you are going to be editing human-language text, such as this file, you
> -should probably use Text Mode.
> +If you are going to be editing human-language text, such as this
> +tutorial, you should probably use Text Mode.

I don't understand the need for this either.

>  Two features that you may like especially are completion, which saves
> -typing, and dired, which simplifies file handling.
> +typing, and Dired, which simplifies file handling.

I think this qualifies as a typo: well spotted.

Best regards,
Stefan Kangas