misc.texi cyd
modes.texi cyd
msdog.texi rgm (can't actually test any of it though)
- It was not obvious to me that the following is true (it could well be though):
-
- Emacs on Windows automatically determines your default printer and
- sets the variable `printer-name' to that printer's name.
-
msdog-xtra.texi rgm (can't actually test any of it though)
-mule.texi
+mule.texi rgm (not 100% sure about "Fontsets")
m-x.texi cyd
package.texi cyd
picture-xtra.texi rgm
abbrevs.texi rgm
advice.texi cyd
-anti.texi
+anti.texi rgm
back.texi rgm
backups.texi cyd
buffers.texi cyd
+2012-04-15 Chong Yidong <cyd@gnu.org>
+
+ * misc.texi (emacsclient Options): More clarifications.
+
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * msdog.texi (Windows Printing): It doesn't set printer-name.
+
+ * mule.texi (Language Environments): Move font info to "Fontsets".
+ (Fontsets): Move intlfonts etc here from "Language Environments".
+ Copyedits.
+ (Defining Fontsets, Modifying Fontsets, Undisplayable Characters)
+ (Unibyte Mode, Charsets, Bidirectional Editing): Copyedits.
+
+2012-04-15 Chong Yidong <cyd@gnu.org>
+
+ * glossary.texi (Glossary): Standardize on "text terminal"
+ terminology. All callers changed.
+
+ * misc.texi (emacsclient Options): Document "client frame" concept
+ and its effect on C-x C-c more carefully.
+
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * frames.texi (Scroll Bars):
+ * glossary.texi (Glossary): Use consistent case for "X Window System".
+
+ * mule.texi (Select Input Method, Coding Systems):
+ State command names in kbd tables.
+ (Recognize Coding): Add cross-ref.
+ (Output Coding): Don't mention message mode in particular.
+ (Text Coding, Communication Coding, File Name Coding, Terminal Coding):
+ Copyedits.
+
2012-04-14 Glenn Morris <rgm@gnu.org>
* mule.texi (Select Input Method, Coding Systems, Recognize Coding):
creates a virtual Info manual of package keywords.
@item
-Károly L@H{o}rentey wrote the ``multi-terminal'' code, which allows Emacs to
-run on graphical and text-only terminals simultaneously.
+Károly L@H{o}rentey wrote the ``multi-terminal'' code, which allows
+Emacs to run on graphical and text terminals simultaneously.
@item
Martin Lorentzon wrote @file{vc-annotate.el}, support for version
On most keyboards, @key{DEL} is labeled @key{Backspace}, but we
refer to it as @key{DEL} in this manual. (Do not confuse @key{DEL}
with the @key{Delete} key; we will discuss @key{Delete} momentarily.)
-On some text-only terminals, Emacs may not recognize the @key{DEL} key
+On some text terminals, Emacs may not recognize the @key{DEL} key
properly. @xref{DEL Does Not Delete}, if you encounter this problem.
The @key{delete} (@code{delete-forward-char}) command deletes in the
@dfn{continuation}, and the long logical line is called a
@dfn{continued line}. On a graphical display, Emacs indicates line
wrapping with small bent arrows in the left and right window fringes.
-On a text-only terminal, Emacs indicates line wrapping by displaying a
+On a text terminal, Emacs indicates line wrapping by displaying a
@samp{\} character at the right margin.
Most commands that act on lines act on logical lines, not screen
continuing them. This means that every logical line occupies a single
screen line; if it is longer than the width of the window, the rest of
the line is not displayed. On a graphical display, a truncated line
-is indicated by a small straight arrow in the right fringe; on a
-text-only terminal, it is indicated by a @samp{$} character in the
-right margin. @xref{Line Truncation}.
+is indicated by a small straight arrow in the right fringe; on a text
+terminal, it is indicated by a @samp{$} character in the right margin.
+@xref{Line Truncation}.
By default, continued lines are wrapped at the right window edge.
Since the wrapping may occur in the middle of a word, continued lines
If the @file{*compilation*} buffer is shown in a window with a left
fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
the fringe, pointing to the current error message. If the window has
-no left fringe, such as on a text-only terminal, these commands scroll
-the window so that the current message is at the top of the window.
-If you change the variable @code{compilation-context-lines} to an
-integer value @var{n}, these commands scroll the window so that the
-current error message is @var{n} lines from the top, whether or not
-there is a fringe; the default value, @code{nil}, gives the behavior
-described above.
+no left fringe, such as on a text terminal, these commands scroll the
+window so that the current message is at the top of the window. If
+you change the variable @code{compilation-context-lines} to an integer
+value @var{n}, these commands scroll the window so that the current
+error message is @var{n} lines from the top, whether or not there is a
+fringe; the default value, @code{nil}, gives the behavior described
+above.
@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
As you debug a program, Emacs displays the relevant source files by
visiting them in Emacs buffers, with an arrow in the left fringe
-indicating the current execution line. (On a text-only terminal, the
-arrow appears as @samp{=>}, overlaid on the first two text columns.)
-Moving point in such a buffer does not move the arrow. You are free
-to edit these source files, but note that inserting or deleting lines
-will throw off the arrow's positioning, as Emacs has no way to figure
-out which edited source line corresponds to the line reported by the
+indicating the current execution line. (On a text terminal, the arrow
+appears as @samp{=>}, overlaid on the first two text columns.) Moving
+point in such a buffer does not move the arrow. You are free to edit
+these source files, but note that inserting or deleting lines will
+throw off the arrow's positioning, as Emacs has no way to figure out
+which edited source line corresponds to the line reported by the
debugger subprocess. To update this information, you typically have
to recompile and restart the program.
enables or disables an existing breakpoint; a breakpoint that is
disabled, but not unset, is indicated by a gray dot.
- On a text-only terminal, or when fringes are disabled, enabled
+ On a text terminal, or when fringes are disabled, enabled
breakpoints are indicated with a @samp{B} character in the left margin
of the window. Disabled breakpoints are indicated with @samp{b}.
(The margin is only displayed if a breakpoint is present.)
@findex gdb-frames-select
On graphical displays, the selected stack frame is indicated by an
-arrow in the fringe. On text-only terminals, or when fringes are
-disabled, the selected stack frame is displayed in reverse contrast.
-To select a stack frame, move point in its line and type @key{RET}
+arrow in the fringe. On text terminals, or when fringes are disabled,
+the selected stack frame is displayed in reverse contrast. To select
+a stack frame, move point in its line and type @key{RET}
(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so
also updates the Locals buffer
@ifnottex
You can reverse the foreground and background colors through the
@samp{-rv} option or with the X resource @samp{reverseVideo}.
- The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on
-text-only terminals as well as on graphical displays.
+ The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text
+terminals as well as on graphical displays.
@node Window Size X
@appendixsec Options for Window Size and Position
C-a}. Unlike @key{Meta}, @key{ESC} is entered as a separate
character. You don't hold down @key{ESC} while typing the next
character; instead, press @key{ESC} and release it, then enter the
-next character. This feature is useful on certain text-only terminals
+next character. This feature is useful on certain text terminals
where the @key{Meta} key does not function reliably.
@cindex keys stolen by window manager
screen. To disable automatic horizontal scrolling, set the variable
@code{auto-hscroll-mode} to @code{nil}. Note that when the automatic
horizontal scrolling is turned off, if point moves off the edge of the
-screen, the cursor disappears to indicate that. (On text-only
-terminals, the cursor is left at the edge instead.)
+screen, the cursor disappears to indicate that. (On text terminals,
+the cursor is left at the edge instead.)
@vindex hscroll-margin
The variable @code{hscroll-margin} controls how close point can get
matching that regular expression (@pxref{Regexps}).
It's possible for a given face to look different in different
-frames. For instance, some text-only terminals do not support all
-face attributes, particularly font, height, and width, and some
-support a limited range of colors.
+frames. For instance, some text terminals do not support all face
+attributes, particularly font, height, and width, and some support a
+limited range of colors.
@cindex background color
@cindex default face
@samp{medium sea green}. To view a list of color names, type @kbd{M-x
list-colors-display}. To control the order in which colors are shown,
customize @code{list-colors-sort}. If you run this command on a
-graphical display, it shows the full range of color names known to Emacs
-(these are the standard X11 color names, defined in X's @file{rgb.txt}
-file). If you run the command on a text-only terminal, it shows only a
-small subset of colors that can be safely displayed on such terminals.
-However, Emacs understands X11 color names even on text-only terminals;
-if a face is given a color specified by an X11 color name, it is
-displayed using the closest-matching terminal color.
+graphical display, it shows the full range of color names known to
+Emacs (these are the standard X11 color names, defined in X's
+@file{rgb.txt} file). If you run the command on a text terminal, it
+shows only a small subset of colors that can be safely displayed on
+such terminals. However, Emacs understands X11 color names even on
+text terminals; if a face is given a color specified by an X11 color
+name, it is displayed using the closest-matching terminal color.
An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the
R, G, and B components is a hexadecimal number specifying the
Most windows do not have a header line---only some special modes, such
Info mode, create one.
@item vertical-border
-This face is used for the vertical divider between windows on
-text-only terminals.
+This face is used for the vertical divider between windows on text
+terminals.
@item minibuffer-prompt
@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
@end table
The following faces likewise control the appearance of parts of the
-Emacs frame, but only on text-only terminals, or when Emacs is built
-on X with no toolkit support. (For all other cases, the appearance of
-the respective frame elements is determined by system-wide settings.)
+Emacs frame, but only on text terminals, or when Emacs is built on X
+with no toolkit support. (For all other cases, the appearance of the
+respective frame elements is determined by system-wide settings.)
@table @code
@item scroll-bar
Emacs can display long lines by @dfn{truncation}. This means that all
the characters that do not fit in the width of the screen or window do
not appear at all. On graphical displays, a small straight arrow in
-the fringe indicates truncation at either end of the line. On
-text-only terminals, this is indicated with @samp{$} signs in the
-leftmost and/or rightmost columns.
+the fringe indicates truncation at either end of the line. On text
+terminals, this is indicated with @samp{$} signs in the leftmost
+and/or rightmost columns.
@vindex truncate-lines
@findex toggle-truncate-lines
itself, in pixels; the default is 2.
@findex tty-suppress-bold-inverse-default-colors
- On some text-only terminals, bold face and inverse video together
-result in text that is hard to read. Call the function
+ On some text terminals, bold face and inverse video together result
+in text that is hard to read. Call the function
@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
argument to suppress the effect of bold-face in this case.
* Tooltips:: Displaying information at the current mouse position.
* Mouse Avoidance:: Moving the mouse pointer out of the way.
* Non-Window Terminals:: Multiple frames on terminals that show only one.
-* Text-Only Mouse:: Using the mouse in text-only terminals.
+* Text-Only Mouse:: Using the mouse in text terminals.
International Character Set Support
process (usually a shell); in most shells, you can resume Emacs after
suspending it with the shell command @command{%emacs}.
- Text-only terminals usually listen for certain special characters
-whose meaning is to kill or suspend the program you are running.
-@b{This terminal feature is turned off while you are in Emacs.} The
-meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired
-by the use of @kbd{C-z} and @kbd{C-c} on several operating systems as
-the characters for stopping or killing a program, but that is their
-only relationship with the operating system. You can customize these
-keys to run any commands of your choice (@pxref{Keymaps}).
+ Text terminals usually listen for certain special characters whose
+meaning is to kill or suspend the program you are running. @b{This
+terminal feature is turned off while you are in Emacs.} The meanings
+of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired by the
+use of @kbd{C-z} and @kbd{C-c} on several operating systems as the
+characters for stopping or killing a program, but that is their only
+relationship with the operating system. You can customize these keys
+to run any commands of your choice (@pxref{Keymaps}).
@ifnottex
@lowersections
(@code{file-cache-minibuffer-complete}) completes it using the file
name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the
possible completions of what you had originally typed. (However, note
-that the @kbd{C-@key{tab}} character cannot be typed on most text-only
+that the @kbd{C-@key{tab}} character cannot be typed on most text
terminals.)
The file name cache does not fill up automatically. Instead, you
@kbd{C-x u})@footnote{Aside from @kbd{C-/}, the @code{undo} command is
also bound to @kbd{C-x u} because that is more straightforward for
beginners to remember: @samp{u} stands for ``undo''. It is also bound
-to @kbd{C-_} because typing @kbd{C-/} on some text-only terminals
-actually enters @kbd{C-_}.}. This undoes the most recent change in
-the buffer, and moves point back to where it was before that change.
+to @kbd{C-_} because typing @kbd{C-/} on some text terminals actually
+enters @kbd{C-_}.}. This undoes the most recent change in the buffer,
+and moves point back to where it was before that change.
Consecutive repetitions of @kbd{C-/} (or its aliases) undo earlier
and earlier changes in the current buffer. If all the recorded
This chapter describes Emacs features specific to graphical displays
(particularly mouse commands), and features for managing multiple
-frames. On text-only terminals, many of these features are
-unavailable. However, it is still possible to create multiple
-``frames'' on text-only terminals; such frames are displayed one at a
-time, filling the entire terminal screen (@pxref{Non-Window
-Terminals}). It is also possible to use the mouse on some text-only
-terminals (@pxref{Text-Only Mouse}, for doing so on GNU and Unix
-systems; and
+frames. On text terminals, many of these features are unavailable.
+However, it is still possible to create multiple ``frames'' on text
+terminals; such frames are displayed one at a time, filling the entire
+terminal screen (@pxref{Non-Window Terminals}). It is also possible
+to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for
+doing so on GNU and Unix systems; and
@iftex
@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
@end iftex
* Tooltips:: Displaying information at the current mouse position.
* Mouse Avoidance:: Preventing the mouse pointer from obscuring text.
* Non-Window Terminals:: Multiple frames on terminals that show only one.
-* Text-Only Mouse:: Using the mouse in text-only terminals.
+* Text-Only Mouse:: Using the mouse in text terminals.
@end menu
@node Mouse Commands
The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all
other frames on the current terminal (this terminal refers to either a
-graphical display, or a text-only terminal; @pxref{Non-Window
-Terminals}). If the Emacs session has frames open on other graphical
-displays or text terminals, those are not deleted.
+graphical display, or a text terminal; @pxref{Non-Window Terminals}).
+If the Emacs session has frames open on other graphical displays or
+text terminals, those are not deleted.
@vindex focus-follows-mouse
The @kbd{C-x 5 o} (@code{other-frame}) command selects the next
the left), or @code{nil} (disable scroll bars). By default, Emacs
puts scroll bars on the right if it was compiled with GTK+ support on
the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll
-bars on the left if compiled on the X Window system without GTK+
+bars on the left if compiled on the X Window System without GTK+
support (following the old convention for X applications).
@vindex scroll-bar-width
@code{menu-bar-mode}.
@kindex C-Mouse-3 @r{(when menu bar is disabled)}
- Expert users often turn off the menu bar, especially on text-only
+ Expert users often turn off the menu bar, especially on text
terminals, where this makes one additional line available for text.
If the menu bar is off, you can still pop up a menu of its contents
with @kbd{C-Mouse-3} on a display which supports pop-up menus.
@node Non-Window Terminals
@section Non-Window Terminals
-@cindex text-only terminal
+@cindex text terminal
- On a text-only terminal, Emacs can display only one Emacs frame at a
+ On a text terminal, Emacs can display only one Emacs frame at a
time. However, you can still create multiple Emacs frames, and switch
between them. Switching frames on these terminals is much like
switching between different window configurations.
in the mode line when the frame is selected.
@node Text-Only Mouse
-@section Using a Mouse in Text-only Terminals
+@section Using a Mouse in Text Terminals
@cindex mouse support
@cindex terminal emulators, mouse support
-Some text-only terminals support mouse clicks in the terminal window.
+Some text terminals support mouse clicks in the terminal window.
@cindex xterm
In a terminal emulator which is compatible with @command{xterm}, you
particular alphabet or script. @xref{International}.
@item Character Terminal
-@xref{Glossary - Text-only Terminal}.
+@xref{Glossary - Text Terminal}.
@item Click Event
A click event is the kind of input event (q.v.@:) generated when you
@item Clipboard
A clipboard is a buffer provided by the window system for transferring
-text between applications. On the X Window system, the clipboard is
+text between applications. On the X Window System, the clipboard is
provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac,
the clipboard is used @emph{instead} of the primary selection.
@xref{Clipboard}.
or following the stylistic conventions of human language.
@end itemize
-@anchor{Glossary - Text-only Terminal}
-@item Text-only Terminal
-A text-only terminal is a display that is limited to displaying text in
-character units. Such a terminal cannot control individual pixels it
-displays. Emacs supports a subset of display features on text-only
-terminals.
+@anchor{Glossary - Text Terminal}
+@item Text Terminal
+A text terminal, or character terminal, is a display that is limited
+to displaying text in character units. Such a terminal cannot control
+individual pixels it displays. Emacs supports a subset of display
+features on text terminals.
@item Text Properties
Text properties are annotations recorded for particular characters in
@ref{Glossary - Continuation Line}.
@item TTY
-@xref{Glossary - Text-only Terminal}.
+@xref{Glossary - Text Terminal}.
@item Undoing
Undoing means making your previous editing go in reverse, bringing
the shell command @samp{emacsclient @var{file}}, where @var{file} is a
file name. This connects to an Emacs server, and tells that Emacs
process to visit @var{file} in one of its existing frames---either a
-graphical frame, or one in a text-only terminal (@pxref{Frames}). You
+graphical frame, or one in a text terminal (@pxref{Frames}). You
can then select that frame to begin editing.
If there is no Emacs server, the @command{emacsclient} program halts
called @command{emacsclient}.
You can also force @command{emacsclient} to open a new frame on a
-graphical display, or on a text-only terminal, using the @samp{-c} and
+graphical display, or on a text terminal, using the @samp{-c} and
@samp{-t} options. @xref{emacsclient Options}.
- If you are running on a single text-only terminal, you can switch
-between @command{emacsclient}'s shell and the Emacs server using one
-of two methods: (i) run the Emacs server and @command{emacsclient} on
+ If you are running on a single text terminal, you can switch between
+@command{emacsclient}'s shell and the Emacs server using one of two
+methods: (i) run the Emacs server and @command{emacsclient} on
different virtual terminals, and switch to the Emacs server's virtual
terminal after calling @command{emacsclient}; or (ii) call
@command{emacsclient} from within the Emacs server itself, using Shell
the @samp{-a} option. If both are present, the latter takes
precedence.
+@cindex client frame
@item -c
-Create a new graphical frame, instead of using an existing Emacs
-frame. Emacs can create a graphical frame even if it was started in a
-text-only terminal, provided it is able to connect to a graphical
-display. If Emacs is unable to connect to a graphical display, and on
-systems, such as MS-Windows (@pxref{Windows Startup, emacsclient}),
-where it cannot create graphical frames when started from a text-only
-terminal, it creates a new text-only terminal frame (@pxref{Frames}).
-If you omit a filename argument while supplying the @samp{-c} option,
-the new frame displays the @file{*scratch*} buffer (@pxref{Buffers}).
+Create a new graphical @dfn{client frame}, instead of using an
+existing Emacs frame. If you omit a filename argument while supplying
+the @samp{-c} option, the new frame displays the @file{*scratch*}
+buffer (@pxref{Buffers}). See below for the special behavior of
+@kbd{C-x C-c} in a client frame.
+
+If Emacs is unable to create a new graphical frame (e.g.@: if it is
+unable to connect to the X server), it tries to create a text terminal
+client frame, as though you had supplied the @samp{-t} option instead
+(see below).
+
+On MS-Windows, a single Emacs session cannot display frames on both
+graphical and text terminals, nor on multiple text terminals. Thus,
+if the Emacs server is running on a text terminal, the @samp{-c}
+option, like the @samp{-t} option, creates a new frame in the server's
+current text terminal. @xref{Windows Startup}.
@item -F @var{alist}
@itemx --frame-parameters=@var{alist}
@item -t
@itemx --tty
@itemx -nw
-Create a new Emacs frame on the current text-only terminal, instead of
-using an existing Emacs frame. Emacs can open a text-only terminal
-even if it was started in another text-only terminal, or on a
-graphical display. On systems, such as MS-Windows, where this is
-impossible, Emacs will create a new frame, either GUI or text-only, on
-the same terminal where it was started (@pxref{Windows Startup,
-emacsclient}). If you omit a filename argument while supplying this
-option, the new frame displays the @file{*scratch*} buffer.
-@xref{Buffers}.
+Create a new client frame on the current text terminal, instead of
+using an existing Emacs frame. This is similar to the @samp{-c}
+option, above, except that it creates a text terminal frame
+(@pxref{Non-Window Terminals}). If you omit a filename argument while
+supplying this option, the new frame displays the @file{*scratch*}
+buffer (@pxref{Buffers}). See below for the special behavior of
+@kbd{C-x C-c} in a client frame.
+
+On MS-Windows, a single Emacs session cannot display frames on both
+graphical and text terminals, nor on multiple text terminals. Thus,
+if the Emacs server is using the graphical display, @samp{-t} behaves
+like @samp{-c} (see above); whereas if the Emacs server is running on
+a text terminal, it creates a new frame in its current text terminal.
+@xref{Windows Startup}.
@end table
- If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
-Emacs frame created with @command{emacsclient}, via the @samp{-c} or
-@samp{-t} options, Emacs deletes the frame instead of killing the
-Emacs process itself. On a text-only terminal frame created with the
-@samp{-t} option, this returns control to the terminal. Emacs also
-marks all the server buffers for the client as finished, as though you
-had typed @kbd{C-x #} in all of them.
-
- When Emacs is started as a daemon, all frames are considered client
-frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs
-process, type @kbd{M-x kill-emacs}.
+ The new graphical or text terminal frames created by the @samp{-c}
+or @samp{-t} options are considered @dfn{client frames}. Any new
+frame that you create from a client frame is also considered a client
+frame. If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal})
+in a client frame, that command does not kill the Emacs session as it
+normally does (@pxref{Exiting}). Instead, Emacs deletes the client
+frame; furthermore, if the client frame has an @command{emacsclient}
+waiting to regain control (i.e.@: if you did not supply the @samp{-n}
+option), Emacs deletes all other frames of the same client, and marks
+the client's server buffers as finished, as though you had typed
+@kbd{C-x #} in all of them. If it so happens that there are no
+remaining frames after the client frame(s) are deleted, the Emacs
+session exits.
+
+ As an exception, when Emacs is started as a daemon, all frames are
+considered client frames, and @kbd{C-x C-c} never kills Emacs. To
+kill a daemon session, type @kbd{M-x kill-emacs}.
+
+ Note that the @samp{-t} and @samp{-n} options are contradictory:
+@samp{-t} says to take control of the current text terminal to create
+a new client frame, while @samp{-n} says not to take control of the
+text terminal. If you supply both options, Emacs visits the specified
+files(s) in an existing frame rather than a new client frame, negating
+the effect of @samp{-t}.
@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
@cindex frames on MS-DOS
The MS-DOS terminal can only display a single frame at a time. The
-Emacs frame facilities work on MS-DOS much as they do on text-only
+Emacs frame facilities work on MS-DOS much as they do on text
terminals
@iftex
(@pxref{Frames,,,emacs, the Emacs Manual}).
created only if the server runs in a GUI session. Similarly, if you
invoke @command{emacsclient} with the @option{-t} option, Emacs will
create a GUI frame if the server runs in a GUI session, or a text-mode
-frame when the session runs in text-only mode in a @dfn{Command
-Prompt} window. @xref{emacsclient Options}.
+frame when the session runs in text mode in a @dfn{Command Prompt}
+window. @xref{emacsclient Options}.
@node Text and Binary
@section Text Files and Binary Files
variables control printing on all systems, but in some cases they have
different default values on MS-DOS and MS-Windows.
- Emacs on Windows automatically determines your default printer and
-sets the variable @code{printer-name} to that printer's name. But in
-some rare cases this can fail, or you may wish to use a different
+ Emacs on MS Windows attempts to determine your default printer
+automatically (using the function @code{default-printer-name}).
+But in some rare cases this can fail, or you may wish to use a different
printer from within Emacs. The rest of this section explains how to
tell Emacs which printer to use.
@item
You can display non-@acronym{ASCII} characters encoded by the various
scripts. This works by using appropriate fonts on graphics displays
-(@pxref{Defining Fontsets}), and by sending special codes to text-only
+(@pxref{Defining Fontsets}), and by sending special codes to text
displays (@pxref{Terminal Coding}). If some characters are displayed
incorrectly, refer to @ref{Undisplayable Characters}, which describes
possible problems and explains how to solve them.
@item
If you are running Emacs on a graphical display, the font name and
-glyph code for the character. If you are running Emacs on a text-only
+glyph code for the character. If you are running Emacs on a text
terminal, the code(s) sent to the terminal.
@item
which prefers Cyrillic characters and files encoded in Windows-1255).
@end quotation
-@cindex fonts for various scripts
-@cindex Intlfonts package, installation
To display the script(s) used by your language environment on a
-graphical display, you need to have a suitable font. If some of the
-characters appear as empty boxes or hex codes, you should install
-extra fonts. Your operating system may have optional fonts that
-you can install; or you can install the
-GNU Intlfonts package, which includes fonts for most supported
-scripts.@footnote{If you run Emacs on X, you may need to inform the X
-server about the location of the newly installed fonts with
-commands such as:
-@c FIXME? I feel like this may be out of date.
-@c Eg the intlfonts tarfile is ~ 10 years old.
-
-@example
- xset fp+ /usr/local/share/emacs/fonts
- xset fp rehash
-@end example
-}
+graphical display, you need to have suitable fonts.
@xref{Fontsets}, for more details about setting up your fonts.
@findex set-locale-environment
@table @kbd
@item C-\
-Enable or disable use of the selected input method.
+Enable or disable use of the selected input method (@code{toggle-input-method}).
@item C-x @key{RET} C-\ @var{method} @key{RET}
-Select a new input method for the current buffer.
+Select a new input method for the current buffer (@code{set-input-method}).
@item C-h I @var{method} @key{RET}
@itemx C-h C-\ @var{method} @key{RET}
@table @kbd
@item C-h C @var{coding} @key{RET}
-Describe coding system @var{coding}.
+Describe coding system @var{coding} (@code{describe-coding-system}).
@item C-h C @key{RET}
Describe the coding systems currently in use.
the strongest way to specify the coding system for certain patterns of
file names, or for files containing certain patterns, respectively.
These variables even override @samp{-*-coding:-*-} tags in the file
-itself. For example, Emacs
+itself (@pxref{Specify Coding}). For example, Emacs
uses @code{auto-coding-alist} for tar and archive files, to prevent it
from being confused by a @samp{-*-coding:-*-} tag in a member of the
archive and thinking it applies to the archive file as a whole.
If you insert the unsuitable characters in a mail message, Emacs
behaves a bit differently. It additionally checks whether the
+@c What determines this?
most-preferred coding system is recommended for use in MIME messages;
if not, Emacs tells you that the most-preferred coding system is not
recommended and prompts you for another coding system. This is so you
still use an unsuitable coding system if you type its name in response
to the question.)
+@c It seems that select-message-coding-system does this.
+@c Both sendmail.el and smptmail.el call it; i.e. smtpmail.el still
+@c obeys sendmail-coding-system.
@vindex sendmail-coding-system
- When you send a message with Message mode (@pxref{Sending Mail}),
+ When you send a mail message (@pxref{Sending Mail}),
Emacs has four different ways to determine the coding system to use
for encoding the message text. It tries the buffer's own value of
@code{buffer-file-coding-system}, if that is non-@code{nil}.
Otherwise, it uses the value of @code{sendmail-coding-system}, if that
is non-@code{nil}. The third way is to use the default coding system
for new files, which is controlled by your choice of language
+@c i.e., default-sendmail-coding-system
environment, if that is non-@code{nil}. If all of these three values
are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding
system.
+@c FIXME? Where does the Latin-1 default come in?
@node Text Coding
@section Specifying a Coding System for File Text
@table @kbd
@item C-x @key{RET} f @var{coding} @key{RET}
-Use coding system @var{coding} to save or revisit the visited file in
-the current buffer (@code{set-buffer-file-coding-system})
+Use coding system @var{coding} to save or revisit the file in
+the current buffer (@code{set-buffer-file-coding-system}).
@item C-x @key{RET} c @var{coding} @key{RET}
Specify coding system @var{coding} for the immediately following
You can also use this command to specify the end-of-line conversion
(@pxref{Coding Systems, end-of-line conversion}) for encoding the
current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will
-cause Emacs to save the current buffer's text with DOS-style CRLF line
-endings.
+cause Emacs to save the current buffer's text with DOS-style
+carriage-return linefeed line endings.
@kindex C-x RET c
@findex universal-coding-system-argument
The variable @code{x-select-request-type} specifies the data type to
request from the X Window System for receiving text selections from
other applications. If the value is @code{nil} (the default), Emacs
-tries @code{COMPOUND_TEXT} and @code{UTF8_STRING}, in this order, and
+tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and
uses various heuristics to choose the more appropriate of the two
results; if none of these succeed, Emacs falls back on @code{STRING}.
If the value of @code{x-select-request-type} is one of the symbols
The variable @code{locale-coding-system} specifies a coding system
to use when encoding and decoding system strings such as system error
messages and @code{format-time-string} formats and time stamps. That
-coding system is also used for decoding non-@acronym{ASCII} keyboard input on X
-Window systems. You should choose a coding system that is compatible
+coding system is also used for decoding non-@acronym{ASCII} keyboard
+input on the X Window System. You should choose a coding system that is compatible
with the underlying system's text representation, which is normally
specified by one of the environment variables @env{LC_ALL},
@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
@table @kbd
@item C-x @key{RET} F @var{coding} @key{RET}
Use coding system @var{coding} for encoding and decoding file
-@emph{names} (@code{set-file-name-coding-system}).
+names (@code{set-file-name-coding-system}).
@end table
-@vindex file-name-coding-system
-@cindex file names with non-@acronym{ASCII} characters
- The variable @code{file-name-coding-system} specifies a coding
-system to use for encoding file names. It has no effect on reading
-and writing the @emph{contents} of files.
-
@findex set-file-name-coding-system
@kindex C-x @key{RET} F
- If you set the variable to a coding system name (as a Lisp symbol or
-a string), Emacs encodes file names using that coding system for all
-file operations. This makes it possible to use non-@acronym{ASCII}
-characters in file names---or, at least, those non-@acronym{ASCII}
-characters which the specified coding system can encode. Use @kbd{C-x
-@key{RET} F} (@code{set-file-name-coding-system}) to specify this
-interactively.
+@cindex file names with non-@acronym{ASCII} characters
+ The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system})
+specifies a coding system to use for encoding file @emph{names}. It
+has no effect on reading and writing the @emph{contents} of files.
+
+@vindex file-name-coding-system
+ In fact, all this command does is set the value of the variable
+@code{file-name-coding-system}. If you set the variable to a coding
+system name (as a Lisp symbol or a string), Emacs encodes file names
+using that coding system for all file operations. This makes it
+possible to use non-@acronym{ASCII} characters in file names---or, at
+least, those non-@acronym{ASCII} characters that the specified coding
+system can encode.
If @code{file-name-coding-system} is @code{nil}, Emacs uses a
-default coding system determined by the selected language environment.
+default coding system determined by the selected language environment,
+and stored in the @code{default-file-name-coding-system} variable.
+@c FIXME? Is this correct? What is the "default language environment"?
In the default language environment, non-@acronym{ASCII} characters in
file names are not encoded specially; they appear in the file system
using the internal Emacs representation.
the earlier coding system and cannot be encoded (or are encoded
differently) under the new coding system. If you try to save one of
these buffers under the visited file name, saving may use the wrong file
-name, or it may get an error. If such a problem happens, use @kbd{C-x
+name, or it may encounter an error. If such a problem happens, use @kbd{C-x
C-w} to specify a new file name for that buffer.
@findex recode-file-name
@section Coding Systems for Terminal I/O
@table @kbd
-@item C-x @key{RET} k @var{coding} @key{RET}
-Use coding system @var{coding} for keyboard input
-(@code{set-keyboard-coding-system}).
-
@item C-x @key{RET} t @var{coding} @key{RET}
Use coding system @var{coding} for terminal output
(@code{set-terminal-coding-system}).
+
+@item C-x @key{RET} k @var{coding} @key{RET}
+Use coding system @var{coding} for keyboard input
+(@code{set-keyboard-coding-system}).
@end table
@kindex C-x RET t
@kindex C-x RET k
@findex set-keyboard-coding-system
@vindex keyboard-coding-system
- The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
-or the variable @code{keyboard-coding-system} specifies the coding
+ The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}),
+or the variable @code{keyboard-coding-system}, specifies the coding
system for keyboard input. Character-code translation of keyboard
input is useful for terminals with keys that send non-@acronym{ASCII}
graphic characters---for example, some terminals designed for ISO
A font typically defines shapes for a single alphabet or script.
Therefore, displaying the entire range of scripts that Emacs supports
requires a collection of many fonts. In Emacs, such a collection is
-called a @dfn{fontset}. A fontset is defined by a list of font specs,
+called a @dfn{fontset}. A fontset is defined by a list of font specifications,
each assigned to handle a range of character codes, and may fall back
-on another fontset for characters which are not covered by the fonts
+on another fontset for characters that are not covered by the fonts
it specifies.
+@cindex fonts for various scripts
+@cindex Intlfonts package, installation
Each fontset has a name, like a font. However, while fonts are
stored in the system and the available font names are defined by the
system, fontsets are defined within Emacs itself. Once you have
defined a fontset, you can use it within Emacs by specifying its name,
anywhere that you could use a single font. Of course, Emacs fontsets
-can use only the fonts that the system supports; if certain characters
-appear on the screen as hollow boxes, this means that the fontset in
-use for them has no font for those characters.@footnote{The Emacs
-installation instructions have information on additional font
-support.}
+can use only the fonts that the system supports. If some characters
+appear on the screen as empty boxes or hex codes, this means that the
+fontset in use for them has no font for those characters. In this
+case, or if the characters are shown, but not as well as you would
+like, you may need to install extra fonts. Your operating system may
+have optional fonts that you can install; or you can install the GNU
+Intlfonts package, which includes fonts for most supported
+scripts.@footnote{If you run Emacs on X, you may need to inform the X
+server about the location of the newly installed fonts with commands
+such as:
+@c FIXME? I feel like this may be out of date.
+@c Eg the intlfonts tarfile is ~ 10 years old.
+
+@example
+ xset fp+ /usr/local/share/emacs/fonts
+ xset fp rehash
+@end example
+}
Emacs creates three fontsets automatically: the @dfn{standard
fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
+@c FIXME? The doc of *standard*-fontset-spec says:
+@c "You have the biggest chance to display international characters
+@c with correct glyphs by using the *standard* fontset." (my emphasis)
The default fontset is most likely to have fonts for a wide variety of
-non-@acronym{ASCII} characters and is the default fallback for the
+non-@acronym{ASCII} characters, and is the default fallback for the
other two fontsets, and if you set a default font rather than fontset.
-However it does not specify font family names, so results can be
+However, it does not specify font family names, so results can be
somewhat random if you use it directly. You can specify use of a
-specific fontset with the @samp{-fn} option. For example,
+particular fontset by starting Emacs with the @samp{-fn} option.
+For example,
@example
emacs -fn fontset-standard
@noindent
or just @samp{fontset-standard} for short.
- On GNUstep and Mac, fontset-standard is created using the value of
-@code{ns-standard-fontset-spec}, and on Windows it is
+ On GNUstep and Mac OS X, the standard fontset is created using the value of
+@code{ns-standard-fontset-spec}, and on MS Windows it is
created using the value of @code{w32-standard-fontset-spec}.
+@c FIXME? How does one access these, or do anything with them?
+@c Does it matter?
Bold, italic, and bold-italic variants of the standard fontset are
created automatically. Their names have @samp{bold} instead of
@samp{medium}, or @samp{i} instead of @samp{r}, or both.
@var{charset_encoding} field with @samp{startup}, then using the
resulting string to specify a fontset.
- For instance, if you start Emacs this way,
+ For instance, if you start Emacs with a font of this form,
+@c FIXME? I think this is a little misleading, because you cannot (?)
+@c actually specify a font with wildcards, it has to be a complete spec.
+@c Also, an X font specification of this form hasn't (?) been
+@c mentioned before now, and is somewhat obsolete these days.
+@c People are more likely to use a form like
+@c emacs -fn "DejaVu Sans Mono-12"
+@c How does any of this apply in that case?
@example
emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
@end example
-*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
@end example
- The startup fontset will use the font that you specify or a variant
-with a different registry and encoding for all the characters which
+ The startup fontset will use the font that you specify, or a variant
+with a different registry and encoding, for all the characters that
are supported by that font, and fallback on @samp{fontset-default} for
other characters.
just like an actual font name. But be careful not to specify a fontset
name in a wildcard resource like @samp{Emacs*Font}---that wildcard
specification matches various other resources, such as for menus, and
-menus cannot handle fontsets.
+@c FIXME is this still true?
+menus cannot handle fontsets. @xref{X Resources}.
You can specify additional fontsets using X resources named
@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
@end smallexample
@noindent
-@var{fontpattern} should have the form of a standard X font name, except
+@var{fontpattern} should have the form of a standard X font name (see
+the previous fontset-startup example), except
for the last two fields. They should have the form
@samp{fontset-@var{alias}}.
In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard. This is to prevent use of
auto-scaled fonts. Fonts made by scaling larger fonts are not usable
-for editing, and scaling a smaller font is not useful because it is
+for editing, and scaling a smaller font is not also useful, because it is
better to use the smaller font in its own size, which is what Emacs
does.
You may not have any Chinese font matching the above font
specification. Most X distributions include only Chinese fonts that
-have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
-such a case, @samp{Fontset-@var{n}} can be specified as below:
+have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
+such a case, @samp{Fontset-@var{n}} can be specified as:
@smallexample
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
Fontsets can be modified using the function @code{set-fontset-font},
specifying a character, a charset, a script, or a range of characters
-to modify the font for, and a font-spec for the font to be used. Some
-examples are:
+to modify the font for, and a font specification for the font to be
+used. Some examples are:
@example
;; Use Liberation Mono for latin-3 charset.
@node Undisplayable Characters
@section Undisplayable Characters
- There may be a some non-@acronym{ASCII} characters that your terminal cannot
-display. Most text-only terminals support just a single character
-set (use the variable @code{default-terminal-coding-system}
-(@pxref{Terminal Coding}) to tell Emacs which one); characters which
+ There may be some non-@acronym{ASCII} characters that your
+terminal cannot display. Most text terminals support just a single
+character set (use the variable @code{default-terminal-coding-system}
+to tell Emacs which one, @ref{Terminal Coding}); characters that
can't be encoded in that coding system are displayed as @samp{?} by
default.
accented letters and punctuation needed by various European languages
(and some non-European ones). Note that Emacs considers bytes with
codes in this range as raw bytes, not as characters, even in a unibyte
-session, i.e.@: if you disable multibyte characters. However, Emacs
+buffer, i.e.@: if you disable multibyte characters. However, Emacs
can still handle these character codes as if they belonged to
@emph{one} of the single-byte character sets at a time. To specify
@emph{which} of these codes to use, invoke @kbd{M-x
set-language-environment} and specify a suitable language environment
such as @samp{Latin-@var{n}}.
- For more information about unibyte operation, see @ref{Disabling
-Multibyte}. Note particularly that you probably want to ensure that
-your initialization files are read as unibyte if they contain
-non-@acronym{ASCII} characters.
+ For more information about unibyte operation, see
+@ref{Disabling Multibyte}.
@vindex unibyte-display-via-language-environment
Emacs can also display bytes in the range 160 to 255 as readable
set, Emacs can display these characters as @acronym{ASCII} sequences which at
least give you a clear idea of what the characters are. To do this,
load the library @code{iso-ascii}. Similar libraries for other
-Latin-@var{n} character sets could be implemented, but we don't have
-them yet.
+Latin-@var{n} character sets could be implemented, but have not been
+so far.
@findex standard-display-8bit
@cindex 8-bit display
representing non-@acronym{ASCII} characters, you can type those character codes
directly.
-On a graphical display, you should not need to do anything special to use
-these keys; they should simply work. On a text-only terminal, you
-should use the command @code{M-x set-keyboard-coding-system} or the
+On a graphical display, you should not need to do anything special to
+use these keys; they should simply work. On a text terminal, you
+should use the command @code{M-x set-keyboard-coding-system} or customize the
variable @code{keyboard-coding-system} to specify which coding system
your keyboard uses (@pxref{Terminal Coding}). Enabling this feature
will probably require you to use @kbd{ESC} to type Meta characters;
@findex list-character-sets
@kbd{M-x list-character-sets} displays a list of all supported
charsets. The list gives the names of charsets and additional
-information to identity each charset (see
-@url{http://www.itscj.ipsj.or.jp/ISO-IR/} for details). In this list,
+information to identity each charset; see the
+@url{http://www.itscj.ipsj.or.jp/ISO-IR/, International Register of
+Coded Character Sets} for more details. In this list,
charsets are divided into two categories: @dfn{normal charsets} are
listed first, followed by @dfn{supplementary charsets}. A
supplementary charset is one that is used to define another charset
Hebrew, whose natural ordering of horizontal text for display is from
right to left. However, digits and Latin text embedded in these
scripts are still displayed left to right. It is also not uncommon to
-have small portions of text in Arabic or Hebrew embedded in otherwise
-Latin document, e.g., as comments and strings in a program source
+have small portions of text in Arabic or Hebrew embedded in an otherwise
+Latin document; e.g., as comments and strings in a program source
file. For these reasons, text that uses these scripts is actually
@dfn{bidirectional}: a mixture of runs of left-to-right and
right-to-left characters.
Each paragraph of bidirectional text can have its own @dfn{base
direction}, either right-to-left or left-to-right. (Paragraph
+@c paragraph-separate etc have no influence on this?
boundaries are empty lines, i.e.@: lines consisting entirely of
whitespace characters.) Text in left-to-right paragraphs begins at
the left margin of the window and is truncated or continued when it
jump when point traverses reordered bidirectional text. Similarly, a
highlighted region covering a contiguous range of character positions
may look discontinuous if the region spans reordered text. This is
-normal and similar to behavior of other programs that support
+normal and similar to the behavior of other programs that support
bidirectional text.
@cindex frame
On a graphical display, such as on GNU/Linux using the X Window
-System, Emacs occupies a ``graphical window''. On a text-only
-terminal, Emacs occupies the entire terminal screen. We will use the
-term @dfn{frame} to mean a graphical window or terminal screen
-occupied by Emacs. Emacs behaves very similarly on both kinds of
-frames. It normally starts out with just one frame, but you can
-create additional frames if you wish (@pxref{Frames}).
+System, Emacs occupies a ``graphical window''. On a text terminal,
+Emacs occupies the entire terminal screen. We will use the term
+@dfn{frame} to mean a graphical window or terminal screen occupied by
+Emacs. Emacs behaves very similarly on both kinds of frames. It
+normally starts out with just one frame, but you can create additional
+frames if you wish (@pxref{Frames}).
Each frame consists of several distinct regions. At the top of the
frame is a @dfn{menu bar}, which allows you to access commands via a
@end example
@noindent
-On a text-only terminal, this text is followed by a series of dashes
+On a text terminal, this text is followed by a series of dashes
extending to the right edge of the window. These dashes are omitted
on a graphical display.
containing non-textual data. Other characters represent various
@dfn{coding systems}---for example, @samp{1} represents ISO Latin-1.
- On a text-only terminal, @var{cs} is preceded by two additional
+ On a text terminal, @var{cs} is preceded by two additional
characters that describe the coding systems for keyboard input and
terminal output. Furthermore, if you are using an input method,
@var{cs} is preceded by a string that identifies the input method
remote machine, @samp{@@} is displayed instead (@pxref{File Names}).
@var{fr} gives the selected frame name (@pxref{Frames}). It appears
-only on text-only terminals. The initial frame's name is @samp{F1}.
+only on text terminals. The initial frame's name is @samp{F1}.
@var{buf} is the name of the buffer displayed in the window.
Usually, this is the same as the name of a file you are editing.
selected menu item, press @key{RET}; to cancel menu navigation, press
@key{ESC}.
- On a text-only terminal, you can use the menu bar by typing
-@kbd{M-`} or @key{F10} (these run the command @code{tmm-menubar}).
-This lets you select a menu item with the keyboard. A provisional
-choice appears in the echo area. You can use the up and down arrow
-keys to move through the menu to different items, and then you can
-type @key{RET} to select the item. Each menu item is also designated
-by a letter or digit (usually the initial of some word in the item's
-name). This letter or digit is separated from the item name by
-@samp{=>}. You can type the item's letter or digit to select the
-item.
+ On a text terminal, you can use the menu bar by typing @kbd{M-`} or
+@key{F10} (these run the command @code{tmm-menubar}). This lets you
+select a menu item with the keyboard. A provisional choice appears in
+the echo area. You can use the up and down arrow keys to move through
+the menu to different items, and then you can type @key{RET} to select
+the item. Each menu item is also designated by a letter or digit
+(usually the initial of some word in the item's name). This letter or
+digit is separated from the item name by @samp{=>}. You can type the
+item's letter or digit to select the item.
too suggests Emacs got the wrong information---but in the opposite
sense.
- On a text-only terminal, if you find that @key{Backspace} prompts
-for a Help command, like @kbd{Control-h}, instead of deleting a
-character, it means that key is actually sending the @key{BS}
-character. Emacs ought to be treating @key{BS} as @key{DEL}, but it
-isn't.
+ On a text terminal, if you find that @key{Backspace} prompts for a
+Help command, like @kbd{Control-h}, instead of deleting a character,
+it means that key is actually sending the @key{BS} character. Emacs
+ought to be treating @key{BS} as @key{DEL}, but it isn't.
@findex normal-erase-is-backspace-mode
In all of those cases, the immediate remedy is the same: use the
command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
between the two modes that Emacs supports for handling @key{DEL}, so
if Emacs starts in the wrong mode, this should switch to the right
-mode. On a text-only terminal, if you want to ask for help when
-@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also
-work, if it sends character code 127.
+mode. On a text terminal, if you want to ask for help when @key{BS}
+is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it
+sends character code 127.
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
@node Emergency Escape
@subsection Emergency Escape
- On text-only terminals, the @dfn{emergency escape} feature suspends
-Emacs immediately if you type @kbd{C-g} a second time before Emacs can
+ On text terminals, the @dfn{emergency escape} feature suspends Emacs
+immediately if you type @kbd{C-g} a second time before Emacs can
actually respond to the first one by quitting. This is so you can
always get out of GNU Emacs no matter how badly it might be hung.
When things are working properly, Emacs recognizes and handles the
At any time, one Emacs window is the @dfn{selected window}; the
buffer this window is displaying is the current buffer. On graphical
displays, the point is indicated by a solid blinking cursor in the
-selected window, and by a hollow box in non-selected windows. On
-text-only terminals, the cursor is drawn only in the selected window.
+selected window, and by a hollow box in non-selected windows. On text
+terminals, the cursor is drawn only in the selected window.
@xref{Cursor Display}.
Commands to move point affect the value of point for the selected
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * processes.texi (Processes, Subprocess Creation, Shell Arguments):
+ (Synchronous Processes, Asynchronous Processes, Deleting Processes):
+ Copyedits.
+ (Subprocess Creation): Discourage modifying exec-path directly.
+ (Synchronous Processes, Asynchronous Processes):
+ Update some example output.
+ (Process Information): Fix typo.
+ (Bindat Spec): Use Texinfo-recommended form of quote+punctuation.
+
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * anti.texi (Antinews): Copyedits. Don't @dfn anything here.
+ open-network-stream does exist in Emacs 23, but is simpler.
+
+2012-04-15 Chong Yidong <cyd@gnu.org>
+
+ * customize.texi (Custom Themes): Also document load-theme etc.
+
2012-04-14 Chong Yidong <cyd@gnu.org>
* customize.texi (Applying Customizations):
Internal windows are no longer visible to Lisp; functions such as
@code{window-parent}, window parameters related to window arrangement,
and window-local buffer lists have all been removed. Functions for
-resizing windows can delete windows if when they become too small.
+resizing windows can delete windows if they become too small.
-The @dfn{action function} feature for controlling buffer display has
+The ``action function'' feature for controlling buffer display has
been removed, including @code{display-buffer-overriding-action} and
related variables, as well as the @var{action} argument to
@code{display-buffer} and other functions. The way to
The standard completion interface has been simplified, eliminating the
@code{completion-extra-properties} variable, the @code{metadata}
action flag for completion functions, and the concept of
-@dfn{completion categories}. Lisp programmers may now find the choice
+``completion categories''. Lisp programmers may now find the choice
of methods for tuning completion less bewildering, but if a package
finds the streamlined interface insufficient for its needs, it must
implement its own specialized completion feature.
The @var{cache} entry is used internally by Emacs to record equivalent
keyboard key sequences for invoking the same command; Lisp programs
should never use it.
+@c Not really NEWS-worthy then...
@item
-The @code{open-network-stream} function has been removed, and so has
-the @code{gnutls} library. Lisp programs that want an encrypted
-network connection must now call external utilities such as
-@command{starttls} or @command{gnutls-cli}.
+The @code{gnutls} library has been removed, and the function
+@code{open-network-stream} correspondingly simplified.
+Lisp programs that want an encrypted network connection must now call
+external utilities such as @command{starttls} or @command{gnutls-cli}.
@item
Tool bars can no longer display separators, which frees up several
pixels of space on each graphical frame.
@item
-Many other functions and variables have been eliminated.
+As part of the ongoing quest for simplicity, many other functions and
+variables have been eliminated.
@end itemize
before continuing execution. When you create an asynchronous
subprocess, it can run in parallel with the Lisp program. This kind of
subprocess is represented within Emacs by a Lisp object which is also
-called a ``process.'' Lisp programs can use this object to communicate
+called a ``process''. Lisp programs can use this object to communicate
with the subprocess or to control it. For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.
process and returns a process object (@pxref{Asynchronous Processes}).
The other two, @code{call-process} and @code{call-process-region},
create a synchronous process and do not return a process object
-(@pxref{Synchronous Processes}).
+(@pxref{Synchronous Processes}). There are various higher-level
+functions that make use of these primitives to run particular types of
+process.
Synchronous and asynchronous processes are explained in the following
sections. Since the three functions are all called in a similar
@strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You
-must use @var{args} to provide those.
+must use a separate argument, @var{args}, to provide those, as
+described below.
Each of the subprocess-creating functions has a @var{buffer-or-name}
-argument which specifies where the standard output from the program will
+argument that specifies where the standard output from the program will
go. It should be a buffer or a buffer name; if it is a buffer name,
that will create the buffer if it does not already exist. It can also
be @code{nil}, which says to discard the output unless a filter function
handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
Normally, you should avoid having multiple processes send output to the
same buffer because their output would be intermixed randomly.
+For synchronous processes, you can send the output to a file instead
+of a buffer.
@cindex program arguments
All three of the subprocess-creating functions have a @code{&rest}
characters and other shell constructs have no special meanings in these
strings, since the strings are passed directly to the specified program.
- The subprocess gets its current directory from the value of
-@code{default-directory} (@pxref{File Name Expansion}).
-
@cindex environment variables, subprocesses
The subprocess inherits its environment from Emacs, but you can
specify overrides for it with @code{process-environment}. @xref{System
-Environment}.
+Environment}. The subprocess gets its current directory from the
+value of @code{default-directory}.
@defvar exec-directory
@pindex movemail
The value of this variable is a string, the name of a directory that
-contains programs that come with GNU Emacs, programs intended for Emacs
+contains programs that come with GNU Emacs and are intended for Emacs
to invoke. The program @code{movemail} is an example of such a program;
Rmail uses it to fetch new mail from an inbox.
@end defvar
The value of @code{exec-path} is used by @code{call-process} and
@code{start-process} when the @var{program} argument is not an absolute
file name.
+
+Generally, you should not modify @code{exec-path} directly. Instead,
+ensure that your @env{PATH} environment variable is set appropriately
+before starting Emacs. Trying to modify @code{exec-path}
+independently of @env{PATH} can lead to confusing results.
@end defopt
@node Shell Arguments
characters, use the function @code{shell-quote-argument}:
@defun shell-quote-argument argument
-This function returns a string which represents, in shell syntax,
+This function returns a string that represents, in shell syntax,
an argument whose actual contents are @var{argument}. It should
work reliably to concatenate the return value into a shell command
and then pass it to a shell for execution.
The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line
-arguments. These functions are mainly intended to be used for
+arguments. These functions are mainly intended for
converting user input in the minibuffer, a Lisp string, into a list of
string arguments to be passed to @code{call-process} or
-@code{start-process}, or for the converting such lists of arguments in
+@code{start-process}, or for converting such lists of arguments into
a single Lisp string to be presented in the minibuffer or echo area.
@defun split-string-and-unquote string &optional separators
@result{} 0
---------- Buffer: foo ----------
-/usr/user/lewis/manual
+/home/lewis/manual
---------- Buffer: foo ----------
@end group
@result{} 0
---------- Buffer: bar ----------
-lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash
---------- Buffer: bar ----------
@end group
@end smallexample
-Here is a good example of the use of @code{call-process}, which used to
-be found in the definition of @code{insert-directory}:
+Here is an example of the use of @code{call-process}, as used to
+be found in the definition of the @code{insert-directory} function:
@smallexample
@group
-(call-process insert-directory-program nil t nil @var{switches}
+(call-process insert-directory-program nil t nil switches
(if full-directory-p
(concat (file-name-as-directory file) ".")
file))
@defun process-file program &optional infile buffer display &rest args
This function processes files synchronously in a separate process. It
-is similar to @code{call-process} but may invoke a file handler based
-on the value of the variable @code{default-directory}. The current
-working directory of the subprocess is @code{default-directory}.
+is similar to @code{call-process}, but may invoke a file handler based
+on the value of the variable @code{default-directory}, which specifies
+the current working directory of the subprocess.
The arguments are handled in almost the same way as for
@code{call-process}, with the following differences:
output by way of the @var{buffer} argument.
If a file handler is invoked, it determines the program to run based
-on the first argument @var{program}. For instance, consider that a
+on the first argument @var{program}. For instance, suppose that a
handler for remote files is invoked. Then the path that is used for
-searching the program might be different than @code{exec-path}.
+searching for the program might be different from @code{exec-path}.
The second argument @var{infile} may invoke a file handler. The file
handler could be different from the handler chosen for the
@code{process-file} function itself. (For example,
-@code{default-directory} could be on a remote host, whereas
-@var{infile} is on another remote host. Or @code{default-directory}
+@code{default-directory} could be on one remote host, and
+@var{infile} on a different remote host. Or @code{default-directory}
could be non-special, whereas @var{infile} is on a remote host.)
If @var{buffer} is a list of the form @code{(@var{real-destination}
@end defun
@defvar process-file-side-effects
-This variable indicates, whether a call of @code{process-file} changes
+This variable indicates whether a call of @code{process-file} changes
remote files.
-Per default, this variable is always set to @code{t}, meaning that a
+By default, this variable is always set to @code{t}, meaning that a
call of @code{process-file} could potentially change any file on a
remote host. When set to @code{nil}, a file handler could optimize
-its behavior with respect to remote file attributes caching.
+its behavior with respect to remote file attribute caching.
-This variable should never be changed by @code{setq}. Instead of, it
-shall be set only by let-binding.
+You should only ever change this variable with a let-binding; never
+with @code{setq}.
@end defvar
@defun call-process-region start end program &optional delete destination display &rest args
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish (this only
-works if asynchronous subprocesses are supported).
+works if asynchronous subprocesses are supported; i.e. not on MS-DOS).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@end group
@end smallexample
- The @code{shell-command-on-region} command uses
-@code{call-process-region} like this:
+ For example, the @code{shell-command-on-region} command uses
+@code{call-process-region} in a manner similar to this:
@smallexample
@group
(call-process-region
start end
- shell-file-name ; @r{Name of program.}
- nil ; @r{Do not delete region.}
- buffer ; @r{Send output to @code{buffer}.}
- nil ; @r{No redisplay during output.}
- "-c" command) ; @r{Arguments for the shell.}
+ shell-file-name ; @r{name of program}
+ nil ; @r{do not delete region}
+ buffer ; @r{send output to @code{buffer}}
+ nil ; @r{no redisplay during output}
+ "-c" command) ; @r{arguments for the shell}
@end group
@end smallexample
+@c It actually uses shell-command-switch, but no need to mention that here.
@end defun
@defun call-process-shell-command command &optional infile destination display &rest args
then returns the command's output as a string.
@end defun
+@c There is also shell-command-on-region, but that is more of a user
+@c command, not something to use in programs.
+
@defun process-lines program &rest args
This function runs @var{program}, waits for it to finish, and returns
its output as a list of strings. Each string in the list holds a
line arguments for the program.
In the example below, the first process is started and runs (rather,
-sleeps) for 100 seconds. Meanwhile, the second process is started, and
+sleeps) for 100 seconds (the output buffer @samp{foo} is created
+immediately). Meanwhile, the second process is started, and
given the name @samp{my-process<1>} for the sake of uniqueness. It
inserts the directory listing at the end of the buffer @samp{foo},
before the first process finishes. Then it finishes, and a message to
@end group
@group
-(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+(start-process "my-process" "foo" "ls" "-l" "/bin")
@result{} #<process my-process<1>>
---------- Buffer: foo ----------
-total 2
-lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
--rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+total 8336
+-rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
+-rwxr-xr-x 1 root root 146920 Jul 5 2011 bsd-csh
+@dots{}
+-rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4
Process my-process<1> finished
@defun start-file-process name buffer-or-name program &rest args
Like @code{start-process}, this function starts a new asynchronous
subprocess running @var{program} in it, and returns its process
-object---when @code{default-directory} is not a magic file name.
+object.
-If @code{default-directory} is magic, the function invokes its file
-handler instead. This handler ought to run @var{program}, perhaps on
-the local host, perhaps on a remote host that corresponds to
-@code{default-directory}. In the latter case, the local part of
-@code{default-directory} becomes the working directory of the process.
+The difference from @code{start-process} is that this function may
+invoked a file handler based on the value of @code{default-directory}.
+This handler ought to run @var{program}, perhaps on the local host,
+perhaps on a remote host that corresponds to @code{default-directory}.
+In the latter case, the local part of @code{default-directory} becomes
+the working directory of the process.
This function does not try to invoke file name handlers for
@var{program} or for the @var{program-args}.
Depending on the implementation of the file handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to
-the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
+the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}.
+@c FIXME Can we find a better example (i.e. a more modern function
+@c that is actually documented).
Some file handlers may not support @code{start-file-process} (for
-example @code{ange-ftp-hook-function}). In such cases, the function
-does nothing and returns @code{nil}.
+example the function @code{ange-ftp-hook-function}). In such cases,
+this function does nothing and returns @code{nil}.
@end defun
@defun start-process-shell-command name buffer-or-name command
-This function is like @code{start-process} except that it uses a shell
+This function is like @code{start-process}, except that it uses a shell
to execute the specified command. The argument @var{command} is a shell
command name. The variable @code{shell-file-name} specifies which shell to
use.
The point of running a program through the shell, rather than directly
with @code{start-process}, is so that you can employ shell features such
-as wildcards in the arguments. It follows that if you include an
-arbitrary user-specified arguments in the command, you should quote it
+as wildcards in the arguments. It follows that if you include any
+arbitrary user-specified arguments in the command, you should quote them
with @code{shell-quote-argument} first, so that any special shell
characters do @emph{not} have their special shell meanings. @xref{Shell
-Arguments}.
+Arguments}. Of course, when executing commands based on user input
+you should also consider the security implications.
@end defun
@defun start-file-process-shell-command name buffer-or-name command
This function is like @code{start-process-shell-command}, but uses
-@code{start-file-process} internally. By this, @var{command} can be
-executed also on remote hosts, depending on @code{default-directory}.
+@code{start-file-process} internally. Because of this, @var{command}
+can also be executed on remote hosts, depending on @code{default-directory}.
@end defun
@defvar process-connection-type
@smallexample
@group
-(let ((process-connection-type nil)) ; @r{Use a pipe.}
+(let ((process-connection-type nil)) ; @r{use a pipe}
(start-process @dots{}))
@end group
@end smallexample
@dfn{Deleting a process} disconnects Emacs immediately from the
subprocess. Processes are deleted automatically after they terminate,
but not necessarily right away. You can delete a process explicitly
-at any time. If you delete a terminated process explicitly before it
+at any time. If you explicitly delete a terminated process before it
is deleted automatically, no harm results. Deleting a running
-process sends a signal to terminate it (and its child processes if
+process sends a signal to terminate it (and its child processes, if
any), and calls the process sentinel if it has one. @xref{Sentinels}.
When a process is deleted, the process object itself continues to
@end defun
@defun process-live-p process
-This function returns nin-@code{nil} if @var{process} is alive. A
+This function returns non-@code{nil} if @var{process} is alive. A
process is considered alive if its status is @code{run}, @code{open},
@code{listen}, @code{connect} or @code{stop}.
@end defun
@dfn{fields}. This specification controls length of each field to be
processed, and how to pack or unpack it. We normally keep bindat specs
in variables whose names end in @samp{-bindat-spec}; that kind of name
-is automatically recognized as ``risky.''
+is automatically recognized as ``risky''.
@cindex endianness
@cindex big endian
that the field represents and, in the case of multibyte fields, how
the bytes are ordered within the field. The two possible orderings
are ``big endian'' (also known as ``network byte ordering'') and
-``little endian.'' For instance, the number @code{#x23cd} (decimal
+``little endian''. For instance, the number @code{#x23cd} (decimal
9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
and in little endian, @code{#xcd} @code{#x23}. Here are the possible
type values:
+2012-04-15 Stefan Monnier <monnier@iro.umontreal.ca>
+
+ Avoid the use of ((lambda ...) ...) in lexical-binding code.
+ * emacs-lisp/easy-mmode.el (define-minor-mode):Use funcall (bug#11241).
+
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * simple.el (process-file-side-effects): Doc fix.
+
+2012-04-15 Glenn Morris <rgm@gnu.org>
+
+ * international/mule-cmds.el (set-language-environment): Doc fix.
+
2012-04-14 Juanma Barranquero <lekktu@gmail.com>
* server.el (server-auth-key, server-generate-key): Doc fixes.
;; repeat-command still does the toggling correctly.
(interactive (list (or current-prefix-arg 'toggle)))
(let ((,last-message (current-message)))
- (,@(if setter (list setter)
+ (,@(if setter `(funcall #',setter)
(list (if (symbolp mode) 'setq 'setf) mode))
(if (eq arg 'toggle)
(not ,mode)
This sets the coding system priority and the default input method
and sometimes other things. LANGUAGE-NAME should be a string
which is the name of a language environment. For example, \"Latin-1\"
-specifies the character set for the major languages of Western Europe."
+specifies the character set for the major languages of Western Europe.
+
+If there is a prior value for `current-language-environment', this
+runs the hook `exit-language-environment-hook'. After setting up
+the new language environment, it runs `set-language-environment-hook'."
(interactive (list (read-language-name
nil
"Set language environment (default English): ")))
;;; simple.el --- basic editing commands for Emacs
-;; Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: internal
(defvar process-file-side-effects t
"Whether a call of `process-file' changes remote files.
-Per default, this variable is always set to `t', meaning that a
+By default, this variable is always set to `t', meaning that a
call of `process-file' could potentially change any file on a
remote host. When set to `nil', a file handler could optimize
-its behavior with respect to remote file attributes caching.
+its behavior with respect to remote file attribute caching.
-This variable should never be changed by `setq'. Instead of, it
-shall be set only by let-binding.")
+You should only ever change this variable with a let-binding;
+never with `setq'.")
(defun start-file-process (name buffer program &rest program-args)
"Start a program in a subprocess. Return the process object for it.