Re: emacs doc changes

[Ted Zlatanov <tzz@lifelogs.com>]

[-- Attachment #1: Type: text/plain, Size: 135 bytes --]

Attached is patch #2, covering commands.texi and entering.texi.  I
fixed some info regarding multibyte vs. unibyte data as well.

Ted


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: commands+entering.texi.patch --]
[-- Type: text/x-patch, Size: 17818 bytes --]

Index: commands.texi
===================================================================
RCS file: /sources/emacs/emacs/man/commands.texi,v
retrieving revision 1.22
diff -r1.22 commands.texi
9,11c9,11
< commands and for the contents of files, and also explains the concepts
< of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
< how Emacs interprets your keyboard and mouse input.
---
> commands and for the contents of files and the fundamental concepts of
> @dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
> and mouse input.
38,42c38,42
<   Some @acronym{ASCII} control characters have special names, and most terminals
< have special keys you can type them with: for example, @key{RET},
< @key{TAB}, @key{DEL} and @key{ESC}.  The space character is usually
< referred to below as @key{SPC}, even though strictly speaking it is a
< graphic character whose graphic happens to be blank.
---
>   Some @acronym{ASCII} control characters have special names, and most
> terminals have special keys you can type them with: for example,
> @key{RET}, @key{TAB}, @key{DEL} and @key{ESC}.  The space character is
> usually known as @key{SPC}, even though strictly speaking it is a
> blank graphic character.
54,56c54,56
<   But the Emacs character set has room for control variants of all
< printing characters, and for distinguishing between @kbd{C-a} and
< @kbd{C-A}.  Graphical terminals make it possible to enter all these
---
>   The Emacs character set has room for control variants of all
> printing characters, and knows @kbd{C-a} and @kbd{C-A} are not the
> same.  Graphical terminals make it possible to enter all these
109,112c109,112
< all: for example function keys and arrow keys.  Mouse buttons are also
< outside the gamut of characters.  However, you can modify these events
< with the modifier keys @key{CTRL}, @key{META}, @key{SUPER},
< @key{HYPER} and @key{ALT}, just as you can modify keyboard characters.
---
> all, such as function keys and arrow keys.  Mouse buttons are also not
> characters.  However, you can modify these events with the modifier
> keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
> just as you can modify keyboard characters.
124c124
< because the keyboard input routines recognize these special sequences
---
> because the keyboard input routines catch these special sequences
133,138c133,137
<   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
< events that are meaningful as a unit---as ``a single command.''  Some
< Emacs command sequences are just one character or one event; for
< example, just @kbd{C-f} is enough to move forward one character in the
< buffer.  But Emacs also has commands that take two or more events to
< invoke.
---
>   A @dfn{key sequence} (@dfn{key}, for short) is a meaningful sequence
> of input events---a ``single command.''  Some Emacs command sequences
> are invoked by just one character or one event; for example, just
> @kbd{C-f} moves forward one character in the buffer.  But Emacs also
> has commands that take two or more events to invoke.
161,165c160,164
<   By contrast, you can't add more events onto a complete key.  For
< example, the two-event sequence @kbd{C-f C-k} is not a key, because
< the @kbd{C-f} is a complete key in itself.  It's impossible to give
< @kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
< key sequences, not one.@refill
---
>   You can't add input events onto a complete key.  For example, the
> two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
> is a complete key in itself.  It's impossible to give @kbd{C-f C-k} an
> independent meaning as a command.  @kbd{C-f C-k} is two key sequences,
> not one.@refill
171,174c170,173
< aliases for @kbd{C-h} and @kbd{C-x 6}.)  But this list is not cast in
< concrete; it is just a matter of Emacs's standard key bindings.  If
< you customize Emacs, you can make new prefix keys, or eliminate some
< of the standard ones.  @xref{Key Bindings}.
---
> aliases for @kbd{C-h} and @kbd{C-x 6}.)  This list is only due to
> Emacs's standard key bindings.  If you customize Emacs, you can make
> new prefix keys, or eliminate some of the standard ones (not
> recommended for most users).  @xref{Key Bindings}.
176c175
<   If you do make or eliminate prefix keys, that changes the set of
---
>   If you make or eliminate prefix keys, that changes the set of
178,181c177,180
< prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
< define that too as a prefix).  Conversely, if you remove the prefix
< definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
< @var{anything}}) is no longer a key.
---
> prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
> you define that too as a prefix).  Conversely, if you remove the
> prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
> @var{anything}} are no longer keys.
187c186
< change.  But @key{F1} should work for all prefix keys.
---
> change.  @key{F1} works for all prefix keys.
200,201c199,200
<   Every command has a name chosen by a programmer.  The name is usually
< made of a few English words separated by dashes; for example,
---
>   Every command has a name chosen by a programmer.  The name is
> usually made of a few English words separated by dashes; for example,
203,209c202,207
< @dfn{function definition} which is a Lisp program; this is what makes
< the command do what it does.  In Emacs Lisp, a command is actually a
< special kind of Lisp function; one which specifies how to read arguments
< for it and call it interactively.  For more information on commands and
< functions, see @ref{What Is a Function,, What Is a Function, elisp, The
< Emacs Lisp Reference Manual}.  (The definition we use in this manual is
< simplified slightly.)
---
> @dfn{function definition} which is a Lisp program; this is how the
> command does work.  In Emacs Lisp, a command is a Lisp function with
> special options to read arguments and for interactive use.  For more
> information on commands and functions, see @ref{What Is a Function,,
> What Is a Function, elisp, The Emacs Lisp Reference Manual}.  (The
> definition here is simplified slightly.)
211,212c209,210
<   The bindings between keys and commands are recorded in various tables
< called @dfn{keymaps}.  @xref{Keymaps}.
---
>   The bindings between keys and commands are recorded in tables called
> @dfn{keymaps}.  @xref{Keymaps}.
215,220c213,218
< glossing over a distinction that is irrelevant in ordinary use but is vital
< in understanding how to customize Emacs.  It is the command
< @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
< this effect @emph{because} it is bound to that command.  If you rebind
< @kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
< forward by words instead.  Rebinding keys is a common method of
---
> glossing over a minor distinction that is irrelevant in ordinary use
> but is vital to Emacs customization.  The command @code{next-line}
> does a vertical move downward.  @kbd{C-n} has this effect
> @emph{because} it is bound to @code{next-line}.  If you rebind
> @kbd{C-n} to the command @code{forward-word}, then @kbd{C-n} will move
> forward one word instead.  Rebinding keys is common in
225,226c223
< commands, even though strictly speaking a key is bound to some
< command.  To give the information needed for customization, we state
---
> commands, even though the key is bound to a command.  Usually we state
230,231c227,228
< down,'' meaning that @code{next-line} is a command that moves
< vertically down, and @kbd{C-n} is a key that is normally bound to it.
---
> down,'' meaning that the command @code{next-line} moves vertically
> down, and @kbd{C-n} is a key that is normally bound to it.
233,243c230,239
<   While we are on the subject of information for customization only,
< it's a good time to tell you about @dfn{variables}.  Often the
< description of a command will say, ``To change this, set the variable
< @code{mumble-foo}.''  A variable is a name used to remember a value.
< Most of the variables documented in this manual exist just to facilitate
< customization: some command or other part of Emacs examines the variable
< and behaves differently according to the value that you set.  Until you
< are interested in customizing, you can ignore the information about
< variables.  When you are ready to be interested, read the basic
< information on variables, and then the information on individual
< variables will make sense.  @xref{Variables}.
---
>   Since we are discussing customization, you should know about
> @dfn{variables}.  Often the description of a command will say, ``To
> change this, set the variable @code{mumble-foo}.''  A variable is a
> name used to store a value.  Most of the variables documented in this
> manual are meant for customization: some command or other part of
> Emacs examines the variable and behaves differently according to the
> value that you set.  You can ignore the information about variables
> until you want to customize them.  When you are ready, read the basic
> information on variables, and then customizing individual variables
> will make sense.  @xref{Variables}.
249,254c245,252
<   Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
< hold a single @acronym{ASCII} character.  Both @acronym{ASCII} control characters (octal
< codes 000 through 037, and 0177) and @acronym{ASCII} printing characters (codes
< 040 through 0176) are allowed; however, non-@acronym{ASCII} control characters
< cannot appear in a buffer.  The other modifier flags used in keyboard
< input, such as Meta, are not allowed in buffers either.
---
>   Text in Emacs buffers is a sequence of characters.  In the default
> Unibyte Mode, each character in an 8-bit byte that can hold a single
> @acronym{ASCII} character.  Both @acronym{ASCII} control characters
> (octal codes 000 through 037, and 0177) and @acronym{ASCII} printing
> characters (codes 040 through 0176) are allowed; however,
> non-@acronym{ASCII} control characters cannot appear in a buffer.  The
> other modifier flags used in keyboard input, such as Meta, are not
> allowed in buffers either.
270,271c268,269
< alphabet of non-@acronym{ASCII} characters, but they all fit in one byte.  They
< use codes 0200 through 0377.  @xref{Unibyte Mode}.
---
> alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
> They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.
Index: entering.texi
===================================================================
RCS file: /sources/emacs/emacs/man/entering.texi,v
retrieving revision 1.16
diff -r1.16 entering.texi
11,21c11,21
< @command{emacs}.  Emacs clears the screen and then displays an initial
< help message and copyright notice.  Some operating systems discard all
< type-ahead when Emacs starts up; they give Emacs no way to prevent
< this.  If you ever use those systems, learn the habit of waiting for
< Emacs to clear the screen before typing your first editing command.
< 
<   If you run Emacs from a shell window under the X Window System, run it
< in the background with @command{emacs&}.  This way, Emacs does not tie up
< the shell window, so you can use that to run other shell commands while
< Emacs operates its own X windows.  You can begin typing Emacs commands
< as soon as you direct your keyboard input to the Emacs frame.
---
> @command{emacs}.  Emacs clears the screen and displays an initial help
> message and copyright notice.  Some operating systems discard all your
> input while Emacs starts up; they give Emacs no way to prevent this.
> If you ever use those systems, wait for Emacs to clear the screen
> before you start typing.
> 
>   From a shell window under the X Window System, run Emacs in the
> background with @command{emacs&}.  This way, Emacs won't tie up the
> shell window, so you can use it to run other shell commands while
> Emacs is running.  You can type Emacs commands as soon as you direct
> your keyboard input to an Emacs frame.
25,28c25,28
< That's the buffer you start out in.  The @samp{*scratch*} buffer uses
< Lisp Interaction mode; you can use it to type Lisp expressions and
< evaluate them, or you can ignore that capability and just write notes
< in it.  (You can specify a different major mode for this buffer by
---
> That's the first buffer you'll see.  The @samp{*scratch*} buffer uses
> Lisp Interaction mode; that lets you type Lisp expressions and
> evaluate them.  You can ignore that capability and just write notes
> there.  You can specify a different major mode for this buffer by
30c30
< @xref{Init File}.)
---
> @xref{Init File}.
33,41c33,39
< loaded, and functions to be called, by giving Emacs arguments in the
< shell command line.  @xref{Emacs Invocation}.  But we don't recommend
< doing this.  The feature exists mainly for compatibility with other
< editors.
< 
<   Many other editors are designed to be started afresh each time you
< want to edit.  You edit one file and then exit the editor.  The next
< time you want to edit either another file or the same one, you must run
< the editor again.  With these editors, it makes sense to use a
---
> loaded, and functions to be called through Emacs command-line
> arguments.  @xref{Emacs Invocation}.  The feature exists mainly for
> compatibility with other editors, and is normally not recommended.
> 
>   Many other editors are designed so you edit one file and then exit
> the editor.  The next time you want to edit a file, you must run the
> editor again.  With these editors, it makes sense to use a
44,49c42,46
<   But starting a new Emacs each time you want to edit a different file
< does not make sense.  This would fail to take advantage of Emacs's
< ability to visit more than one file in a single editing session, and
< it would lose the other accumulated context, such as the kill ring,
< registers, undo history, and mark ring, that are useful for operating
< on multiple files or even one.
---
>   It's not smart to start a new Emacs for every edited file.  Emacs
> can visit more than one file in a single editing session, and upon
> exit Emacs loses valuable accumulated context, such as the kill ring,
> registers, undo history, and mark ring.  These features are useful for
> operating on multiple files or even one.
53,62c50,57
< Each time you want to edit a different file, you visit it with the
< existing Emacs, which eventually comes to have many files in it ready
< for editing.  Usually you do not kill the Emacs until you are about to
< log out.  @xref{Files}, for more information on visiting more than one
< file.
< 
<   If you want to edit a file from another program and already have
< Emacs running, you can use the @command{emacsclient} program to open a
< file in the already running Emacs.  @xref{Emacs Server}, for more
< information on editing files with Emacs from other programs.
---
> To edit a different file, you visit it with the existing Emacs, which
> eventually will have many files in it ready for editing.  Usually you
> do not kill Emacs until you are about to log out.  @xref{Files}, for
> more information on visiting more than one file.
> 
>   To edit a file from another program while Emacs is running, you can
> use the @command{emacsclient} helper program to open a file in the
> already running Emacs.  @xref{Emacs Server}.
76c71
<   There are two commands for exiting Emacs because there are three
---
>   There are two commands for exiting Emacs and three
113,117c108,112
< directly with the terminal, and Emacs waits until you exit the subshell.
< (The way to do that is probably with @kbd{C-d} or @command{exit}, but
< it depends on which shell you use.)  The only way on these systems to
< get back to the shell from which Emacs was run (to log out, for
< example) is to kill Emacs.
---
> directly with the terminal, and Emacs waits until you exit the
> subshell.  (The way to do that is probably with @kbd{C-d} or
> @command{exit}, but it depends on which shell you use.)  On these
> systems, you can only get back to the shell from which Emacs was run
> (to log out, for example) when you kill Emacs.
136,142c131,137
< (@code{save-buffers-kill-emacs}).  A two-character key is used for
< this to make it harder to type by accident.  This command first offers
< to save any modified file-visiting buffers.  If you do not save them
< all, it asks for reconfirmation with @kbd{yes} before killing Emacs,
< since any changes not saved will be lost forever.  Also, if any
< subprocesses are still running, @kbd{C-x C-c} asks for confirmation
< about them, since killing Emacs will also kill the subprocesses.
---
> (@code{save-buffers-kill-emacs}).  A two-character key is used to make
> it harder to type by accident.  This command first offers to save any
> modified file-visiting buffers.  If you do not save them all, it asks
> for confirmation with @kbd{yes} before killing Emacs, since any
> unsaved changes will be lost forever.  Also, if any subprocesses are
> still running, @kbd{C-x C-c} asks for confirmation about them, since
> killing Emacs will also kill the subprocesses.
153,157c148,151
<   There is no way to resume an Emacs session once you have killed it.
< You can, however, arrange for Emacs to record certain session
< information when you kill it, such as which files are visited, so that
< the next time you start Emacs it will try to visit the same files and
< so on.  @xref{Saving Emacs Sessions}.
---
>   You can't resume an Emacs session after Emacs is killed.  Emacs can,
> however, record certain session information when you kill it, such as
> which files you visited, so the next time you start Emacs it will try
> to visit the same files.  @xref{Saving Emacs Sessions}.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel