[Emacs-diffs] emacs/doc/lispref frames.texi

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    09/01/17 16:31:22

Modified files:
        doc/lispref    : frames.texi 

Log message:
        (Frames): Document `frame-terminal' and `terminal-live-p'.
        (Multiple Displays): Document `make-frame-on-tty'.
        (Multiple Terminals): Document `terminal-list', `delete-terminal',
        `terminal-name', and `get-device-terminal'.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/frames.texi?cvsroot=emacs&r1=1.20&r2=1.21

Patches:
Index: frames.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/frames.texi,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -b -r1.20 -r1.21
--- frames.texi 8 Jan 2009 13:04:22 -0000       1.20
+++ frames.texi 17 Jan 2009 16:31:21 -0000      1.21
@@ -13,12 +13,20 @@
 is called a ``window'' in the terminology of graphical environments; but
 we can't call it a ``window'' here, because Emacs uses that word in a
 different way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object
-that represents a frame on the screen.
+that represents a frame on the screen.  @xref{Frame Type}.
 
   A frame initially contains a single main window and/or a minibuffer
 window; you can subdivide the main window vertically or horizontally
 into smaller windows.  @xref{Splitting Windows}.
 
+  A @dfn{terminal} is a display device capable of displaying one or
+more Emacs frames.  On GNU and Unix systems, Emacs supports any number
+of different terminals in one session, and can mix GUI and text-only
+frames in the same session.
+
+  Emacs represents each terminal on which it displays frames as a
+special @dfn{terminal object} data type, see @ref{Terminal Type}.
+
 @cindex terminal frame
   When Emacs runs on a text-only terminal, it starts with one
 @dfn{terminal frame}.  If you create additional frames on the same
@@ -51,10 +59,26 @@
 @end table
 @end defun
 
address@hidden frame-terminal &optional frame
+This function returns the terminal object (@pxref{Terminal Type}) that
+displays @var{frame}.  If @var{frame} is @code{nil} or unspecified, it
+defaults to the selected frame.
address@hidden defun
+
address@hidden terminal-live-p object
+This predicate returns a address@hidden value if @var{object} is a
+terminal that is alive (i.e.@: was not deleted), and @code{nil}
+otherwise.  For live terminals, the return value indicates what kind
+of frames are displayed on that terminal; the list of possible values
+is the same as for @code{framep} above.
address@hidden defun
+
 @menu
 * Creating Frames::             Creating additional frames.
 * Multiple Displays::           Creating frames on other displays.
+* Multiple Terminals::          Displaying on several different devices.
 * Frame Parameters::            Controlling frame size, position, font, etc.
+* Terminal Parameters::         Parameters common for all frames on terminal.
 * Frame Titles::                Automatic updating of frame titles.
 * Deleting Frames::            Frames last until explicitly deleted.
 * Finding All Frames::         How to examine all existing frames.
@@ -77,7 +101,6 @@
 * Text Terminal Colors::        Defining colors for text-only terminals.
 * Resources::                  Getting resource values from the server.
 * Display Feature Testing::     Determining the features of a terminal.
-* Multiple Terminals::          Displaying on several different devices.
 @end menu
 
   @xref{Display}, for information about the related topic of
@@ -182,6 +205,16 @@
 Frames}).
 @end deffn
 
address@hidden Command make-frame-on-tty tty type &optional parameters
+This command creates a text-only frame on another text terminal.  The
+argument @var{tty} identifies the terminal device by its file name,
+e.g., @file{/dev/ttys2}, and @var{type} gives the device type as a
+string, e.g., @code{"vt100"}, to use for searching the
+termcap/terminfo database for the entry describing capabilities of the
+device.  Optional argument @var{parameters} specifies additional
+parameters for the frame.
address@hidden deffn
+
 @defun x-display-list
 This returns a list that indicates which X displays Emacs has a
 connection to.  The elements of the list are strings, and each one is
@@ -216,6 +249,71 @@
 that display (@pxref{Deleting Frames}).
 @end defun
 
