GNU bug report logs - #11689
[PATCH 00/14] Copyediting: etc/tutorials/TUTORIAL

Previous Next

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

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

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 00/14] Copyediting: etc/tutorials/TUTORIAL
Date: Wed, 13 Jun 2012 00:00:54 -0000

Whilst reading through the TUTORIAL, I made a few minor modifications.
The following is a summary of the resulting patch series, the last
patch of which adds an entry to etc/ChangeLog:

  etc/tutorials/TUTORIAL: Remove text saying `C-x 1' is first 2-char command

  etc/tutorials/TUTORIAL: Describe the act of scrolling text more consistently

  etc/tutorials/TUTORIAL: Remove redundant comparison of killing and deleting

  etc/tutorials/TUTORIAL: Eradicate the future tense

  etc/tutorials/TUTORIAL: Minor rewording to streamline and generalize `C-x s'
                          intro

  etc/tutorials/TUTORIAL: Use `application' consistently by replacing an
                          occurence of `program'

  etc/tutorials/TUTORIAL: Generalize the description of when to use `C-x C-c'

  etc/tutorials/TUTORIAL: Remove the word `globally'

  etc/tutorials/TUTORIAL: Replace occurences of `--' with more appropriate
                          text

  etc/tutorials/TUTORIAL: c-h-a-n-g-e-d -> "changed"

  etc/tutorials/TUTORIAL: Complete instructions by telling the user to move
                          the cursor

  etc/tutorials/TUTORIAL: Make consistent the white space around `>>'
                          instructions

  etc/tutorials/TUTORIAL: Place `C-x C-f' beside `find-file' for clarity

  etc/ChangeLog: Note my patch series for etc/tutorials/TUTORIAL

 etc/ChangeLog          |  10 +++++
 etc/tutorials/TUTORIAL | 118 ++++++++++++++++++++++++++++---------------------
 2 files changed, 78 insertions(+), 50 deletions(-)

