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

Previous Next

Full log

Message #16 received at 39359 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: "Jorge" <jorge+list <at> disroot.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 39359 <at> debbugs.gnu.org
Subject: Re: bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs "file";
 capitalize Dired. Four other trivial TUTORIAL patches
Date: Sat, 29 Feb 2020 06:02:54 +0100

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 <at> disroot.org> writes:

> January 31, 2020 6:29 AM, "Eli Zaretskii" <eliz <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.