--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/consoles-devices.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,270 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1995, 1996 Ben Wing.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/consoles-devices.info
+@node Consoles and Devices, Positions, Frames, top
+@chapter Consoles and Devices
+@cindex devices
+@cindex consoles
+
+  A @dfn{console} is an object representing a single input connection
+to XEmacs, such as an X display or a TTY connection.  It is possible
+for XEmacs to have frames on multiple consoles at once (even on
+heterogeneous types -- you can simultaneously have a frame on an
+X display and a TTY connection).  Normally, there is only one
+console in existence.
+
+  A @dfn{device} is an object representing a single output device, such
+as a particular screen on an X display. (Usually there is exactly one
+device per X console connection, but there may be more than one if you
+have a multi-headed X display.  For TTY connections, there is always
+exactly one device per console.)
+
+  Each device has one or more @dfn{frames} in which text can be
+displayed.  For X displays and the like, a frame corresponds to the
+normal window-system concept of a window.  Frames can overlap, be
+displayed at various locations within the display, be resized, etc.  For
+TTY, only one frame can be displayed at a time, and it occupies the
+entire TTY display area.  However, you can still define multiple frames
+and switch between them.  Their contents are entirely separate from each
+other.  These sorts of frames resemble the ``virtual console''
+capability provided under Linux or the multiple screens provided by the
+multiplexing program @samp{screen} under Unix.
+
+  When you start up XEmacs, an initial console and device are created to
+receive input and display frames on.  This will either be an X display
+or a TTY connection, depending on what mode you started XEmacs in (this
+is determined by the @samp{DISPLAY} environment variable, the
+@samp{-nw}, @samp{-t} and @samp{-display} command-line options, etc.).
+
+  You can connect to other X displays and TTY connections by creating
+new console objects, and to other X screens on an existing display by
+creating new device objects, as described below.  Many functions (for
+example the frame-creation functions) take an optional device argument
+specifying which device the function pertains to.  If the argument is
+omitted, it defaults to the selected device (see below).
+
+@defun consolep object
+This returns non-@code{nil} if @var{object} is a console.
+@end defun
+
+@defun devicep object
+This returns non-@code{nil} if @var{object} is a device.
+@end defun
+
+@menu
+* Basic Console Functions::     Functions for working with consoles.
+* Basic Device Functions::      Functions for working with devices.
+* Console Types and Device Classes::
+                                I/O and color characteristics.
+* Connecting to a Console or Device::
+* The Selected Console and Device::
+* Console and Device I/O::      Controlling input and output.
+@end menu
+
+@node Basic Console Functions
+@section Basic Console Functions
+
+@defun console-list
+This function returns a list of all existing consoles.
+@end defun
+
+@defun console-device-list &optional console
+This function returns a list of all devices on @var{console}.  If
+@var{console} is @code{nil}, the selected console will be used.
+@end defun
+
+@node Basic Device Functions
+@section Basic Device Functions
+
+@defun device-list
+This function returns a list of all existing devices.
+@end defun
+
+@defun device-or-frame-p object
+This function returns non-@code{nil} if @var{object} is a device or
+frame.  This function is useful because devices and frames are similar
+in many respects and many functions can operate on either one.
+@end defun
+
+@defun device-frame-list device
+This function returns a list of all frames on @var{device}.
+@end defun
+
+@defun frame-device frame
+This function returns the device that @var{frame} is on.
+@end defun
+
+@node Console Types and Device Classes
+@section Console Types and Device Classes
+
+Every device is of a particular @dfn{type}, which describes how the
+connection to that device is made and how the device operates, and
+a particular @dfn{class}, which describes other characteristics of
+the device (currently, the color capabilities of the device).
+
+The currently-defined device types are
+
+@table @code
+@item x
+A connection to an X display (such as @samp{willow:0}).
+
+@item tty
+A connection to a tty (such as @samp{/dev/ttyp3}).
+
+@item stream
+A stdio connection.  This describes a device for which input and output
+is only possible in a stream-like fashion, such as when XEmacs in running
+in batch mode.  The very first device created by XEmacs is a terminal
+device and is used to print out messages of various sorts (for example,
+the help message when you use the @samp{-help} command-line option).
+@end table
+
+The currently-defined device classes are
+@table @code
+@item color
+A color device.
+
+@item grayscale
+A grayscale device (a device that can display multiple shades of gray,
+but no color).
+
+@item mono
+A device that can only display two colors (e.g. black and white).
+@end table
+
+@defun device-type device
+This function returns the type of @var{device}.  This is a symbol whose
+name is one of the device types mentioned above.
+@end defun
+
+@defun device-or-frame-type device-or-frame
+This function returns the type of @var{device-or-frame}.
+@end defun
+
+@defun device-class device
+This function returns the class (color behavior) of @var{device}.  This
+is a symbol whose name is one of the device classes mentioned above.
+@end defun
+
+@defun valid-device-type-p device-type
+This function returns whether @var{device-type} (which should be a symbol)
+species a valid device type.
+@end defun
+
+@defun valid-device-class-p device-class
+This function returns whether @var{device-class} (which should be a symbol)
+species a valid device class.
+@end defun
+
+@defvar terminal-device
+This variable holds the initial terminal device object, which
+represents XEmacs's stdout.
+@end defvar
+
+@node Connecting to a Console or Device
+@section Connecting to a Console or Device
+
+@defun make-device &optional type device-data
+This function creates a new device.
+@end defun
+
+The following two functions create devices of specific types and are
+written in terms of @code{make-device}.
+
+@defun make-tty-device &optional tty terminal-type 
+This function creates a new tty device on @var{tty}.  This also creates
+the tty's first frame.  @var{tty} should be a string giving the name of
+a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
+returned by the @samp{tty} command issued from the Unix shell.  A value
+of @code{nil} means use the stdin and stdout as passed to XEmacs from
+the shell.  If @var{terminal-type} is non-@code{nil}, it should be a
+string specifying the type of the terminal attached to the specified
+tty.  If it is @code{nil}, the terminal type will be inferred from the
+@samp{TERM} environment variable.
+@end defun
+
+@defun make-x-device &optional display argv-list
+This function creates a new device connected to @var{display}.  Optional
+argument @var{argv-list} is a list of strings describing command line
+options.
+@end defun
+
+@defun delete-device device
+This function deletes @var{device}, permanently eliminating it from use.
+This disconnects XEmacs's connection to the device.
+@end defun
+
+@defvar create-device-hook
+This variable, if non-@code{nil}, should contain a list of functions,
+which are called when a device is created.
+@end defvar
+
+@defvar delete-device-hook
+This variable, if non-@code{nil}, should contain a list of functions,
+which are called when a device is deleted.
+@end defvar
+
+@defun console-live-p object
+This function returns non-@code{nil} if @var{object} is a console that
+has not been deleted.
+@end defun
+
+@defun device-live-p object
+This function returns non-@code{nil} if @var{object} is a device that
+has not been deleted.
+@end defun
+
+@defun device-x-display device
+This function returns the X display which @var{device} is connected to,
+if @var{device} is an X device.
+@end defun
+
+@node The Selected Console and Device
+@section The Selected Console and Device
+
+@defun select-console console
+This function selects the console @var{console}.  Subsequent editing
+commands apply to its selected device, selected frame, and selected
+window.  The selection of @var{console} lasts until the next time the
+user does something to select a different console, or until the next
+time this function is called.
+@end defun
+
+@defun selected-console
+This function returns the console which is currently active.
+@end defun
+
+@defun select-device device
+This function selects the device @var{device}.
+@end defun
+
+@defun selected-device &optional console
+This function returns the device which is currently active.  If optional
+@var{console} is non-@code{nil}, this function returns the device that
+would be currently active if @var{console} were the selected console.
+@end defun
+
+@node Console and Device I/O
+@section Console and Device I/O
+
+@defun console-disable-input console
+This function disables input on console @var{console}.
+@end defun
+
+@defun console-enable-input console
+This function enables input on console @var{console}.
+@end defun
+
+Each device has a @dfn{baud rate} value associated with it.
+On most systems, changing this value will affect the amount of padding
+and other strategic decisions made during redisplay.
+
+@defun device-baud-rate &optional device
+This function returns the output baud rate of @var{device}.
+@end defun
+
+@defun set-device-baud-rate device rate
+This function sets the output baud rate of @var{device} to @var{rate}.
+@end defun