X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-41;h=c4ba9ddfda7feda01e26de8014fa7f5eea6b3b8d;hb=dbfc38b11cb852dc18107ed3822f6efb13630a8b;hp=971cd0806ad32bd43ec7aa3330d8d44cbe7d5286;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-41 b/info/lispref.info-41 index 971cd08..c4ba9dd 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1175 +50,1122 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3 +File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input + +Input Modes +----------- + + - Function: set-input-mode interrupt flow meta quit-char + This function sets the mode for reading keyboard input. If + INTERRUPT is non-null, then XEmacs uses input interrupts. If it is + `nil', then it uses CBREAK mode. When XEmacs communicates + directly with X, it ignores this argument and uses interrupts if + that is the way it knows how to communicate. + + If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s') + flow control for output to the terminal. This has no effect except + in CBREAK mode. *Note Flow Control::. + + The default setting is system dependent. Some systems always use + CBREAK mode regardless of what is specified. + + The argument META controls support for input character codes above + 127. If META is `t', XEmacs converts characters with the 8th bit + set into Meta characters. If META is `nil', XEmacs disregards the + 8th bit; this is necessary when the terminal uses it as a parity + bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of + input unchanged. This is good for terminals using European 8-bit + character sets. + + If QUIT-CHAR is non-`nil', it specifies the character to use for + quitting. Normally this character is `C-g'. *Note Quitting::. + + The `current-input-mode' function returns the input mode settings +XEmacs is currently using. + + - Function: current-input-mode + This function returns current mode for reading keyboard input. It + returns a list, corresponding to the arguments of `set-input-mode', + of the form `(INTERRUPT FLOW META QUIT)' in which: + INTERRUPT + is non-`nil' when XEmacs is using interrupt-driven input. If + `nil', Emacs is using CBREAK mode. + + FLOW + is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow + control for output to the terminal. This value has no effect + unless INTERRUPT is non-`nil'. + + META + is `t' if XEmacs treats the eighth bit of input characters as + the meta bit; `nil' means XEmacs clears the eighth bit of + every input character; any other value means XEmacs uses all + eight bits as the basic character code. + + QUIT + is the character XEmacs currently uses for quitting, usually + `C-g'. -Level 3 Primitives ------------------- - - - Function: gettext string - This function looks up STRING in the default message domain and - returns its translation. If `I18N3' was not enabled when XEmacs - was compiled, it just returns STRING. - - - Function: dgettext domain string - This function looks up STRING in the specified message domain and - returns its translation. If `I18N3' was not enabled when XEmacs - was compiled, it just returns STRING. - - - Function: bind-text-domain domain pathname - This function associates a pathname with a message domain. Here's - how the path to message file is constructed under SunOS 5.x: - - `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo' - - If `I18N3' was not enabled when XEmacs was compiled, this function - does nothing. - - - Special Form: domain string - This function specifies the text domain used for translating - documentation strings and interactive prompts of a function. For - example, write: + +File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input - (defun foo (arg) "Doc string" (domain "emacs-foo") ...) +Translating Input Events +------------------------ - to specify `emacs-foo' as the text domain of the function `foo'. - The "call" to `domain' is actually a declaration rather than a - function; when actually called, `domain' just returns `nil'. + This section describes features for translating input events into +other input events before they become part of key sequences. + + - Variable: function-key-map + This variable holds a keymap that describes the character sequences + sent by function keys on an ordinary character terminal. This + keymap uses the same data structure as other keymaps, but is used + differently: it specifies translations to make while reading + events. + + If `function-key-map' "binds" a key sequence K to a vector V, then + when K appears as a subsequence _anywhere_ in a key sequence, it + is replaced with the events in V. + + For example, VT100 terminals send ` O P' when the keypad PF1 + key is pressed. Therefore, we want XEmacs to translate that + sequence of events into the single event `pf1'. We accomplish + this by "binding" ` O P' to `[pf1]' in `function-key-map', + when using a VT100. + + Thus, typing `C-c ' sends the character sequence `C-c O + P'; later the function `read-key-sequence' translates this back + into `C-c ', which it returns as the vector `[?\C-c pf1]'. + + Entries in `function-key-map' are ignored if they conflict with + bindings made in the minor mode, local, or global keymaps. The + intent is that the character sequences that function keys send + should not have command bindings in their own right. + + The value of `function-key-map' is usually set up automatically + according to the terminal's Terminfo or Termcap entry, but + sometimes those need help from terminal-specific Lisp files. + XEmacs comes with terminal-specific files for many common + terminals; their main purpose is to make entries in + `function-key-map' beyond those that can be deduced from Termcap + and Terminfo. *Note Terminal-Specific::. + + Emacs versions 18 and earlier used totally different means of + detecting the character sequences that represent function keys. + + - Variable: key-translation-map + This variable is another keymap used just like `function-key-map' + to translate input events into other events. It differs from + `function-key-map' in two ways: + + * `key-translation-map' goes to work after `function-key-map' is + finished; it receives the results of translation by + `function-key-map'. + + * `key-translation-map' overrides actual key bindings. + + The intent of `key-translation-map' is for users to map one + character set to another, including ordinary characters normally + bound to `self-insert-command'. + + You can use `function-key-map' or `key-translation-map' for more +than simple aliases, by using a function, instead of a key sequence, as +the "translation" of a key. Then this function is called to compute +the translation of that key. + + The key translation function receives one argument, which is the +prompt that was specified in `read-key-sequence'--or `nil' if the key +sequence is being read by the editor command loop. In most cases you +can ignore the prompt value. + + If the function reads input itself, it can have the effect of +altering the event that follows. For example, here's how to define +`C-c h' to turn the character that follows into a Hyper character: + + (defun hyperify (prompt) + (let ((e (read-event))) + (vector (if (numberp e) + (logior (lsh 1 20) e) + (if (memq 'hyper (event-modifiers e)) + e + (add-event-modifier "H-" e)))))) + + (defun add-event-modifier (string e) + (let ((symbol (if (symbolp e) e (car e)))) + (setq symbol (intern (concat string + (symbol-name symbol)))) + (if (symbolp e) + symbol + (cons symbol (cdr e))))) + + (define-key function-key-map "\C-ch" 'hyperify) - - Function: domain-of function - This function returns the text domain of FUNCTION; it returns - `nil' if it is the default domain. If `I18N3' was not enabled - when XEmacs was compiled, it always returns `nil'. + The `iso-transl' library uses this feature to provide a way of +inputting non-ASCII Latin-1 characters.  -File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3 - -Dynamic Messaging ------------------ +File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input - The `format' function has been extended to permit you to change the -order of parameter insertion. For example, the conversion format -`%1$s' inserts parameter one as a string, while `%2$s' inserts -parameter two. This is useful when creating translations which require -you to change the word order. +Recording Input +--------------- - -File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3 - -Domain Specification --------------------- + - Function: recent-keys &optional number + This function returns a vector containing recent input events from + the keyboard or mouse. By default, 100 events are recorded, which + is how many `recent-keys' returns. - The default message domain of XEmacs is `emacs'. For add-on -packages, it is best to use a different domain. For example, let us -say we want to convert the "gorilla" package to use the domain -`emacs-gorilla'. To translate the message "What gorilla?", use -`dgettext' as follows: + All input events are included, whether or 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 that invoked the macros.) - (dgettext "emacs-gorilla" "What gorilla?") + If NUMBER is specified, not more than NUMBER events will be + returned. You may change the number of stored events using + `set-recent-keys-ring-size'. - A function (or macro) which has a documentation string or an -interactive prompt needs to be associated with the domain in order for -the documentation or prompt to be translated. This is done with the -`domain' special form as follows: + - Function: recent-keys-ring-size + This function returns the number of recent events stored + internally. This is also the maximum number of events + `recent-keys' can return. By default, 100 events are stored. - (defun scratch (location) - "Scratch the specified location." - (domain "emacs-gorilla") - (interactive "sScratch: ") - ... ) + - Function: set-recent-keys-ring-size size + This function changes the number of events stored by XEmacs and + returned by `recent-keys'. - It is most efficient to specify the domain in the first line of the -function body, before the `interactive' form. + For example, `(set-recent-keys-ring-size 250)' will make XEmacs + remember last 250 events and will make `recent-keys' return last + 250 events by default. - For variables and constants which have documentation strings, -specify the domain after the documentation. + - Command: open-dribble-file filename + This function opens a "dribble file" named FILENAME. When a + dribble file is open, each input event from the keyboard or mouse + (but not those from keyboard macros) is written in that file. A + non-character event is expressed using its printed representation + surrounded by `<...>'. - - Special Form: defvar symbol [value [doc-string [domain]]] - Example: - (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") + You close the dribble file by calling this function with an + argument of `nil'. - - Special Form: defconst symbol [value [doc-string [domain]]] - Example: - (defconst limbs 4 "Number of limbs" "emacs-gorilla") + This function is normally used to record the input necessary to + trigger an XEmacs bug, for the sake of a bug report. - Autoloaded functions which are specified in `loaddefs.el' do not need -to have a domain specification, because their documentation strings are -extracted into the main message base. However, for autoloaded functions -which are specified in a separate package, use following syntax: + (open-dribble-file "~/dribble") + => nil - - Function: autoload symbol filename &optional docstring interactive - macro domain - Example: - (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") + See also the `open-termscript' function (*note Terminal Output::).  -File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3 - -Documentation String Extraction -------------------------------- +File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface - The utility `etc/make-po' scans the file `DOC' to extract -documentation strings and creates a message file `doc.po'. This file -may then be inserted within `emacs.po'. - - Currently, `make-po' is hard-coded to read from `DOC' and write to -`doc.po'. In order to extract documentation strings from an add-on -package, first run `make-docfile' on the package to produce the `DOC' -file. Then run `make-po -p' with the `-p' argument to indicate that we -are extracting documentation for an add-on package. +Terminal Output +=============== - (The `-p' argument is a kludge to make up for a subtle difference -between pre-loaded documentation and add-on documentation: For add-on -packages, the final carriage returns in the strings produced by -`make-docfile' must be ignored.) + 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  -File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization +File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface -I18N Level 4 +Flow Control ============ - The Asian-language support in XEmacs is called "MULE". *Note MULE::. + 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::.  -File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top - -MULE -**** - - "MULE" is the name originally given to the version of GNU Emacs -extended for multi-lingual (and in particular Asian-language) support. -"MULE" is short for "MUlti-Lingual Emacs". It was originally called -Nemacs ("Nihon Emacs" where "Nihon" is the Japanese word for "Japan"), -when it only provided support for Japanese. XEmacs refers to its -multi-lingual support as "MULE support" since it is based on "MULE". - -* Menu: - -* Internationalization Terminology:: - Definition of various internationalization terms. -* Charsets:: Sets of related characters. -* MULE Characters:: Working with characters in XEmacs/MULE. -* Composite Characters:: Making new characters by overstriking other ones. -* ISO 2022:: An international standard for charsets and encodings. -* Coding Systems:: Ways of representing a string of chars using integers. -* CCL:: A special language for writing fast converters. -* Category Tables:: Subdividing charsets into groups. +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.  -File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE - -Internationalization Terminology -================================ - - In internationalization terminology, a string of text is divided up -into "characters", which are the printable units that make up the text. -A single character is (for example) a capital `A', the number `2', a -Katakana character, a Kanji ideograph (an "ideograph" is a "picture" -character, such as is used in Japanese Kanji, Chinese Hanzi, and Korean -Hangul; typically there are thousands of such ideographs in each -language), etc. The basic property of a character is its shape. Note -that the same character may be drawn by two different people (or in two -different fonts) in slightly different ways, although the basic shape -will be the same. - - In some cases, the differences will be significant enough that it is -actually possible to identify two or more distinct shapes that both -represent the same character. For example, the lowercase letters `a' -and `g' each have two distinct possible shapes - the `a' can optionally -have a curved tail projecting off the top, and the `g' can be formed -either of two loops, or of one loop and a tail hanging off the bottom. -Such distinct possible shapes of a character are called "glyphs". The -important characteristic of two glyphs making up the same character is -that the choice between one or the other is purely stylistic and has no -linguistic effect on a word (this is the reason why a capital `A' and -lowercase `a' are different characters rather than different glyphs - -e.g. `Aspen' is a city while `aspen' is a kind of tree). - - Note that "character" and "glyph" are used differently here than -elsewhere in XEmacs. - - A "character set" is simply a set of related characters. ASCII, for -example, is a set of 94 characters (or 128, if you count non-printing -characters). Other character sets are ISO8859-1 (ASCII plus various -accented characters and other international symbols), JISX0201 (ASCII, -more or less, plus half-width Katakana), JISX0208 (Japanese Kanji), -JISX0212 (a second set of less-used Japanese Kanji), GB2312 (Mainland -Chinese Hanzi), etc. - - Every character set has one or more "orderings", which can be viewed -as a way of assigning a number (or set of numbers) to each character in -the set. For most character sets, there is a standard ordering, and in -fact all of the character sets mentioned above define a particular -ordering. ASCII, for example, places letters in their "natural" order, -puts uppercase letters before lowercase letters, numbers before -letters, etc. Note that for many of the Asian character sets, there is -no natural ordering of the characters. The actual orderings are based -on one or more salient characteristic, of which there are many to -choose from - e.g. number of strokes, common radicals, phonetic -ordering, etc. - - The set of numbers assigned to any particular character are called -the character's "position codes". The number of position codes -required to index a particular character in a character set is called -the "dimension" of the character set. ASCII, being a relatively small -character set, is of dimension one, and each character in the set is -indexed using a single position code, in the range 0 through 127 (if -non-printing characters are included) or 33 through 126 (if only the -printing characters are considered). JISX0208, i.e. Japanese Kanji, -has thousands of characters, and is of dimension two - every character -is indexed by two position codes, each in the range 33 through 126. -(Note that the choice of the range here is somewhat arbitrary. -Although a character set such as JISX0208 defines an _ordering_ of all -its characters, it does not define the actual mapping between numbers -and characters. You could just as easily index the characters in -JISX0208 using numbers in the range 0 through 93, 1 through 94, 2 -through 95, etc. The reason for the actual range chosen is so that the -position codes match up with the actual values used in the common -encodings.) - - An "encoding" is a way of numerically representing characters from -one or more character sets into a stream of like-sized numerical values -called "words"; typically these are 8-bit, 16-bit, or 32-bit -quantities. If an encoding encompasses only one character set, then the -position codes for the characters in that character set could be used -directly. (This is the case with ASCII, and as a result, most people do -not understand the difference between a character set and an encoding.) -This is not possible, however, if more than one character set is to be -used in the encoding. For example, printed Japanese text typically -requires characters from multiple character sets - ASCII, JISX0208, and -JISX0212, to be specific. Each of these is indexed using one or more -position codes in the range 33 through 126, so the position codes could -not be used directly or there would be no way to tell which character -was meant. Different Japanese encodings handle this differently - JIS -uses special escape characters to denote different character sets; EUC -sets the high bit of the position codes for JISX0208 and JISX0212, and -puts a special extra byte before each JISX0212 character; etc. (JIS, -EUC, and most of the other encodings you will encounter are 7-bit or -8-bit encodings. There is one common 16-bit encoding, which is Unicode; -this strives to represent all the world's characters in a single large -character set. 32-bit encodings are generally used internally in -programs to simplify the code that manipulates them; however, they are -not much used externally because they are not very space-efficient.) - - Encodings are classified as either "modal" or "non-modal". In a -"modal encoding", there are multiple states that the encoding can be in, -and the interpretation of the values in the stream depends on the -current global state of the encoding. Special values in the encoding, -called "escape sequences", are used to change the global state. JIS, -for example, is a modal encoding. The bytes `ESC $ B' indicate that, -from then on, bytes are to be interpreted as position codes for -JISX0208, rather than as ASCII. This effect is cancelled using the -bytes `ESC ( B', which mean "switch from whatever the current state is -to ASCII". To switch to JISX0212, the escape sequence `ESC $ ( D'. -(Note that here, as is common, the escape sequences do in fact begin -with `ESC'. This is not necessarily the case, however.) - - A "non-modal encoding" has no global state that extends past the -character currently being interpreted. EUC, for example, is a -non-modal encoding. Characters in JISX0208 are encoded by setting the -high bit of the position codes, and characters in JISX0212 are encoded -by doing the same but also prefixing the character with the byte 0x8F. - - The advantage of a modal encoding is that it is generally more -space-efficient, and is easily extendable because there are essentially -an arbitrary number of escape sequences that can be created. The -disadvantage, however, is that it is much more difficult to work with -if it is not being processed in a sequential manner. In the non-modal -EUC encoding, for example, the byte 0x41 always refers to the letter -`A'; whereas in JIS, it could either be the letter `A', or one of the -two position codes in a JISX0208 character, or one of the two position -codes in a JISX0212 character. Determining exactly which one is meant -could be difficult and time-consuming if the previous bytes in the -string have not already been processed. - - Non-modal encodings are further divided into "fixed-width" and -"variable-width" formats. A fixed-width encoding always uses the same -number of words per character, whereas a variable-width encoding does -not. EUC is a good example of a variable-width encoding: one to three -bytes are used per character, depending on the character set. 16-bit -and 32-bit encodings are nearly always fixed-width, and this is in fact -one of the main reasons for using an encoding with a larger word size. -The advantages of fixed-width encodings should be obvious. The -advantages of variable-width encodings are that they are generally more -space-efficient and allow for compatibility with existing 8-bit -encodings such as ASCII. - - Note that the bytes in an 8-bit encoding are often referred to as -"octets" rather than simply as bytes. This terminology dates back to -the days before 8-bit bytes were universal, when some computers had -9-bit bytes, others had 10-bit bytes, etc. +File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top - -File: lispref.info, Node: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE +Functions Specific to the X Window System +***************************************** -Charsets -======== - - A "charset" in MULE is an object that encapsulates a particular -character set as well as an ordering of those characters. Charsets are -permanent objects and are named using symbols, like faces. - - - Function: charsetp object - This function returns non-`nil' if OBJECT is a charset. + 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: -* Charset Properties:: Properties of a charset. -* Basic Charset Functions:: Functions for working with charsets. -* Charset Property Functions:: Functions for accessing charset properties. -* Predefined Charsets:: Predefined charset objects. +* 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.  -File: lispref.info, Node: Charset Properties, Next: Basic Charset Functions, Up: Charsets - -Charset Properties ------------------- - - Charsets have the following properties: - -`name' - A symbol naming the charset. Every charset must have a different - name; this allows a charset to be referred to using its name - rather than the actual charset object. - -`doc-string' - A documentation string describing the charset. - -`registry' - A regular expression matching the font registry field for this - character set. For example, both the `ascii' and `latin-iso8859-1' - charsets use the registry `"ISO8859-1"'. This field is used to - choose an appropriate font when the user gives a general font - specification such as `-*-courier-medium-r-*-140-*', i.e. a - 14-point upright medium-weight Courier font. - -`dimension' - Number of position codes used to index a character in the - character set. XEmacs/MULE can only handle character sets of - dimension 1 or 2. This property defaults to 1. - -`chars' - Number of characters in each dimension. In XEmacs/MULE, the only - allowed values are 94 or 96. (There are a couple of pre-defined - character sets, such as ASCII, that do not follow this, but you - cannot define new ones like this.) Defaults to 94. Note that if - the dimension is 2, the character set thus described is 94x94 or - 96x96. - -`columns' - Number of columns used to display a character in this charset. - Only used in TTY mode. (Under X, the actual width of a character - can be derived from the font used to display the characters.) If - unspecified, defaults to the dimension. (This is almost always the - correct value, because character sets with dimension 2 are usually - ideograph character sets, which need two columns to display the - intricate ideographs.) - -`direction' - A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left). - Defaults to `l2r'. This specifies the direction that the text - should be displayed in, and will be left-to-right for most - charsets but right-to-left for Hebrew and Arabic. (Right-to-left - display is not currently implemented.) - -`final' - Final byte of the standard ISO 2022 escape sequence designating - this charset. Must be supplied. Each combination of (DIMENSION, - CHARS) defines a separate namespace for final bytes, and each - charset within a particular namespace must have a different final - byte. Note that ISO 2022 restricts the final byte to the range - 0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2. - Note also that final bytes in the range 0x30 - 0x3F are reserved - for user-defined (not official) character sets. For more - information on ISO 2022, see *Note Coding Systems::. - -`graphic' - 0 (use left half of font on output) or 1 (use right half of font on - output). Defaults to 0. This specifies how to convert the - position codes that index a character in a character set into an - index into the font used to display the character set. With - `graphic' set to 0, position codes 33 through 126 map to font - indices 33 through 126; with it set to 1, position codes 33 - through 126 map to font indices 161 through 254 (i.e. the same - number but with the high bit set). For example, for a font whose - registry is ISO8859-1, the left half of the font (octets 0x20 - - 0x7F) is the `ascii' charset, while the right half (octets 0xA0 - - 0xFF) is the `latin-iso8859-1' charset. - -`ccl-program' - A compiled CCL program used to convert a character in this charset - into an index into the font. This is in addition to the `graphic' - property. If a CCL program is defined, the position codes of a - character will first be processed according to `graphic' and then - passed through the CCL program, with the resulting values used to - index the font. - - This is used, for example, in the Big5 character set (used in - Taiwan). This character set is not ISO-2022-compliant, and its - size (94x157) does not fit within the maximum 96x96 size of - ISO-2022-compliant character sets. As a result, XEmacs/MULE - splits it (in a rather complex fashion, so as to group the most - commonly used characters together) into two charset objects - (`big5-1' and `big5-2'), each of size 94x94, and each charset - object uses a CCL program to convert the modified position codes - back into standard Big5 indices to retrieve a character from a - Big5 font. - - Most of the above properties can only be changed when the charset is -created. *Note Charset Property Functions::. +File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows - -File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Functions, Prev: Charset Properties, Up: Charsets - -Basic Charset Functions ------------------------ +X Selections +============ - - Function: find-charset charset-or-name - This function retrieves the charset of the given name. If - CHARSET-OR-NAME is a charset object, it is simply returned. - Otherwise, CHARSET-OR-NAME should be a symbol. If there is no - such charset, `nil' is returned. Otherwise the associated charset - object is returned. - - - Function: get-charset name - This function retrieves the charset of the given name. Same as - `find-charset' except an error is signalled if there is no such - charset instead of returning `nil'. - - - Function: charset-list - This function returns a list of the names of all defined charsets. - - - Function: make-charset name doc-string props - This function defines a new character set. This function is for - use with Mule support. NAME is a symbol, the name by which the - character set is normally referred. DOC-STRING is a string - describing the character set. PROPS is a property list, - describing the specific nature of the character set. The - recognized properties are `registry', `dimension', `columns', - `chars', `final', `graphic', `direction', and `ccl-program', as - previously described. - - - Function: make-reverse-direction-charset charset new-name - This function makes a charset equivalent to CHARSET but which goes - in the opposite direction. NEW-NAME is the name of the new - charset. The new charset is returned. - - - Function: charset-from-attributes dimension chars final &optional - direction - This function returns a charset with the given DIMENSION, CHARS, - FINAL, and DIRECTION. If DIRECTION is omitted, both directions - will be checked (left-to-right will be returned if character sets - exist for both directions). - - - Function: charset-reverse-direction-charset charset - This function returns the charset (if any) with the same dimension, - number of characters, and final byte as CHARSET, but which is - displayed in the opposite direction. + 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.)  -File: lispref.info, Node: Charset Property Functions, Next: Predefined Charsets, Prev: Basic Charset Functions, Up: Charsets - -Charset Property Functions --------------------------- - - All of these functions accept either a charset name or charset -object. - - - Function: charset-property charset prop - This function returns property PROP of CHARSET. *Note Charset - Properties::. - - Convenience functions are also provided for retrieving individual -properties of a charset. +File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows - - Function: charset-name charset - This function returns the name of CHARSET. This will be a symbol. - - - Function: charset-doc-string charset - This function returns the doc string of CHARSET. - - - Function: charset-registry charset - This function returns the registry of CHARSET. - - - Function: charset-dimension charset - This function returns the dimension of CHARSET. - - - Function: charset-chars charset - This function returns the number of characters per dimension of - CHARSET. - - - Function: charset-columns charset - This function returns the number of display columns per character - (in TTY mode) of CHARSET. - - - Function: charset-direction charset - This function returns the display direction of CHARSET - either - `l2r' or `r2l'. - - - Function: charset-final charset - This function returns the final byte of the ISO 2022 escape - sequence designating CHARSET. - - - Function: charset-graphic charset - This function returns either 0 or 1, depending on whether the - position codes of characters in CHARSET map to the left or right - half of their font, respectively. +X Server +======== - - Function: charset-ccl-program charset - This function returns the CCL program, if any, for converting - position codes of characters in CHARSET into font indices. + This section describes how to access and change the overall status of +the X server XEmacs is using. - The only property of a charset that can currently be set after the -charset has been created is the CCL program. +* Menu: - - Function: set-charset-ccl-program charset ccl-program - This function sets the `ccl-program' property of CHARSET to - CCL-PROGRAM. +* Resources:: Getting resource values from the server. +* Server Data:: Getting info about the X server. +* Grabs:: Restricting access to the server by other apps.  -File: lispref.info, Node: Predefined Charsets, Prev: Charset Property Functions, Up: Charsets - -Predefined Charsets -------------------- - - The following charsets are predefined in the C code. - - Name Type Fi Gr Dir Registry - -------------------------------------------------------------- - ascii 94 B 0 l2r ISO8859-1 - control-1 94 0 l2r --- - latin-iso8859-1 94 A 1 l2r ISO8859-1 - latin-iso8859-2 96 B 1 l2r ISO8859-2 - latin-iso8859-3 96 C 1 l2r ISO8859-3 - latin-iso8859-4 96 D 1 l2r ISO8859-4 - cyrillic-iso8859-5 96 L 1 l2r ISO8859-5 - arabic-iso8859-6 96 G 1 r2l ISO8859-6 - greek-iso8859-7 96 F 1 l2r ISO8859-7 - hebrew-iso8859-8 96 H 1 r2l ISO8859-8 - latin-iso8859-9 96 M 1 l2r ISO8859-9 - thai-tis620 96 T 1 l2r TIS620 - katakana-jisx0201 94 I 1 l2r JISX0201.1976 - latin-jisx0201 94 J 0 l2r JISX0201.1976 - japanese-jisx0208-1978 94x94 @ 0 l2r JISX0208.1978 - japanese-jisx0208 94x94 B 0 l2r JISX0208.19(83|90) - japanese-jisx0212 94x94 D 0 l2r JISX0212 - chinese-gb2312 94x94 A 0 l2r GB2312 - chinese-cns11643-1 94x94 G 0 l2r CNS11643.1 - chinese-cns11643-2 94x94 H 0 l2r CNS11643.2 - chinese-big5-1 94x94 0 0 l2r Big5 - chinese-big5-2 94x94 1 0 l2r Big5 - korean-ksc5601 94x94 C 0 l2r KSC5601 - composite 96x96 0 l2r --- - - The following charsets are predefined in the Lisp code. - - Name Type Fi Gr Dir Registry - -------------------------------------------------------------- - arabic-digit 94 2 0 l2r MuleArabic-0 - arabic-1-column 94 3 0 r2l MuleArabic-1 - arabic-2-column 94 4 0 r2l MuleArabic-2 - sisheng 94 0 0 l2r sisheng_cwnn\|OMRON_UDC_ZH - chinese-cns11643-3 94x94 I 0 l2r CNS11643.1 - chinese-cns11643-4 94x94 J 0 l2r CNS11643.1 - chinese-cns11643-5 94x94 K 0 l2r CNS11643.1 - chinese-cns11643-6 94x94 L 0 l2r CNS11643.1 - chinese-cns11643-7 94x94 M 0 l2r CNS11643.1 - ethiopic 94x94 2 0 l2r Ethio - ascii-r2l 94 B 0 r2l ISO8859-1 - ipa 96 0 1 l2r MuleIPA - vietnamese-lower 96 1 1 l2r VISCII1.1 - vietnamese-upper 96 2 1 l2r VISCII1.1 - - For all of the above charsets, the dimension and number of columns -are the same. - - Note that ASCII, Control-1, and Composite are handled specially. -This is why some of the fields are blank; and some of the filled-in -fields (e.g. the type) are not really accurate. +File: lispref.info, Node: Resources, Next: Server Data, Up: X Server - -File: lispref.info, Node: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE +Resources +--------- -MULE Characters -=============== + - Function: default-x-device + This function return the default X device for resourcing. This is + the first-created X device that still exists. - - Function: make-char charset arg1 &optional arg2 - This function makes a multi-byte character from CHARSET and octets - ARG1 and ARG2. + - Function: x-get-resource name class type &optional locale device + noerror + This function retrieves a resource value from the X resource + manager. - - Function: char-charset ch - This function returns the character set of char CH. + * The first arg is the name of the resource to retrieve, such as + `"font"'. - - Function: char-octet ch &optional n - This function returns the octet (i.e. position code) numbered N - (should be 0 or 1) of char CH. N defaults to 0 if omitted. + * The second arg is the class of the resource to retrieve, like + `"Font"'. - - Function: find-charset-region start end &optional buffer - This function returns a list of the charsets in the region between - START and END. BUFFER defaults to the current buffer if omitted. + * 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. - - Function: find-charset-string string - This function returns a list of the charsets in STRING. + * 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'. - -File: lispref.info, Node: Composite Characters, Next: ISO 2022, Prev: MULE Characters, Up: MULE + * 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'. -Composite Characters -==================== + * 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. - Composite characters are not yet completely implemented. + The resource names passed to this function are looked up relative + to the locale. - - Function: make-composite-char string - This function converts a string into a single composite character. - The character is the result of overstriking all the characters in - the string. + 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"'. - - Function: composite-char-string ch - This function returns a string of the characters comprising a - composite character. + Specifically, - - Function: compose-region start end &optional buffer - This function composes the characters in the region from START to - END in BUFFER into one composite character. The composite - character replaces the composed characters. BUFFER defaults to - the current buffer if omitted. + 1. If LOCALE is a buffer, a call - - Function: decompose-region start end &optional buffer - This function decomposes any composite characters in the region - from START to END in BUFFER. This converts each composite - character into one or more characters, the individual characters - out of which the composite character was formed. Non-composite - characters are left as-is. BUFFER defaults to the current buffer - if omitted. + `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)' - -File: lispref.info, Node: ISO 2022, Next: Coding Systems, Prev: Composite Characters, Up: MULE + is an interface to a C call something like -ISO 2022 -======== + `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsBuffer.Foreground", + "String");' - This section briefly describes the ISO 2022 encoding standard. For -more thorough understanding, please refer to the original document of -ISO 2022. + 2. If LOCALE is a frame, a call - Character sets ("charsets") are classified into the following four -categories, according to the number of characters of charset: -94-charset, 96-charset, 94x94-charset, and 96x96-charset. + `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)' -94-charset - ASCII(B), left(J) and right(I) half of JISX0201, ... + is an interface to a C call something like -96-charset - Latin-1(A), Latin-2(B), Latin-3(C), ... + `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsFrame.Foreground", + "String");' -94x94-charset - GB2312(A), JISX0208(B), KSC5601(C), ... + 3. If LOCALE is a device, a call -96x96-charset - none for the moment + `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)' - The character in parentheses after the name of each charset is the -"final character" F, which can be regarded as the identifier of the -charset. ECMA allocates F to each charset. F is in the range of -0x30..0x7F, but 0x30..0x3F are only for private use. + is an interface to a C call something like - Note: "ECMA" = European Computer Manufacturers Association + `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsDevice.Foreground", + "String");' - There are four "registers of charsets", called G0 thru G3. You can -designate (or assign) any charset to one of these registers. + 4. If LOCALE is the symbol `global', a call - The code space contained within one octet (of size 256) is divided -into 4 areas: C0, GL, C1, and GR. GL and GR are the areas into which a -register of charset can be invoked into. + `(x-get-resource "foreground" "Foreground" 'string 'global)' - C0: 0x00 - 0x1F - GL: 0x20 - 0x7F - C1: 0x80 - 0x9F - GR: 0xA0 - 0xFF + is an interface to a C call something like - Usually, in the initial state, G0 is invoked into GL, and G1 is -invoked into GR. + `XrmGetResource (db, "xemacs.foreground", + "Emacs.Foreground", + "String");' - ISO 2022 distinguishes 7-bit environments and 8-bit environments. In -7-bit environments, only C0 and GL are used. + 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. - Charset designation is done by escape sequences of the form: + 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". - ESC [I] I F + - 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. - where I is an intermediate character in the range 0x20 - 0x2F, and F -is the final character identifying this charset. + - 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'. - The meaning of intermediate characters are: + 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". - $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96). - ( [0x28]: designate to G0 a 94-charset whose final byte is F. - ) [0x29]: designate to G1 a 94-charset whose final byte is F. - * [0x2A]: designate to G2 a 94-charset whose final byte is F. - + [0x2B]: designate to G3 a 94-charset whose final byte is F. - - [0x2D]: designate to G1 a 96-charset whose final byte is F. - . [0x2E]: designate to G2 a 96-charset whose final byte is F. - / [0x2F]: designate to G3 a 96-charset whose final byte is F. + +File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server - The following rule is not allowed in ISO 2022 but can be used in -Mule. +Data about the X Server +----------------------- - , [0x2C]: designate to G0 a 96-charset whose final byte is F. + 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. - Here are examples of designations: + - 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. - ESC ( B : designate to G0 ASCII - ESC - A : designate to G1 Latin-1 - ESC $ ( A or ESC $ A : designate to G0 GB2312 - ESC $ ( B or ESC $ B : designate to G0 JISX0208 - ESC $ ) C : designate to G1 KSC5601 + - Function: x-server-vendor &optional device + This function returns the vendor supporting the X server DEVICE is + on. - To use a charset designated to G2 or G3, and to use a charset -designated to G1 in a 7-bit environment, you must explicitly invoke G1, -G2, or G3 into GL. There are two types of invocation, Locking Shift -(forever) and Single Shift (one character only). + - 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.) - Locking Shift is done as follows: + +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. - LS0 or SI (0x0F): invoke G0 into GL - LS1 or SO (0x0E): invoke G1 into GL - LS2: invoke G2 into GL - LS3: invoke G3 into GL - LS1R: invoke G1 into GR - LS2R: invoke G2 into GR - LS3R: invoke G3 into GR + +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 - Single Shift is done as follows: + +File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top - SS2 or ESC N: invoke G2 into GL - SS3 or ESC O: invoke G3 into GL +ToolTalk Support +**************** - (#### Ben says: I think the above is slightly incorrect. It appears -that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N -and ESC O behave as indicated. The above definitions will not parse -EUC-encoded text correctly, and it looks like the code in mule-coding.c -has similar problems.) +* Menu: - You may realize that there are a lot of ISO-2022-compliant ways of -encoding multilingual text. Now, in the world, there exist many coding -systems such as X11's Compound Text, Japanese JUNET code, and so-called -EUC (Extended UNIX Code); all of these are variants of ISO 2022. +* XEmacs ToolTalk API Summary:: +* Sending Messages:: +* Receiving Messages:: - In Mule, we characterize ISO 2022 by the following attributes: + +File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support - 1. Initial designation to G0 thru G3. +XEmacs ToolTalk API Summary +=========================== - 2. Allow designation of short form for Japanese and Chinese. + 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: - 3. Should we designate ASCII to G0 before control characters? + * 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. - 4. Should we designate ASCII to G0 at the end of line? + * There are fewer entry points; polymorphic functions with keyword + arguments are used instead. - 5. 7-bit environment or 8-bit environment. + * 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). - 6. Use Locking Shift or not. + * The session attribute for messages and patterns is always + initialized to the default session. - 7. Use ASCII or JIS0201-1976-Roman. + * 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. - 8. Use JISX0208-1983 or JISX0208-1976. + +File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support - (The last two are only for Japanese.) +Sending Messages +================ - By specifying these attributes, you can create any variant of ISO -2022. +* Menu: - Here are several examples: +* Example of Sending Messages:: +* Elisp Interface for Sending Messages:: - junet -- Coding system used in JUNET. - 1. G0 <- ASCII, G1..3 <- never used - 2. Yes. - 3. Yes. - 4. Yes. - 5. 7-bit environment - 6. No. - 7. Use ASCII - 8. Use JISX0208-1983 - - ctext -- Compound Text - 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used - 2. No. - 3. No. - 4. Yes. - 5. 8-bit environment - 6. No. - 7. Use ASCII - 8. Use JISX0208-1983 + +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"))))) - euc-china -- Chinese EUC. Although many people call this - as "GB encoding", the name may cause misunderstanding. - 1. G0 <- ASCII, G1 <- GB2312, G2,3 <- never used - 2. No. - 3. Yes. - 4. Yes. - 5. 8-bit environment - 6. No. - 7. Use ASCII - 8. Use JISX0208-1983 + (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)) - korean-mail -- Coding system used in Korean network. - 1. G0 <- ASCII, G1 <- KSC5601, G2,3 <- never used - 2. No. - 3. Yes. - 4. Yes. - 5. 7-bit environment - 6. Yes. - 7. No. - 8. No. - - Mule creates all these coding systems by default. + (let ((m (make-tooltalk-message random-query-message))) + (send-tooltalk-message m))  -File: lispref.info, Node: Coding Systems, Next: CCL, Prev: ISO 2022, Up: MULE +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_' 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. -Coding Systems -============== - - A coding system is an object that defines how text containing -multiple character sets is encoded into a stream of (typically 8-bit) -bytes. The coding system is used to decode the stream into a series of -characters (which may be from multiple charsets) when the text is read -from a file or process, and is used to encode the text back into the -same format when it is written out to a file or process. - - For example, many ISO-2022-compliant coding systems (such as Compound -Text, which is used for inter-client data under the X Window System) use -escape sequences to switch between different charsets - Japanese Kanji, -for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC ( -B'; and Cyrillic is invoked with `ESC - L'. See `make-coding-system' -for more information. - - Coding systems are normally identified using a symbol, and the -symbol is accepted in place of the actual coding system object whenever -a coding system is called for. (This is similar to how faces and -charsets work.) + +File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support - - Function: coding-system-p object - This function returns non-`nil' if OBJECT is a coding system. +Receiving Messages +================== * Menu: -* Coding System Types:: Classifying coding systems. -* EOL Conversion:: Dealing with different ways of denoting - the end of a line. -* Coding System Properties:: Properties of a coding system. -* Basic Coding System Functions:: Working with coding systems. -* Coding System Property Functions:: Retrieving a coding system's properties. -* Encoding and Decoding Text:: Encoding and decoding text. -* Detection of Textual Encoding:: Determining how text is encoded. -* Big5 and Shift-JIS Functions:: Special functions for these non-standard - encodings. - - -File: lispref.info, Node: Coding System Types, Next: EOL Conversion, Up: Coding Systems - -Coding System Types -------------------- - -`nil' -`autodetect' - Automatic conversion. XEmacs attempts to detect the coding system - used in the file. - -`no-conversion' - No conversion. Use this for binary files and such. On output, - graphic characters that are not in ASCII or Latin-1 will be - replaced by a `?'. (For a no-conversion-encoded buffer, these - characters will only be present if you explicitly insert them.) - -`shift-jis' - Shift-JIS (a Japanese encoding commonly used in PC operating - systems). - -`iso2022' - Any ISO-2022-compliant encoding. Among other things, this - includes JIS (the Japanese encoding commonly used for e-mail), - national variants of EUC (the standard Unix encoding for Japanese - and other languages), and Compound Text (an encoding used in X11). - You can specify more specific information about the conversion - with the FLAGS argument. - -`big5' - Big5 (the encoding commonly used for Taiwanese). - -`ccl' - The conversion is performed using a user-written pseudo-code - program. CCL (Code Conversion Language) is the name of this - pseudo-code. - -`internal' - Write out or read in the raw contents of the memory representing - the buffer's text. This is primarily useful for debugging - purposes, and is only enabled when XEmacs has been compiled with - `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*: - Reading in a file using `internal' conversion can result in an - internal inconsistency in the memory representing a buffer's text, - which will produce unpredictable results and may cause XEmacs to - crash. Under normal circumstances you should never use `internal' - conversion. +* Example of Receiving Messages:: +* Elisp Interface for Receiving Messages::  -File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: Coding System Types, Up: Coding Systems - -EOL Conversion --------------- - -`nil' - Automatically detect the end-of-line type (LF, CRLF, or CR). Also - generate subsidiary coding systems named `NAME-unix', `NAME-dos', - and `NAME-mac', that are identical to this coding system but have - an EOL-TYPE value of `lf', `crlf', and `cr', respectively. +File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages -`lf' - The end of a line is marked externally using ASCII LF. Since this - is also the way that XEmacs represents an end-of-line internally, - specifying this option results in no end-of-line conversion. This - is the standard format for Unix text files. - -`crlf' - The end of a line is marked externally using ASCII CRLF. This is - the standard format for MS-DOS text files. +Example of Receiving Messages +----------------------------- -`cr' - The end of a line is marked externally using ASCII CR. This is the - standard format for Macintosh text files. + 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. -`t' - Automatically detect the end-of-line type but do not generate - subsidiary coding systems. (This value is converted to `nil' when - stored internally, and `coding-system-property' will return `nil'.) + (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))  -File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems - -Coding System Properties ------------------------- - -`mnemonic' - String to be displayed in the modeline when this coding system is - active. - -`eol-type' - End-of-line conversion to be used. It should be one of the types - listed in *Note EOL Conversion::. - -`post-read-conversion' - Function called after a file has been read in, to perform the - decoding. Called with two arguments, BEG and END, denoting a - region of the current buffer to be decoded. - -`pre-write-conversion' - Function called before a file is written out, to perform the - encoding. Called with two arguments, BEG and END, denoting a - region of the current buffer to be encoded. - - The following additional properties are recognized if TYPE is -`iso2022': - -`charset-g0' -`charset-g1' -`charset-g2' -`charset-g3' - The character set initially designated to the G0 - G3 registers. - The value should be one of - - * A charset object (designate that character set) - - * `nil' (do not ever use this register) - - * `t' (no character set is initially designated to the - register, but may be later on; this automatically sets the - corresponding `force-g*-on-output' property) - -`force-g0-on-output' -`force-g1-on-output' -`force-g2-on-output' -`force-g3-on-output' - If non-`nil', send an explicit designation sequence on output - before using the specified register. - -`short' - If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $ - B' on output in place of the full designation sequences `ESC $ ( - @', `ESC $ ( A', and `ESC $ ( B'. - -`no-ascii-eol' - If non-`nil', don't designate ASCII to G0 at each end of line on - output. Setting this to non-`nil' also suppresses other - state-resetting that normally happens at the end of a line. - -`no-ascii-cntl' - If non-`nil', don't designate ASCII to G0 before control chars on - output. - -`seven' - If non-`nil', use 7-bit environment on output. Otherwise, use - 8-bit environment. - -`lock-shift' - If non-`nil', use locking-shift (SO/SI) instead of single-shift or - designation by escape sequence. - -`no-iso6429' - If non-`nil', don't use ISO6429's direction specification. - -`escape-quoted' - If non-nil, literal control characters that are the same as the - beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in - particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3 - (0x8F), and CSI (0x9B)) are "quoted" with an escape character so - that they can be properly distinguished from an escape sequence. - (Note that doing this results in a non-portable encoding.) This - encoding flag is used for byte-compiled files. Note that ESC is a - good choice for a quoting character because there are no escape - sequences whose second byte is a character from the Control-0 or - Control-1 character sets; this is explicitly disallowed by the ISO - 2022 standard. - -`input-charset-conversion' - A list of conversion specifications, specifying conversion of - characters in one charset to another when decoding is performed. - Each specification is a list of two elements: the source charset, - and the destination charset. - -`output-charset-conversion' - A list of conversion specifications, specifying conversion of - characters in one charset to another when encoding is performed. - The form of each specification is the same as for - `input-charset-conversion'. - - The following additional properties are recognized (and required) if -TYPE is `ccl': - -`decode' - CCL program used for decoding (converting to internal format). - -`encode' - CCL program used for encoding (converting to external format). +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.  -File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems +File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top -Basic Coding System Functions ------------------------------ +LDAP Support +************ - - Function: find-coding-system coding-system-or-name - This function retrieves the coding system of the given name. + XEmacs can be linked with a LDAP client library to provide Elisp +primitives to access directory servers using the Lightweight Directory +Access Protocol. - If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply - returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol. - If there is no such coding system, `nil' is returned. Otherwise - the associated coding system object is returned. +* Menu: - - Function: get-coding-system name - This function retrieves the coding system of the given name. Same - as `find-coding-system' except an error is signalled if there is no - such coding system instead of returning `nil'. +* 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 - - Function: coding-system-list - This function returns a list of the names of all defined coding - systems. + +File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support - - Function: coding-system-name coding-system - This function returns the name of the given coding system. +Building XEmacs with LDAP support +================================= - - Function: make-coding-system name type &optional doc-string props - This function registers symbol NAME as a coding system. + 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 - TYPE describes the conversion method used and should be one of the - types listed in *Note Coding System Types::. + * OpenLDAP 1.2 () - DOC-STRING is a string describing the coding system. + * University of Michigan's LDAP 3.3 + () - PROPS is a property list, describing the specific nature of the - character set. Recognized properties are as in *Note Coding - System Properties::. + * LDAP SDK 1.0 from Netscape Corp. () - - Function: copy-coding-system old-coding-system new-name - This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME - does not name an existing coding system, a new one will be created. + Other libraries conforming to RFC 1823 will probably work also but +may require some minor tweaking at C level. - - Function: subsidiary-coding-system coding-system eol-type - This function returns the subsidiary coding system of - CODING-SYSTEM with eol type EOL-TYPE. + The standard XEmacs configure script auto-detects 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.  -File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems - -Coding System Property Functions --------------------------------- - - - Function: coding-system-doc-string coding-system - This function returns the doc string for CODING-SYSTEM. - - - Function: coding-system-type coding-system - This function returns the type of CODING-SYSTEM. +File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support - - Function: coding-system-property coding-system prop - This function returns the PROP property of CODING-SYSTEM. +XEmacs LDAP API +=============== - -File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems - -Encoding and Decoding Text --------------------------- - - - Function: decode-coding-region start end coding-system &optional - buffer - This function decodes the text between START and END which is - encoded in CODING-SYSTEM. This is useful if you've read in - encoded text from a file without decoding it (e.g. you read in a - JIS-formatted file but used the `binary' or `no-conversion' coding - system, so that it shows up as `^[$B!