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

From: "Jorge" <[email-masked]>
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?]]