-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 01/14] etc/tutorials/TUTORIAL: Remove text saying `C-x 1' is
	first 2-char command
Date: Wed, 13 Jun 2012 00:05:43 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

There are previous examples and explanations of multi-character commands,
so pointing out this quality is not really consistent or even worthwhile.
---
 etc/tutorials/TUTORIAL | 2 --
 1 file changed, 2 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index ccd438a..c68f239 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -281,8 +281,6 @@ other windows.
 
 >> Type C-x 1 and see the documentation listing window disappear.
 
-This command is unlike the other commands you have learned in that it
-consists of two characters.  It starts with the character CONTROL-x.
 There is a whole series of commands that start with CONTROL-x; many of
 them have to do with windows, files, buffers, and related things.
 These commands are two, three or four characters long.
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 02/14] etc/tutorials/TUTORIAL: Describe the act of scrolling
	text more consistently
Date: Wed, 13 Jun 2012 00:06:29 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

The action of "scrolling the text up and down" is commonly described
as "scrolling the screen (or window) down and up". In particular, note
the way in which the two descriptions use direction; scrolling may
be interpreted as either moving the text with respect to the user's
view, or moving the user's view with respect to the text.

This commit clarifies this discrepancy in terminology, and introduces
language that prefers EMACS's tradition of describing the scrolling
of text (rather than of screens/windows).
---
 etc/tutorials/TUTORIAL | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index c68f239..e873023 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -208,22 +208,31 @@ those you have learned so far) use it as a flag--the presence of a
 prefix argument, regardless of its value, makes the command do
 something different.
 
-C-v and M-v are another kind of exception.  When given an argument,
-they scroll the screen up or down by that many lines, rather than by a
-screenful.  For example, C-u 8 C-v scrolls the screen by 8 lines.
+C-v and M-v are other exceptions.  When given an argument, each scrolls
+the text up or down, respectively, by that many lines, rather than by
+the usual screenful of text.  For example, C-u 8 C-v scrolls the text
+up by 8 lines.
 
 >> Try typing C-u 8 C-v now.
 
-This should have scrolled the screen up by 8 lines.  If you would like
-to scroll it down again, you can give an argument to M-v.
+This should have scrolled the text up by 8 lines.  If you would like
+to scroll the text down again, you can give an argument to M-v.
 
 If you are using a graphical display, such as X or MS-Windows, there
 should be a tall rectangular area called a scroll bar on one side of
 the Emacs window.  You can scroll the text by clicking the mouse in
-the scroll bar.
+the scroll bar; one often drags the scroll bar's handle, a rectangular
+region that is within the scroll bar and that is used to represent the
+portion of the text that is currently visible in the associated window.
 
 If your mouse has a wheel button, you can also use this to scroll.
 
+(Note that "scrolling the text up and down" is commonly described as
+"scrolling the screen (or window) down and up". In particular, note
+the way in which the two descriptions use direction; scrolling may
+be interpreted as either moving the text with respect to the user's
+view, or moving the user's view with respect to the text.)
+
 
 * IF EMACS STOPS RESPONDING
 ---------------------------
@@ -873,7 +882,7 @@ Emacs terms.)
    Both windows display this tutorial.  The editing cursor stays in
    the top window.
 
->> Type C-M-v to scroll the bottom window.
+>> Type C-M-v to scroll the text of the bottom window up.
    (If you do not have a real META key, type <ESC> C-v.)
 
 >> Type C-x o ("o" for "other") to move the cursor to the bottom window.
@@ -891,7 +900,8 @@ display, those cursors are drawn as unblinking hollow boxes.
 
 The command C-M-v is very useful when you are editing text in one
 window and using the other window just for reference.  Without leaving
-the selected window, you can scroll the other window with C-M-v.
+the selected window, you can use C-M-v to scroll the text of the other
+window up.
 
 C-M-v is an example of a CONTROL-META character.  If you have a META
 (or Alt) key, you can type C-M-v by holding down both CONTROL and META
@@ -1042,7 +1052,7 @@ This displays in another window a list of all M-x commands with "file"
 in their names.  You will see character-commands like C-x C-f listed
 beside the corresponding command names such as find-file.
 
->> Type C-M-v to scroll the help window.  Do this a few times.
+>> Type C-M-v to scroll the text of the help window up.  Do this a few times.
 
 >> Type C-x 1 to delete the help window.
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 03/14] etc/tutorials/TUTORIAL: Remove redundant comparison of
	killing and deleting
Date: Wed, 13 Jun 2012 00:06:46 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

There's no point in rehashing the distinction; it is enough simply to state
that undoing the removal of text works regardless of how that text was
removed.
---
 etc/tutorials/TUTORIAL | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index e873023..e426056 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -469,9 +469,9 @@ convenient to type.
 
 A numeric argument to C-/, C-_, or C-x u acts as a repeat count.
 
-You can undo deletion of text just as you can undo killing of text.
-The distinction between killing something and deleting it affects
-whether you can yank it with C-y; it makes no difference for undo.
+You can undo the removal of text regardless of whether the text was
+yanked or killed; there is no distinction as far as undoing is
+concerned.
 
 
 * FILES
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 04/14] etc/tutorials/TUTORIAL: Eradicate the future tense
Date: Wed, 13 Jun 2012 00:07:05 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

There is usually very little value in using the future tense when
writing about universal and eternal principles.
---
 etc/tutorials/TUTORIAL | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index e426056..7d027f7 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -532,8 +532,8 @@ not lost.  The new name is made by adding "~" to the end of the
 original file's name.
 
 When saving is finished, Emacs displays the name of the file written.
-You should save fairly often, so that you will not lose very much
-work if the system should crash (see the section "Auto Save" below).
+You should save fairly often, so that you do not lose very much
+work if the system crashes (see the section "Auto Save" below).
 
 >> Type C-x C-s TUTORIAL <Return>.
    This should save this tutorial to a file named TUTORIAL, and show
@@ -541,10 +541,10 @@ work if the system should crash (see the section "Auto Save" below).
 
 You can find an existing file, to view it or edit it.  You can also
 find a file which does not already exist.  This is the way to create a
-file with Emacs: find the file, which will start out empty, and then
+file with Emacs: find the file, which starts out empty, and then
 begin inserting the text for the file.  When you ask to "save" the
-file, Emacs will really create the file with the text that you have
-inserted.  From then on, you can consider yourself to be editing an
+file, Emacs actually creates the file with the text that you have
+inserted.  From then on, you may consider yourself to be editing an
 already existing file.
 
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 05/14] etc/tutorials/TUTORIAL: Minor rewording to streamline
	and generalize `C-x s' intro
Date: Wed, 13 Jun 2012 00:07:33 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000
---
 etc/tutorials/TUTORIAL | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 7d027f7..3f0942c 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -603,7 +603,7 @@ in that file's buffer.  The creation or editing of the second file's
 buffer has no effect on the first file's buffer.  This is very useful,
 but it also means that you need a convenient way to save the first
 file's buffer.  It would be a nuisance to have to switch back to
-it with C-x C-f in order to save it with C-x C-s.  So we have
+a buffer in order to save it with C-x C-s, so we have
 
 	C-x s     Save some buffers
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 06/14] etc/tutorials/TUTORIAL: Use `application' consistently
	by replacing an occurence of `program'
Date: Wed, 13 Jun 2012 00:08:02 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000
---
 etc/tutorials/TUTORIAL | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 3f0942c..e0eaa35 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -638,7 +638,7 @@ If you are using a graphical display, you don't need any special
 command to move from Emacs to another application.  You can do this
 with the mouse or with window manager commands.  However, if you're
 using a text terminal which can only show one application at a time,
-you need to "suspend" Emacs to move to any other program.
+you need to "suspend" Emacs to move to any other application.
 
 C-z is the command to exit Emacs *temporarily*--so that you can go
 back to the same Emacs session afterward.  When Emacs is running on a
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 07/14] etc/tutorials/TUTORIAL: Generalize the description of
	when to use `C-x C-c'
Date: Wed, 13 Jun 2012 00:08:19 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

Listing the specific case of "mail handling programs" so prominently was
confusing to me at first blush. Also, the original text mixes plurality;
an Emacs can only be invoked by ONE such program at a time, a pedantic
subtlety that is reflected in the new language.
---
 etc/tutorials/TUTORIAL | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index e0eaa35..0b3cd77 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -647,8 +647,8 @@ but does not destroy the Emacs job.  In the most common shells, you
 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 under mail handling
-programs and other miscellaneous utilities.
+the right thing to use to exit an Emacs invoked for temporary input
+by some utility (such as a mail handling program).
 
 There are many C-x commands.  Here is a list of the ones you have learned:
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 08/14] etc/tutorials/TUTORIAL: Remove the word `globally'
Date: Wed, 13 Jun 2012 00:08:33 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

If anything, "in the buffer" is the more accurate notion to convey;
I would have liked to write "in the active buffer", but that extended
the line of text a bit too much, requiring changes to more lines
(would that there were a widely used diff format more amenable to
altering human languages).
---
 etc/tutorials/TUTORIAL | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 0b3cd77..a754b47 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -663,8 +663,8 @@ There are many C-x commands.  Here is a list of the ones you have learned:
 
 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 globally replaces one
-string with another.  When you type M-x, Emacs prompts you at the
+example is the command replace-string, which replaces one string with
+another in the buffer.  When you type M-x, Emacs prompts you at the
 bottom of the screen with M-x and you should type the name of the
 command; in this case, "replace-string".  Just type "repl s<TAB>" and
 Emacs will complete the name.  (<TAB> is the Tab key, usually found
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 09/14] etc/tutorials/TUTORIAL: Replace occurences of `--'
	with more appropriate text
Date: Wed, 13 Jun 2012 00:08:50 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

Under TeX and Texinfo, `---' is actually what is meant to be an
em dash, so that would be a better choice than `--', and is thus
used to replace `--' a few times.

However, other occurrences of `--' have been replaced entirely
with other punctuation (such as `:' or `;' or `,') or verbiage in
order to make the intention clearer.
---
 etc/tutorials/TUTORIAL | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index a754b47..ba89417 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -204,7 +204,7 @@ For instance, C-u 8 C-f moves forward eight characters.
 
 Most commands use the numeric argument as a repeat count, but some
 commands use it in some other way.  Several commands (but none of
-those you have learned so far) use it as a flag--the presence of a
+those you have learned so far) use it as a flag---the presence of a
 prefix argument, regardless of its value, makes the command do
 something different.
 
@@ -311,7 +311,7 @@ the last character typed.
 There may also be another key on your keyboard labeled <Delete>, but
 that's not the one we refer to as <DEL>.
 
->> Do this now--type a few characters, then delete them by
+>> Do this now; type a few characters, then delete them by
    typing <DEL> a few times.  Don't worry about this file
    being changed; you will not alter the master tutorial.
    This is your personal copy of it.
@@ -344,7 +344,7 @@ Remember that most Emacs commands can be given a repeat count;
 this includes text characters.  Repeating a text character inserts
 it several times.
 
->>  Try that now -- type C-u 8 * to insert ********.
+>>  Try that now; type C-u 8 * to insert ********.
 
 You've now learned the most basic way of typing something in
 Emacs and correcting errors.  You can delete by words or lines
@@ -381,7 +381,7 @@ the text between the two positions.
 
 The difference between "killing" and "deleting" is that "killed" text
 can be reinserted (at any position), whereas "deleted" things cannot
-be reinserted in this way (you can, however, undo a deletion--see below).
+be reinserted in this way (you can, however, undo a deletion---see below).
 Reinsertion of killed text is called "yanking".  Generally, the
 commands that can remove a lot of text kill the text (they are set up so
 that you can yank the text), while the commands that remove just one
@@ -630,8 +630,8 @@ These are commands that are generally useful but are used less than the
 commands you have already learned about.  You have already seen a few
 of them: the file commands C-x C-f to Find and C-x C-s to Save, for
 example.  Another example is the command to end the Emacs
-session--this is the command C-x C-c.  (Do not worry about losing
-changes you have made; C-x C-c offers to save each changed file before
+session: C-x C-c.  (Do not worry about losing changes you have
+made; C-x C-c offers to save each changed file before
 it kills Emacs.)
 
 If you are using a graphical display, you don't need any special
@@ -640,7 +640,7 @@ with the mouse or with window manager commands.  However, if you're
 using a text terminal which can only show one application at a time,
 you need to "suspend" Emacs to move to any other application.
 
-C-z is the command to exit Emacs *temporarily*--so that you can go
+C-z is the command to exit Emacs *temporarily*, so that you can go
 back to the same Emacs session afterward.  When Emacs is running on a
 text terminal, C-z "suspends" Emacs; that is, it returns to the shell
 but does not destroy the Emacs job.  In the most common shells, you
@@ -671,7 +671,7 @@ Emacs will complete the name.  (<TAB> is the Tab key, usually found
 above the CapsLock or Shift key near the left edge of the keyboard.)
 Submit the command name with <Return>.
 
-The replace-string command requires two arguments--the string to be
+The replace-string command requires two arguments: the string to be
 replaced, and the string to replace it with.  You must end each
 argument with <Return>.
 
@@ -720,7 +720,7 @@ 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
+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
@@ -857,8 +857,8 @@ This erases the "u" from the search string, and the cursor moves back
 to the first occurrence of "c".
 
 If you are in the middle of a search and type a control or meta
-character (with a few exceptions--characters that are special in a
-search, such as C-s and C-r), the search is terminated.
+character, the search is terminated---with a few exceptions; characters
+such as C-s and C-r are special during a search.
 
 C-s starts a search that looks for any occurrence of the search string
 AFTER the current cursor position.  If you want to search for
@@ -872,7 +872,7 @@ the search is reversed.
 
 One of the nice features of Emacs is that you can display more than
 one window on the screen at the same time.  (Note that Emacs uses the
-term "frames"--described in the next section--for what some other
+term "frames"---described in the next section---for what some other
 applications call "windows".  The Emacs manual contains a Glossary of
 Emacs terms.)
 
@@ -917,8 +917,8 @@ in its own right, not a modifier key.
 >> Type C-x 1 (in the top window) to get rid of the bottom window.
 
 (If you had typed C-x 1 in the bottom window, that would get rid
-of the top one.  Think of this command as "Keep just one
-window--the window I am already in.")
+of the top one.  Think of this command as "Keep just one window,
+namely the window I am already in.")
 
 You do not have to display the same buffer in both windows.  If you
 use C-x C-f to find a file in one window, the other window does not
@@ -1011,7 +1011,7 @@ The message should be something like this:
 
 This tells you the "name of the function".  Since function names
 are chosen to indicate what the command does, they can serve as
-very brief documentation--sufficient to remind you of commands you
+very brief documentation sufficient to remind you of commands you
 have already learned.
 
 Multi-character commands such as C-x C-s and (if you have no META or
@@ -1095,7 +1095,7 @@ The manual also describes many other Emacs features.
 To exit Emacs use C-x C-c.
 
 This tutorial is meant to be understandable to all new users, so if
-you found something unclear, don't sit and blame yourself - complain!
+you found something unclear, don't sit and blame yourself---complain!
 
 
 * COPYING
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 10/14] etc/tutorials/TUTORIAL: c-h-a-n-g-e-d -> "changed"
Date: Wed, 13 Jun 2012 00:15:49 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

As the replacement string is already listed in double quotes ("altered"),
I don't see the value in using a different format for emphasizing the
text "changed"; both now use double quotes.
---
 etc/tutorials/TUTORIAL | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index ba89417..84bf892 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -679,7 +679,7 @@ argument with <Return>.
    Then type M-x repl s<Return>changed<Return>altered<Return>.
 
    Notice how this line has changed: you've replaced
-   the word c-h-a-n-g-e-d with "altered" wherever it occurred,
+   the word "changed" with "altered" wherever it occurred,
    after the initial position of the cursor.
 
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 11/14] etc/tutorials/TUTORIAL: Complete instructions by
	telling the user to move the cursor
Date: Wed, 13 Jun 2012 00:17:31 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000

The original text is unclear, because it doesn't tell the user that it is
necessary to place the cursor on a particular line.
---
 etc/tutorials/TUTORIAL | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 84bf892..ca451b6 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -769,7 +769,8 @@ differently.
 
 To view documentation on your current major mode, type C-h m.
 
->> Type C-l C-l to bring this line to the top of screen.
+>> Move the cursor to the line that follows this line.
+>> Type C-l C-l to bring this line to the top of the screen.
 >> Type C-h m, to see how Text mode differs from Fundamental mode.
 >> Type C-x 1 to remove the documentation from the screen.
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 12/14] etc/tutorials/TUTORIAL: Make consistent the white space
	around `>>' instructions
Date: Wed, 13 Jun 2012 00:18:22 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000
---
 etc/tutorials/TUTORIAL | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index ca451b6..8f4d8fd 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -16,10 +16,10 @@ The characters ">>" at the left margin indicate directions for you to
 try using a command.  For instance:
 <<Blank lines inserted around following line by help-with-tutorial>>
 [Middle of page left blank for didactic purposes.   Text continues below]
->>  Now type C-v (View next screen) to move to the next screen.
-	(go ahead, do it by holding down the CONTROL key while typing v).
-	From now on, you should do this again whenever you finish
-	reading the screen.
+>> Now type C-v (View next screen) to move to the next screen.
+   (go ahead, do it by holding down the CONTROL key while typing v).
+   From now on, you should do this again whenever you finish
+   reading the screen.
 
 Note that there is an overlap of two lines when you move from screen
 to screen; this provides some continuity so you can continue reading
@@ -30,7 +30,7 @@ to place in the text.  You already know how to move forward one screen,
 with C-v.  To move backwards one screen, type M-v (hold down the META key
 and type v, or type <ESC>v if you do not have a META, EDIT, or ALT key).
 
->>  Try typing M-v and then C-v, a few times.
+>> Try typing M-v and then C-v, a few times.
 
 
 * SUMMARY
@@ -284,6 +284,7 @@ which contains the cursor, to occupy the full screen.  It deletes all
 other windows.
 
 >> Move the cursor to this line and type C-u 0 C-l.
+
 >> Type C-h k C-f.
    See how this window shrinks, while a new one appears
    to display documentation on the C-f command.
@@ -344,7 +345,7 @@ Remember that most Emacs commands can be given a repeat count;
 this includes text characters.  Repeating a text character inserts
 it several times.
 
->>  Try that now; type C-u 8 * to insert ********.
+>> Try that now; type C-u 8 * to insert ********.
 
 You've now learned the most basic way of typing something in
 Emacs and correcting errors.  You can delete by words or lines
@@ -372,10 +373,13 @@ position where you typed C-<SPC>.  Finally, type C-w.  This kills all
 the text between the two positions.
 
 >> Move the cursor to the Y at the start of the previous paragraph.
+
 >> Type C-<SPC>.  Emacs should display a message "Mark set"
    at the bottom of the screen.
+
 >> Move the cursor to the n in "end", on the second line of the
    paragraph.
+
 >> Type C-w.  This will kill the text starting from the Y,
    and ending just before the n.
 
@@ -391,6 +395,7 @@ case, with no argument.  When given an argument, they kill instead.
 
 >> Move the cursor to the beginning of a line which is not empty.
    Then type C-k to kill the text on that line.
+
 >> Type C-k a second time.  You'll see that it kills the Newline
    which follows that line.
 
@@ -836,8 +841,11 @@ you want to search for.  <Return> terminates a search.
    type the word 'cursor', pausing after you type each
    character to notice what happens to the cursor.
    Now you have searched for "cursor", once.
+
 >> Type C-s again, to search for the next occurrence of "cursor".
+
 >> Now type <DEL> four times and see how the cursor moves.
+
 >> Type <Return> to terminate the search.
 
 Did you see what happened?  Emacs, in an incremental search, tries to
@@ -887,6 +895,7 @@ Emacs terms.)
    (If you do not have a real META key, type <ESC> C-v.)
 
 >> Type C-x o ("o" for "other") to move the cursor to the bottom window.
+
 >> Use C-v and M-v in the bottom window to scroll it.
    Keep reading these directions in the top window.
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 13/14] etc/tutorials/TUTORIAL: Place `C-x C-f' beside
	`find-file' for clarity
Date: Wed, 13 Jun 2012 00:18:42 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000
---
 etc/tutorials/TUTORIAL | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 8f4d8fd..11f2e29 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -1059,8 +1059,8 @@ You need to type in the name of the variable when Emacs prompts for it.
 >> Type C-h a file <Return>.
 
 This displays in another window a list of all M-x commands with "file"
-in their names.  You will see character-commands like C-x C-f listed
-beside the corresponding command names such as find-file.
+in their names.  You will see character-commands listed beside corresponding
+command names (such as C-x C-f beside find-file).
 
 >> Type C-M-v to scroll the text of the help window up.  Do this a few times.
 
-- 
1.7.10.2.484.gcd07cc5

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

From: Michael Witten <mfwitten <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH 14/14] etc/ChangeLog: Note my patch series for
	etc/tutorials/TUTORIAL
Date: Wed, 13 Jun 2012 00:19:05 -0000

Date: Tue, 12 Jun 2012 03:47:39 +0000
---
 etc/ChangeLog | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/etc/ChangeLog b/etc/ChangeLog
index 0c43d4c..35364b2 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,13 @@
+2012-06-12  Michael Witten  <mfwitten <at> gmail.com>
+
+	* tutorials/TUTORIAL: Some simple copyediting to reduce
+	  redundancy and improve the consistency of terminology,
+	  whitespace, punctuation, and grammar. In particular,
+	  the topic of scrolling was expounded upon in minor
+	  ways for preciseness. For the most part, the nature
+	  of the content remains unchanged for the entire
+	  document.
+
 2012-06-04  Paul Eggert  <eggert <at> cs.ucla.edu>
 
 	* PROBLEMS (68000 C compiler problems): Remove obsolete section.
-- 
1.7.10.2.484.gcd07cc5

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

From: Chong Yidong <cyd <at> gnu.org>
To: Michael Witten <mfwitten <at> gmail.com>
Cc: 11689 <at> debbugs.gnu.org
Subject: Re: bug#11689: [PATCH 00/14] Copyediting: etc/tutorials/TUTORIAL
Date: Sat, 07 Jul 2012 18:40:25 +0800

> Whilst reading through the TUTORIAL, I made a few minor modifications.
> The following is a summary of the resulting patch series

Thanks.  I've committed these changes, with some exceptions:

> +the scroll bar; one often drags the scroll bar's handle, a rectangular
> +region that is within the scroll bar and that is used to represent the
> +portion of the text that is currently visible in the associated window.

I don't see the point of teaching people how to use scroll bars in the
Emacs tutorial, and anyway this is wrong for non-toolkit X builds.

> +(Note that "scrolling the text up and down" is commonly described as
> +"scrolling the screen (or window) down and up". In particular, note
> +the way in which the two descriptions use direction; scrolling may
> +be interpreted as either moving the text with respect to the user's
> +view, or moving the user's view with respect to the text.)

I'd rather not get into this in the tutorial, where the
scroll-up/scroll-down command names are not mentioned.

> -You can undo deletion of text just as you can undo killing of text.
> -The distinction between killing something and deleting it affects
> -whether you can yank it with C-y; it makes no difference for undo.
> +You can undo the removal of text regardless of whether the text was
> +yanked or killed; there is no distinction as far as undoing is
> +concerned.

This change is gratuitous, since it's more or less the same length.

> -You should save fairly often, so that you will not lose very much
> -work if the system should crash (see the section "Auto Save" below).
> +You should save fairly often, so that you do not lose very much
> +work if the system crashes (see the section "Auto Save" below).

I simply removed this, since the Emacs tutorial is not the place to
dispense this kind of general advice.

> Under TeX and Texinfo, `---' is actually what is meant to be an
> em dash, so that would be a better choice than `--', and is thus
> used to replace `--' a few times.

This is gratuitous--since this is a text file, not TeX or Texinfo, the
meaning should be fairly obvious.

Thanks for the copyedits.

Previous Next

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