--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+
+Terminal Output
+===============
+
+ The terminal output functions send output to the terminal or keep
+track of output sent to the terminal. The function `device-baud-rate'
+tells you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional DEVICE
+ This function's value is the output speed of the terminal
+ associated with DEVICE, as far as XEmacs knows. DEVICE defaults
+ to the selected device (usually the only device) if omitted.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not. If XEmacs has the wrong value, it
+makes decisions that are less than optimal. To fix the problem, use
+`set-device-baud-rate'.
+
+ - Function: set-device-baud-rate &optional DEVICE
+ This function sets the output speed of DEVICE. See
+ `device-baud-rate'. DEVICE defaults to the selected device
+ (usually the only device) if omitted.
+
+ - Function: send-string-to-terminal CHAR-OR-STRING &optional STDOUT-P
+ DEVICE
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
+ => nil
+
+ - Command: open-termscript FILENAME
+ This function is used to open a "termscript file" that will record
+ all the characters sent by XEmacs to the terminal. (If there are
+ multiple tty or stream devices, all characters sent to all such
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
+ => nil
+
+\1f
+File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
+
+Flow Control
+============
+
+ This section attempts to answer the question "Why does XEmacs choose
+to use flow-control characters in its command character set?" For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+ At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial. XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+ Later, some terminals were introduced which required these characters
+for flow control. They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention. In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option. And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+ So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers? This question has no simple answer.
+
+ One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous. There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream. Note also that their use
+for flow control is not an official standard. Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+XEmacs provides a convenient way of enabling flow control if you want
+it: call the function `enable-flow-control'.
+
+ - Function: enable-flow-control
+ This function enables use of `C-s' and `C-q' for output flow
+ control, and provides the characters `C-\' and `C-^' as aliases
+ for them using `keyboard-translate-table' (*note Translating
+ Input::.).
+
+ You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest TERMTYPES
+ This function enables flow control, and the aliases `C-\' and
+ `C-^', if the terminal type is one of TERMTYPES. For example:
+
+ (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+ Here is how `enable-flow-control' does its job:
+
+ 1. It sets CBREAK mode for terminal input, and tells the operating
+ system to handle flow control, with `(set-input-mode nil t)'.
+
+ 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+ into `C-s' and `C-q'. Except at its very lowest level, XEmacs
+ never knows that the characters typed were anything but `C-s' and
+ `C-q', so you can in effect type them as `C-\' and `C-^' even when
+ they are input for other commands. *Note Translating Input::.
+
+ If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal. You can reduce the
+amount of padding by customizing the Termcap entry. You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed. *Note Terminal
+Output::.
+
+\1f
+File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
+
+Batch Mode
+==========
+
+ The command line option `-batch' causes XEmacs to run
+noninteractively. In this mode, XEmacs does not read commands from the
+terminal, it does not alter the terminal modes, and it does not expect
+to be outputting to an erasable screen. The idea is that you specify
+Lisp programs to run; when they are finished, XEmacs should exit. The
+way to specify the programs to run is with `-l FILE', which loads the
+library named FILE, and `-f FUNCTION', which calls FUNCTION with no
+arguments.
+
+ Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+ This function returns non-`nil' when XEmacs is running in batch
+ mode.
+
+ - Variable: noninteractive
+ This variable is non-`nil' when XEmacs is running in batch mode.
+ Setting this variable to `nil', however, will not change whether
+ XEmacs is running in batch mode, and will not change the return
+ value of the `noninteractive' function.
+
+\1f
+File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
+
+Functions Specific to the X Window System
+*****************************************
+
+ XEmacs provides the concept of "devices", which generalizes
+connections to an X server, a TTY device, etc. Most information about
+an X server that XEmacs is connected to can be determined through
+general console and device functions. *Note Consoles and Devices::.
+However, there are some features of the X Window System that do not
+generalize well, and they are covered specially here.
+
+* Menu:
+
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* X Miscellaneous:: Other X-specific functions and variables.
+
+\1f
+File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
+
+X Selections
+============
+
+ The X server records a set of "selections" which permit transfer of
+data between application programs. The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection DATA &optional TYPE
+ This function sets a "selection" in the X server. It takes two
+ arguments: a value, DATA, and the selection type TYPE to assign it
+ to. DATA may be a string, a cons of two markers, or an extent.
+ In the latter cases, the selection is considered to be the text
+ between the markers, or between the extent's endpoints.
+
+ Each possible TYPE has its own selection value, which changes
+ independently. The usual values of TYPE are `PRIMARY' and
+ `SECONDARY'; these are symbols with upper-case names, in accord
+ with X Windows conventions. The default is `PRIMARY'.
+
+ (In FSF Emacs, this function is called `x-set-selection' and takes
+ different arguments.)
+
+ - Function: x-get-selection
+ This function accesses selections set up by XEmacs or by other X
+ clients. It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional SECONDARY-P
+ Assuming we own the selection, this function disowns it. If
+ SECONDARY-P is non-`nil', the secondary selection instead of the
+ primary selection is discarded.
+
+ The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications. Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional N
+ This function returns the contents of cut buffer number N. (This
+ function is called `x-get-cut-buffer' in FSF Emacs.)
+
+ - Function: x-store-cutbuffer STRING
+ This function stores STRING into the first cut buffer (cut buffer
+ 0), moving the other values down through the series of cut buffers,
+ kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
+ Emacs.)
+
+\1f
+File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
+
+X Server
+========
+
+ This section describes how to access and change the overall status of
+the X server XEmacs is using.
+
+* Menu:
+
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
+
+\1f
+File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
+
+Resources
+---------
+
+ - Function: default-x-device
+ This function return the default X device for resourcing. This is
+ the first-created X device that still exists.
+
+ - Function: x-get-resource NAME CLASS TYPE &optional LOCALE DEVICE
+ NOERROR
+ This function retrieves a resource value from the X resource
+ manager.
+
+ * The first arg is the name of the resource to retrieve, such as
+ `"font"'.
+
+ * The second arg is the class of the resource to retrieve, like
+ `"Font"'.
+
+ * The third arg should be one of the symbols `string',
+ `integer', `natnum', or `boolean', specifying the type of
+ object that the database is searched for.
+
+ * The fourth arg is the locale to search for the resources on,
+ and can currently be a a buffer, a frame, a device, or the
+ symbol `global'. If omitted, it defaults to `global'.
+
+ * The fifth arg is the device to search for the resources on.
+ (The resource database for a particular device is constructed
+ by combining non-device- specific resources such any
+ command-line resources specified and any app-defaults files
+ found [or the fallback resources supplied by XEmacs, if no
+ app-defaults file is found] with device-specific resources
+ such as those supplied using `xrdb'.) If omitted, it defaults
+ to the device of LOCALE, if a device can be derived (i.e. if
+ LOCALE is a frame or device), and otherwise defaults to the
+ value of `default-x-device'.
+
+ * The sixth arg NOERROR, if non-`nil', means do not signal an
+ error if a bogus resource specification was retrieved (e.g.
+ if a non-integer was given when an integer was requested).
+ In this case, a warning is issued instead.
+
+ The resource names passed to this function are looked up relative
+ to the locale.
+
+ If you want to search for a subresource, you just need to specify
+ the resource levels in NAME and CLASS. For example, NAME could be
+ `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
+
+ Specifically,
+
+ 1. If LOCALE is a buffer, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+ "String");'
+
+ 2. If LOCALE is a frame, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+ "String");'
+
+ 3. If LOCALE is a device, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+ "String");'
+
+ 4. If LOCALE is the symbol `global', a call
+
+ `(x-get-resource "foreground" "Foreground" 'string 'global)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.foreground",
+ "Emacs.Foreground",
+ "String");'
+
+ Note that for `global', no prefix is added other than that of the
+ application itself; thus, you can use this locale to retrieve
+ arbitrary application resources, if you really want to.
+
+ The returned value of this function is `nil' if the queried
+ resource is not found. If TYPE is `string', a string is returned,
+ and if it is `integer', an integer is returned. If TYPE is
+ `boolean', then the returned value is the list `(t)' for true,
+ `(nil)' for false, and is `nil' to mean "unspecified".
+
+ - Function: x-put-resource RESOURCE-LINE &optional DEVICE
+ This function adds a resource to the resource database for DEVICE.
+ RESOURCE-LINE specifies the resource to add and should be a
+ standard resource specification.
+
+ - Variable: x-emacs-application-class
+ This variable holds The X application class of the XEmacs process.
+ This controls, among other things, the name of the "app-defaults"
+ file that XEmacs will use. For changes to this variable to take
+ effect, they must be made before the connection to the X server is
+ initialized, that is, this variable may only be changed before
+ XEmacs is dumped, or by setting it in the file
+ `lisp/term/x-win.el'.
+
+ By default, this variable is nil at startup. When the connection
+ to the X server is first initialized, the X resource database will
+ be consulted and the value will be set according to whether any
+ resources are found for the application class "XEmacs".
+
+\1f
+File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
+
+Data about the X Server
+-----------------------
+
+ This section describes functions and a variable that you can use to
+get information about the capabilities and origin of the X server
+corresponding to a particular device. The device argument is generally
+optional and defaults to the selected device.
+
+ - Function: x-server-version &optional DEVICE
+ This function returns the list of version numbers of the X server
+ DEVICE is on. The returned value is a list of three integers: the
+ major and minor version numbers of the X protocol in use, and the
+ vendor-specific release number.
+
+ - Function: x-server-vendor &optional DEVICE
+ This function returns the vendor supporting the X server DEVICE is
+ on.
+
+ - Function: x-display-visual-class &optional DEVICE
+ This function returns the visual class of the display DEVICE is
+ on. The value is one of the symbols `static-gray', `gray-scale',
+ `static-color', `pseudo-color', `true-color', and `direct-color'.
+ (Note that this is different from previous versions of XEmacs,
+ which returned `StaticGray', `GrayScale', etc.)
+
+\1f
+File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
+
+Restricting Access to the Server by Other Apps
+----------------------------------------------
+
+ - Function: x-grab-keyboard &optional DEVICE
+ This function grabs the keyboard on the given device (defaulting
+ to the selected one). So long as the keyboard is grabbed, all
+ keyboard events will be delivered to XEmacs - it is not possible
+ for other X clients to eavesdrop on them. Ungrab the keyboard
+ with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
+ if the grab was successful; `nil' otherwise.
+
+ - Function: x-ungrab-keyboard &optional DEVICE
+ This function releases a keyboard grab made with `x-grab-keyboard'.
+
+ - Function: x-grab-pointer &optional DEVICE CURSOR IGNORE-KEYBOARD
+ This function grabs the pointer and restricts it to its current
+ window. If optional DEVICE argument is `nil', the selected device
+ will be used. If optional CURSOR argument is non-`nil', change
+ the pointer shape to that until `x-ungrab-pointer' is called (it
+ should be an object returned by the `make-cursor' function). If
+ the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
+ all keyboard events during the grab. Returns `t' if the grab is
+ successful, `nil' otherwise.
+
+ - Function: x-ungrab-pointer &optional DEVICE
+ This function releases a pointer grab made with `x-grab-pointer'.
+ If optional first arg DEVICE is `nil' the selected device is used.
+ If it is `t' the pointer will be released on all X devices.
+
+\1f
+File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
+
+Miscellaneous X Functions and Variables
+=======================================
+
+ - Variable: x-bitmap-file-path
+ This variable holds a list of the directories in which X bitmap
+ files may be found. If `nil', this is initialized from the
+ `"*bitmapFilePath"' resource. This is used by the
+ `make-image-instance' function (however, note that if the
+ environment variable `XBMLANGPATH' is set, it is consulted first).
+
+ - Variable: x-library-search-path
+ This variable holds the search path used by `read-color' to find
+ `rgb.txt'.
+
+ - Function: x-valid-keysym-name-p KEYSYM
+ This function returns true if KEYSYM names a keysym that the X
+ library knows about. Valid keysyms are listed in the files
+ `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
+ whatever the equivalents are on your system.
+
+ - Function: x-window-id &optional FRAME
+ This function returns the ID of the X11 window. This gives us a
+ chance to manipulate the Emacs window from within a different
+ program. Since the ID is an unsigned long, we return it as a
+ string.
+
+ - Variable: x-allow-sendevents
+ If non-`nil', synthetic events are allowed. `nil' means they are
+ ignored. Beware: allowing XEmacs to process SendEvents opens a
+ big security hole.
+
+ - Function: x-debug-mode ARG &optional DEVICE
+ With a true arg, make the connection to the X server synchronous.
+ With false, make it asynchronous. Synchronous connections are
+ much slower, but are useful for debugging. (If you get X errors,
+ make the connection synchronous, and use a debugger to set a
+ breakpoint on `x_error_handler'. Your backtrace of the C stack
+ will now be useful. In asynchronous mode, the stack above
+ `x_error_handler' isn't helpful because of buffering.) If DEVICE
+ is not specified, the selected device is assumed.
+
+ Calling this function is the same as calling the C function
+ `XSynchronize', or starting the program with the `-sync' command
+ line argument.
+
+ - Variable: x-debug-events
+ If non-zero, debug information about events that XEmacs sees is
+ displayed. Information is displayed on stderr. Currently defined
+ values are:
+
+ * 1 == non-verbose output
+
+ * 2 == verbose output
+
+\1f
+File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
+
+ToolTalk Support
+****************
+
+* Menu:
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
+
+\1f
+File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
+
+XEmacs ToolTalk API Summary
+===========================
+
+ The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
+to the standard C ToolTalk API. Only the message and pattern parts of
+the API are supported at present; more of the API could be added if
+needed. The Lisp interface departs from the C API in a few ways:
+
+ * ToolTalk is initialized automatically at XEmacs startup-time.
+ Messages can only be sent other ToolTalk applications connected to
+ the same X11 server that XEmacs is running on.
+
+ * There are fewer entry points; polymorphic functions with keyword
+ arguments are used instead.
+
+ * The callback interface is simpler and marginally less functional.
+ A single callback may be associated with a message or a pattern;
+ the callback is specified with a Lisp symbol (the symbol should
+ have a function binding).
+
+ * The session attribute for messages and patterns is always
+ initialized to the default session.
+
+ * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
+ can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
+ simplifies building lists that represent messages and patterns.
+
+\1f
+File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
+
+Sending Messages
+================
+
+* Menu:
+
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
+
+\1f
+File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
+
+Example of Sending Messages
+---------------------------
+
+ Here's a simple example that sends a query to another application
+and then displays its reply. Both the query and the reply are stored
+in the first argument of the message.
+
+ (defun tooltalk-random-query-handler (msg)
+ (let ((state (get-tooltalk-message-attribute msg 'state)))
+ (cond
+ ((eq state 'TT_HANDLED)
+ (message (get-tooltalk-message-attribute msg arg_val 0)))
+ ((memq state '(TT_FAILED TT_REJECTED))
+ (message "Random query turns up nothing")))))
+
+ (defvar random-query-message
+ '( class TT_REQUEST
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "random-query"
+ args '((TT_INOUT "?" "string"))
+ callback tooltalk-random-query-handler))
+
+ (let ((m (make-tooltalk-message random-query-message)))
+ (send-tooltalk-message m))
+
+\1f
+File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
+
+Elisp Interface for Sending Messages
+------------------------------------
+
+ - Function: make-tooltalk-message ATTRIBUTES
+ Create a ToolTalk message and initialize its attributes. The
+ value of ATTRIBUTES must be a list of alternating keyword/values,
+ where keywords are symbols that name valid message attributes.
+ For example:
+
+ (make-tooltalk-message
+ '(class TT_NOTICE
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "do-something"
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants. Attribute names are the same as those
+ supported by `set-tooltalk-message-attribute', plus `args'.
+
+ The value of `args' should be a list of message arguments where
+ each message argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk message arguments in chapter 4 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message MSG
+ Send the message on its way. Once the message has been sent it's
+ almost always a good idea to get rid of it with
+ `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message MSG &optional MODE
+ Send a reply to this message. The second argument can be `reply',
+ `reject' or `fail'; the default is `reply'. Before sending a
+ reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+ should have been filled in - see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute MSG ATTRIBUTE &optional ARGN
+ Returns the indicated ToolTalk message attribute. Attributes are
+ identified by symbols with the same name (underscores and all) as
+ the suffix of the ToolTalk `tt_message_<attribute>' function that
+ extracts the value. String attribute values are copied and
+ enumerated type values (except disposition) are converted to
+ symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+ represented by fixnums (small integers), `opnum' is converted to a
+ string, and `disposition' is converted to a fixnum. We convert
+ `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+ there's no guarantee that opnums will fit within the range of
+ XEmacs Lisp integers.
+
+ [TBD] Use the `plist' attribute instead of C API `user' attribute
+ for user-defined message data. To retrieve the value of a message
+ property, specify the indicator for ARGN. For example, to get the
+ value of a property called `rflag', use
+
+ (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+ To get the value of a message argument use one of the `arg_val'
+ (strings), `arg_ival' (integers), or `arg_bval' (strings with
+ embedded nulls), attributes. For example, to get the integer
+ value of the third argument:
+
+ (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+ As you can see, argument numbers are zero-based. The type of each
+ arguments can be retrieved with the `arg_type' attribute; however
+ ToolTalk doesn't define any semantics for the string value of
+ `arg_type'. Conventionally `string' is used for strings and `int'
+ for 32 bit integers. Note that XEmacs Lisp stores the lengths of
+ strings explicitly (unlike C) so treating the value returned by
+ `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute VALUE MSG ATTRIBUTE
+ &optional ARGN
+ Initialize one ToolTalk message attribute.
+
+ Attribute names and values are the same as for
+ `get-tooltalk-message-attribute'. A property list is provided for
+ user data (instead of the `user' message attribute); see
+ `get-tooltalk-message-attribute'.
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the state of the message
+ changes. This is usually used to notice when the message's state
+ has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+ argument values can be used.
+
+ If one of the argument attributes is specified as `arg_val',
+ `arg_ival', or `arg_bval', then ARGN must be the number of an
+ already created argument. Arguments can be added to a message
+ with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg MSG MODE TYPE &optional VALUE
+ Append one new argument to the message. MODE must be one of
+ `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+ can be a string or an integer. ToolTalk doesn't define any
+ semantics for TYPE, so only the participants in the protocol
+ you're using need to agree what types mean (if anything).
+ Conventionally `string' is used for strings and `int' for 32 bit
+ integers. Arguments can initialized by providing a value or with
+ `set-tooltalk-message-attribute'; the latter is necessary if you
+ want to initialize the argument with a string that can contain
+ embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message
+ Create a new ToolTalk message. The message's session attribute is
+ initialized to the default session. Other attributes can be
+ initialized with `set-tooltalk-message-attribute'.
+ `make-tooltalk-message' is the preferred way to create and
+ initialize a message.
+
+
+ - Function: destroy-tooltalk-message MSG
+ Apply `tt_message_destroy' to the message. It's not necessary to
+ destroy messages after they've been processed by a message or
+ pattern callback, the Lisp/ToolTalk callback machinery does this
+ for you.
+
+\1f
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
+
+Receiving Messages
+==================
+
+* Menu:
+
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
+
+\1f
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
+
+Example of Receiving Messages
+-----------------------------
+
+ Here's a simple example of a handler for a message that tells XEmacs
+to display a string in the mini-buffer area. The message operation is
+called `emacs-display-string'. Its first (0th) argument is the string
+to display.
+
+ (defun tooltalk-display-string-handler (msg)
+ (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+
+ (defvar display-string-pattern
+ '(category TT_HANDLE
+ scope TT_SESSION
+ op "emacs-display-string"
+ callback tooltalk-display-string-handler))
+
+ (let ((p (make-tooltalk-pattern display-string-pattern)))
+ (register-tooltalk-pattern p))
+
+\1f
+File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern ATTRIBUTES
+ Create a ToolTalk pattern and initialize its attributes. The
+ value of attributes must be a list of alternating keyword/values,
+ where keywords are symbols that name valid pattern attributes or
+ lists of valid attributes. For example:
+
+ (make-tooltalk-pattern
+ '(category TT_OBSERVE
+ scope TT_SESSION
+ op ("operation1" "operation2")
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Attribute names are the same as those supported by
+ `add-tooltalk-pattern-attribute', plus `'args'.
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants or lists of same. When a list of values is
+ provided all of the list elements are added to the attribute. In
+ the example above, messages whose `op' attribute is `"operation1"'
+ or `"operation2"' would match the pattern.
+
+ The value of ARGS should be a list of pattern arguments where each
+ pattern argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk pattern arguments in chapter 3 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern PAT
+ XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern PAT
+ XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute VALUE PAT INDICATOR
+ Add one value to the indicated pattern attribute. The names of
+ attributes are the same as the ToolTalk accessors used to set them
+ less the `tooltalk_pattern_' prefix and the `_add' suffix. For
+ example, the name of the attribute for the
+ `tt_pattern_disposition_add' attribute is `disposition'. The
+ `category' attribute is handled specially, since a pattern can only
+ be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the pattern matches an
+ incoming message.
+
+ - Function: add-tooltalk-pattern-arg PAT MODE TYPE VALUE
+ Add one fully-specified argument to a ToolTalk pattern. MODE must
+ be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
+ string. VALUE can be an integer, string or `nil'. If VALUE is an
+ integer then an integer argument (`tt_pattern_iarg_add') is added;
+ otherwise a string argument is added. At present there's no way
+ to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+ Create a new ToolTalk pattern and initialize its session attribute
+ to be the default session.
+
+ - Function: destroy-tooltalk-pattern PAT
+ Apply `tt_pattern_destroy' to the pattern. This effectively
+ unregisters the pattern.
+
+ - Function: describe-tooltalk-message MSG &optional STREAM
+ Print the message's attributes and arguments to STREAM. This is
+ often useful for debugging.
+
+\1f
+File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top
+
+LDAP Support
+************
+
+ XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
+
+* Menu:
+
+* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
+* XEmacs LDAP API:: Lisp access to LDAP functions
+* Syntax of Search Filters:: A brief summary of RFC 1558
+
+\1f
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
+
+Building XEmacs with LDAP support
+=================================
+
+ LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library. As of 21.2, XEmacs has been
+successfully built and tested with
+
+ * OpenLDAP 1.0.3 (`http://www.openldap.org/')
+
+ * University of Michigan's LDAP 3.3
+ (`http://www.umich.edu/~dirsvcs/ldap/')
+
+ * LDAP SDK 1.0 from Netscape Corp. (`http://developer.netscape.com/')
+
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
+
+ The standard XEmacs configure script autodetects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths. A successful detection
+will be signalled in the final output of the configure script.
+
+\1f
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
+
+XEmacs LDAP API
+===============
+
+ XEmacs LDAP API consists of two layers: a low-level layer which
+tries to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
+
+ As of XEmacs 21.0, only interfaces to basic LDAP search functions are
+provided, broader support is planned in future versions.
+
+* Menu:
+
+* LDAP Variables:: Lisp variables related to LDAP
+* The High-Level LDAP API:: High-level LDAP lisp functions
+* The Low-Level LDAP API:: Low-level LDAP lisp primitives
+
+\1f
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
+
+LDAP Variables
+--------------
+
+ - Variable: ldap-default-host
+ The default LDAP server hostname. A TCP port number can be
+ appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+ Default TCP port for LDAP connections. Initialized from the LDAP
+ library. Default value is 389.
+
+ - Variable: ldap-default-base
+ Default base for LDAP searches. This is a string using the syntax
+ of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
+ Acme organization in the United States.
+
+ - Variable: ldap-host-parameters-alist
+ An alist of per host options for LDAP transactions. The list
+ elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+ name of an LDAP server. A TCP port number can be appended to that
+ name using a colon as a separator. PROPN and VALN are
+ property/value pairs describing parameters for the server. Valid
+ properties:
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `base'
+ The base for the search. This may look like `cÿ, o¬me', see
+ RFC 1779 for syntax details.
+
+ `scope'
+ One of the symbols `base', `onelevel' or `subtree' indicating
+ the scope of the search limited to a base object, to a single
+ level or to the whole subtree.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
+
+\1f
+File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
+
+The High-Level LDAP API
+-----------------------
+
+ As of this writing the high-level Lisp LDAP API only provides for
+LDAP searches. Further support is planned in the future.
+
+ The `ldap-search' function provides the most convenient interface to
+perform LDAP searches. It opens a connection to a host, performs the
+query and cleanly closes the connection thus insulating the user from
+all the details of the low-level interface such as LDAP Lisp objects
+*note The Low-Level LDAP API::.
+
+ - Function: ldap-search FILTER &optional HOST ATTRIBUTES ATTRSONLY
+ Perform an LDAP search. FILTER is the search filter *note Syntax
+ of Search Filters::. HOST is the LDAP host on which to perform
+ the search ATTRIBUTES is the specific attributes to retrieve,
+ `nil' means retrieve all ATTRSONLY if non-`nil' retrieves the
+ attributes only without their associated values. Additional
+ search parameters can be specified through
+ `ldap-host-parameters-alist'.
+
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
+
+The Low-Level LDAP API
+----------------------
+
+* Menu:
+
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Searching on a LDAP Server (Low-level)::
+
+\1f
+File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
+
+The LDAP Lisp Object
+....................
+
+ An internal built-in `ldap' lisp object represents a LDAP connection.
+
+ - Function: ldapp OBJECT
+ This function returns non-`nil' if OBJECT is a `ldap' object.
+
+ - Function: ldap-host LDAP
+ Return the server host of the connection represented by LDAP
+
+ - Function: ldap-live-p LDAP
+ Return non-`nil' if LDAP is an active LDAP connection
+
+\1f
+File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
+
+Opening and Closing a LDAP Connection
+.....................................
+
+ - Function: ldap-open HOST &optional PLIST
+ Open a LDAP connection to HOST. PLIST is a property list
+ containing additional parameters for the connection. Valid keys
+ in that list are:
+ `port'
+ The TCP port to use for the connection if different from
+ `ldap-default-port' or the library builtin value
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search The default is `never'.
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
+
+ - Function: ldap-close LDAP
+ Close the connection represented by LDAP
+
+\1f
+File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
+
+Searching on a LDAP Server (Low-level)
+......................................
+
+ `ldap-search-internal' is the low-level primitive to perform a
+search on a LDAP server. It works directly on an open LDAP connection
+thus requiring a preliminary call to `ldap-open'. Multiple searches
+can be made on the same connection, then the session must be closed
+with `ldap-close'.
+
+ - Function: ldap-search-internal LDAP FILTER BASE SCOPE ATTRS ATTRSONLY
+ Perform a search on an open connection LDAP created with
+ `ldap-open'. FILTER is a filter string for the search *note
+ Syntax of Search Filters::. BASE is the distinguished name at
+ which to start the search. SCOPE is one of the symbols `base',
+ `onelevel' or `subtree' indicating the scope of the search limited
+ to a base object, to a single level or to the whole subtree. The
+ default is `subtree'. `attrs' is a list of strings indicating
+ which attributes to retrieve for each matching entry. If `nil' all
+ available attributes are returned. If `attrsonly' is non-`nil'
+ then only the attributes are retrieved, not their associated values
+ The function returns a list of matching entries. Each entry being
+ itself an alist of attribute/values.
+
+\1f
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
+
+Syntax of Search Filters
+========================
+
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
+
+ (<attr> <filtertype> <value>)
+
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
+
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
+
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
+
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
+
+ A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute. For instance `(mail=*)'
+matches all records containing a `mail' attribute.
+
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
+
+ `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
+matches records of class `Person' containing a `mail' attribute and
+corresponding to people whose last name is `Smith' or whose first name
+is `John'.
+
+\1f
+File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top
+
+Internationalization
+********************
+
+* Menu:
+
+* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
+* I18N Level 3:: Support for localized messages.
+* I18N Level 4:: Support for Asian languages.
+
+\1f
+File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+
+I18N Levels 1 and 2
+===================
+
+ XEmacs is now compliant with I18N levels 1 and 2. Specifically,
+this means that it is 8-bit clean and correctly handles time and date
+functions. XEmacs will correctly display the entire ISO-Latin 1
+character set.
+
+ The compose key may now be used to create any character in the
+ISO-Latin 1 character set not directly available via the keyboard.. In
+order for the compose key to work it is necessary to load the file
+`x-compose.el'. At any time while composing a character, `C-h' will
+display all valid completions and the character which would be produced.
+
+\1f
+File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+
+I18N Level 3
+============
+
+* Menu:
+
+* Level 3 Basics::
+* Level 3 Primitives::
+* Dynamic Messaging::
+* Domain Specification::
+* Documentation String Extraction::
+
+\1f
+File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
+
+Level 3 Basics
+--------------
+
+ XEmacs now provides alpha-level functionality for I18N Level 3.
+This means that everything necessary for full messaging is available,
+but not every file has been converted.
+
+ The two message files which have been created are `src/emacs.po' and
+`lisp/packages/mh-e.po'. Both files need to be converted using
+`msgfmt', and the resulting `.mo' files placed in some locale's
+`LC_MESSAGES' directory. The test "translations" in these files are
+the original messages prefixed by `TRNSLT_'.
+
+ The domain for a variable is stored on the variable's property list
+under the property name VARIABLE-DOMAIN. The function
+`documentation-property' uses this information when translating a
+variable's documentation.
+
projects / chise / xemacs-chise.git / blobdiff