address@hidden Multiple Terminals
address@hidden Multiple Terminals
address@hidden multiple terminals
address@hidden multi-tty
+
+  Emacs represents each terminal on which it displays frames as a
+special @dfn{terminal object} data type, see @ref{Terminal Type}.  The
+terminal object has the following attributes:
+
address@hidden @bullet
address@hidden
+The name of the device used by the terminal (e.g., @file{/dev/tty}).
+
address@hidden
+The terminal and keyboard coding systems (@pxref{Terminal I/O
+Encoding}) used on the terminal.
+
address@hidden
+The kind of frames (@pxref{Frames}) the terminal is displaying.
+
address@hidden
+A list of the terminal parameters (@pxref{Terminal Parameters}).
address@hidden itemize
+
+  There's no primitive for creating terminal objects; Emacs creates
+them as needed when you call one of the primitives, such as
address@hidden (@pxref{Multiple Displays}), that start
+displaying on a new terminal.
+
address@hidden terminal-list
+This function return the list of all the terminal objects used by
+Emacs to display frames in this session.
address@hidden defun
+
address@hidden delete-terminal &optional terminal force
+This function deletes all frames on @var{terminal} and frees the
+resources used by it.  @var{terminal} can be a terminal object, a
+frame (meaning that frame's terminal), or @code{nil} (meaning the
+selected frame's terminal).  Normally, the function signals an error
+if you attempt to delete the sole active terminal, but if @var{force}
+is address@hidden, you are allowed to do so.  This function runs the
+hook @code{delete-terminal-functions}, passing each function a single
+argument, @var{terminal}.
address@hidden defun
+
address@hidden terminal-name &optional terminal
+This function returns the file name of the device used by
address@hidden  If @var{terminal} is omitted or @code{nil}, it
+defaults to the selected frame's terminal.  @var{terminal} can also be
+a frame, meaning that frame's terminal.
address@hidden defun
+
address@hidden get-device-terminal device
+This function is in a sense the opposite of @code{terminal-name}: it
+returns a terminal whose device name is given by @var{device}.  If
address@hidden is a string, it can be either the file name of a terminal
+device or the name of an X display of the form
address@hidden@var{host}:@address@hidden (@pxref{Multiple
+Displays}).  If @var{device} is a frame, this function returns that
+frame's terminal; @code{nil} means the selected frame.  Finally, if
address@hidden is a terminal object that represents a live terminal,
+that terminal is returned.  The function signals an error if its
+argument is none of the above.
address@hidden defun
+
 @node Frame Parameters
 @section Frame Parameters
 @cindex frame parameters
@@ -951,6 +1049,22 @@
 @end example
 @end defun
 
address@hidden Terminal Parameters
address@hidden Terminal Parameters
address@hidden terminal parameters
+
+  This subsection describes how to read and change the parameter
+values of a terminal.
+
address@hidden terminal-parameters &optional terminal
address@hidden defun
+
address@hidden terminal-parameter terminal parameter
address@hidden defun
+
address@hidden set-terminal-parameter terminal parameter value
address@hidden defun
+
 @node Frame Titles
 @section Frame Titles
 @cindex frame title
@@ -1326,6 +1440,16 @@
 Emacs does provide events that you can use to keep track of such
 changes.  @xref{Misc Events}.
 
address@hidden suspend-frame
address@hidden defun
+
address@hidden FIXME: xref to suspend-emacs, and xref there.
address@hidden suspend-tty &optional tty
address@hidden defun
+
address@hidden resume-tty &optional tty
address@hidden defun
+
 @node Raising and Lowering
 @section Raising and Lowering Frames
 
@@ -2242,108 +2366,6 @@
 width and height of an X Window frame, measured in pixels.
 @end ignore
 
address@hidden Multiple Terminals
address@hidden Multiple Terminals
address@hidden multiple terminals
address@hidden multi-tty
-
-  A @dfn{terminal} is a display device capable of displaying one or
-more Emacs frames.  On GNU and Unix systems, Emacs supports any number
-of different terminals in one session, and can mix GUI and text-only
-frames in the same session.
-
-  Emacs represents each terminal on which it displays frames as a
-special @dfn{terminal object} data type, see @ref{Terminal Type}.  The
-terminal object has a unique integer identifier and the following
-attributes:
-
address@hidden @bullet
address@hidden
-The name of the device used by the terminal (e.g., @file{/dev/tty}).
-
address@hidden
-The terminal and keyboard coding systems (@pxref{Terminal I/O
-Encoding}) used on the terminal.
-
address@hidden
-The type of frames (@pxref{Frames}) the terminal is displaying.
-
address@hidden
-A list of the terminal parameters (@pxref{Terminal Parameters}).
address@hidden itemize
-
address@hidden This is still under construction.
-
address@hidden frame-terminal
address@hidden defun
-
address@hidden get-device-terminal device
address@hidden defun
-
address@hidden terminal-list
address@hidden defun
-
address@hidden
-* Low-level Terminal::          Low-level manipulation of terminal objects.
-* Terminal Parameters::         Parameters common for all frames on terminal.
-* Frames on Other TTY devices:: Creating frames on other terminal devices.
address@hidden menu
-
address@hidden Low-level Terminal
address@hidden Low-level Access to Terminals
-
-  This subsection describes low-level primitives for accessing and
-manipulating Emacs terminal objects.  There's no primitive for
-creating terminal objects; Emacs creates them as needed when you call
-one of the primitives, such as @code{make-frame-on-tty} (@pxref{Frames
-on Other TTY devices}), that start displaying on a new terminal.
-
address@hidden suspend-tty &optional tty
address@hidden defun
-
address@hidden resume-tty &optional tty
address@hidden defun
-
address@hidden terminal-live-p object
address@hidden defun
-
address@hidden terminal-name &optional terminal
address@hidden defun
-
address@hidden delete-terminal &optional terminal force
address@hidden defun
-
address@hidden Terminal Parameters
address@hidden Terminal Parameters
address@hidden terminal parameters
-
-  This subsection describes how to read and change the parameter
-values of a terminal.
-
address@hidden terminal-parameters &optional terminal
address@hidden defun
-
address@hidden terminal-parameter terminal parameter
address@hidden defun
-
address@hidden set-terminal-parameter terminal parameter value
address@hidden defun
-
address@hidden environment &optional frame
address@hidden defun
-
address@hidden initial-environment
address@hidden defvar
-
address@hidden Frames on Other TTY devices
address@hidden Frames on Other TTY devices
-
-  This subsection documents functions related to displaying Emacs
-frames on a terminal device other than the current one.
-
address@hidden make-frame-on-tty tty type &optional parameters
address@hidden defun
-
 
 @ignore
    arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba