Some terminal emulators record separate contents for display-oriented
programs such as Emacs and for ordinary sequential display. If you are
using such a terminal, you might want to inhibit the redisplay on
-resumption. @xref{Suspending Emacs}.
+resumption.
@defvar no-redraw-on-reenter
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex display columns
@cindex resize redisplay
- The screen size functions report or tell Emacs the height or width of
+ The screen size functions access or specify the height or width of
the terminal. When you are using multiple frames, they apply to the
selected frame (@pxref{Frames}).
This variant is designed as a user-level feature.
The way you control explicit selective display is by replacing a
-newline (control-j) with a carriage return (control-m). The text which
+newline (control-j) with a carriage return (control-m). The text that
was formerly a line following that newline is now invisible. Strictly
speaking, it is temporarily no longer a line at all, since only newlines
can separate lines; it is now part of the previous line.
about to be executed.
@defvar overlay-arrow-string
-This variable holds the string to display as an arrow, or @code{nil} if
-the arrow feature is not in use.
+This variable holds the string to display to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
@end defvar
@defvar overlay-arrow-position
-This variable holds a marker which indicates where to display the arrow.
-It should point at the beginning of a line. The arrow text appears at
-the beginning of that line, overlaying any text that would otherwise
-appear. Since the arrow is usually short, and the line usually begins
-with indentation, normally nothing significant is overwritten.
-
-The overlay string is displayed only in the buffer which this marker
+This variable holds a marker that indicates where to display the overlay
+arrow. It should point at the beginning of a line. The arrow text
+appears at the beginning of that line, overlaying any text that would
+otherwise appear. Since the arrow is usually short, and the line
+usually begins with indentation, normally nothing significant is
+overwritten.
+
+The overlay string is displayed only in the buffer that this marker
points into. Thus, only one buffer can have an overlay arrow at any
given time.
@c !!! overlay-arrow-position: but the overlay string may remain in the display
@end defspec
@defvar temp-buffer-show-function
-If this variable, if non-@code{nil}, @code{with-output-to-temp-buffer}
+If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
@cindex overlays
You can use @dfn{overlays} to alter the appearance of a buffer's text on
-the screen. An overlay is an object which belongs to a particular
+the screen. An overlay is an object that belongs to a particular
buffer, and has a specified beginning and end. It also has properties
that you can examine and set; these affect the display of the text
within the overlay.
overlays, and to examine their contents.
@defun make-overlay start end &optional buffer
-This function creates and returns an overlay which belongs to
+This function creates and returns an overlay that belongs to
@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
and @var{end} must specify buffer positions; they may be integers or
markers. If @var{buffer} is omitted, the overlay is created in the
@item
With text properties. A character may have a @code{face} property; if so,
-it's displayed with that face. @xref{Special Properties}.
+it is displayed with that face. @xref{Special Properties}.
If the character has a @code{mouse-face} property, that is used instead
of the @code{face} property when the mouse is ``near enough'' to the
@defun set-face-foreground face color &optional frame
@defunx set-face-background face color &optional frame
-These functions set the foreground (respectively, background) color of
-face @var{face} to @var{color}. The argument @var{color} should be a
+These functions set the foreground (or background, respectively) color
+of face @var{face} to @var{color}. The argument @var{color} should be a
string, the name of a color.
@end defun
@defun invert-face face &optional frame
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
-and background are set to the default background and foreground.
+and background are set to the default background and foreground,
+respectively.
@end defun
These functions examine the attributes of a face. If you don't
@defun face-foreground face &optional frame
@defunx face-background face &optional frame
-These functions return the foreground (respectively, background) color
-of face @var{face}, as a string.
+These functions return the foreground color (or background color,
+respectively) of face @var{face}, as a string.
@end defun
@defun face-font face &optional frame
@item
All other codes in the range 0 through 31, and code 127, display in one
-of two ways according to the value of @code{ctl-arrow}. If it is is
+of two ways according to the value of @code{ctl-arrow}. If it is
non-@code{nil}, these codes map to sequences of two glyphs, where the
first glyph is the @sc{ASCII} code for @samp{^}. (A display table can
specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
@end example
If you are editing buffers written in the ISO Latin 1 character set and
-your terminal doesn't handle anything but @sc{ASCII}, you can load the file
-@file{iso-ascii} to set up a display table which makes the other ISO
-characters display as sequences of @sc{ASCII} characters. For example, the
-character ``o with umlaut'' displays as @samp{@{"o@}}.
+your terminal doesn't handle anything but @sc{ASCII}, you can load the
+file @file{iso-ascii} to set up a display table that displays the other
+ISO characters as explanatory sequences of @sc{ASCII} characters. For
+example, the character ``o with umlaut'' displays as @samp{@{"o@}}.
Some European countries have terminals that don't support ISO Latin 1
but do support the special characters for that country's language. You
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
-values in the operating system environment, and terminal input, output
+values in the operating system environment, and terminal input, output,
and flow control.
@xref{Building Emacs}, for related information. See also
@item
It loads the file @file{~/.emacs} unless @samp{-q} was specified on
-command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
+the command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
option can specify the user name whose home directory should be used
instead of @file{~}.
@item
It loads the library @file{default} unless @code{inhibit-default-init}
is non-@code{nil}. (This is not done in @samp{-batch} mode or if
-@samp{-q} was specified on command line.) The library's file name is
-usually @file{default.el}.
+@samp{-q} was specified on the command line.) The library's file name
+is usually @file{default.el}.
@cindex @file{default.el}
@item
It runs @code{window-setup-hook}. @xref{Window Systems}.
@item
-It displays copyleft, nonwarranty and basic use information, provided
+It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command line arguments (a few steps above) and
the value of @code{inhibit-startup-message} is @code{nil}.
@end enumerate
@end defvar
@defvar term-setup-hook
-This variable is a normal hook which Emacs runs after loading your
+This variable is a normal hook that Emacs runs after loading your
@file{.emacs} file, the default initialization file (if any) and the
terminal-specific Lisp file.
@end ignore
@defun command-line
-This function parses the command line which Emacs was called with,
+This function parses the command line that Emacs was called with,
processes it, loads the user's @file{.emacs} file and displays the
-initial nonwarranty information, etc.
+startup messages.
@end defun
@defvar command-line-processed
This variable's value is a list of functions for handling an
unrecognized command-line argument. Each time the next argument to be
processed has no special meaning, the functions in this list are called,
-in the order they appear, until one of them returns a non-@code{nil}
+in order of appearance, until one of them returns a non-@code{nil}
value.
These functions are called with no arguments. They can access the
non-@code{nil}, then @code{suspend-emacs} returned immediately without
actually suspending anything.
-After the user resumes Emacs, it runs the normal hook
+After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
@code{suspend-resume-hook}. @xref{Hooks}.
The next redisplay after resumption will redraw the entire screen,
If non-@code{nil}, this is a directory within which to look for the
@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
when Emacs can't find those directories in their standard installed
-locations, but can find them near where the Emacs executable was found.
+locations, but can find them in a directory related somehow to the one
+containing the Emacs executable.
@end defvar
@defun load-average
-This function returns the current 1 minute, 5 minute and 15 minute
+This function returns the current 1-minute, 5-minute and 15-minute
load averages in a list. The values are integers that are 100 times
the system load averages. (The load averages indicate the number of
processes trying to run.)
@var{high} * 2**16 + @var{low}.
@end ifinfo
@tex
-$high*-2^{16}+low$.
+$high*2^{16}+low$.
@end tex
The third element, @var{microsec}, gives the microseconds since the
The argument @var{repeat} specifies how often to repeat the call. If
@var{repeat} is @code{nil}, there are no repetitions; @var{function} is
called just once, at @var{time}. If @var{repeat} is an integer, it
-specifies a repetition period measured in seconds.
+specifies a repetition period measured in seconds. In any case, @var{repeat}
+has no effect on when @emph{first} call takes place---@var{time} specifies
+that.
+
+The function @code{run-at-time} returns a timer value that identifies
+the particular scheduled future action. You can use this value to call
+@code{cancel-timer}.
@end defun
@defun cancel-timer timer
@code{nil}, then it uses @sc{cbreak} mode.
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
-@kbd{C-s}) flow control for output to terminal. This has no effect except
+@kbd{C-s}) flow control for output to the terminal. This has no effect except
in @sc{cbreak} mode. @xref{Flow Control}.
The default setting is system dependent. Some systems always use
@end defun
@defvar function-key-map
-This variable holds a keymap which describes the character sequences
+This variable holds a keymap that describes the character sequences
sent by function keys on an ordinary character terminal. This keymap
-uses the data structure as other keymaps, but is used differently: it
+uses the same data structure as other keymaps, but is used differently: it
specifies translations to make while reading events.
If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
not they were used as parts of key sequences. Thus, you always get the
last 100 inputs, not counting keyboard macros. (Events from keyboard
macros are excluded because they are less interesting for debugging; it
-should be enough to see the events which invoked the macros.)
+should be enough to see the events that invoked the macros.)
@end defun
@deffn Command open-dribble-file filename
Emacs knows. Setting this variable does not change the speed of actual
data transmission, but the value is used for calculations such as
padding. It also affects decisions about whether to scroll part of the
-screen or repaint---even when using a window system, (We designed it
+screen or repaint---even when using a window system. (We designed it
this way despite the fact that a window system has no true ``output
speed'', to give you a way to tune these decisions.)
@item
It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
-@kbd{C-^} into @kbd{C-s} and @kbd{C-q} were typed. Except at its very
+@kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
lowest level, Emacs never knows that the characters typed were anything
but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
and @kbd{C-^} even when they are input for other commands.
@defun process-id process
This function returns the @sc{pid} of @var{process}. This is an
-integer which distinguishes the process @var{process} from all other
+integer that distinguishes the process @var{process} from all other
processes running on the same computer at the current time. The
@sc{pid} of a process is chosen by the operating system kernel when the
process is started and remains constant as long as the process exists.
The argument @var{current-group} is a flag that makes a difference
when you are running a job-control shell as an Emacs subprocess. If it
is non-@code{nil}, then the signal is sent to the current process-group
-of the terminal which Emacs uses to communicate with the subprocess. If
+of the terminal that Emacs uses to communicate with the subprocess. If
the process is a job-control shell, this means the shell's current
subjob. If it is @code{nil}, the signal is sent to the process group of
the immediate subprocess of Emacs. If the subprocess is a job-control
There are two ways to receive the output that a subprocess writes to
its standard output stream. The output can be inserted in a buffer,
which is called the associated buffer of the process, or a function
-called the @dfn{filter function} can be called to act on the output.
+called the @dfn{filter function} can be called to act on the output. If
+the process has no buffer and no filter function, its output is
+discarded.
@menu
* Process Buffers:: If no filter, output is put in a buffer.
Unless the process has a filter function (@pxref{Filter Functions}),
its output is inserted in the associated buffer. The position to insert
-the output is determined by the @code{process-mark} (@pxref{Process
-Information}), which is then updated to point to the end of the text
-just inserted. Usually, but not always, the @code{process-mark} is at
-the end of the buffer. If the process has no buffer and no filter
-function, its output is discarded.
+the output is determined by the @code{process-mark}, which is then
+updated to point to the end of the text just inserted. Usually, but not
+always, the @code{process-mark} is at the end of the buffer.
@defun process-buffer process
This function returns the associated buffer of the process
A process @dfn{filter function} is a function that receives the
standard output from the associated process. If a process has a filter,
-then @emph{all} output from that process, that would otherwise have been
-in a buffer, is passed to the filter. The process buffer is used
-directly for output from the process only when there is no filter.
+then @emph{all} output from that process is passed to the filter. The
+process buffer is used directly for output from the process only when
+there is no filter.
A filter function must accept two arguments: the associated process and
a string, which is the output. The function is then free to do whatever it
input, or for time to elapse, or for process output). This avoids the
timing errors that could result from running filters at random places in
the middle of other Lisp programs. You may explicitly cause Emacs to
-wait, so that filter functions will run, by calling @code{sit-for},
-@code{sleep-for} or @code{accept-process-output} (@pxref{Accepting
-Output}). Emacs is also waiting when the command loop is reading input.
+wait, so that filter functions will run, by calling @code{sit-for} or
+@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
+(@pxref{Accepting Output}). Emacs is also waiting when the command loop
+is reading input.
Quitting is normally inhibited within a filter function---otherwise,
the effect of typing @kbd{C-g} at command level or to quit a user
or for time to elapse, or for process output). This avoids the timing
errors that could result from running them at random places in the
middle of other Lisp programs. A program can wait, so that sentinels
-will run, by calling @code{sit-for}, @code{sleep-for} or
-@code{accept-process-output} (@pxref{Accepting Output}). Emacs is also
-waiting when the command loop is reading input.
+will run, by calling @code{sit-for} or @code{sleep-for}
+(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
+Output}). Emacs is also waiting when the command loop is reading input.
Quitting is normally inhibited within a sentinel---otherwise, the
effect of typing @kbd{C-g} at command level or to quit a user command
This function creates and returns a transaction queue communicating with
@var{process}. The argument @var{process} should be a subprocess
capable of sending and receiving streams of bytes. It may be a child
-process, or it may be a TCP connection to a server possibly on another
+process, or it may be a TCP connection to a server, possibly on another
machine.
@end defun
This function sends a transaction to queue @var{queue}. Specifying the
queue has the effect of specifying the subprocess to talk to.
-The argument @var{question} is the outgoing message which starts the
+The argument @var{question} is the outgoing message that starts the
transaction. The argument @var{fn} is the function to call when the
corresponding answer comes back; it is called with two arguments:
@var{closure}, and the answer received.
projects / emacs.git / commitdiff