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

Previous Next

Package: emacs;

Reported by: "Jorge" <jorge+list <at> disroot.org>

Date: Thu, 30 Jan 2020 15:43:01 UTC

Severity: minor

Tags: fixed, patch

Fixed in version 28.1

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39359 in the body.
You can then email your comments to 39359 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Thu, 30 Jan 2020 15:43:01 GMT) Full text and rfc822 format available.

Acknowledgement sent to "Jorge" <jorge+list <at> disroot.org>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Thu, 30 Jan 2020 15:43:01 GMT) Full text and rfc822 format available.

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

From: "Jorge" <jorge+list <at> disroot.org>
To: bug-gnu-emacs <at> gnu.org
Subject: [patch] TUTORIAL: Be accurate about "buffer" vs "file";
 capitalize Dired.  Four other trivial TUTORIAL patches
Date: Thu, 30 Jan 2020 15:41:48 +0000
Hello.  This trivial patch is my first patch submitted to a free
software project (not counting wiki edits), so please do not hesitate to
correct any mistakes (including the potential mistake of being too
nitpicky).  Now the commit message, followed by the patch:

TUTORIAL: Be accurate about "buffer" vs "file"; capitalize Dired

- Disambiguate "buffer" vs "file" after the section that explains
  buffers.
- Capitalize "Dired".

--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index a7017336a7..4f24264f4d 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -662,5 +662,5 @@ 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 C-s		Save buffer
 	C-x s		Save some buffers
 	C-x C-b		List buffers
@@ -697,11 +697,11 @@ want to change only some of the occurrences.)
 -----------
 
-When you have made changes in a file, but you have not saved them yet,
-they could be lost if your computer crashes.  To protect you from
-this, Emacs periodically writes an "auto save" file for each file that
-you are editing.  The auto save file name has a # at the beginning and
-the end; for example, if your file is named "hello.c", its auto save
-file's name is "#hello.c#".  When you save the file in the normal way,
-Emacs deletes its auto save file.
+When you have made changes in a file-visiting buffer, but you have not
+saved them yet, they could be lost if your computer crashes.  To
+protect you from this, Emacs periodically writes an "auto save" file
+for each such buffer that you are editing.  The auto save file name has
+a # at the beginning and the end; for example, if your file is named
+"hello.c", its auto save file's name is "#hello.c#".  When you save
+the buffer in the normal way, Emacs deletes its auto save file.
 
 If the computer crashes, you can recover your auto-saved editing by
@@ -731,6 +731,6 @@ This line gives useful information about the status of Emacs and
 the text you are editing.
 
-You already know what the filename means--it is the file you have
-found.  NN% indicates your current position in the buffer text; it
+You already know what "TUTORIAL" means--it is the current buffer's
+name.  NN% indicates your current position in the buffer text; it
 means that NN percent of the buffer is above the top of the screen.
 If the top of the buffer is on the screen, it will say "Top" instead
@@ -764,6 +764,6 @@ switch to that mode.  For example, M-x fundamental-mode is a command to
 switch to Fundamental mode.
 
-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
+buffer, you should probably use Text Mode.
 
 >> Type M-x text-mode <Return>.
@@ -1085,5 +1085,5 @@ You can learn more about Emacs by reading its manual, either as a
 printed book, or inside Emacs (use the Help menu or type C-h r).
 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.
 
 Completion is a way to avoid unnecessary typing.  For instance, if you
--8<---------------cut here---------------end--------------->8---


Below are four other tiny patches to the TUTORIAL.  The largest adds
two lines.  If you wish, I can open a separate bug report for each.

TUTORIAL: Put the least relevant (nowadays) reason last
--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index eb3acde9c0..ee2ed65378 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -186,12 +186,13 @@ to type M-< also; without the shift key, you would be typing M-comma.
 
 You can also move the cursor with the arrow keys, if your terminal has
 arrow keys.  We recommend learning C-b, C-f, C-n and C-p for three
-reasons.  First, they work on all kinds of terminals.  Second, once
-you gain practice at using Emacs, you will find that typing these Control
-characters is faster than typing the arrow keys (because you do not
-have to move your hands away from touch-typing position).  Third, once
-you form the habit of using these Control character commands, you can
-easily learn to use other advanced cursor motion commands as well.
+reasons.  First, once you gain practice at using Emacs, you will find
+that typing these Control characters is faster than typing the arrow
+keys (because you do not have to move your hands away from
+touch-typing position).  Second, once you form the habit of using
+these Control character commands, you can easily learn to use other
+advanced cursor motion commands as well.  Third, they work on all
+kinds of terminals.
 
 Most Emacs commands accept a numeric argument; for most commands, this
 serves as a repeat-count.  The way you give a command a repeat count
--8<---------------cut here---------------end--------------->8---


TUTORIAL: One can save to a file /after/ entering the text, via C-x C-w
--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index ee2ed65378..29b76792ea 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -490,8 +490,8 @@ whether you can yank it with C-y; it makes no difference for undo.
 
 In order to make the text you edit permanent, you must put it in a
 file.  Otherwise, it will go away when you exit Emacs.  In order to
-put your text in a file, you must "find" the file before you enter the
-text.  (This is also called "visiting" the file.)
+put your text in a file, you normally "find" the file before you enter
+the text.  (This is also called "visiting" the file.)
 
 Finding a file means that you see the contents of the file within
 Emacs.  In many ways, it is as if you were editing the file itself.
--8<---------------cut here---------------end--------------->8---


TUTORIAL: Mention (in passing) Emacs server for quick edits
--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 29b76792ea..dcfd2a3315 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -656,7 +656,7 @@ can resume Emacs with the "fg" command or with "%emacs".
 
 The time to use C-x C-c is when you are about to log out.  It's also
 the right thing to use to exit an Emacs invoked for a quick edit, such
-as by a mail handling utility.
+as by a mail handling utility (unless you use the Emacs server feature).
 
 There are many C-x commands.  Here is a list of the ones you have learned:
--8<---------------cut here---------------end--------------->8---


TUTORIAL: Query-replace is more user-friendly than replace-string

If we mention just replace-string, we might leave the impression that
it is the usual way to do find-and-replace in Emacs, and thus scare
the user.
--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index dcfd2a3315..a7017336a7 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -690,6 +690,8 @@ argument with <Return>.
    "changed" with "altered" wherever it occurred, after the
    initial position of the cursor.
 
+(The command query-replace, by default bound to M-%, is useful if you
+want to change only some of the occurrences.)
 
 * AUTO SAVE
 -----------
--8<---------------cut here---------------end--------------->8---

And I noticed the TUTORIAL exceeds the 72-character line limit in a few
places.  Can I refill it?

Regards
--
- I am Brazilian.  I hope my English is correct and I welcome feedback
- Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z
- Free/libre software for Android: https://f-droid.org/
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Fri, 31 Jan 2020 09:30:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Jorge" <jorge+list <at> disroot.org>
Cc: 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: Fri, 31 Jan 2020 11:29:09 +0200
> Date: Thu, 30 Jan 2020 15:41:48 +0000
> From: "Jorge" <jorge+list <at> disroot.org>
> 
> Hello.  This trivial patch is my first patch submitted to a free
> software project (not counting wiki edits), so please do not hesitate to
> correct any mistakes (including the potential mistake of being too
> nitpicky).  Now the commit message, followed by the patch:
> 
> TUTORIAL: Be accurate about "buffer" vs "file"; capitalize Dired
> 
> - Disambiguate "buffer" vs "file" after the section that explains
>   buffers.

Thanks.

Personally, my gut feeling is that we shouldn't introduce this
complexity in the tutorial.  Users coming from other editors are used
to saying "save the file" (and the evidence is the File->Save menu
item present in many applications, including Emacs).  So "save file"
is natural, whereas "save buffer into the file it visits" is less so,
and for newbies any complication at this stage is an obstacle.  It is
no accident that buffers are described in the tutorial only after
files.  (This is yet another reason why introducing buffers before
they are described in the tutorial might be a step in the wrong
direction.)

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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Fri, 31 Jan 2020 13:29:02 GMT) Full text and rfc822 format available.

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

From: "Jorge" <jorge+list <at> disroot.org>
To: "Eli Zaretskii" <eliz <at> gnu.org>
Cc: 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: Fri, 31 Jan 2020 13:28:14 +0000
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.

Besides, the current tutorial is slightly inconsistent in the EXTENDING
THE COMMAND SET section, because it says "Save file" for C-x C-s, but
"Save some buffers" for	C-x s.

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.

--8<---------------cut here---------------start------------->8---
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
 	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.)
+
 Named eXtended commands are commands which are used even less
 frequently, or commands which are used only in certain modes.  An
 example is the command replace-string, which replaces one string with
@@ -696,13 +698,13 @@ want to change only some of the occurrences.)
 * AUTO SAVE
 -----------
 
-When you have made changes in a file, but you have not saved them yet,
-they could be lost if your computer crashes.  To protect you from
-this, Emacs periodically writes an "auto save" file for each file that
-you are editing.  The auto save file name has a # at the beginning and
-the end; for example, if your file is named "hello.c", its auto save
-file's name is "#hello.c#".  When you save the file in the normal way,
-Emacs deletes its auto save file.
+When you have made changes in a file (technically, to its buffer), but
+you have not saved them yet, they could be lost if your computer
+crashes.  To protect you from this, Emacs periodically writes an "auto
+save" file for each file that you are editing.  The auto save file
+name has a # at the beginning and the end; for example, if your file
+is named "hello.c", its auto save file's name is "#hello.c#".  When
+you save the file in the normal way, Emacs deletes its auto save file.
 
 If the computer crashes, you can recover your auto-saved editing by
 finding the file normally (the file you were editing, not the auto
@@ -730,13 +732,15 @@ The mode line says something like this:
 This line gives useful information about the status of Emacs and
 the text you are editing.
 
-You already know what the filename means--it is the file you have
-found.  NN% indicates your current position in the buffer text; it
-means that NN percent of the buffer is above the top of the screen.
-If the top of the buffer is on the screen, it will say "Top" instead
-of " 0%".  If the bottom of the buffer is on the screen, it will say
-"Bot".  If you are looking at a buffer so small that all of it fits on
-the screen, the mode line says "All".
+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).  NN% indicates your current
+position in the buffer text; it means that NN percent of the buffer is
+above the top of the screen.  If the top of the buffer is on the
+screen, it will say "Top" instead of " 0%".  If the bottom of the
+buffer is on the screen, it will say "Bot".  If you are looking at a
+buffer so small that all of it fits on the screen, the mode line says
+"All".
 
 The L and digits indicate position in another way: they give the
 current line number of point.
@@ -763,8 +767,8 @@ major mode is the name of an extended command, which is how you can
 switch to that mode.  For example, M-x fundamental-mode is a command to
 switch to Fundamental mode.
 
-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.
 
 >> Type M-x text-mode <Return>.
 
@@ -1084,7 +1088,7 @@ corresponding command names (such as C-x C-f beside find-file).
 You can learn more about Emacs by reading its manual, either as a
 printed book, or inside Emacs (use the Help menu or type C-h r).
 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.
 
 Completion is a way to avoid unnecessary typing.  For instance, if you
 want to switch to the *Messages* buffer, you can type C-x b *M<Tab>
--8<---------------cut here---------------end--------------->8---

Regards
- I am Brazilian.  I hope my English is correct and I welcome feedback
- Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z
- Free/libre software for Replicant, LineageOS and Android: https://f-droid.org/
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]




Severity set to 'minor' from 'normal' Request was from Noam Postavsky <npostavs <at> gmail.com> to control <at> debbugs.gnu.org. (Thu, 20 Feb 2020 16:08:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sat, 29 Feb 2020 05:04:01 GMT) Full text and rfc822 format available.

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




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Tue, 03 Mar 2020 11:31:01 GMT) Full text and rfc822 format available.

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

From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
To: Stefan Kangas <stefan <at> marxist.se>
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: Tue, 03 Mar 2020 08:30:25 -0300
Hi.

Em [2020-02-29 sáb 06:02:54+0100], Stefan Kangas escreveu:

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

Thank you!

And you accepted parts of my first trivial patch.  However, the original
email in this thread had four other trivial patches for the tutorial.
Can you look at them or do you want me to open four separate bug
reports?  Again, I hope not to waste your time with my OCD, so please
give me feedback if I am being too nitpicky.

Regards
-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Free Software Supporter:
  <https://www.fsf.org/free-software-supporter/subscribe>




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Fri, 24 Apr 2020 10:11:01 GMT) Full text and rfc822 format available.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Jorge P. de Morais Neto <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: Fri, 24 Apr 2020 12:10:19 +0200
Jorge P. de Morais Neto <jorge+list <at> disroot.org> writes:

>> First, I'd like to congratulate you on writing your first patch to a
>> free software project.  Let's hope we see many more.
>
> Thank you!
>
> And you accepted parts of my first trivial patch.  However, the original
> email in this thread had four other trivial patches for the tutorial.
> Can you look at them or do you want me to open four separate bug
> reports?  Again, I hope not to waste your time with my OCD, so please
> give me feedback if I am being too nitpicky.

Sorry for the late reply here.

Could you please send a new patch including these changes?  I had a
look at your first message but found it hard to ascertain what it is
exactly that you're proposing.

Best regards,
Stefan Kangas




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 07 Jun 2020 16:22:02 GMT) Full text and rfc822 format available.

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

From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
To: Stefan Kangas <stefan <at> marxist.se>
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: Sun, 07 Jun 2020 13:20:46 -0300
Em [2020-04-24 sex 12:10:19+0200], Stefan Kangas escreveu:

> Could you please send a new patch including these changes?  I had a
> look at your first message but found it hard to ascertain what it is
> exactly that you're proposing.

I did not understand what is difficult to understand about my first
message.  It has five patches, each surrounded by the output of
~message-mark-inserted-region~ and preceded by a tentative commit
message.  I also did not understand what you asked above.  Maybe my
English comprehension has failed me (I am Brazilian).

Anyway, here is the revised first patch, preceded by a tentative commit
message -- is this what you asked for?:

TUTORIAL: "buffer" vs "file" consistency; capitalize Dired

- For consistency with C-x C-f ("Find file") and C-x C-s ("Save file"),
  refer to C-x s as "Save some files".
- Capitalize "Dired".
--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index eb3acde9c0..4465e32e81 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -612,11 +612,11 @@ but it also means that you need a convenient way to save the first
 file's buffer.  Having to switch back to that buffer, in order to save
 it with C-x C-s, would be a nuisance.  So we have
 
-	C-x s     Save some buffers
+	C-x s     Save some files
 
-C-x s asks you about each buffer which contains changes that you have
-not saved.  It asks you, for each such buffer, whether to save the
-buffer.
+C-x s asks you about each file-visiting buffer which contains changes
+that you have not saved.  It asks you, for each such buffer, whether
+to save the buffer.
 
 >> Insert a line of text, then type C-x s.
    It should ask you whether to save the buffer named TUTORIAL.
@@ -661,7 +661,7 @@ 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
 	C-x C-b		List buffers
 	C-x b		Switch buffer
 	C-x C-c		Quit Emacs
@@ -1081,7 +1081,7 @@ corresponding command names (such as C-x C-f beside find-file).
 You can learn more about Emacs by reading its manual, either as a
 printed book, or inside Emacs (use the Help menu or type C-h r).
 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.
 
 Completion is a way to avoid unnecessary typing.  For instance, if you
 want to switch to the *Messages* buffer, you can type C-x b *M<Tab>
--8<---------------cut here---------------end--------------->8---

Best regards,
  Jorge

-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- <https://www.defectivebydesign.org/>
- <https://www.gnu.org/>




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 07 Jun 2020 16:42:01 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
Cc: 39359 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs
 "file"; capitalize Dired. Four other trivial TUTORIAL patches
Date: Sun, 07 Jun 2020 19:40:50 +0300
> From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 39359 <at> debbugs.gnu.org
> Date: Sun, 07 Jun 2020 13:20:46 -0300
> 
> - For consistency with C-x C-f ("Find file") and C-x C-s ("Save file"),
>   refer to C-x s as "Save some files".

But that is inaccurate: "C-x C-f" indeed reads a file into a buffer,
but "C-x C-f" saves the _buffer_ into its file.  "Save file" is not
what "C-x C-s" does, since the file is not saved anywhere.

How about saying "Save some buffers to their files" instead?

Thanks.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 07 Jun 2020 18:02:01 GMT) Full text and rfc822 format available.

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

From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39359 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs
 "file"; capitalize Dired. Four other trivial TUTORIAL patches
Date: Sun, 07 Jun 2020 15:01:29 -0300
Em [2020-06-07 dom 19:40:50+0300], Eli Zaretskii escreveu:

>> - For consistency with C-x C-f ("Find file") and C-x C-s ("Save file"),
>>   refer to C-x s as "Save some files".
>
> But that is inaccurate: "C-x C-f" indeed reads a file into a buffer,
> but "C-x C-f" saves the _buffer_ into its file.  "Save file" is not
> what "C-x C-s" does, since the file is not saved anywhere.
>
> How about saying "Save some buffers to their files" instead?

You mean like this?

--8<---------------cut here---------------start------------->8---
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index eb3acde9c0..227c13f3e3 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -612,11 +612,11 @@ but it also means that you need a convenient way to save the first
 file's buffer.  Having to switch back to that buffer, in order to save
 it with C-x C-s, would be a nuisance.  So we have
 
-	C-x s     Save some buffers
+	C-x s     Save some buffers to their files
 
-C-x s asks you about each buffer which contains changes that you have
-not saved.  It asks you, for each such buffer, whether to save the
-buffer.
+C-x s asks you about each file-visiting buffer which contains changes
+that you have not saved.  It asks you, for each such buffer, whether
+to save the buffer to its file.
 
 >> Insert a line of text, then type C-x s.
    It should ask you whether to save the buffer named TUTORIAL.
@@ -660,8 +660,8 @@ as by a mail handling utility.
 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 C-s		Save buffer to file
+	C-x s		Save some buffers to their files
 	C-x C-b		List buffers
 	C-x b		Switch buffer
 	C-x C-c		Quit Emacs
@@ -1081,7 +1081,7 @@ corresponding command names (such as C-x C-f beside find-file).
 You can learn more about Emacs by reading its manual, either as a
 printed book, or inside Emacs (use the Help menu or type C-h r).
 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.
 
 Completion is a way to avoid unnecessary typing.  For instance, if you
 want to switch to the *Messages* buffer, you can type C-x b *M<Tab>
 --8<---------------cut here---------------end--------------->8---

Best regards,
  Jorge

-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Free Software Supporter: <https://www.fsf.org/free-software-supporter>
- If an email of mine arrives at your spam box, please notify me.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 07 Jun 2020 18:07:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
Cc: 39359 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs
 "file"; capitalize Dired. Four other trivial TUTORIAL patches
Date: Sun, 07 Jun 2020 21:06:21 +0300
> From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
> Cc: stefan <at> marxist.se, 39359 <at> debbugs.gnu.org
> Date: Sun, 07 Jun 2020 15:01:29 -0300
> 
> > But that is inaccurate: "C-x C-f" indeed reads a file into a buffer,
> > but "C-x C-f" saves the _buffer_ into its file.  "Save file" is not
> > what "C-x C-s" does, since the file is not saved anywhere.
> >
> > How about saying "Save some buffers to their files" instead?
> 
> You mean like this?

Yes, thanks.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 07 Jun 2020 18:25:03 GMT) Full text and rfc822 format available.

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

From: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39359 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#39359: [patch] TUTORIAL: Be accurate about "buffer" vs
 "file"; capitalize Dired. Four other trivial TUTORIAL patches
Date: Sun, 07 Jun 2020 15:24:21 -0300
Em [2020-06-07 dom 21:06:21+0300], Eli Zaretskii escreveu:

> Yes, thanks.

Then you can apply that instead of the first patch of my original
email.  I suggest the following commit message:

TUTORIAL: "buffer" vs "file" consistency; capitalize Dired

- For consistency with C-x s ("save some buffers") and for accuracy,
  describe C-x C-s as "Save buffer to file"), and then C-x s as "Save
  some buffers to their files"
- Capitalize "Dired".

Regards

-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Free Software Supporter: <https://www.fsf.org/free-software-supporter>
- If an email of mine arrives at your spam box, please notify me.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#39359; Package emacs. (Sun, 09 Aug 2020 11:48:02 GMT) Full text and rfc822 format available.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Jorge P. de Morais Neto <jorge+list <at> disroot.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, stefan <at> marxist.se, 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: Sun, 09 Aug 2020 13:47:30 +0200
Jorge P. de Morais Neto <jorge+list <at> disroot.org> writes:

> Then you can apply that instead of the first patch of my original
> email.  I suggest the following commit message:
>
> TUTORIAL: "buffer" vs "file" consistency; capitalize Dired
>
> - For consistency with C-x s ("save some buffers") and for accuracy,
>   describe C-x C-s as "Save buffer to file"), and then C-x s as "Save
>   some buffers to their files"
> - Capitalize "Dired".

Thanks for the patch; I've applied it to Emacs 28.1.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




Added tag(s) fixed. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Sun, 09 Aug 2020 11:48:02 GMT) Full text and rfc822 format available.

bug marked as fixed in version 28.1, send any further explanations to 39359 <at> debbugs.gnu.org and "Jorge" <jorge+list <at> disroot.org> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Sun, 09 Aug 2020 11:48:02 GMT) Full text and rfc822 format available.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Mon, 07 Sep 2020 11:24:07 GMT) Full text and rfc822 format available.

This bug report was last modified 3 years and 203 days ago.

Previous Next


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