[Emacs-diffs] emacs/etc ChangeLog tutorials/TUTORIAL

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       09/07/08 02:31:03

Modified files:
        etc            : ChangeLog 
        etc/tutorials  : TUTORIAL 

Log message:
        Standardize the way M-x commands are written:
        dashes inside command names, not spaces; spaces before <Return>.
        (Summary): Describe the new behavior of C-l.
        (Basic Cursor Control): Don't say that files "ought" to end in newlines.
        Try to distinguish scroll bar from fringes.
        You can also scroll with a wheel mouse.
        (If Emacs Stops Responding): Rename from "When Emacs is hung".
        (Inserting And Deleting): Continuation marks appear in the fringe.
        Clarify that deletion can be undone.  Mention cut and paste, and the 
Glossary.
        (Files, Mode Line): Update mode-line format.
        (Extending The Command Set): Downplay C-z, since using Emacs on a
        text-only terminal is less common these days.
        (Searching): Incremental searching is no longer atypical.
        Downplay flow control issues, remove reference to deleted FAQ node.
        (Multiple Windows): Mention frames.
        (Multiple Frames): New section.
        (Getting More Help): Downplay C-h having a different binding.
        Don't say help is "on-line", since the meaning has changed.
        (More Features): Replace "on-line".  Use C-h rather than F10 h.
        Say a little more about completion.
        (Conclusion): Don't mention C-z again here.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/etc/ChangeLog?cvsroot=emacs&r1=1.783&r2=1.784
http://cvs.savannah.gnu.org/viewcvs/emacs/etc/tutorials/TUTORIAL?cvsroot=emacs&r1=1.6&r2=1.7

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/etc/ChangeLog,v
retrieving revision 1.783
retrieving revision 1.784
diff -u -b -r1.783 -r1.784
--- ChangeLog   1 Jul 2009 14:02:27 -0000       1.783
+++ ChangeLog   8 Jul 2009 02:31:02 -0000       1.784
@@ -1,3 +1,28 @@
+2009-07-08  Glenn Morris  <address@hidden>
+
+       * tutorials/TUTORIAL: Standardize the way M-x commands are written:
+       dashes inside command names, not spaces; spaces before <Return>.
+       (Summary): Describe the new behavior of C-l.
+       (Basic Cursor Control): Don't say that files "ought" to end in newlines.
+       Try to distinguish scroll bar from fringes.
+       You can also scroll with a wheel mouse.
+       (If Emacs Stops Responding): Rename from "When Emacs is hung".
+       (Inserting And Deleting): Continuation marks appear in the fringe.
+       Clarify that deletion can be undone.  Mention cut and paste, and
+       the Glossary.
+       (Files, Mode Line): Update mode-line format.
+       (Extending The Command Set): Downplay C-z, since using Emacs on a
+       text-only terminal is less common these days.
+       (Searching): Incremental searching is no longer atypical.
+       Downplay flow control issues, remove reference to deleted FAQ node.
+       (Multiple Windows): Mention frames.
+       (Multiple Frames): New section.
+       (Getting More Help): Downplay C-h having a different binding.
+       Don't say help is "on-line", since the meaning has changed.
+       (More Features): Replace "on-line".  Use C-h rather than F10 h.
+       Say a little more about completion.
+       (Conclusion): Don't mention C-z again here.
+
 2009-07-01  Jan Djärv  <address@hidden>
 
        * NEWS: Mention maximized.

Index: tutorials/TUTORIAL
===================================================================
RCS file: /sources/emacs/emacs/etc/tutorials/TUTORIAL,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- tutorials/TUTORIAL  8 Jan 2009 05:12:06 -0000       1.6
+++ tutorials/TUTORIAL  8 Jul 2009 02:31:03 -0000       1.7
@@ -45,10 +45,11 @@
                 to the center of the screen.
                 (That's CONTROL-L, not CONTROL-1.)
 
->> Find the cursor, and note what text is near it.
-   Then type C-l.
-   Find the cursor again and notice that the same text
-   is near the cursor now.
+>> Find the cursor, and note what text is near it.  Then type C-l.
+   Find the cursor again and notice that the same text is still near
+   the cursor, but now it is in the center of the screen.
+   If you press C-l again, this piece of text will move to the top of
+   the screen.  Press C-l again, and it moves to the bottom.
 
 You can also use the PageUp and PageDn keys to move by screenfuls, if
 your terminal has them, but you can edit more efficiently if you use
@@ -88,9 +89,8 @@
    See what C-p does when the cursor is in the middle of the line.
 
 Each line of text ends with a Newline character, which serves to
-separate it from the following line.  The last line in your file ought
-to have a Newline at the end (but Emacs does not require it to have
-one).
+separate it from the following line.  (Normally, the last line in
+a file will have a Newline at the end, but Emacs does not require it.)
 
 >> Try to C-b at the beginning of a line.  It should move to
    the end of the previous line.  This is because it moves back
@@ -217,10 +217,13 @@
 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.
 
-If you are using a windowed display, such as X11 or MS-Windows, there
-should be a tall rectangular area called a scroll bar at the
-side of the Emacs window.  You can scroll the text by clicking the
-mouse in the scroll bar.
+If you are using a windowed 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.  (There are other tall rectangles on either side of
+the Emacs display.  These "fringes" are used for displaying
+continuation characters and other symbols.  The scroll bar appears on
+only one side, and is the outermost column on that side.)
+You can scroll the text by clicking the mouse in the scroll bar.
 
 >> Try pressing the middle button at the top of the highlighted area
    within the scroll bar.  This should scroll the text to a position
@@ -230,9 +233,11 @@
    pressed down.  You'll see that the text scrolls up and down as
    you move the mouse.
 
+If your mouse has a wheel button, you can also use this to scroll.
 
-* WHEN EMACS IS HUNG
---------------------
+
+* IF EMACS STOPS RESPONDING
+---------------------------
 
 If Emacs stops responding to your commands, you can stop it safely by
 typing C-g.  You can use C-g to stop a command which is taking too
@@ -241,12 +246,11 @@
 You can also use C-g to discard a numeric argument or the beginning of
 a command that you do not want to finish.
 
->> Type C-u 100 to make a numeric arg of 100, then type C-g.
+>> Type C-u 100 to make a numeric argument of 100, then type C-g.
    Now type C-f.  It should move just one character,
    because you canceled the argument with C-g.
 
-If you have typed an <ESC> by mistake, you can get rid of it
-with a C-g.
+If you have typed an <ESC> by mistake, you can get rid of it with a C-g.
 
 
 * DISABLED COMMANDS
@@ -324,7 +328,8 @@
 When a line of text gets too big for one line on the screen, the line
 of text is "continued" onto a second screen line.  A backslash ("\")
 (or, if you're using a windowed display, a little curved arrow) at the
-right margin indicates a line which has been continued.
+right margin (actually, in the right "fringe") indicates a line which
+has been continued.
 
 >> Insert text until you reach the right margin, and keep on inserting.
    You'll see a continuation line appear.
@@ -364,7 +369,7 @@
 Notice that <Delback> and C-d vs M-<Delback> and M-d extend the parallel
 started by C-f and M-f (well, <Delback> is not really a control
 character, but let's not worry about that).  C-k and M-k are like C-e
-and M-e, sort of, in that lines are opposite sentences.
+and M-e, sort of, in that lines are paired with sentences.
 
 You can also kill any part of the text with one uniform method.  Move
 to one end of that part, and type C-@ or C-<SPC> (either one).  (<SPC>
@@ -380,9 +385,10 @@
    and ending just before the n.
 
 The difference between "killing" and "deleting" is that "killed" text
-can be reinserted, whereas "deleted" things cannot be reinserted.
+can be reinserted (at any position), whereas "deleted" things cannot
+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 set up so
+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
 character, or only remove blank lines and spaces, do deletion (so you
 cannot yank that text).  <Delback> and C-d  do deletion in the simplest
@@ -404,7 +410,8 @@
 can yank the killed text either at the same place where it was killed,
 or at some other place in the text you are editing, or even in a
 different file.  You can yank the same text several times; that makes
-multiple copies of it.
+multiple copies of it.  Some other editors call killing and yanking
+"cutting" and "pasting" (see the Glossary in the Emacs manual).
 
 The command for yanking is C-y.  It reinserts the last killed text,
 at the current cursor position.
@@ -455,7 +462,7 @@
 
 But there are two exceptions: commands that do not change the text do
 not count (this includes cursor motion commands and scrolling
-command), and self-inserting characters are usually handled in groups
+commands), and self-inserting characters are usually handled in groups
 of up to 20.  (This is to reduce the number of C-x u's you have to
 type to undo insertion of text.)
 
@@ -491,7 +498,7 @@
 you later decide that your changes were a mistake.
 
 If you look near the bottom of the screen you will see a line that
-begins and ends with dashes, and starts with "--:-- TUTORIAL" or
+begins and ends with dashes, and starts with "--:--- TUTORIAL" or
 something like that.  This part of the screen normally shows the name
 of the file that you are visiting.  Right now, you are visiting a file
 called "TUTORIAL" which is your personal scratch copy of the Emacs
@@ -518,7 +525,7 @@
    minibuffer.  So you do not find any file.
 
 When you have finished entering the file name, type <Return> to
-terminate it.  Then C-x C-f command goes to work, and finds the file
+terminate it.  The C-x C-f command goes to work, and finds the file
 you chose.  The minibuffer disappears when the C-x C-f command is
 finished.
 
@@ -535,7 +542,7 @@
 
 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.
+work if the system should crash (see the section "Auto Save" below).
 
 >> Type C-x C-s, saving your copy of the tutorial.
    This should show "Wrote ...TUTORIAL" at the bottom of the screen.
@@ -631,13 +638,13 @@
        C-x     Character eXtend.  Followed by one character.
        M-x     Named command eXtend.  Followed by a long name.
 
-These are commands that are generally useful but used less than the
+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
-it kills the Emacs.)
+it kills Emacs.)
 
 If you are using a graphical display that supports multiple
 applications in parallel, you don't need any special command to move
@@ -655,9 +662,7 @@
 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, since they may not know
-how to cope with suspension of Emacs.  In ordinary circumstances,
-though, if you are not about to log out, it is better to suspend Emacs
-with C-z instead of exiting Emacs.
+how to cope with suspension of Emacs.
 
 There are many C-x commands.  Here is a list of the ones you have learned:
 
@@ -705,7 +710,7 @@
 
 If the computer crashes, you can recover your auto-saved editing by
 finding the file normally (the file you were editing, not the auto
-save file) and then typing M-x recover file<Return>.  When it asks for
+save file) and then typing M-x recover-file <Return>.  When it asks for
 confirmation, type yes<Return> to go ahead and recover the auto-save
 data.
 
@@ -724,7 +729,7 @@
 The line immediately above the echo area is called the "mode line".
 The mode line says something like this:
 
---:**  TUTORIAL       63% L749    (Fundamental)-----------------------
+--:**-  TUTORIAL       63% L749    (Fundamental)-----------------------
 
 This line gives useful information about the status of Emacs and
 the text you are editing.
@@ -765,7 +770,7 @@
 If you are going to be editing human-language text, such as this file, you
 should probably use Text Mode.
 
->> Type M-x text mode<Return>.
+>> Type M-x text-mode <Return>.
 
 Don't worry, none of the  Emacs commands you have learned changes in
 any great way.  But you can observe that M-f and M-b now treat
@@ -794,13 +799,13 @@
 breaks the line in between words automatically whenever you insert
 text and make a line that is too wide.
 
-You can turn Auto Fill mode on by doing M-x auto fill mode<Return>.
-When the mode is on, you can turn it off again by doing M-x
-auto fill mode<Return>.  If the mode is off, this command turns it on,
-and if the mode is on, this command turns it off.  We say that the
-command "toggles the mode".
+You can turn Auto Fill mode on by doing M-x auto-fill-mode <Return>.
+When the mode is on, you can turn it off again by doing
+M-x auto-fill-mode <Return>.  If the mode is off, this command turns
+it on, and if the mode is on, this command turns it off.  We say that
+the command "toggles the mode".
 
->> Type M-x auto fill mode<Return> now.  Then insert a line of "asdf "
+>> Type M-x auto-fill-mode <Return> now.  Then insert a line of "asdf "
    over again until you see it divide into two lines.  You must put in
    spaces between them because Auto Fill breaks lines only at spaces.
 
@@ -829,8 +834,7 @@
 through it.  Searching for a string is a cursor motion command;
 it moves the cursor to the next place where that string appears.
 
-The Emacs search command is different from the search commands
-of most editors, in that it is "incremental".  This means that the
+The Emacs search command is "incremental".  This means that the
 search happens while you type in the string to search for.
 
 The command to initiate a search is C-s for forward search, and C-r
@@ -855,12 +859,11 @@
 occurrence exists, Emacs beeps and tells you the search is currently
 "failing".  C-g would also terminate the search.
 
-NOTE: On some systems, typing C-s will freeze the screen and you will
-see no further output from Emacs.  This indicates that an operating
-system "feature" called "flow control" is intercepting the C-s and not
-letting it get through to Emacs.  To unfreeze the screen, type C-q.
-Then see the section "Spontaneous Entry to Incremental Search" in the
-Emacs manual for advice on dealing with this "feature".
+(Note that on some systems, typing C-s will freeze the screen and you
+will see no further output from Emacs.  This indicates that an
+operating system "feature" called "flow control" is intercepting the
+C-s and not letting it get through to Emacs.  To unfreeze the screen,
+type C-q.)
 
 If you are in the middle of an incremental search and type <Delback>,
 you'll notice that the last character in the search string is erased
@@ -886,7 +889,10 @@
 ------------------
 
 One of the nice features of Emacs is that you can display more than one
-window on the screen at the same time.
+window on the screen at the same time.  (Note that Emacs uses the term
+"frames"--described in the next section--for what some other
+applications call "windows".  The Emacs manual contains a Glossary of
+Emacs terms.)
 
 >> Move the cursor to this line and type C-u 0 C-l (that's CONTROL-L, not
    CONTROL-1).
@@ -934,8 +940,7 @@
 use C-x C-f to find a file in one window, the other window does not
 change.  You can find a file in each window independently.
 
-Here is another way to use two windows to display two different
-things:
+Here is another way to use two windows to display two different things:
 
 >> Type C-x 4 C-f followed by the name of one of your files.
    End with <Return>.  See the specified file appear in the bottom
@@ -945,6 +950,29 @@
    the bottom window.
 
 
+* MULTIPLE FRAMES
+------------------
+
+Emacs can also create multiple "frames" (unless you are using a
+text-only terminal).  A frame is what we call one collection of
+windows, together with its menus, scroll bars, echo area, etc.
+(Some other applications call a frame a "window".)
+
+>> Type M-x make-frame <Return>.
+   See a new frame appear on your screen.
+
+You can do everything you did in the original frame in the new frame.
+There is nothing special about the first frame.
+
+>> Type M-x delete-frame <Return>.
+   This removes the selected frame.
+
+You can also remove a frame by using the normal method provided by
+your window manager (often clicking a button with an "X" at a top
+corner of the frame).  No information is lost when you close a frame
+(or window), it is simply removed from sight and can be restored later.
+
+
 * RECURSIVE EDITING LEVELS
 --------------------------
 
@@ -982,11 +1010,8 @@
 If you have typed C-h and decide you do not want any help, just
 type C-g to cancel it.
 
-(Some sites change the meaning of the character C-h.  They really
-should not do this as a blanket measure for all users, so you have
-grounds to complain to the system administrator.  Meanwhile, if C-h
-does not display a message about help at the bottom of the screen, try
-typing the F1 key or M-x help <Return> instead.)
+(If C-h does not display a message about help at the bottom of the
+screen, try typing the F1 key or M-x help <Return> instead.)
 
 The most basic HELP feature is C-h c.  Type C-h, the character c, and
 a command character or sequence; then Emacs displays a very brief
@@ -998,9 +1023,8 @@
 
        C-p runs the command previous-line
 
-This tells you the "name of the function".  Function names are used
-mainly for customizing and extending Emacs.  But since function names
-are chosen to indicate what the command does, they can serve also as
+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
 have already learned.
 
@@ -1022,13 +1046,13 @@
    C-h f       Describe a function.  You type in the name of the
                function.
 
->> Try typing C-h f previous-line<Return>.
+>> Try typing C-h f previous-line <Return>.
    This displays all the information Emacs has about the
    function which implements the C-p command.
 
-A similar command C-h v displays the documentation of variables whose
-values you can set to customize Emacs behavior.  You need to type in
-the name of the variable when Emacs prompts for it.
+A similar command C-h v displays the documentation of variables,
+including those whose values you can set to customize Emacs behavior.
+You need to type in the name of the variable when Emacs prompts for it.
 
    C-h a       Command Apropos.  Type in a keyword and Emacs will list
                all the commands whose names contain that keyword.
@@ -1036,7 +1060,7 @@
                For some commands, Command Apropos will also list a one
                or two character sequence which runs the same command.
 
->> Type C-h a file<Return>.
+>> 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
@@ -1046,35 +1070,35 @@
 
 >> Type C-x 1 to delete the help window.
 
-   C-h i       Read On-line Manuals (a.k.a. Info).  This command puts
+   C-h i       Read included Manuals (a.k.a. Info).  This command puts
                you into a special buffer called `*info*' where you
-               can read on-line manuals for the packages installed on
-               your system.  Type m emacs <Return> to read the Emacs
-               manual.  If you have never before used Info, type ?
-               and Emacs will take you on a guided tour of Info mode
-               facilities.  Once you are through with this tutorial,
-               you should consult the Emacs Info manual as your
-               primary documentation.
+               can read manuals for the packages installed on your system.
+               Type m emacs <Return> to read the Emacs manual.
+               If you have never before used Info, type ? and Emacs
+               will take you on a guided tour of Info mode facilities.
+               Once you are through with this tutorial, you should
+               consult the Emacs Info manual as your primary documentation.
 
 
 * MORE FEATURES
 ---------------
 
-You can learn more about Emacs by reading its manual, either as a book
-or on-line in Info (use the Help menu or type F10 h r).  Two features
-that you may like especially are completion, which saves typing, and
-dired, which simplifies file handling.
+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.
 
 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>
 and Emacs will fill in the rest of the buffer name as far as it can
-determine from what you have already typed.  Completion is described
-in Info in the Emacs manual in the node called "Completion".
+determine from what you have already typed.  Completion also works for
+command names and file names.  Completion is described in the Emacs
+manual in the node called "Completion".
 
 Dired enables you to list files in a directory (and optionally its
 subdirectories), move around that list, visit, rename, delete and
-otherwise operate on the files.  Dired is described in Info in the
-Emacs manual in the node called "Dired".
+otherwise operate on the files.  Dired is described in the Emacs
+manual in the node called "Dired".
 
 The manual also describes many other Emacs features.
 
@@ -1082,8 +1106,7 @@
 * CONCLUSION
 ------------
 
-Remember, to exit Emacs permanently use C-x C-c.  To exit to a shell
-temporarily, so that you can come back to Emacs afterward, use C-z.
+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!