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

["Jorge" <jorge+list@disroot.org>]

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.

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?]]