From: tomo Date: Tue, 6 Jun 2000 04:16:57 +0000 (+0000) Subject: XEmacs 21.2.34 "Molpe". X-Git-Tag: r21-2-34^2 X-Git-Url: http://git.chise.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dc04f3440df515be7a8ff252127e61a1a9b21d71;p=chise%2Fxemacs-chise.git XEmacs 21.2.34 "Molpe". --- diff --git a/info/internals.info-5 b/info/internals.info-5 index d2c73c5..5b22b50 100644 --- a/info/internals.info-5 +++ b/info/internals.info-5 @@ -68,7 +68,7 @@ the internals: *Note lrecords::. Our next candidates are the other objects that behave quite differently than everything else: the strings. They consists of two -parts, a fixed-size portion (`struct Lisp_string') holding the string's +parts, a fixed-size portion (`struct Lisp_String') holding the string's length, its property list and a pointer to the second part, and the actual string data, which is stored in string-chars blocks comparable to frob blocks. In this block, the data is not only freed, but also a @@ -824,9 +824,9 @@ File: internals.info, Node: Dumping phase, Next: Reloading phase, Prev: Data Dumping phase ============= - Dumping is done by calling the function pdump() (in alloc.c) which is -invoked from Fdump_emacs (in emacs.c). This function performs a number -of tasks. + Dumping is done by calling the function pdump() (in dumper.c) which +is invoked from Fdump_emacs (in emacs.c). This function performs a +number of tasks. * Menu: diff --git a/info/lispref.info-12 b/info/lispref.info-12 index 5c5d7bf..db1578b 100644 --- a/info/lispref.info-12 +++ b/info/lispref.info-12 @@ -659,7 +659,7 @@ around the `require' calls (*note Eval During Compile::). file that gets the error will not, of course, produce any compiled code.) - % emacs -batch -f batch-byte-compile *.el + % xemacs -batch -f batch-byte-compile *.el - Function: batch-byte-recompile-directory This function is similar to `batch-byte-compile' but runs the diff --git a/info/lispref.info-20 b/info/lispref.info-20 index 504086a..240c4a3 100644 --- a/info/lispref.info-20 +++ b/info/lispref.info-20 @@ -350,12 +350,14 @@ Toolbar * Menu: * Toolbar Intro:: An introduction. -* Toolbar Descriptor Format:: How to create a toolbar. +* Creating Toolbar:: How to create a toolbar. +* Toolbar Descriptor Format:: Accessing and modifying a toolbar's + properties. * Specifying the Toolbar:: Setting a toolbar's contents. * Other Toolbar Variables:: Controlling the size of toolbars.  -File: lispref.info, Node: Toolbar Intro, Next: Toolbar Descriptor Format, Up: Toolbar +File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar Toolbar Intro ============= @@ -399,7 +401,29 @@ the position-specific specifiers, and if the user sets the default toolbar to the same position, it will just not be visible.  -File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Toolbar Intro, Up: Toolbar +File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar + +Creating Toolbar +================ + + - Function: make-toolbar-specifier spec-list + Return a new `toolbar' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. *Note + Specifiers::, for more information about specifiers. + + Toolbar specifiers are used to specify the format of a toolbar. + The values of the variables `default-toolbar', `top-toolbar', + `left-toolbar', `right-toolbar', and `bottom-toolbar' are always + toolbar specifiers. + + Valid toolbar instantiators are called "toolbar descriptors" and + are lists of vectors. See `default-toolbar' for a description of + the exact format. + + +File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar Toolbar Descriptor Format ========================= @@ -686,13 +710,15 @@ contain arbitrary text or graphics. * Menu: * Gutter Intro:: An introduction. -* Gutter Descriptor Format:: How to create a gutter. +* Creating Gutter:: How to create a gutter. +* Gutter Descriptor Format:: Accessing and modifying a gutter's + properties. * Specifying a Gutter:: Setting a gutter's contents. * Other Gutter Variables:: Controlling the size of gutters. * Common Gutter Widgets:: Things to put in gutters.  -File: lispref.info, Node: Gutter Intro, Next: Gutter Descriptor Format, Up: Gutter +File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter Gutter Intro ============ @@ -731,7 +757,67 @@ the position-specific specifiers, and if the user sets the default gutter to the same position, it will just not be visible.  -File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Gutter Intro, Up: Gutter +File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter + +Creating Gutter +=============== + + - Function: make-gutter-specifier spec-list + Return a new `gutter' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter specifiers are used to specify the format of a gutter. The + values of the variables `default-gutter', `top-gutter', + `left-gutter', `right-gutter', and `bottom-gutter' are always + gutter specifiers. + + Valid gutter instantiators are called "gutter descriptors" and are + either strings or property-lists of strings. See `default-gutter' + for a description of the exact format. + + - Function: make-gutter-size-specifier spec-list + Return a new `gutter-size' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-size specifiers are used to specify the size of a gutter. + The values of the variables `default-gutter-size', + `top-gutter-size', `left-gutter-size', `right-gutter-size', and + `bottom-gutter-size' are always gutter-size specifiers. + + Valid gutter-size instantiators are either integers or the special + symbol `autodetect'. If a gutter-size is set to `autodetect' them + the size of the gutter will be adjusted to just accomodate the + gutters contents. `autodetect' only works for top and bottom + gutters. + + - Function: make-gutter-visible-specifier spec-list + Return a new `gutter-visible' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-visible specifiers are used to specify the visibility of a + gutter. The values of the variables `default-gutter-visible-p', + `top-gutter-visible-p', `left-gutter-visible-p', + `right-gutter-visible-p', and `bottom-gutter-visible-p' are always + gutter-visible specifiers. + + Valid gutter-visible instantiators are t, nil or a list of + symbols. If a gutter-visible instantiator is set to a list of + symbols, and the correspondong gutter specification is a + property-list strings, then elements of the gutter specification + will only be visible if the corresponding symbol occurs in the + gutter-visible instantiator. + + +File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter Gutter Descriptor Format ======================== @@ -1031,7 +1117,7 @@ time-consuming operations like downloading. File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets Buffer Tabs -=========== +----------- Not documented yet. @@ -1039,7 +1125,7 @@ Buffer Tabs File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets Progress Bars -============= +------------- Not documented yet. @@ -1122,97 +1208,3 @@ application interaction is possible while dragging is in progress. For information about the OffiX project have a look at http://leb.net/~offix/ - -File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols - -CDE dt ------- - - CDE stands for Common Desktop Environment. It is based on the Motif -widget library. It's drag'n'drop protocol is also an abstraction of the -Motif protocol (so it might be possible, that XEmacs will also support -the Motif protocol soon). - - CDE has three different types: file, buffer, and text. XEmacs only -uses file and buffer drags. The API will disallow full URL drags, only -file method URLs are passed through. - - Buffer drags are always converted to plain text. - - -File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols - -MSWindows OLE -------------- - - Only allows file drags and drops. - - -File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols - -Loose ends ----------- - - The following protocols will be supported soon: Xdnd, Motif, Xde (if -I get some specs), KDE OffiX (if KDE can find XEmacs windows). - - In particular Xdnd will be one of the protocols that can benefit from -the XEmacs API, cause it also uses MIME types to encode dragged data. - - -File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop - -Drop Interface -============== - - For each activated low-level protocol, a internal routine will catch -incoming drops and convert them to a dragdrop-drop type misc-user-event. - - This misc-user-event has its function argument set to -`dragdrop-drop-dispatch' and the object contains the data of the drop -(converted to URL/MIME specific data). This function will search the -variable `experimental-dragdrop-drop-functions' for a function that can -handle the dropped data. - - To modify the drop behavior, the user can modify the variable -`experimental-dragdrop-drop-functions'. Each element of this list -specifies a possible handler for dropped data. The first one that can -handle the data will return `t' and exit. Another possibility is to set -a extent-property with the same name. Extents are checked prior to the -variable. - - The customization group `drag-n-drop' shows all variables of user -interest. - - -File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop - -Drag Interface -============== - - This describes the drag API (not implemented yet). - - -File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top - -Major and Minor Modes -********************* - - A "mode" is a set of definitions that customize XEmacs and can be -turned on and off while you edit. There are two varieties of modes: -"major modes", which are mutually exclusive and used for editing -particular kinds of text, and "minor modes", which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how -to indicate them in the modeline, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see *Note -Keymaps::, and *Note Syntax Tables::. - -* Menu: - -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Modeline Format:: Customizing the text that appears in the modeline. -* Hooks:: How to use hooks; how to write code that provides hooks. - diff --git a/info/lispref.info-21 b/info/lispref.info-21 index fb2f5da..bac2669 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -50,6 +50,100 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols + +CDE dt +------ + + CDE stands for Common Desktop Environment. It is based on the Motif +widget library. It's drag'n'drop protocol is also an abstraction of the +Motif protocol (so it might be possible, that XEmacs will also support +the Motif protocol soon). + + CDE has three different types: file, buffer, and text. XEmacs only +uses file and buffer drags. The API will disallow full URL drags, only +file method URLs are passed through. + + Buffer drags are always converted to plain text. + + +File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols + +MSWindows OLE +------------- + + Only allows file drags and drops. + + +File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols + +Loose ends +---------- + + The following protocols will be supported soon: Xdnd, Motif, Xde (if +I get some specs), KDE OffiX (if KDE can find XEmacs windows). + + In particular Xdnd will be one of the protocols that can benefit from +the XEmacs API, cause it also uses MIME types to encode dragged data. + + +File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop + +Drop Interface +============== + + For each activated low-level protocol, a internal routine will catch +incoming drops and convert them to a dragdrop-drop type misc-user-event. + + This misc-user-event has its function argument set to +`dragdrop-drop-dispatch' and the object contains the data of the drop +(converted to URL/MIME specific data). This function will search the +variable `experimental-dragdrop-drop-functions' for a function that can +handle the dropped data. + + To modify the drop behavior, the user can modify the variable +`experimental-dragdrop-drop-functions'. Each element of this list +specifies a possible handler for dropped data. The first one that can +handle the data will return `t' and exit. Another possibility is to set +a extent-property with the same name. Extents are checked prior to the +variable. + + The customization group `drag-n-drop' shows all variables of user +interest. + + +File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop + +Drag Interface +============== + + This describes the drag API (not implemented yet). + + +File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top + +Major and Minor Modes +********************* + + A "mode" is a set of definitions that customize XEmacs and can be +turned on and off while you edit. There are two varieties of modes: +"major modes", which are mutually exclusive and used for editing +particular kinds of text, and "minor modes", which provide features +that users can enable individually. + + This chapter describes how to write both major and minor modes, how +to indicate them in the modeline, and how they run hooks supplied by the +user. For related topics such as keymaps and syntax tables, see *Note +Keymaps::, and *Note Syntax Tables::. + +* Menu: + +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Modeline Format:: Customizing the text that appears in the modeline. +* Hooks:: How to use hooks; how to write code that provides hooks. + + File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes Major Modes @@ -813,7 +907,7 @@ The Data Structure of the Modeline The modeline contents are controlled by a data structure of lists, strings, symbols, and numbers kept in the buffer-local variable -`mode-line-format'. The data structure is called a "modeline +`modeline-format'. The data structure is called a "modeline construct", and it is built in recursive fashion out of simpler modeline constructs. The same data structure is used for constructing frame titles (*note Frame Titles::). @@ -834,8 +928,8 @@ variables such as `mode-name' and `minor-mode-alist'. Because of this, very few modes need to alter `modeline-format'. For most purposes, it is sufficient to alter the variables referenced by `modeline-format'. - A modeline construct may be a list, a symbol, or a string. If the -value is a list, each element may be a list, a symbol, or a string. + A modeline construct may be a string, symbol, glyph, generic +specifier, list or cons cell. `STRING' A string as a modeline construct is displayed verbatim in the mode @@ -845,13 +939,22 @@ value is a list, each element may be a list, a symbol, or a string. `SYMBOL' A symbol as a modeline construct stands for its value. The value - of SYMBOL is used as a modeline construct, in place of SYMBOL. - However, the symbols `t' and `nil' are ignored; so is any symbol - whose value is void. + of SYMBOL is processed as a modeline construct, in place of + SYMBOL. However, the symbols `t' and `nil' are ignored; so is any + symbol whose value is void. There is one exception: if the value of SYMBOL is a string, it is displayed verbatim: the `%'-constructs are not recognized. +`GLYPH' + A glyph is displayed as is. + +`GENERIC-SPECIFIER' + A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands + for its instance. The instance of GENERIC-SPECIFIER is computed + in the current window using the equivalent of `specifier-instance' + and the value is processed. + `(STRING REST...) or (LIST REST...)' A list whose first element is a string or list means to process all the elements recursively and concatenate the results. This is @@ -877,6 +980,17 @@ value is a list, each element may be a list, a symbol, or a string. above the top of the window is to use a list like this: `(-3 "%p")'. +`(EXTENT REST...)' + A list whose car is an extent means the cdr of the list is + processed normally but the results are displayed using the face of + the extent, and mouse clicks over this section are processed using + the keymap of the extent. (In addition, if the extent has a + help-echo property, that string will be echoed when the mouse + moves over this section.) If extents are nested, all keymaps are + properly consulted when processing mouse clicks, but multiple + faces are not correctly merged (only the first face is used), and + lists of faces are not correctly handled. + If you do alter `modeline-format' itself, the new value should use the same variables that appear in the default value (*note Modeline Variables::), rather than duplicating their contents or displaying the @@ -1020,100 +1134,3 @@ to use them. so, which kind. Its value is `nil' for no version control, or a string that appears in the mode line. - -File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format - -`%'-Constructs in the ModeLine ------------------------------- - - The following table lists the recognized `%'-constructs and what -they mean. In any construct except `%%', you can add a decimal integer -after the `%' to specify how many characters to display. - -`%b' - The current buffer name, obtained with the `buffer-name' function. - *Note Buffer Names::. - -`%f' - The visited file name, obtained with the `buffer-file-name' - function. *Note Buffer File Name::. - -`%F' - The name of the selected frame. - -`%c' - The current column number of point. - -`%l' - The current line number of point. - -`%*' - `%' if the buffer is read only (see `buffer-read-only'); - `*' if the buffer is modified (see `buffer-modified-p'); - `-' otherwise. *Note Buffer Modification::. - -`%+' - `*' if the buffer is modified (see `buffer-modified-p'); - `%' if the buffer is read only (see `buffer-read-only'); - `-' otherwise. This differs from `%*' only for a modified - read-only buffer. *Note Buffer Modification::. - -`%&' - `*' if the buffer is modified, and `-' otherwise. - -`%s' - The status of the subprocess belonging to the current buffer, - obtained with `process-status'. *Note Process Information::. - -`%l' - the current line number. - -`%S' - the name of the selected frame; this is only meaningful under the - X Window System. *Note Frame Name::. - -`%t' - Whether the visited file is a text file or a binary file. (This - is a meaningful distinction only on certain operating systems.) - -`%p' - The percentage of the buffer text above the *top* of window, or - `Top', `Bottom' or `All'. - -`%P' - The percentage of the buffer text that is above the *bottom* of - the window (which includes the text visible in the window, as well - as the text above the top), plus `Top' if the top of the buffer is - visible on screen; or `Bottom' or `All'. - -`%n' - `Narrow' when narrowing is in effect; nothing otherwise (see - `narrow-to-region' in *Note Narrowing::). - -`%[' - An indication of the depth of recursive editing levels (not - counting minibuffer levels): one `[' for each editing level. - *Note Recursive Editing::. - -`%]' - One `]' for each recursive editing level (not counting minibuffer - levels). - -`%%' - The character `%'--this is how to include a literal `%' in a - string in which `%'-constructs are allowed. - -`%-' - Dashes sufficient to fill the remainder of the modeline. - - The following two `%'-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -`mode-name' and `global-mode-string'. - -`%m' - The value of `mode-name'. - -`%M' - The value of `global-mode-string'. Currently, only `display-time' - modifies the value of `global-mode-string'. - diff --git a/info/lispref.info-22 b/info/lispref.info-22 index b42187d..c9aa60e 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -50,6 +50,106 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format + +`%'-Constructs in the ModeLine +------------------------------ + + The following table lists the recognized `%'-constructs and what +they mean. In any construct except `%%', you can add a decimal integer +after the `%' to specify how many characters to display. + +`%b' + The current buffer name, obtained with the `buffer-name' function. + *Note Buffer Names::. + +`%f' + The visited file name, obtained with the `buffer-file-name' + function. *Note Buffer File Name::. + +`%F' + The name of the selected frame. + +`%c' + The current column number of point. + +`%l' + The current line number of point. + +`%*' + `%' if the buffer is read only (see `buffer-read-only'); + `*' if the buffer is modified (see `buffer-modified-p'); + `-' otherwise. *Note Buffer Modification::. + +`%+' + `*' if the buffer is modified (see `buffer-modified-p'); + `%' if the buffer is read only (see `buffer-read-only'); + `-' otherwise. This differs from `%*' only for a modified + read-only buffer. *Note Buffer Modification::. + +`%&' + `*' if the buffer is modified, and `-' otherwise. + +`%s' + The status of the subprocess belonging to the current buffer, + obtained with `process-status'. *Note Process Information::. + +`%l' + The current line number. + +`%S' + The name of the selected frame; this is only meaningful under the + X Window System. *Note Frame Name::. + +`%t' + Whether the visited file is a text file or a binary file. (This + is a meaningful distinction only on certain operating systems.) + +`%p' + The percentage of the buffer text above the *top* of window, or + `Top', `Bottom' or `All'. + +`%P' + The percentage of the buffer text that is above the *bottom* of + the window (which includes the text visible in the window, as well + as the text above the top), plus `Top' if the top of the buffer is + visible on screen; or `Bottom' or `All'. + +`%n' + `Narrow' when narrowing is in effect; nothing otherwise (see + `narrow-to-region' in *Note Narrowing::). + +`%C' + Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'. + +`%[' + An indication of the depth of recursive editing levels (not + counting minibuffer levels): one `[' for each editing level. + *Note Recursive Editing::. + +`%]' + One `]' for each recursive editing level (not counting minibuffer + levels). + +`%%' + The character `%'--this is how to include a literal `%' in a + string in which `%'-constructs are allowed. + +`%-' + Dashes sufficient to fill the remainder of the modeline. + + The following two `%'-constructs are still supported, but they are +obsolete, since you can get the same results with the variables +`mode-name' and `global-mode-string'. + +`%m' + The value of `mode-name'. + +`%M' + The value of `global-mode-string'. Currently, only `display-time' + modifies the value of `global-mode-string'. + + File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes Hooks @@ -1008,132 +1108,3 @@ call them directly. The last thing `after-find-file' does is call all the functions in `find-file-hooks'. - -File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files - -Saving Buffers -============== - - When you edit a file in XEmacs, you are actually working on a buffer -that is visiting that file--that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you "save" the buffer, which means -copying the contents of the buffer into the file. - - - Command: save-buffer &optional backup-option - This function saves the contents of the current buffer in its - visited file if the buffer has been modified since it was last - visited or saved. Otherwise it does nothing. - - `save-buffer' is responsible for making backup files. Normally, - BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only - if this is the first save since visiting the file. Other values - for BACKUP-OPTION request the making of backup files in other - circumstances: - - * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the - `save-buffer' function marks this version of the file to be - backed up when the buffer is next saved. - - * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the - `save-buffer' function unconditionally backs up the previous - version of the file before saving it. - - - Command: save-some-buffers &optional save-silently-p exiting - This command saves some modified file-visiting buffers. Normally - it asks the user about each buffer. But if SAVE-SILENTLY-P is - non-`nil', it saves all the file-visiting buffers without querying - the user. - - The optional EXITING argument, if non-`nil', requests this - function to offer also to save certain other buffers that are not - visiting files. These are buffers that have a non-`nil' local - value of `buffer-offer-save'. (A user who says yes to saving one - of these is asked to specify a file name to use.) The - `save-buffers-kill-emacs' function passes a non-`nil' value for - this argument. - - - Variable: buffer-offer-save - When this variable is non-`nil' in a buffer, XEmacs offers to save - the buffer on exit even if the buffer is not visiting a file. The - variable is automatically local in all buffers. Normally, Mail - mode (used for editing outgoing mail) sets this to `t'. - - - Command: write-file filename - This function writes the current buffer into file FILENAME, makes - the buffer visit that file, and marks it not modified. Then it - renames the buffer based on FILENAME, appending a string like `<2>' - if necessary to make a unique buffer name. It does most of this - work by calling `set-visited-file-name' and `save-buffer'. - - - Variable: write-file-hooks - The value of this variable is a list of functions to be called - before writing out a buffer to its visited file. If one of them - returns non-`nil', the file is considered already written and the - rest of the functions are not called, nor is the usual code for - writing the file executed. - - If a function in `write-file-hooks' returns non-`nil', it is - responsible for making a backup file (if that is appropriate). To - do so, execute the following code: - - (or buffer-backed-up (backup-buffer)) - - You might wish to save the file modes value returned by - `backup-buffer' and use that to set the mode bits of the file that - you write. This is what `save-buffer' normally does. - - Even though this is not a normal hook, you can use `add-hook' and - `remove-hook' to manipulate the list. *Note Hooks::. - - - Variable: local-write-file-hooks - This works just like `write-file-hooks', but it is intended to be - made local to particular buffers. It's not a good idea to make - `write-file-hooks' local to a buffer--use this variable instead. - - The variable is marked as a permanent local, so that changing the - major mode does not alter a buffer-local value. This is - convenient for packages that read "file" contents in special ways, - and set up hooks to save the data in a corresponding way. - - - Variable: write-contents-hooks - This works just like `write-file-hooks', but it is intended for - hooks that pertain to the contents of the file, as opposed to - hooks that pertain to where the file came from. Such hooks are - usually set up by major modes, as buffer-local bindings for this - variable. Switching to a new major mode always resets this - variable. - - - Variable: after-save-hook - This normal hook runs after a buffer has been saved in its visited - file. - - - Variable: file-precious-flag - If this variable is non-`nil', then `save-buffer' protects against - I/O errors while saving by writing the new file to a temporary - name instead of the name it is supposed to have, and then renaming - it to the intended name after it is clear there are no errors. - This procedure prevents problems such as a lack of disk space from - resulting in an invalid file. - - As a side effect, backups are necessarily made by copying. *Note - Rename or Copy::. Yet, at the same time, saving a precious file - always breaks all hard links between the file you save and other - file names. - - Some modes set this variable non-`nil' locally in particular - buffers. - - - User Option: require-final-newline - This variable determines whether files may be written out that do - _not_ end with a newline. If the value of the variable is `t', - then `save-buffer' silently adds a newline at the end of the file - whenever the buffer being saved does not already end in one. If - the value of the variable is non-`nil', but not `t', then - `save-buffer' asks the user whether to add a newline each time the - case arises. - - If the value of the variable is `nil', then `save-buffer' doesn't - add newlines at all. `nil' is the default value, but a few major - modes set it to `t' in particular buffers. - diff --git a/info/lispref.info-23 b/info/lispref.info-23 index 35745c5..fa1b689 100644 --- a/info/lispref.info-23 +++ b/info/lispref.info-23 @@ -50,6 +50,135 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files + +Saving Buffers +============== + + When you edit a file in XEmacs, you are actually working on a buffer +that is visiting that file--that is, the contents of the file are +copied into the buffer and the copy is what you edit. Changes to the +buffer do not change the file until you "save" the buffer, which means +copying the contents of the buffer into the file. + + - Command: save-buffer &optional backup-option + This function saves the contents of the current buffer in its + visited file if the buffer has been modified since it was last + visited or saved. Otherwise it does nothing. + + `save-buffer' is responsible for making backup files. Normally, + BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only + if this is the first save since visiting the file. Other values + for BACKUP-OPTION request the making of backup files in other + circumstances: + + * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the + `save-buffer' function marks this version of the file to be + backed up when the buffer is next saved. + + * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the + `save-buffer' function unconditionally backs up the previous + version of the file before saving it. + + - Command: save-some-buffers &optional save-silently-p exiting + This command saves some modified file-visiting buffers. Normally + it asks the user about each buffer. But if SAVE-SILENTLY-P is + non-`nil', it saves all the file-visiting buffers without querying + the user. + + The optional EXITING argument, if non-`nil', requests this + function to offer also to save certain other buffers that are not + visiting files. These are buffers that have a non-`nil' local + value of `buffer-offer-save'. (A user who says yes to saving one + of these is asked to specify a file name to use.) The + `save-buffers-kill-emacs' function passes a non-`nil' value for + this argument. + + - Variable: buffer-offer-save + When this variable is non-`nil' in a buffer, XEmacs offers to save + the buffer on exit even if the buffer is not visiting a file. The + variable is automatically local in all buffers. Normally, Mail + mode (used for editing outgoing mail) sets this to `t'. + + - Command: write-file filename + This function writes the current buffer into file FILENAME, makes + the buffer visit that file, and marks it not modified. Then it + renames the buffer based on FILENAME, appending a string like `<2>' + if necessary to make a unique buffer name. It does most of this + work by calling `set-visited-file-name' and `save-buffer'. + + - Variable: write-file-hooks + The value of this variable is a list of functions to be called + before writing out a buffer to its visited file. If one of them + returns non-`nil', the file is considered already written and the + rest of the functions are not called, nor is the usual code for + writing the file executed. + + If a function in `write-file-hooks' returns non-`nil', it is + responsible for making a backup file (if that is appropriate). To + do so, execute the following code: + + (or buffer-backed-up (backup-buffer)) + + You might wish to save the file modes value returned by + `backup-buffer' and use that to set the mode bits of the file that + you write. This is what `save-buffer' normally does. + + Even though this is not a normal hook, you can use `add-hook' and + `remove-hook' to manipulate the list. *Note Hooks::. + + - Variable: local-write-file-hooks + This works just like `write-file-hooks', but it is intended to be + made local to particular buffers. It's not a good idea to make + `write-file-hooks' local to a buffer--use this variable instead. + + The variable is marked as a permanent local, so that changing the + major mode does not alter a buffer-local value. This is + convenient for packages that read "file" contents in special ways, + and set up hooks to save the data in a corresponding way. + + - Variable: write-contents-hooks + This works just like `write-file-hooks', but it is intended for + hooks that pertain to the contents of the file, as opposed to + hooks that pertain to where the file came from. Such hooks are + usually set up by major modes, as buffer-local bindings for this + variable. Switching to a new major mode always resets this + variable. + + - Variable: after-save-hook + This normal hook runs after a buffer has been saved in its visited + file. + + - Variable: file-precious-flag + If this variable is non-`nil', then `save-buffer' protects against + I/O errors while saving by writing the new file to a temporary + name instead of the name it is supposed to have, and then renaming + it to the intended name after it is clear there are no errors. + This procedure prevents problems such as a lack of disk space from + resulting in an invalid file. + + As a side effect, backups are necessarily made by copying. *Note + Rename or Copy::. Yet, at the same time, saving a precious file + always breaks all hard links between the file you save and other + file names. + + Some modes set this variable non-`nil' locally in particular + buffers. + + - User Option: require-final-newline + This variable determines whether files may be written out that do + _not_ end with a newline. If the value of the variable is `t', + then `save-buffer' silently adds a newline at the end of the file + whenever the buffer being saved does not already end in one. If + the value of the variable is non-`nil', but not `t', then + `save-buffer' asks the user whether to add a newline each time the + case arises. + + If the value of the variable is `nil', then `save-buffer' doesn't + add newlines at all. `nil' is the default value, but a few major + modes set it to `t' in particular buffers. + + File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files Reading from Files @@ -1127,135 +1256,3 @@ name. For other completion functions, see *Note Completion::. completion-ignored-extensions => (".o" ".elc" "~" ".dvi") - -File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names - -User Name Completion --------------------- - - This section describes low-level subroutines for completing a user -name. For other completion functions, see *Note Completion::. - - - Function: user-name-all-completions partial-username - This function returns a list of all possible completions for a user - whose name starts with PARTIAL-USERNAME. The order of the - completions is unpredictable and conveys no useful information. - - The argument PARTIAL-USERNAME must be a partial user name - containing no tilde character and no slash. - - - Function: user-name-completion username - This function completes the user name USERNAME. It returns the - longest prefix common to all user names that start with USERNAME. - - If only one match exists and USERNAME matches it exactly, the - function returns `t'. The function returns `nil' if no user name - starting with USERNAME exists. - - - Function: user-name-completion-1 username - This function completes the user name USERNAME, like - `user-name-completion', differing only in the return value. This - function returns the cons of the completion returned by - `user-name-completion', and a boolean indicating whether that - completion was unique. - - -File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files - -Contents of Directories -======================= - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - XEmacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the `ls' shell command. In the -latter case, it can optionally display information about each file, -depending on the value of switches passed to the `ls' command. - - - Function: directory-files directory &optional full-name match-regexp - nosort files-only - This function returns a list of the names of the files in the - directory DIRECTORY. By default, the list is in alphabetical - order. - - If FULL-NAME is non-`nil', the function returns the files' - absolute file names. Otherwise, it returns just the names - relative to the specified directory. - - If MATCH-REGEXP is non-`nil', this function returns only those - file names that contain that regular expression--the other file - names are discarded from the list. - - If NOSORT is non-`nil', `directory-files' does not sort the list, - so you get the file names in no particular order. Use this if you - want the utmost possible speed and don't care what order the files - are processed in. If the order of processing is visible to the - user, then the user will probably be happier if you do sort the - names. - - If FILES-ONLY is the symbol `t', then only the "files" in the - directory will be returned; subdirectories will be excluded. If - FILES-ONLY is not `nil' and not `t', then only the subdirectories - will be returned. Otherwise, if FILES-ONLY is `nil' (the default) - then both files and subdirectories will be returned. - - (directory-files "~lewis") - => ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") - - An error is signaled if DIRECTORY is not the name of a directory - that can be read. - - - Function: insert-directory file switches &optional wildcard - full-directory-p - This function inserts (in the current buffer) a directory listing - for directory FILE, formatted with `ls' according to SWITCHES. It - leaves point after the inserted text. - - The argument FILE may be either a directory name or a file - specification including wildcard characters. If WILDCARD is - non-`nil', that means treat FILE as a file specification with - wildcards. - - If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory - and switches do not contain `-d', so that the listing should show - the full contents of the directory. (The `-d' option to `ls' says - to describe a directory itself rather than its contents.) - - This function works by running a directory listing program whose - name is in the variable `insert-directory-program'. If WILDCARD is - non-`nil', it also runs the shell specified by `shell-file-name', - to expand the wildcards. - - - Variable: insert-directory-program - This variable's value is the program to run to generate a - directory listing for the function `insert-directory'. - - -File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files - -Creating and Deleting Directories -================================= - - Most XEmacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with `delete-file'. These special functions exist to create and delete -directories. - - - Command: make-directory dirname &optional parents - This function creates a directory named DIRNAME. Interactively, - the default choice of directory to create is the current default - directory for file names. That is useful when you have visited a - file in a nonexistent directory. - - Non-interactively, optional argument PARENTS says whether to - create parent directories if they don't exist. (Interactively, this - always happens.) - - - Command: delete-directory dirname - This function deletes the directory named DIRNAME. The function - `delete-file' does not work for files that are directories; you - must use `delete-directory' in that case. - diff --git a/info/lispref.info-24 b/info/lispref.info-24 index 5eeea30..f8d1d65 100644 --- a/info/lispref.info-24 +++ b/info/lispref.info-24 @@ -50,6 +50,138 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names + +User Name Completion +-------------------- + + This section describes low-level subroutines for completing a user +name. For other completion functions, see *Note Completion::. + + - Function: user-name-all-completions partial-username + This function returns a list of all possible completions for a user + whose name starts with PARTIAL-USERNAME. The order of the + completions is unpredictable and conveys no useful information. + + The argument PARTIAL-USERNAME must be a partial user name + containing no tilde character and no slash. + + - Function: user-name-completion username + This function completes the user name USERNAME. It returns the + longest prefix common to all user names that start with USERNAME. + + If only one match exists and USERNAME matches it exactly, the + function returns `t'. The function returns `nil' if no user name + starting with USERNAME exists. + + - Function: user-name-completion-1 username + This function completes the user name USERNAME, like + `user-name-completion', differing only in the return value. This + function returns the cons of the completion returned by + `user-name-completion', and a boolean indicating whether that + completion was unique. + + +File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files + +Contents of Directories +======================= + + A directory is a kind of file that contains other files entered under +various names. Directories are a feature of the file system. + + XEmacs can list the names of the files in a directory as a Lisp list, +or display the names in a buffer using the `ls' shell command. In the +latter case, it can optionally display information about each file, +depending on the value of switches passed to the `ls' command. + + - Function: directory-files directory &optional full-name match-regexp + nosort files-only + This function returns a list of the names of the files in the + directory DIRECTORY. By default, the list is in alphabetical + order. + + If FULL-NAME is non-`nil', the function returns the files' + absolute file names. Otherwise, it returns just the names + relative to the specified directory. + + If MATCH-REGEXP is non-`nil', this function returns only those + file names that contain that regular expression--the other file + names are discarded from the list. + + If NOSORT is non-`nil', `directory-files' does not sort the list, + so you get the file names in no particular order. Use this if you + want the utmost possible speed and don't care what order the files + are processed in. If the order of processing is visible to the + user, then the user will probably be happier if you do sort the + names. + + If FILES-ONLY is the symbol `t', then only the "files" in the + directory will be returned; subdirectories will be excluded. If + FILES-ONLY is not `nil' and not `t', then only the subdirectories + will be returned. Otherwise, if FILES-ONLY is `nil' (the default) + then both files and subdirectories will be returned. + + (directory-files "~lewis") + => ("#foo#" "#foo.el#" "." ".." + "dired-mods.el" "files.texi" + "files.texi.~1~") + + An error is signaled if DIRECTORY is not the name of a directory + that can be read. + + - Function: insert-directory file switches &optional wildcard + full-directory-p + This function inserts (in the current buffer) a directory listing + for directory FILE, formatted with `ls' according to SWITCHES. It + leaves point after the inserted text. + + The argument FILE may be either a directory name or a file + specification including wildcard characters. If WILDCARD is + non-`nil', that means treat FILE as a file specification with + wildcards. + + If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory + and switches do not contain `-d', so that the listing should show + the full contents of the directory. (The `-d' option to `ls' says + to describe a directory itself rather than its contents.) + + This function works by running a directory listing program whose + name is in the variable `insert-directory-program'. If WILDCARD is + non-`nil', it also runs the shell specified by `shell-file-name', + to expand the wildcards. + + - Variable: insert-directory-program + This variable's value is the program to run to generate a + directory listing for the function `insert-directory'. + + +File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files + +Creating and Deleting Directories +================================= + + Most XEmacs Lisp file-manipulation functions get errors when used on +files that are directories. For example, you cannot delete a directory +with `delete-file'. These special functions exist to create and delete +directories. + + - Command: make-directory dirname &optional parents + This function creates a directory named DIRNAME. Interactively, + the default choice of directory to create is the current default + directory for file names. That is useful when you have visited a + file in a nonexistent directory. + + Non-interactively, optional argument PARENTS says whether to + create parent directories if they don't exist. (Interactively, this + always happens.) + + - Command: delete-directory dirname + This function deletes the directory named DIRNAME. The function + `delete-file' does not work for files that are directories; you + must use `delete-directory' in that case. + + File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files Making Certain File Names "Magic" @@ -1047,46 +1179,3 @@ not be displayed in any windows. * Killing Buffers:: Buffers exist until explicitly killed. * Indirect Buffers:: An indirect buffer shares text with some other buffer. - -File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers - -Buffer Basics -============= - - A "buffer" is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the "current -buffer" at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - - Buffers in Emacs editing are objects that have distinct names and -hold text that can be edited. Buffers appear to Lisp programs as a -special data type. You can think of the contents of a buffer as an -extendable string; insertions and deletions may occur in any part of -the buffer. *Note Text::. - - A Lisp buffer object contains numerous pieces of information. Some -of this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -"buffer-local" variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as `fill-column' or `comment-column' in this way. For -more information about buffer-local variables and functions related to -them, see *Note Buffer-Local Variables::. - - For functions and variables related to visiting files in buffers, see -*Note Visiting Files:: and *Note Saving Buffers::. For functions and -variables related to the display of buffers in windows, see *Note -Buffers and Windows::. - - - Function: bufferp object - This function returns `t' if OBJECT is a buffer, `nil' otherwise. - diff --git a/info/lispref.info-25 b/info/lispref.info-25 index feffc1f..4c3e6d6 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -50,6 +50,49 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers + +Buffer Basics +============= + + A "buffer" is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers that are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the "current +buffer" at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any windows. + + Buffers in Emacs editing are objects that have distinct names and +hold text that can be edited. Buffers appear to Lisp programs as a +special data type. You can think of the contents of a buffer as an +extendable string; insertions and deletions may occur in any part of +the buffer. *Note Text::. + + A Lisp buffer object contains numerous pieces of information. Some +of this information is directly accessible to the programmer through +variables, while other information is accessible only through +special-purpose functions. For example, the visited file name is +directly accessible through a variable, while the value of point is +accessible only through a primitive function. + + Buffer-specific information that is directly accessible is stored in +"buffer-local" variable bindings, which are variable values that are +effective only in a particular buffer. This feature allows each buffer +to override the values of certain variables. Most major modes override +variables such as `fill-column' or `comment-column' in this way. For +more information about buffer-local variables and functions related to +them, see *Note Buffer-Local Variables::. + + For functions and variables related to visiting files in buffers, see +*Note Visiting Files:: and *Note Saving Buffers::. For functions and +variables related to the display of buffers in windows, see *Note +Buffers and Windows::. + + - Function: bufferp object + This function returns `t' if OBJECT is a buffer, `nil' otherwise. + + File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers The Current Buffer diff --git a/info/lispref.info-33 b/info/lispref.info-33 index 785b693..826fca3 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -684,10 +684,10 @@ functions in preference to the lower-level extent functions. For more information, *Note Annotations::. If an extent has its `detachable' property set, it will become -"detached" (i.e. no longer in the buffer) when all its text its -deleted. Otherwise, it will simply shrink down to zero-length and sit -it the same place in the buffer. By default, the `detachable' property -is set on newly-created extents. *Note Detached Extents::. +"detached" (i.e. no longer in the buffer) when all its text is deleted. +Otherwise, it will simply shrink down to zero-length and sit in the +same place in the buffer. By default, the `detachable' property is set +on newly-created extents. *Note Detached Extents::. If an extent has its `duplicable' property set, it will be remembered when a string is created from text bounded by the extent. diff --git a/info/lispref.info-35 b/info/lispref.info-35 index 83b50f0..db3eddf 100644 --- a/info/lispref.info-35 +++ b/info/lispref.info-35 @@ -138,7 +138,7 @@ and can be used to restrict the scope of that instantiator to a particular device class or device type and/or to mark instantiators added by a particular package so that they can be later removed. - A specifier tag set consists of a list of zero of more specifier + A specifier tag set consists of a list of zero or more specifier tags, each of which is a symbol that is recognized by XEmacs as a tag. (The valid device types and device classes are always tags, as are any tags defined by `define-specifier-tag'.) It is called a "tag set" (as @@ -358,10 +358,11 @@ Creating New Specifier Objects `font', `image', `face-boolean', or `toolbar'. For more information on particular types of specifiers, see the - functions `generic-specifier-p', `integer-specifier-p', - `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p', - `font-specifier-p', `image-specifier-p', - `face-boolean-specifier-p', and `toolbar-specifier-p'. + functions `make-generic-specifier', `make-integer-specifier', + `make-natnum-specifier', `make-boolean-specifier', + `make-color-specifier', `make-font-specifier', + `make-image-specifier', `make-face-boolean-specifier', and + `make-toolbar-specifier'. - Function: make-specifier-and-init type spec-list &optional dont-canonicalize @@ -377,6 +378,50 @@ Creating New Specifier Objects and the SPEC-LIST must already be in full form. See `canonicalize-spec-list'. + - Function: make-integer-specifier spec-list + Return a new `integer' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for integer specifiers are integers. + + - Function: make-boolean-specifier spec-list + Return a new `boolean' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for boolean specifiers are `t' and `nil'. + + - Function: make-natnum-specifier spec-list + Return a new `natnum' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for natnum specifiers are non-negative + integers. + + - Function: make-generic-specifier spec-list + Return a new `generic' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for generic specifiers are all Lisp values. + They are returned back unchanged when a specifier is instantiated. + + - Function: make-display-table-specifier spec-list + Return a new `display-table' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for display-table specifiers are described in + detail in the doc string for `current-display-table' (*note Active + Display Table::). +  File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers @@ -981,6 +1026,28 @@ Font Specifiers This predicate returns `t' if OBJECT is a font specifier, and `nil' otherwise. + - Function: make-font-specifier spec-list + Return a new `font' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Valid instantiators for font specifiers are: + + * A string naming a font (e.g. under X this might be + "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a + 14-point upright medium-weight Courier font). + + * A font instance (use that instance directly if the device + matches, or use the string that generated it). + + * A vector of no elements (only on TTY's; this means to set no + font at all, thus using the "natural" font of the terminal's + text). + + * A vector of one element (a face to inherit from). +  File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts @@ -1052,84 +1119,3 @@ Font Instance Size which is 1 point smaller. Otherwise, it returns the next smaller version of this font that is defined. - -File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts - -Font Instance Characteristics ------------------------------ - - - Function: font-instance-properties font - This function returns the properties (an alist or `nil') of - FONT-INSTANCE. - - - Function: x-make-font-bold font &optional device - Given an X font specification, this attempts to make a "bold" font. - If it fails, it returns `nil'. - - - Function: x-make-font-unbold font &optional device - Given an X font specification, this attempts to make a non-bold - font. If it fails, it returns `nil'. - - - Function: x-make-font-italic font &optional device - Given an X font specification, this attempts to make an "italic" - font. If it fails, it returns `nil'. - - - Function: x-make-font-unitalic font &optional device - Given an X font specification, this attempts to make a non-italic - font. If it fails, it returns `nil'. - - - Function: x-make-font-bold-italic font &optional device - Given an X font specification, this attempts to make a - "bold-italic" font. If it fails, it returns `nil'. - - -File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts - -Font Convenience Functions --------------------------- - - - Function: font-name font &optional domain - This function returns the name of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-name' to the result. - - - Function: font-truename font &optional domain - This function returns the truename of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-truename' to the result. - - - Function: font-properties font &optional domain - This function returns the properties of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-properties' to the result. - - -File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects - -Colors -====== - -* Menu: - -* Color Specifiers:: Specifying how a color will appear. -* Color Instances:: What a color specifier gets instanced as. -* Color Instance Properties:: Properties of color instances. -* Color Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties - of a color specifier. - - -File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors - -Color Specifiers ----------------- - - - Function: color-specifier-p object - This function returns non-`nil' if OBJECT is a color specifier. - diff --git a/info/lispref.info-36 b/info/lispref.info-36 index 473b7f6..c9d855f 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -50,6 +50,133 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts + +Font Instance Characteristics +----------------------------- + + - Function: font-instance-properties font + This function returns the properties (an alist or `nil') of + FONT-INSTANCE. + + - Function: x-make-font-bold font &optional device + Given an X font specification, this attempts to make a "bold" font. + If it fails, it returns `nil'. + + - Function: x-make-font-unbold font &optional device + Given an X font specification, this attempts to make a non-bold + font. If it fails, it returns `nil'. + + - Function: x-make-font-italic font &optional device + Given an X font specification, this attempts to make an "italic" + font. If it fails, it returns `nil'. + + - Function: x-make-font-unitalic font &optional device + Given an X font specification, this attempts to make a non-italic + font. If it fails, it returns `nil'. + + - Function: x-make-font-bold-italic font &optional device + Given an X font specification, this attempts to make a + "bold-italic" font. If it fails, it returns `nil'. + + +File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts + +Font Convenience Functions +-------------------------- + + - Function: font-name font &optional domain + This function returns the name of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-name' to the result. + + - Function: font-truename font &optional domain + This function returns the truename of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-truename' to the result. + + - Function: font-properties font &optional domain + This function returns the properties of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-properties' to the result. + + +File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects + +Colors +====== + +* Menu: + +* Color Specifiers:: Specifying how a color will appear. +* Color Instances:: What a color specifier gets instanced as. +* Color Instance Properties:: Properties of color instances. +* Color Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a color specifier. + + +File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors + +Color Specifiers +---------------- + + - Function: color-specifier-p object + This function returns non-`nil' if OBJECT is a color specifier. + + - Function: make-color-specifier spec-list + Return a new `color' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + a detailed description of how specifiers work. + + Valid instantiators for color specifiers are: + + * A string naming a color (e.g. under X this might be + "lightseagreen2" or "#F534B2"). + + * A color instance (use that instance directly if the device + matches, or use the string that generated it). + + * A vector of no elements (only on TTY's; this means to set no + color at all, thus using the "natural" color of the + terminal's text). + + * A vector of one or two elements: a face to inherit from, and + optionally a symbol naming which property of that face to + inherit, either `foreground' or `background' (if omitted, + defaults to the same property that this color specifier is + used for; if this specifier is not part of a face, the + instantiator would not be valid). + + - Function: make-face-boolean-specifier spec-list + Return a new `face-boolean' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + a detailed description of how specifiers work. + + Valid instantiators for face-boolean specifiers are + + * t or nil. + + * A vector of two or three elements: a face to inherit from, + optionally a symbol naming the property of that face to + inherit from (if omitted, defaults to the same property that + this face-boolean specifier is used for; if this specifier is + not part of a face, the instantiator would not be valid), and + optionally a value which, if non-nil, means to invert the + sense of the inherited property. + + + File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors Color Instances @@ -116,15 +243,15 @@ File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-S Glyphs ****** - A "glyph" is an object that is used for pixmaps and images of all -sorts, as well as for things that "act" like pixmaps, such as + A "glyph" is an object that is used for pixmaps, widgets and images +of all sorts, as well as for things that "act" like pixmaps, such as non-textual strings ("annotations") displayed in a buffer or in the -margins. It is used in begin-glyphs and end-glyphs attached to extents, -marginal and textual annotations, overlay arrows (`overlay-arrow-*' -variables), toolbar buttons, mouse pointers, frame icons, truncation and -continuation markers, and the like. (Basically, any place there is an -image or something that acts like an image, there will be a glyph object -representing it.) +margins. It is used in begin-glyphs and end-glyphs attached to +extents, marginal and textual annotations, overlay arrows +(`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame +icons, truncation and continuation markers, and the like. (Basically, +any place there is an image or something that acts like an image, there +will be a glyph object representing it.) The actual image that is displayed (as opposed to its position or clipping) is defined by an "image specifier" object contained within @@ -187,16 +314,202 @@ Creating Glyphs for the mouse-pointer), or `icon' (used for a frame's icon), and defaults to `buffer'. *Note Glyph Types::. + A glyph in XEmacs does *NOT* refer to a single unit of textual + display (the XEmacs term for this is "rune"), but rather is an + object encapsulating a graphical element, such as an image or + widget (an element such as a button or text field; "widget" is the + term for this under X Windows, and it's called a "control" under + MS Windows). This graphical element could appear in a buffer, a + margin, a gutter, or a toolbar, or as a mouse pointer or an icon, + for example. + + Creating a glyph using `make-glyph' does not specify _where_ the + glyph will be used, but it does specify _what_ the glyph will look + like. In particular, SPEC-LIST is used to specify this, and it's + used to initialize the glyph's `image' property, which is an image + specifier. (Note that "image" as used in the context of a glyph's + `image' property or in the terms "image specifier", "image + instantiator", or "image instance" does not refer to what people + normally think of as an image (which in XEmacs is called a + "pixmap"), but to any graphical element--a pixmap, a widget, or + even a block of text, when used in the places that call for a + glyph.) The format of the SPEC-LIST is typically an image + instantiator (a string or a vector; *Note Image Specifiers::), but + can also be a list of such instantiators (each one in turn is + tried until an image is successfully produced), a cons of a locale + (frame, buffer, etc.) and an instantiator, a list of such conses, + or any other form accepted by `canonicalize-spec-list'. *Note + Specifiers::, for more information about specifiers. + + If you're not familiar with specifiers, you should be in order to + understand how glyphs work. The clearest introduction to + specifiers is in the Lispref manual, available under Info. (Choose + Help->Info->Info Contents on the menubar or type C-h i.) You can + also see `make-specifier' for a capsule summary. What's important + to keep in mind is that a specifier lets you set a different value + for any particular buffer, window, frame, device, or console. + This allows for a great deal of flexibility; in particular, only + one global glyph needs to exist for a particular purpose (e.g. the + icon used to represent an iconified frame, the mouse pointer used + over particular areas of a frame, etc.), and in these cases you do + not create your own glyph, but rather modify the existing one. + + As well as using SPEC-LIST to initialize the glyph, you can set + specifications using `set-glyph-image'. Note that, due to a + possibly questionable historical design decision, a glyph itself + is not actually a specifier, but rather is an object containing an + image specifier (as well as other, seldom-used properties). + Therefore, you cannot set or access specifications for the glyph's + image by directly using `set-specifier', `specifier-instance' or + the like on the glyph; instead use them on `(glyph-image GLYPH)' + or use the convenience functions `set-glyph-image', + `glyph-image-instance', and `glyph-image'. + + Once you have created a glyph, you specify where it will be used as + follows: + + * To insert a glyph into a buffer, create an extent in the + buffer and then use `set-extent-begin-glyph' or + `set-extent-end-glyph' to set a glyph to be displayed at the + corresponding edge of the extent. (It is common to create + zero-width extents for this purpose.) + + * To insert a glyph into the left or right margin of a buffer, + first make sure the margin is visible by setting a value for + the specifiers `left-margin-width' or `right-margin-width'. + (Not strictly necessary when using margin glyphs with layout + policy `whitespace'.) Then follow the same procedure above + for inserting a glyph in a buffer, and then set a non-default + layout policy for the glyph using + `set-extent-begin-glyph-layout' or + `set-extent-end-glyph-layout'. Alternatively, use the + high-level annotations API (see `make-annotation'). (In point + of fact, you can also use the annotations API for glyphs in a + buffer, by setting a layout policy of `text'.) + + * To insert a glyph into the modeline, just put the glyph + directly as one of the modeline elements. (Unfortunately you + can't currently put a begin glyph or end glyph on one of the + modeline extents--they're ignored.) + + * To insert a glyph into a toolbar, specify it as part of a + toolbar instantiator (typically set on the specifier + `default-toolbar'). See `default-toolbar' for more + information. (Note that it is standard practice to use a + symbol in place of the glyph list in the toolbar + instantiator; the symbol is evalled to get the glyph list. + This facilitates both creating the toolbar instantiator and + modifying individual glyphs in a toolbar later on. For + example, you can change the way that the Mail toolbar button + looks by modifying the value of the variable + `toolbar-mail-icon' (in general, `toolbar-*-icon') and then + calling `(set-specifier-dirty-flag default-toolbar)'. (#### + Unfortunately this doesn't quite work the way it should; the + change will appear in new frames, but not existing ones. + + * To insert a glyph into a gutter, create or modify a gutter + instantiator (typically set on the specifier + `default-gutter'). Gutter instantiators consist of strings + or lists of strings, so to insert a glyph, create an extent + over the string, and use `set-extent-begin-glyph' or + `set-extent-end-glyph' to set a glyph to be displayed at the + corresponding edge of the extent, just like for glyphs in a + buffer. + + * To use a glyph as the icon for a frame, you do not actually + create a new glyph; rather, you change the specifications for + the existing glyph `frame-icon-glyph'. (Remember that, + because of the specifier nature of glyphs, you can set + different values for any particular buffer or frame.) + + * To use a glyph as the mouse pointer, in general you do not + create a new glyph, but rather you change the specifications + of various existing glyphs, such as `text-pointer-glyph' for + the pointer used over text, `modeline-pointer-glyph' for the + pointer used over the modeline, etc. Do an apropos over + `*-pointer-glyph' to find all of them. (Note also that you + can temporarily set the mouse pointer to some specific shape + by using `set-frame-pointer', which takes an image instace, + as obtained from calling `glyph-image-instance' on a glyph of + type `pointer' - either one of the above-mentioned variables + or one you created yourself. (See below for what it means to + create a glyph of type `pointer'.) This pointer will last + only until the next mouse motion event is processed or + certain other things happen, such as creating or deleting a + window. (In fact, the above-mentioned pointer glyph variables + are implemented as part of the default handler for mouse + motion events. If you want to customize this behavior, take a + look at `mode-motion-hook', or `mouse-motion-handler' if you + really want to get low-level.) + + * To use a glyph to control the shape of miscellaneous + redisplay effects such as the truncation and continuation + markers, set the appropriate existing glyph variables, as for + icons and pointers above. See `continuation-glyph', + `control-arrow-glyph', `hscroll-glyph', + `invisible-text-glyph', `octal-escape-glyph', and + `truncation-glyph'. See also `overlay-arrow-string', an odd + redisplay leftover which can be set to a glyph you created, + and will cause the glyph to be displayed on top of the text + position specified in the marker stored in + `overlay-arrow-position'. + + * To use a glyph in a display table (i.e. to control the + appearance of any individual character), create the + appropriate character glyphs and then set a specification for + the specifier `current-display-table', which controls the + appearance of characters. You can also set an overriding + display table for use with text displayed in a particular + face; see `set-face-display-table' and `make-display-table'. + #### Note: Display tables do not currently support general + Mule characters. They will be overhauled at some point to + support this and to provide other features required under + Mule. + + * To use a glyph as the background pixmap of a face: Note that + the background pixmap of a face is actually an image + specifier - probably the only place in XEmacs where an image + specifier occurs outside of a glyph. Similarly to how the + glyph's image specifier works, you don't create your own + image specifier, but rather add specifications to the + existing one (using `set-face-background-pixmap'). Note that + the image instance that is generated in order to actually + display the background pixmap is of type `mono-pixmap', + meaning that it's a two-color image and the foreground and + background of the image get filled in with the corresponding + colors from the face. + + It is extremely rare that you will ever have to specify a value for + TYPE, which should be one of `buffer' (used for glyphs in an + extent, the modeline, the toolbar, or elsewhere in a buffer), + `pointer' (used for the mouse-pointer), or `icon' (used for a + frame's icon), and defaults to `buffer'. The only cases where it + needs to be specified is when creating icon or pointer glyphs, and + in both cases the necessary glyphs have already been created at + startup and are accessed through the appropriate variables, e.g. + `text-pointer-glyph' (or in general, `*-pointer-glyph') and + `frame-icon-glyph'. *Note Glyph Types::. + - Function: make-glyph-internal &optional type This function creates a new, uninitialized glyph of type TYPE. - Function: make-pointer-glyph &optional spec-list - This function is equivalent to calling `make-glyph' with a TYPE of - `pointer'. + Return a new `pointer-glyph' object with the specification list + SPEC-LIST. This function is equivalent to calling `make-glyph' + with a TYPE of `pointer'. + + It is extremely unlikely that you will ever need to create a + pointer glyph. Instead, you probably want to be calling + `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'. - Function: make-icon-glyph &optional spec-list - This function is equivalent to calling `make-glyph' with a TYPE of - `icon'. + Return a new `pointer-glyph' object with the specification list + SPEC-LIST. This function is equivalent to calling `make-glyph' + with a TYPE of `icon'. + + It is extremely unlikely that you will ever need to create a + pointer glyph. Instead, you probably want to be calling + `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.  File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions @@ -507,657 +820,3 @@ Images are passed to `make-image-instance'. * Image Instances:: What an image specifier gets instanced as. - -File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images - -Image Specifiers ----------------- - - An image specifier is used to describe the actual image of a glyph. -It works like other specifiers (*note Specifiers::), in that it contains -a number of specifications describing how the image should appear in a -variety of circumstances. These specifications are called "image -instantiators". When XEmacs wants to display the image, it instantiates -the image into an "image instance". Image instances are their own -primitive object type (similar to font instances and color instances), -describing how the image appears in a particular domain. (On the other -hand, image instantiators, which are just descriptions of how the image -should appear, are represented using strings or vectors.) - - - Function: image-specifier-p object - This function returns non-`nil' if OBJECT is an image specifier. - Usually, an image specifier results from calling `glyph-image' on - a glyph. - - - Function: make-image-specifier spec-list - This function creates a new image specifier object and initializes - it according to SPEC-LIST. It is unlikely that you will ever want - to do this, but this function is provided for completeness and for - experimentation purposes. *Note Specifiers::. - - Image instantiators come in many formats: `xbm', `xpm', `gif', -`jpeg', etc. This describes the format of the data describing the -image. The resulting image instances also come in many -types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This -refers to the behavior of the image and the sorts of places it can -appear. (For example, a color-pixmap image has fixed colors specified -for it, while a mono-pixmap image comes in two unspecified shades -"foreground" and "background" that are determined from the face of the -glyph or surrounding text; a text image appears as a string of text and -has an unspecified foreground, background, and font; a pointer image -behaves like a mono-pixmap image but can only be used as a mouse -pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It -is important to keep the distinction between image instantiator format -and image instance type in mind. Typically, a given image instantiator -format can result in many different image instance types (for example, -`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer'; -whereas `cursor-font' can be instanced only as `pointer'), and a -particular image instance type can be generated by many different image -instantiator formats (e.g. `color-pixmap' can be generated by `xpm', -`gif', `jpeg', etc.). - - *Note Image Instances::, for a more detailed discussion of image -instance types. - - An image instantiator should be a string or a vector of the form - - `[FORMAT :KEYWORD VALUE ...]' - - i.e. a format symbol followed by zero or more alternating -keyword-value pairs. The "format" field should be a symbol, one of - -`nothing' - Don't display anything; no keywords are valid for this. Can only - be instanced as `nothing'. - -`string' - Display this image as a text string. Can only be instanced as - `text', although support for instancing as `mono-pixmap' should be - added. - -`formatted-string' - Display this image as a text string with replaceable fields, - similar to a modeline format string; not currently implemented. - -`xbm' - An X bitmap; only if X support was compiled into this XEmacs. Can - be instanced as `mono-pixmap', `color-pixmap', or `pointer'. - -`xpm' - An XPM pixmap; only if XPM support was compiled into this XEmacs. - Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'. - XPM is an add-on library for X that was designed to rectify the - shortcomings of the XBM format. Most implementations of X include - the XPM library as a standard part. If your vendor does not, it - is highly recommended that you download it and install it. You - can get it from the standard XEmacs FTP site, among other places. - -`xface' - An X-Face bitmap, used to encode people's faces in e-mail messages; - only if X-Face support was compiled into this XEmacs. Can be - instanced as `mono-pixmap', `color-pixmap', or `pointer'. - -`gif' - A GIF87 or GIF89 image; only if GIF support was compiled into this - XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs - includes GIF decoding functions as a standard part of it, so if - you have X support, you will normally have GIF support, unless you - explicitly disable it at configure time. - -`jpeg' - A JPEG-format image; only if JPEG support was compiled into this - XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG - libraries present on your system when XEmacs is built, XEmacs will - automatically detect this and use them, unless you explicitly - disable it at configure time. - -`png' - A PNG/GIF24 image; only if PNG support was compiled into this - XEmacs. Can be instanced as `color-pixmap'. - -`tiff' - A TIFF-format image; only if TIFF support was compiled into this - XEmacs. - -`cursor-font' - One of the standard cursor-font names, such as `watch' or - `right_ptr' under X. Under X, this is, more specifically, any of - the standard cursor names from appendix B of the Xlib manual [also - known as the file `'] minus the `XC_' prefix. On - other window systems, the valid names will be specific to the type - of window system. Can only be instanced as `pointer'. - -`font' - A glyph from a font; i.e. the name of a font, and glyph index into - it of the form `FONT fontname index [[mask-font] mask-index]'. - Only if X support was compiled into this XEmacs. Currently can - only be instanced as `pointer', although this should probably be - fixed. - -`subwindow' - An embedded X window; not currently implemented. - -`autodetect' - XEmacs tries to guess what format the data is in. If X support - exists, the data string will be checked to see if it names a - filename. If so, and this filename contains XBM or XPM data, the - appropriate sort of pixmap or pointer will be created. [This - includes picking up any specified hotspot or associated mask - file.] Otherwise, if `pointer' is one of the allowable - image-instance types and the string names a valid cursor-font - name, the image will be created as a pointer. Otherwise, the - image will be displayed as text. If no X support exists, the - image will always be displayed as text. - - The valid keywords are: - -`:data' - Inline data. For most formats above, this should be a string. For - XBM images, this should be a list of three elements: width, - height, and a string of bit data. This keyword is not valid for - instantiator format `nothing'. - -`:file' - Data is contained in a file. The value is the name of this file. - If both `:data' and `:file' are specified, the image is created - from what is specified in `:data' and the string in `:file' - becomes the value of the `image-instance-file-name' function when - applied to the resulting image-instance. This keyword is not - valid for instantiator formats `nothing', `string', - `formatted-string', `cursor-font', `font', and `autodetect'. - -`:foreground' -`:background' - For `xbm', `xface', `cursor-font', and `font'. These keywords - allow you to explicitly specify foreground and background colors. - The argument should be anything acceptable to - `make-color-instance'. This will cause what would be a - `mono-pixmap' to instead be colorized as a two-color color-pixmap, - and specifies the foreground and/or background colors for a pointer - instead of black and white. - -`:mask-data' - For `xbm' and `xface'. This specifies a mask to be used with the - bitmap. The format is a list of width, height, and bits, like for - `:data'. - -`:mask-file' - For `xbm' and `xface'. This specifies a file containing the mask - data. If neither a mask file nor inline mask data is given for an - XBM image, and the XBM image comes from a file, XEmacs will look - for a mask file with the same name as the image file but with - `Mask' or `msk' appended. For example, if you specify the XBM file - `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the - associated mask file `left_ptrmsk' will automatically be picked up. - -`:hotspot-x' -`:hotspot-y' - For `xbm' and `xface'. These keywords specify a hotspot if the - image is instantiated as a `pointer'. Note that if the XBM image - file specifies a hotspot, it will automatically be picked up if no - explicit hotspot is given. - -`:color-symbols' - Only for `xpm'. This specifies an alist that maps strings that - specify symbolic color names to the actual color to be used for - that symbolic color (in the form of a string or a color-specifier - object). If this is not specified, the contents of - `xpm-color-symbols' are used to generate the alist. - - If instead of a vector, the instantiator is a string, it will be -converted into a vector by looking it up according to the specs in the -`console-type-image-conversion-list' for the console type of the domain -(usually a window; sometimes a frame or device) over which the image is -being instantiated. - - If the instantiator specifies data from a file, the data will be -read in at the time that the instantiator is added to the image -specifier (which may be well before the image is actually displayed), -and the instantiator will be converted into one of the inline-data -forms, with the filename retained using a `:file' keyword. This -implies that the file must exist when the instantiator is added to the -image, but does not need to exist at any other time (e.g. it may safely -be a temporary file). - - - Function: valid-image-instantiator-format-p format - This function returns non-`nil' if FORMAT is a valid image - instantiator format. Note that the return value for many formats - listed above depends on whether XEmacs was compiled with support - for that format. - - - Function: image-instantiator-format-list - This function return a list of valid image-instantiator formats. - - - Variable: xpm-color-symbols - This variable holds definitions of logical color-names used when - reading XPM files. Elements of this list should be of the form - `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a - string, which is the name of the color to define; the - FORM-TO-EVALUATE should evaluate to a color specifier object, or a - string to be passed to `make-color-instance' (*note Colors::). If - a loaded XPM file references a symbolic color called COLOR-NAME, - it will display as the computed color instead. - - The default value of this variable defines the logical color names - `"foreground"' and `"background"' to be the colors of the - `default' face. - - - Variable: x-bitmap-file-path - 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). - - -File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images - -Image Instantiator Conversion ------------------------------ - - - Function: set-console-type-image-conversion-list console-type list - This function sets the image-conversion-list for consoles of the - given CONSOLE-TYPE. The image-conversion-list specifies how image - instantiators that are strings should be interpreted. Each - element of the list should be a list of two elements (a regular - expression string and a vector) or a list of three elements (the - preceding two plus an integer index into the vector). The string - is converted to the vector associated with the first matching - regular expression. If a vector index is specified, the string - itself is substituted into that position in the vector. - - Note: The conversion above is applied when the image instantiator - is added to an image specifier, not when the specifier is actually - instantiated. Therefore, changing the image-conversion-list only - affects newly-added instantiators. Existing instantiators in - glyphs and image specifiers will not be affected. - - - Function: console-type-image-conversion-list console-type - This function returns the image-conversion-list for consoles of - the given CONSOLE-TYPE. - - -File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images - -Image Instances ---------------- - - Image-instance objects encapsulate the way a particular image -(pixmap, etc.) is displayed on a particular device. - - In most circumstances, you do not need to directly create image -instances; use a glyph instead. However, it may occasionally be useful -to explicitly create image instances, if you want more control over the -instantiation process. - - - Function: image-instance-p object - This function returns non-`nil' if OBJECT is an image instance. - -* Menu: - -* Image Instance Types:: Each image instances has a particular type. -* Image Instance Functions:: Functions for working with image instances. - - -File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances - -Image Instance Types -.................... - - Image instances come in a number of different types. The type of an -image instance specifies the nature of the image: Whether it is a text -string, a mono pixmap, a color pixmap, etc. - - The valid image instance types are - -`nothing' - Nothing is displayed. - -`text' - Displayed as text. The foreground and background colors and the - font of the text are specified independent of the pixmap. - Typically these attributes will come from the face of the - surrounding text, unless a face is specified for the glyph in - which the image appears. - -`mono-pixmap' - Displayed as a mono pixmap (a pixmap with only two colors where the - foreground and background can be specified independent of the - pixmap; typically the pixmap assumes the foreground and background - colors of the text around it, unless a face is specified for the - glyph in which the image appears). - -`color-pixmap' - Displayed as a color pixmap. - -`pointer' - Used as the mouse pointer for a window. - -`subwindow' - A child window that is treated as an image. This allows (e.g.) - another program to be responsible for drawing into the window. - Not currently implemented. - - - Function: valid-image-instance-type-p type - This function returns non-`nil' if TYPE is a valid image instance - type. - - - Function: image-instance-type-list - This function returns a list of the valid image instance types. - - - Function: image-instance-type image-instance - This function returns the type of the given image instance. The - return value will be one of `nothing', `text', `mono-pixmap', - `color-pixmap', `pointer', or `subwindow'. - - - Function: text-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `text'. - - - Function: mono-pixmap-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `mono-pixmap'. - - - Function: color-pixmap-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `color-pixmap'. - - - Function: pointer-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `pointer'. - - - Function: subwindow-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `subwindow'. - - - Function: nothing-image-instance-p object - This function returns non-`nil' if OBJECT is an image instance of - type `nothing'. - - -File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances - -Image Instance Functions -........................ - - - Function: make-image-instance data &optional device dest-types - no-error - This function creates a new image-instance object. - - DATA is an image instantiator, which describes the image (*note - Image Specifiers::). - - DEST-TYPES should be a list of allowed image instance types that - can be generated. The DEST-TYPES list is unordered. If multiple - destination types are possible for a given instantiator, the "most - natural" type for the instantiator's format is chosen. (For XBM, - the most natural types are `mono-pixmap', followed by - `color-pixmap', followed by `pointer'. For the other normal image - formats, the most natural types are `color-pixmap', followed by - `mono-pixmap', followed by `pointer'. For the string and - formatted-string formats, the most natural types are `text', - followed by `mono-pixmap' (not currently implemented), followed by - `color-pixmap' (not currently implemented). The other formats can - only be instantiated as one type. (If you want to control more - specifically the order of the types into which an image is - instantiated, just call `make-image-instance' repeatedly until it - succeeds, passing less and less preferred destination types each - time. - - If DEST-TYPES is omitted, all possible types are allowed. - - NO-ERROR controls what happens when the image cannot be generated. - If NIL, an error message is generated. If T, no messages are - generated and this function returns NIL. If anything else, a - warning message is generated and this function returns NIL. - - - Function: colorize-image-instance image-instance foreground - background - This function makes the image instance be displayed in the given - colors. Image instances come in two varieties: bitmaps, which are - 1 bit deep which are rendered in the prevailing foreground and - background colors; and pixmaps, which are of arbitrary depth - (including 1) and which have the colors explicitly specified. - This function converts a bitmap to a pixmap. If the image - instance was a pixmap already, nothing is done (and `nil' is - returned). Otherwise `t' is returned. - - - Function: image-instance-name image-instance - This function returns the name of the given image instance. - - - Function: image-instance-string image-instance - This function returns the string of the given image instance. - This will only be non-`nil' for text image instances. - - - Function: image-instance-file-name image-instance - This function returns the file name from which IMAGE-INSTANCE was - read, if known. - - - Function: image-instance-mask-file-name image-instance - This function returns the file name from which IMAGE-INSTANCE's - mask was read, if known. - - - Function: image-instance-depth image-instance - This function returns the depth of the image instance. This is 0 - for a mono pixmap, or a positive integer for a color pixmap. - - - Function: image-instance-height image-instance - This function returns the height of the image instance, in pixels. - - - Function: image-instance-width image-instance - This function returns the width of the image instance, in pixels. - - - Function: image-instance-hotspot-x image-instance - This function returns the X coordinate of the image instance's - hotspot, if known. This is a point relative to the origin of the - pixmap. When an image is used as a mouse pointer, the hotspot is - the point on the image that sits over the location that the - pointer points to. This is, for example, the tip of the arrow or - the center of the crosshairs. - - This will always be `nil' for a non-pointer image instance. - - - Function: image-instance-hotspot-y image-instance - This function returns the Y coordinate of the image instance's - hotspot, if known. - - - Function: image-instance-foreground image-instance - This function returns the foreground color of IMAGE-INSTANCE, if - applicable. This will be a color instance or `nil'. (It will only - be non-`nil' for colorized mono pixmaps and for pointers.) - - - Function: image-instance-background image-instance - This function returns the background color of IMAGE-INSTANCE, if - applicable. This will be a color instance or `nil'. (It will only - be non-`nil' for colorized mono pixmaps and for pointers.) - - -File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs - -Glyph Types -=========== - - Each glyph has a particular type, which controls how the glyph's -image is generated. Each glyph type has a corresponding list of -allowable image instance types that can be generated. When you call -`glyph-image-instance' to retrieve the image instance of a glyph, -XEmacs does the equivalent of calling `make-image-instance' and passing -in DEST-TYPES the list of allowable image instance types for the -glyph's type. - - * `buffer' glyphs can be used as the begin-glyph or end-glyph of an - extent, in the modeline, and in the toolbar. Their image can be - instantiated as `nothing', `mono-pixmap', `color-pixmap', `text', - and `subwindow'. - - * `pointer' glyphs can be used to specify the mouse pointer. Their - image can be instantiated as `pointer'. - - * `icon' glyphs can be used to specify the icon used when a frame is - iconified. Their image can be instantiated as `mono-pixmap' and - `color-pixmap'. - - - Function: glyph-type glyph - This function returns the type of the given glyph. The return - value will be a symbol, one of `buffer', `pointer', or `icon'. - - - Function: valid-glyph-type-p glyph-type - Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. - - - Function: glyph-type-list - This function returns a list of valid glyph types. - - - Function: buffer-glyph-p object - This function returns non-`nil' if OBJECT is a glyph of type - `buffer'. - - - Function: icon-glyph-p object - This function returns non-`nil' if OBJECT is a glyph of type - `icon'. - - - Function: pointer-glyph-p object - This function returns non-`nil' if OBJECT is a glyph of type - `pointer'. - - -File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs - -Mouse Pointer -============= - - The shape of the mouse pointer when over a particular section of a -frame is controlled using various glyph variables. Since the image of -a glyph is a specifier, it can be controlled on a per-buffer, -per-frame, per-window, or per-device basis. - - You should use `set-glyph-image' to set the following variables, -_not_ `setq'. - - - Glyph: text-pointer-glyph - This variable specifies the shape of the mouse pointer when over - text. - - - Glyph: nontext-pointer-glyph - This variable specifies the shape of the mouse pointer when over a - buffer, but not over text. If unspecified in a particular domain, - `text-pointer-glyph' is used. - - - Glyph: modeline-pointer-glyph - This variable specifies the shape of the mouse pointer when over - the modeline. If unspecified in a particular domain, - `nontext-pointer-glyph' is used. - - - Glyph: selection-pointer-glyph - This variable specifies the shape of the mouse pointer when over a - selectable text region. If unspecified in a particular domain, - `text-pointer-glyph' is used. - - - Glyph: gc-pointer-glyph - This variable specifies the shape of the mouse pointer when a - garbage collection is in progress. If the selected window is on a - window system and this glyph specifies a value (i.e. a pointer - image instance) in the domain of the selected window, the pointer - will be changed as specified during garbage collection. - Otherwise, a message will be printed in the echo area, as - controlled by `gc-message'. - - - Glyph: busy-pointer-glyph - This variable specifies the shape of the mouse pointer when XEmacs - is busy. If unspecified in a particular domain, the pointer is - not changed when XEmacs is busy. - - - Glyph: menubar-pointer-glyph - This variable specifies the shape of the mouse pointer when over - the menubar. If unspecified in a particular domain, the - window-system-provided default pointer is used. - - - Glyph: scrollbar-pointer-glyph - This variable specifies the shape of the mouse pointer when over a - scrollbar. If unspecified in a particular domain, the - window-system-provided default pointer is used. - - - Glyph: toolbar-pointer-glyph - This variable specifies the shape of the mouse pointer when over a - toolbar. If unspecified in a particular domain, - `nontext-pointer-glyph' is used. - - Internally, these variables are implemented in -`default-mouse-motion-handler', and thus only take effect when the -mouse moves. That function calls `set-frame-pointer', which sets the -current mouse pointer for a frame. - - - Function: set-frame-pointer frame image-instance - This function sets the mouse pointer of FRAME to the given pointer - image instance. You should not call this function directly. (If - you do, the pointer will change again the next time the mouse - moves.) - - -File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs - -Redisplay Glyphs -================ - - - Glyph: truncation-glyph - This variable specifies what is displayed at the end of truncated - lines. - - - Glyph: continuation-glyph - This variable specifies what is displayed at the end of wrapped - lines. - - - Glyph: octal-escape-glyph - This variable specifies what to prefix character codes displayed - in octal with. - - - Glyph: hscroll-glyph - This variable specifies what to display at the beginning of - horizontally scrolled lines. - - - Glyph: invisible-text-glyph - This variable specifies what to use to indicate the presence of - invisible text. This is the glyph that is displayed when an - ellipsis is called for, according to `selective-display-ellipses' - or `buffer-invisibility-spec'). Normally this is three dots - ("..."). - - - Glyph: control-arrow-glyph - This variable specifies what to use as an arrow for control - characters. - - -File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs - -Subwindows -========== - - Subwindows are not currently implemented. - - - Function: subwindowp object - This function returns non-`nil' if OBJECT is a subwindow. - - -File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top - -Annotations -*********** - - An "annotation" is a pixmap or string that is not part of a buffer's -text but is displayed next to a particular location in a buffer. -Annotations can be displayed intermixed with text, in any whitespace at -the beginning or end of a line, or in a special area at the left or -right side of the frame called a "margin", whose size is controllable. -Annotations are implemented using extents (*note Extents::); but you -can work with annotations without knowing how extents work. - -* Menu: - -* Annotation Basics:: Introduction to annotations. -* Annotation Primitives:: Creating and deleting annotations. -* Annotation Properties:: Retrieving and changing the characteristics - of an annotation. -* Margin Primitives:: Controlling the size of the margins. -* Locating Annotations:: Looking for annotations in a buffer. -* Annotation Hooks:: Hooks called at certain times during an - annotation's lifetime. - diff --git a/info/lispref.info-37 b/info/lispref.info-37 index 7a64c76..d4e9b21 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -50,6 +50,809 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images + +Image Specifiers +---------------- + + An image specifier is used to describe the actual image of a glyph. +It works like other specifiers (*note Specifiers::), in that it contains +a number of specifications describing how the image should appear in a +variety of circumstances. These specifications are called "image +instantiators". When XEmacs wants to display the image, it instantiates +the image into an "image instance". Image instances are their own +primitive object type (similar to font instances and color instances), +describing how the image appears in a particular domain. (On the other +hand, image instantiators, which are just descriptions of how the image +should appear, are represented using strings or vectors.) + + - Function: image-specifier-p object + This function returns non-`nil' if OBJECT is an image specifier. + Usually, an image specifier results from calling `glyph-image' on + a glyph. + + - Function: make-image-specifier spec-list + This function creates a new image specifier object and initializes + it according to SPEC-LIST. *Note Specifiers::. + + Note that, in practice, you rarely, if ever, need to actually + create an image specifier! (This function exists mainly for + completeness.) Pretty much the only use for image specifiers is to + control how glyphs are displayed, and the image specifier + associated with a glyph (the `image' property of a glyph) is + created automatically when a glyph is created and need not (and + cannot, for that matter) ever be changed (*note Glyphs::). In + fact, the design decision to create a separate image specifier + type, rather than make glyphs themselves be specifiers, is + debatable--the other properties of glyphs are rarely used and could + conceivably have been incorporated into the glyph's instantiator. + The rarely used glyph types (buffer, pointer, icon) could also + have been incorporated into the instantiator. + + Image instantiators come in many formats: `xbm', `xpm', `gif', +`jpeg', etc. This describes the format of the data describing the +image. The resulting image instances also come in many +types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This +refers to the behavior of the image and the sorts of places it can +appear. (For example, a color-pixmap image has fixed colors specified +for it, while a mono-pixmap image comes in two unspecified shades +"foreground" and "background" that are determined from the face of the +glyph or surrounding text; a text image appears as a string of text and +has an unspecified foreground, background, and font; a pointer image +behaves like a mono-pixmap image but can only be used as a mouse +pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It +is important to keep the distinction between image instantiator format +and image instance type in mind. Typically, a given image instantiator +format can result in many different image instance types (for example, +`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer'; +whereas `cursor-font' can be instanced only as `pointer'), and a +particular image instance type can be generated by many different image +instantiator formats (e.g. `color-pixmap' can be generated by `xpm', +`gif', `jpeg', etc.). + + *Note Image Instances::, for a more detailed discussion of image +instance types. + + An image instantiator should be a string or a vector of the form + + `[FORMAT :KEYWORD VALUE ...]' + + i.e. a format symbol followed by zero or more alternating +keyword-value pairs. The "format" field should be a symbol, one of + +`nothing' + Don't display anything; no keywords are valid for this. Can only + be instanced as `nothing'. + +`string' + Display this image as a text string. Can only be instanced as + `text', although support for instancing as `mono-pixmap' should be + added. + +`formatted-string' + Display this image as a text string with replaceable fields, + similar to a modeline format string; not currently implemented. + +`xbm' + An X bitmap; only if X support was compiled into this XEmacs. Can + be instanced as `mono-pixmap', `color-pixmap', or `pointer'. + +`xpm' + An XPM pixmap; only if XPM support was compiled into this XEmacs. + Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'. + XPM is an add-on library for X that was designed to rectify the + shortcomings of the XBM format. Most implementations of X include + the XPM library as a standard part. If your vendor does not, it + is highly recommended that you download it and install it. You + can get it from the standard XEmacs FTP site, among other places. + +`xface' + An X-Face bitmap, used to encode people's faces in e-mail messages; + only if X-Face support was compiled into this XEmacs. Can be + instanced as `mono-pixmap', `color-pixmap', or `pointer'. + +`gif' + A GIF87 or GIF89 image; only if GIF support was compiled into this + XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs + includes GIF decoding functions as a standard part of it, so if + you have X support, you will normally have GIF support, unless you + explicitly disable it at configure time. + +`jpeg' + A JPEG-format image; only if JPEG support was compiled into this + XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG + libraries present on your system when XEmacs is built, XEmacs will + automatically detect this and use them, unless you explicitly + disable it at configure time. + +`png' + A PNG/GIF24 image; only if PNG support was compiled into this + XEmacs. Can be instanced as `color-pixmap'. + +`tiff' + A TIFF-format image; only if TIFF support was compiled into this + XEmacs. + +`cursor-font' + One of the standard cursor-font names, such as `watch' or + `right_ptr' under X. Under X, this is, more specifically, any of + the standard cursor names from appendix B of the Xlib manual [also + known as the file `'] minus the `XC_' prefix. On + other window systems, the valid names will be specific to the type + of window system. Can only be instanced as `pointer'. + +`font' + A glyph from a font; i.e. the name of a font, and glyph index into + it of the form `FONT fontname index [[mask-font] mask-index]'. + Only if X support was compiled into this XEmacs. Currently can + only be instanced as `pointer', although this should probably be + fixed. + +`mswindows-resource' + An MS Windows pointer resource. Specifies a resource to retrieve + directly from the system (an OEM resource) or from a file, + particularly an executable file. If the resource is to be + retrieved from a file, use :file and optionally :resource-id. + Otherwise use :resource-id. Always specify :resource-type to + specify the type (cursor, bitmap or icon) of the resource. + Possible values for :resource-id are listed below. Can be + instanced as `pointer' or `color-pixmap'. + +`subwindow' + An embedded windowing system window. Can only be instanced as + `subwindow'. + +`button' + A button widget; either a push button, radio button or toggle + button. Can only be instanced as `widget'. + +`combo-box' + A drop list of selectable items in a widget, for editing text. + Can only be instanced as `widget'. + +`edit-field' + A text editing widget. Can only be instanced as `widget'. + +`label' + A static, text-only, widget; for displaying text. Can only be + instanced as `widget'. + +`layout' + A widget for controlling the positioning of children underneath it. + Through the use of nested layouts, a widget hierarchy can be + created which can have the appearance of any standard dialog box + or similar arrangement; all of this is counted as one "glyph" and + could appear in many of the places that expect a single glyph. + Can only be instanced as `widget'. + +`native-layout' + The native version of a layout widget. Can only be instanced as + `widget'. + +`progress-gauge' + A sliding widget, for showing progress. Can only be instanced as + `widget'. + +`tab-control' + A tab widget; a series of user selectable tabs. Can only be + instanced as `widget'. + +`tree-view' + A folding widget. Can only be instanced as `widget'. + +`scrollbar' + A scrollbar widget. Can only be instanced as `widget'. + +`autodetect' + XEmacs tries to guess what format the data is in. If X support + exists, the data string will be checked to see if it names a + filename. If so, and this filename contains XBM or XPM data, the + appropriate sort of pixmap or pointer will be created. [This + includes picking up any specified hotspot or associated mask + file.] Otherwise, if `pointer' is one of the allowable + image-instance types and the string names a valid cursor-font + name, the image will be created as a pointer. Otherwise, the + image will be displayed as text. If no X support exists, the + image will always be displayed as text. + +`inherit' + Inherit from the background-pixmap property of a face. Can only be + instanced as `mono-pixmap'. + + The valid keywords are: + +`:data' + Inline data. For most formats above, this should be a string. For + XBM images, this should be a list of three elements: width, + height, and a string of bit data. This keyword is not valid for + instantiator format `nothing'. + +`:file' + Data is contained in a file. The value is the name of this file. + If both `:data' and `:file' are specified, the image is created + from what is specified in `:data' and the string in `:file' + becomes the value of the `image-instance-file-name' function when + applied to the resulting image-instance. This keyword is not + valid for instantiator formats `nothing', `string', + `formatted-string', `cursor-font', `font', and `autodetect'. + +`:foreground' +`:background' + For `xbm', `xface', `cursor-font', and `font'. These keywords + allow you to explicitly specify foreground and background colors. + The argument should be anything acceptable to + `make-color-instance'. This will cause what would be a + `mono-pixmap' to instead be colorized as a two-color color-pixmap, + and specifies the foreground and/or background colors for a pointer + instead of black and white. + +`:mask-data' + For `xbm' and `xface'. This specifies a mask to be used with the + bitmap. The format is a list of width, height, and bits, like for + `:data'. + +`:mask-file' + For `xbm' and `xface'. This specifies a file containing the mask + data. If neither a mask file nor inline mask data is given for an + XBM image, and the XBM image comes from a file, XEmacs will look + for a mask file with the same name as the image file but with + `Mask' or `msk' appended. For example, if you specify the XBM file + `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the + associated mask file `left_ptrmsk' will automatically be picked up. + +`:hotspot-x' +`:hotspot-y' + For `xbm' and `xface'. These keywords specify a hotspot if the + image is instantiated as a `pointer'. Note that if the XBM image + file specifies a hotspot, it will automatically be picked up if no + explicit hotspot is given. + +`:color-symbols' + Only for `xpm'. This specifies an alist that maps strings that + specify symbolic color names to the actual color to be used for + that symbolic color (in the form of a string or a color-specifier + object). If this is not specified, the contents of + `xpm-color-symbols' are used to generate the alist. + +`:resource-id' + Only for `mswindows-resource'. This must be either an integer + (which directly specifies a resource number) or a string. Valid + strings are + + For bitmaps: + + "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce", + "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd", + "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo", + "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize", + "check", "checkboxes", and "btncorners". + + For cursors: + + "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw", + "sizewe", "sizens", "sizeall", and "no". + + For icons: + + "sample", "hand", "ques", "bang", "note", and "winlogo". + +`:resource-type' + Only for `mswindows-resource'. This must be a symbol, either + `cursor', `icon', or `bitmap', specifying the type of resource to + be retrieved. + +`:face' + Only for `inherit'. This specifies the face to inherit from. For + widgets this also specifies the face to use for display. It + defaults to gui-element-face. + + Keywords accepted as menu item specs are also accepted by widgets. +These are `:selected', `:active', `:suffix', `:keys', `:style', +`:filter', `:config', `:included', `:key-sequence', `:accelerator', +`:label' and `:callback'. + + If instead of a vector, the instantiator is a string, it will be +converted into a vector by looking it up according to the specs in the +`console-type-image-conversion-list' for the console type of the domain +(usually a window; sometimes a frame or device) over which the image is +being instantiated. + + If the instantiator specifies data from a file, the data will be +read in at the time that the instantiator is added to the image +specifier (which may be well before the image is actually displayed), +and the instantiator will be converted into one of the inline-data +forms, with the filename retained using a `:file' keyword. This +implies that the file must exist when the instantiator is added to the +image, but does not need to exist at any other time (e.g. it may safely +be a temporary file). + + - Function: valid-image-instantiator-format-p format + This function returns non-`nil' if FORMAT is a valid image + instantiator format. Note that the return value for many formats + listed above depends on whether XEmacs was compiled with support + for that format. + + - Function: image-instantiator-format-list + This function return a list of valid image-instantiator formats. + + - Variable: xpm-color-symbols + This variable holds definitions of logical color-names used when + reading XPM files. Elements of this list should be of the form + `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a + string, which is the name of the color to define; the + FORM-TO-EVALUATE should evaluate to a color specifier object, or a + string to be passed to `make-color-instance' (*note Colors::). If + a loaded XPM file references a symbolic color called COLOR-NAME, + it will display as the computed color instead. + + The default value of this variable defines the logical color names + `"foreground"' and `"background"' to be the colors of the + `default' face. + + - Variable: x-bitmap-file-path + 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). + + +File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images + +Image Instantiator Conversion +----------------------------- + + - Function: set-console-type-image-conversion-list console-type list + This function sets the image-conversion-list for consoles of the + given CONSOLE-TYPE. The image-conversion-list specifies how image + instantiators that are strings should be interpreted. Each + element of the list should be a list of two elements (a regular + expression string and a vector) or a list of three elements (the + preceding two plus an integer index into the vector). The string + is converted to the vector associated with the first matching + regular expression. If a vector index is specified, the string + itself is substituted into that position in the vector. + + Note: The conversion above is applied when the image instantiator + is added to an image specifier, not when the specifier is actually + instantiated. Therefore, changing the image-conversion-list only + affects newly-added instantiators. Existing instantiators in + glyphs and image specifiers will not be affected. + + - Function: console-type-image-conversion-list console-type + This function returns the image-conversion-list for consoles of + the given CONSOLE-TYPE. + + +File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images + +Image Instances +--------------- + + Image-instance objects encapsulate the way a particular image +(pixmap, etc.) is displayed on a particular device. + + In most circumstances, you do not need to directly create image +instances; use a glyph instead. However, it may occasionally be useful +to explicitly create image instances, if you want more control over the +instantiation process. + + - Function: image-instance-p object + This function returns non-`nil' if OBJECT is an image instance. + +* Menu: + +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances. + + +File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances + +Image Instance Types +.................... + + Image instances come in a number of different types. The type of an +image instance specifies the nature of the image: Whether it is a text +string, a mono pixmap, a color pixmap, etc. + + The valid image instance types are + +`nothing' + Nothing is displayed. + +`text' + Displayed as text. The foreground and background colors and the + font of the text are specified independent of the pixmap. + Typically these attributes will come from the face of the + surrounding text, unless a face is specified for the glyph in + which the image appears. + +`mono-pixmap' + Displayed as a mono pixmap (a pixmap with only two colors where the + foreground and background can be specified independent of the + pixmap; typically the pixmap assumes the foreground and background + colors of the text around it, unless a face is specified for the + glyph in which the image appears). + +`color-pixmap' + Displayed as a color pixmap. + +`pointer' + Used as the mouse pointer for a window. + +`subwindow' + A child window that is treated as an image. This allows (e.g.) + another program to be responsible for drawing into the window. + Not currently implemented. + + - Function: valid-image-instance-type-p type + This function returns non-`nil' if TYPE is a valid image instance + type. + + - Function: image-instance-type-list + This function returns a list of the valid image instance types. + + - Function: image-instance-type image-instance + This function returns the type of the given image instance. The + return value will be one of `nothing', `text', `mono-pixmap', + `color-pixmap', `pointer', or `subwindow'. + + - Function: text-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `text'. + + - Function: mono-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `mono-pixmap'. + + - Function: color-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `color-pixmap'. + + - Function: pointer-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `pointer'. + + - Function: subwindow-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `subwindow'. + + - Function: nothing-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `nothing'. + + - Function: widget-image-instance-p object + Return t if OBJECT is an image instance of type `widget'. + + +File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances + +Image Instance Functions +........................ + + - Function: make-image-instance data &optional domain dest-types + no-error + This function creates a new image-instance object. + + DATA is an image instantiator, which describes the image (*note + Image Specifiers::). + + DEST-TYPES should be a list of allowed image instance types that + can be generated. The DEST-TYPES list is unordered. If multiple + destination types are possible for a given instantiator, the "most + natural" type for the instantiator's format is chosen. (For XBM, + the most natural types are `mono-pixmap', followed by + `color-pixmap', followed by `pointer'. For the other normal image + formats, the most natural types are `color-pixmap', followed by + `mono-pixmap', followed by `pointer'. For the string and + formatted-string formats, the most natural types are `text', + followed by `mono-pixmap' (not currently implemented), followed by + `color-pixmap' (not currently implemented). For MS Windows + resources, the most natural type for pointer resources is + `pointer', and for the others it's `color-pixmap'. The other + formats can only be instantiated as one type. (If you want to + control more specifically the order of the types into which an + image is instantiated, just call `make-image-instance' repeatedly + until it succeeds, passing less and less preferred destination + types each time. + + If DEST-TYPES is omitted, all possible types are allowed. + + DOMAIN specifies the domain to which the image instance will be + attached. This domain is termed the "governing domain". The type + of the governing domain depends on the image instantiator format. + (Although, more correctly, it should probably depend on the image + instance type.) For example, pixmap image instances are specific + to a device, but widget image instances are specific to a + particular XEmacs window because in order to display such a widget + when two windows onto the same buffer want to display the widget, + two separate underlying widgets must be created. (That's because a + widget is actually a child window-system window, and all + window-system windows have a unique existence on the screen.) This + means that the governing domain for a pixmap image instance will + be some device (most likely, the only existing device), whereas + the governing domain for a widget image instance will be some + XEmacs window. + + If you specify an overly general DOMAIN (e.g. a frame when a + window was wanted), an error is signaled. If you specify an overly + specific DOMAIN (e.g. a window when a device was wanted), the + corresponding general domain is fetched and used instead. For + `make-image-instance', it makes no difference whether you specify + an overly specific domain or the properly general domain derived + from it. However, it does matter when creating an image instance + by instantiating a specifier or glyph (e.g. with + `glyph-image-instance'), because the more specific domain causes + spec lookup to start there and proceed to more general domains. (It + would also matter when creating an image instance with an + instantiator format of `inherit', but we currently disallow this. + #### We should fix this.) n If omitted, DOMAIN defaults to the + selected window. + + NO-ERROR controls what happens when the image cannot be generated. + If NIL, an error message is generated. If T, no messages are + generated and this function returns NIL. If anything else, a + warning message is generated and this function returns NIL. + + - Function: colorize-image-instance image-instance foreground + background + This function makes the image instance be displayed in the given + colors. Image instances come in two varieties: bitmaps, which are + 1 bit deep which are rendered in the prevailing foreground and + background colors; and pixmaps, which are of arbitrary depth + (including 1) and which have the colors explicitly specified. + This function converts a bitmap to a pixmap. If the image + instance was a pixmap already, nothing is done (and `nil' is + returned). Otherwise `t' is returned. + + - Function: image-instance-name image-instance + This function returns the name of the given image instance. + + - Function: image-instance-domain image-instance + Return the governing domain of the given IMAGE-INSTANCE. The + governing domain of an image instance is the domain that the image + instance is specific to. It is _NOT_ necessarily the domain that + was given to the call to `specifier-instance' that resulted in the + creation of this image instance. See `make-image-instance' for + more information on governing domains. + + - Function: image-instance-string image-instance + This function returns the string of the given image instance. + This will only be non-`nil' for text image instances. + + - Function: image-instance-file-name image-instance + This function returns the file name from which IMAGE-INSTANCE was + read, if known. + + - Function: image-instance-mask-file-name image-instance + This function returns the file name from which IMAGE-INSTANCE's + mask was read, if known. + + - Function: image-instance-depth image-instance + This function returns the depth of the image instance. This is 0 + for a mono pixmap, or a positive integer for a color pixmap. + + - Function: image-instance-height image-instance + This function returns the height of the image instance, in pixels. + + - Function: image-instance-width image-instance + This function returns the width of the image instance, in pixels. + + - Function: image-instance-hotspot-x image-instance + This function returns the X coordinate of the image instance's + hotspot, if known. This is a point relative to the origin of the + pixmap. When an image is used as a mouse pointer, the hotspot is + the point on the image that sits over the location that the + pointer points to. This is, for example, the tip of the arrow or + the center of the crosshairs. + + This will always be `nil' for a non-pointer image instance. + + - Function: image-instance-hotspot-y image-instance + This function returns the Y coordinate of the image instance's + hotspot, if known. + + - Function: image-instance-foreground image-instance + This function returns the foreground color of IMAGE-INSTANCE, if + applicable. This will be a color instance or `nil'. (It will only + be non-`nil' for colorized mono pixmaps and for pointers.) + + - Function: image-instance-background image-instance + This function returns the background color of IMAGE-INSTANCE, if + applicable. This will be a color instance or `nil'. (It will only + be non-`nil' for colorized mono pixmaps and for pointers.) + + +File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs + +Glyph Types +=========== + + Each glyph has a particular type, which controls how the glyph's +image is generated. Each glyph type has a corresponding list of +allowable image instance types that can be generated. When you call +`glyph-image-instance' to retrieve the image instance of a glyph, +XEmacs does the equivalent of calling `make-image-instance' and passing +in DEST-TYPES the list of allowable image instance types for the +glyph's type. + + * `buffer' glyphs can be used as the begin-glyph or end-glyph of an + extent, in the modeline, and in the toolbar. Their image can be + instantiated as `nothing', `mono-pixmap', `color-pixmap', `text', + and `subwindow'. + + * `pointer' glyphs can be used to specify the mouse pointer. Their + image can be instantiated as `pointer'. + + * `icon' glyphs can be used to specify the icon used when a frame is + iconified. Their image can be instantiated as `mono-pixmap' and + `color-pixmap'. + + - Function: glyph-type glyph + This function returns the type of the given glyph. The return + value will be a symbol, one of `buffer', `pointer', or `icon'. + + - Function: valid-glyph-type-p glyph-type + Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. + + - Function: glyph-type-list + This function returns a list of valid glyph types. + + - Function: buffer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `buffer'. + + - Function: icon-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `icon'. + + - Function: pointer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `pointer'. + + +File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs + +Mouse Pointer +============= + + The shape of the mouse pointer when over a particular section of a +frame is controlled using various glyph variables. Since the image of +a glyph is a specifier, it can be controlled on a per-buffer, +per-frame, per-window, or per-device basis. + + You should use `set-glyph-image' to set the following variables, +_not_ `setq'. + + - Glyph: text-pointer-glyph + This variable specifies the shape of the mouse pointer when over + text. + + - Glyph: nontext-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + buffer, but not over text. If unspecified in a particular domain, + `text-pointer-glyph' is used. + + - Glyph: modeline-pointer-glyph + This variable specifies the shape of the mouse pointer when over + the modeline. If unspecified in a particular domain, + `nontext-pointer-glyph' is used. + + - Glyph: selection-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + selectable text region. If unspecified in a particular domain, + `text-pointer-glyph' is used. + + - Glyph: gc-pointer-glyph + This variable specifies the shape of the mouse pointer when a + garbage collection is in progress. If the selected window is on a + window system and this glyph specifies a value (i.e. a pointer + image instance) in the domain of the selected window, the pointer + will be changed as specified during garbage collection. + Otherwise, a message will be printed in the echo area, as + controlled by `gc-message'. + + - Glyph: busy-pointer-glyph + This variable specifies the shape of the mouse pointer when XEmacs + is busy. If unspecified in a particular domain, the pointer is + not changed when XEmacs is busy. + + - Glyph: menubar-pointer-glyph + This variable specifies the shape of the mouse pointer when over + the menubar. If unspecified in a particular domain, the + window-system-provided default pointer is used. + + - Glyph: scrollbar-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + scrollbar. If unspecified in a particular domain, the + window-system-provided default pointer is used. + + - Glyph: toolbar-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + toolbar. If unspecified in a particular domain, + `nontext-pointer-glyph' is used. + + Internally, these variables are implemented in +`default-mouse-motion-handler', and thus only take effect when the +mouse moves. That function calls `set-frame-pointer', which sets the +current mouse pointer for a frame. + + - Function: set-frame-pointer frame image-instance + This function sets the mouse pointer of FRAME to the given pointer + image instance. You should not call this function directly. (If + you do, the pointer will change again the next time the mouse + moves.) + + +File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs + +Redisplay Glyphs +================ + + - Glyph: truncation-glyph + This variable specifies what is displayed at the end of truncated + lines. + + - Glyph: continuation-glyph + This variable specifies what is displayed at the end of wrapped + lines. + + - Glyph: octal-escape-glyph + This variable specifies what to prefix character codes displayed + in octal with. + + - Glyph: hscroll-glyph + This variable specifies what to display at the beginning of + horizontally scrolled lines. + + - Glyph: invisible-text-glyph + This variable specifies what to use to indicate the presence of + invisible text. This is the glyph that is displayed when an + ellipsis is called for, according to `selective-display-ellipses' + or `buffer-invisibility-spec'). Normally this is three dots + ("..."). + + - Glyph: control-arrow-glyph + This variable specifies what to use as an arrow for control + characters. + + +File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs + +Subwindows +========== + + Subwindows are not currently implemented. + + - Function: subwindowp object + This function returns non-`nil' if OBJECT is a subwindow. + + +File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top + +Annotations +*********** + + An "annotation" is a pixmap or string that is not part of a buffer's +text but is displayed next to a particular location in a buffer. +Annotations can be displayed intermixed with text, in any whitespace at +the beginning or end of a line, or in a special area at the left or +right side of the frame called a "margin", whose size is controllable. +Annotations are implemented using extents (*note Extents::); but you +can work with annotations without knowing how extents work. + +* Menu: + +* Annotation Basics:: Introduction to annotations. +* Annotation Primitives:: Creating and deleting annotations. +* Annotation Properties:: Retrieving and changing the characteristics + of an annotation. +* Margin Primitives:: Controlling the size of the margins. +* Locating Annotations:: Looking for annotations in a buffer. +* Annotation Hooks:: Hooks called at certain times during an + annotation's lifetime. + + File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations Annotation Basics @@ -410,834 +1213,3 @@ occur if there is input pending. *Note Command Loop::. This function causes an immediate update of the cursor on the selected frame. (This function does not exist in FSF Emacs.) - -File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display - -Truncation -========== - - When a line of text extends beyond the right edge of a window, the -line can either be truncated or continued on the next line. When a line -is truncated, this is normally shown with a `\' in the rightmost column -of the window on X displays, and with a `$' on TTY devices. When a -line is continued or "wrapped" onto the next line, this is shown with a -curved arrow in the rightmost column of the window (or with a `\' on -TTY devices). The additional screen lines used to display a long text -line are called "continuation" lines. - - Normally, whenever line truncation is in effect for a particular -window, a horizontal scrollbar is displayed in that window if the -device supports scrollbars. *Note Scrollbars::. - - Note that continuation is different from filling; continuation -happens on the screen only, not in the buffer contents, and it breaks a -line precisely at the right margin, not at a word boundary. *Note -Filling::. - - - User Option: truncate-lines - This buffer-local variable controls how XEmacs displays lines that - extend beyond the right edge of the window. If it is non-`nil', - then XEmacs does not display continuation lines; rather each line - of text occupies exactly one screen line, and a backslash appears - at the edge of any line that extends to or beyond the edge of the - window. The default is `nil'. - - If the variable `truncate-partial-width-windows' is non-`nil', - then truncation is always used for side-by-side windows (within one - frame) regardless of the value of `truncate-lines'. - - - User Option: default-truncate-lines - This variable is the default value for `truncate-lines', for - buffers that do not have local values for it. - - - User Option: truncate-partial-width-windows - This variable controls display of lines that extend beyond the - right edge of the window, in side-by-side windows (*note Splitting - Windows::). If it is non-`nil', these lines are truncated; - otherwise, `truncate-lines' says what to do with them. - - The backslash and curved arrow used to indicate truncated or -continued lines are only defaults, and can be changed. These images -are actually glyphs (*note Glyphs::). XEmacs provides a great deal of -flexibility in how glyphs can be controlled. (This differs from FSF -Emacs, which uses display tables to control these images.) - - For details, *Note Redisplay Glyphs::. - - -File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display - -The Echo Area -============= - - The "echo area" is used for displaying messages made with the -`message' primitive, and for echoing keystrokes. It is not the same as -the minibuffer, despite the fact that the minibuffer appears (when -active) in the same place on the screen as the echo area. The `XEmacs -Reference Manual' specifies the rules for resolving conflicts between -the echo area and the minibuffer for use of that screen space (*note -The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo -area; see *Note Errors::. - - You can write output in the echo area by using the Lisp printing -functions with `t' as the stream (*note Output Functions::), or as -follows: - - - Function: message string &rest arguments - This function displays a one-line message in the echo area. The - argument STRING is similar to a C language `printf' control - string. See `format' in *Note String Conversion::, for the details - on the conversion specifications. `message' returns the - constructed string. - - In batch mode, `message' prints the message text on the standard - error stream, followed by a newline. - - If STRING is `nil', `message' clears the echo area. If the - minibuffer is active, this brings the minibuffer contents back onto - the screen immediately. - - (message "Minibuffer depth is %d." - (minibuffer-depth)) - -| Minibuffer depth is 0. - => "Minibuffer depth is 0." - - ---------- Echo Area ---------- - Minibuffer depth is 0. - ---------- Echo Area ---------- - - In addition to only displaying a message, XEmacs allows you to -"label" your messages, giving you fine-grained control of their -display. Message label is a symbol denoting the message type. Some -standard labels are: - - * `message'--default label used by the `message' function; - - * `error'--default label used for reporting errors; - - * `progress'--progress indicators like `Converting... 45%' (not - logged by default); - - * `prompt'--prompt-like messages like `Isearch: foo' (not logged by - default); - - * `command'--helper command messages like `Mark set' (not logged by - default); - - * `no-log'--messages that should never be logged - - Several messages may be stacked in the echo area at once. Lisp -programs may access these messages, or remove them as appropriate, via -the message stack. - - - Function: display-message label message &optional frame stdout-p - This function displays MESSAGE (a string) labeled as LABEL, as - described above. - - The FRAME argument specifies the frame to whose minibuffer the - message should be printed. This is currently unimplemented. The - STDOUT-P argument is used internally. - - (display-message 'command "Mark set") - - - Function: lmessage label string &rest arguments - This function displays a message STRING with label LABEL. It is - similar to `message' in that it accepts a `printf'-like strings - and any number of arguments. - - ;; Display a command message. - (lmessage 'command "Comment column set to %d" comment-column) - - ;; Display a progress message. - (lmessage 'progress "Fontifying %s... (%d)" buffer percentage) - - ;; Display a message that should not be logged. - (lmessage 'no-log "Done") - - - Function: clear-message &optional label frame stdout-p no-restore - This function remove any message with the given LABEL from the - message-stack, erasing it from the echo area if it's currently - displayed there. - - If a message remains at the head of the message-stack and - NO-RESTORE is `nil', it will be displayed. The string which - remains in the echo area will be returned, or `nil' if the - message-stack is now empty. If LABEL is nil, the entire - message-stack is cleared. - - ;; Show a message, wait for 2 seconds, and restore old minibuffer - ;; contents. - (message "A message") - -| A message - => "A Message" - (lmessage 'my-label "Newsflash! Newsflash!") - -| Newsflash! Newsflash! - => "Newsflash! Newsflash!" - (sit-for 2) - (clear-message 'my-label) - -| A message - => "A message" - - Unless you need the return value or you need to specify a label, - you should just use `(message nil)'. - - - Function: current-message &optional frame - This function returns the current message in the echo area, or - `nil'. The FRAME argument is currently unused. - - Some of the messages displayed in the echo area are also recorded in -the ` *Message-Log*' buffer. Exactly which messages will be recorded -can be tuned using the following variables. - - - User Option: log-message-max-size - This variable specifies the maximum size of the ` *Message-log*' - buffer. - - - Variable: log-message-ignore-labels - This variable specifies the labels whose messages will not be - logged. It should be a list of symbols. - - - Variable: log-message-ignore-regexps - This variable specifies the regular expressions matching messages - that will not be logged. It should be a list of regular - expressions. - - Normally, packages that generate messages that might need to be - ignored should label them with `progress', `prompt', or `no-log', - so they can be filtered by `log-message-ignore-labels'. - - - Variable: echo-keystrokes - This variable determines how much time should elapse before command - characters echo. Its value must be a number, which specifies the - number of seconds to wait before echoing. If the user types a - prefix key (such as `C-x') and then delays this many seconds - before continuing, the prefix key is echoed in the echo area. Any - subsequent characters in the same command will be echoed as well. - - If the value is zero, then command input is not echoed. - - - Variable: cursor-in-echo-area - This variable controls where the cursor appears when a message is - displayed in the echo area. If it is non-`nil', then the cursor - appears at the end of the message. Otherwise, the cursor appears - at point--not in the echo area at all. - - The value is normally `nil'; Lisp programs bind it to `t' for - brief periods of time. - - -File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display - -Warnings -======== - - XEmacs contains a facility for unified display of various warnings. -Unlike errors, warnings are displayed in the situations when XEmacs -encounters a problem that is recoverable, but which should be fixed for -safe future operation. - - For example, warnings are printed by the startup code when it -encounters problems with X keysyms, when there is an error in `.emacs', -and in other problematic situations. Unlike messages, warnings are -displayed in a separate buffer, and include an explanatory message that -may span across several lines. Here is an example of how a warning is -displayed: - - (1) (initialization/error) An error has occurred while loading ~/.emacs: - - Symbol's value as variable is void: bogus-variable - - To ensure normal operation, you should investigate the cause of the error - in your initialization file and remove it. Use the `-debug-init' option - to XEmacs to view a complete error backtrace. - - Each warning has a "class" and a "priority level". The class is a -symbol describing what sort of warning this is, such as -`initialization', `resource' or `key-mapping'. - - The warning priority level specifies how important the warning is. -The recognized warning levels, in increased order of priority, are: -`debug', `info', `notice', `warning', `error', `critical', `alert' and -`emergency'. - - - Function: display-warning class message &optional level - This function displays a warning message MESSAGE (a string). - CLASS should be a warning class symbol, as described above, or a - list of such symbols. LEVEL describes the warning priority level. - If unspecified, it default to `warning'. - - (display-warning 'resource - "Bad resource specification encountered: - something like - - Emacs*foo: bar - - You should replace the * with a . in order to get proper behavior when - you use the specifier and/or `set-face-*' functions.") - - ---------- Warning buffer ---------- - (1) (resource/warning) Bad resource specification encountered: - something like - - Emacs*foo: bar - - You should replace the * with a . in order to get proper behavior when - you use the specifier and/or `set-face-*' functions. - ---------- Warning buffer ---------- - - - Function: lwarn class level message &rest args - This function displays a formatted labeled warning message. As - above, CLASS should be the warning class symbol, or a list of such - symbols, and LEVEL should specify the warning priority level - (`warning' by default). - - Unlike in `display-warning', MESSAGE may be a formatted message, - which will be, together with the rest of the arguments, passed to - `format'. - - (lwarn 'message-log 'warning - "Error caught in `remove-message-hook': %s" - (error-message-string e)) - - - Variable: log-warning-minimum-level - This variable specifies the minimum level of warnings that should - be generated. Warnings with level lower than defined by this - variable are completely ignored, as if they never happened. - - - Variable: display-warning-minimum-level - This variable specifies the minimum level of warnings that should - be displayed. Unlike `log-warning-minimum-level', setting this - function does not suppress warnings entirely--they are still - generated in the `*Warnings*' buffer, only they are not displayed - by default. - - - Variable: log-warning-suppressed-classes - This variable specifies a list of classes that should not be - logged or displayed. If any of the class symbols associated with - a warning is the same as any of the symbols listed here, the - warning will be completely ignored, as it they never happened. - - - Variable: display-warning-suppressed-classes - This variable specifies a list of classes that should not be - logged or displayed. If any of the class symbols associated with - a warning is the same as any of the symbols listed here, the - warning will not be displayed. The warning will still logged in - the *Warnings* buffer (unless also contained in - `log-warning-suppressed-classes'), but the buffer will not be - automatically popped up. - - -File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display - -Invisible Text -============== - - You can make characters "invisible", so that they do not appear on -the screen, with the `invisible' property. This can be either a text -property or a property of an overlay. - - In the simplest case, any non-`nil' `invisible' property makes a -character invisible. This is the default case--if you don't alter the -default value of `buffer-invisibility-spec', this is how the -`invisibility' property works. This feature is much like selective -display (*note Selective Display::), but more general and cleaner. - - More generally, you can use the variable `buffer-invisibility-spec' -to control which values of the `invisible' property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different `invisible' values, and -subsequently make various subsets visible or invisible by changing the -value of `buffer-invisibility-spec'. - - Controlling visibility with `buffer-invisibility-spec' is especially -useful in a program to display the list of entries in a data base. It -permits the implementation of convenient filtering commands to view -just a part of the entries in the data base. Setting this variable is -very fast, much faster than scanning all the text in the buffer looking -for properties to change. - - - Variable: buffer-invisibility-spec - This variable specifies which kinds of `invisible' properties - actually make a character invisible. - - `t' - A character is invisible if its `invisible' property is - non-`nil'. This is the default. - - a list - Each element of the list makes certain characters invisible. - Ultimately, a character is invisible if any of the elements - of this list applies to it. The list can have two kinds of - elements: - - `ATOM' - A character is invisible if its `invisible' property - value is ATOM or if it is a list with ATOM as a member. - - `(ATOM . t)' - A character is invisible if its `invisible' property - value is ATOM or if it is a list with ATOM as a member. - Moreover, if this character is at the end of a line and - is followed by a visible newline, it displays an - ellipsis. - - Ordinarily, commands that operate on text or move point do not care -whether the text is invisible. However, the user-level line motion -commands explicitly ignore invisible newlines. - - -File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display - -Selective Display -================= - - "Selective display" is a pair of features that hide certain lines on -the screen. - - The first variant, explicit selective display, is designed for use in -a Lisp program. The program controls which lines are hidden by altering -the text. Outline mode has traditionally used this variant. It has -been partially replaced by the invisible text feature (*note Invisible -Text::); there is a new version of Outline mode which uses that instead. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now invisible. Strictly -speaking, it is temporarily no longer a line at all, since only newlines -can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, `C-f' (`forward-char') moves point unhesitatingly into -invisible text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For example, -`next-line' skips invisible lines, since it searches only for newlines. -Modes that use selective display can also define commands that take -account of the newlines, or that make parts of the text visible or -invisible. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing invisible. The selective display -effect is seen only within XEmacs. - - - Variable: selective-display - This buffer-local variable enables selective display. This means - that lines, or portions of lines, may be made invisible. - - * If the value of `selective-display' is `t', then any portion - of a line that follows a control-m is not displayed. - - * If the value of `selective-display' is a positive integer, - then lines that start with more than that many columns of - indentation are not displayed. - - When some portion of a buffer is invisible, the vertical movement - commands operate as if that portion did not exist, allowing a - single `next-line' command to skip any number of invisible lines. - However, character movement commands (such as `forward-char') do - not skip the invisible portion, and it is possible (if tricky) to - insert or delete text in an invisible portion. - - In the examples below, we show the _display appearance_ of the - buffer `foo', which changes with the value of `selective-display'. - The _contents_ of the buffer do not change. - - (setq selective-display nil) - => nil - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column - 3n this column - 3n this column - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - (setq selective-display 2) - => 2 - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - - Variable: selective-display-ellipses - If this buffer-local variable is non-`nil', then XEmacs displays - `...' at the end of a line that is followed by invisible text. - This example is a continuation of the previous one. - - (setq selective-display-ellipses t) - => t - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column ... - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - You can use a display table to substitute other text for the - ellipsis (`...'). *Note Display Tables::. - - -File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display - -The Overlay Arrow -================= - - The "overlay arrow" is useful for directing the user's attention to -a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. - - - Variable: overlay-arrow-string - This variable holds the string to display to call attention to a - particular line, or `nil' if the arrow feature is not in use. - Despite its name, the value of this variable can be either a string - or a glyph (*note Glyphs::). - - - Variable: overlay-arrow-position - This variable holds a marker that indicates where to display the - overlay arrow. It should point at the beginning of a line. The - arrow text appears at the beginning of that line, overlaying any - text that would otherwise appear. Since the arrow is usually - short, and the line usually begins with indentation, normally - nothing significant is overwritten. - - The overlay string is displayed only in the buffer that this marker - points into. Thus, only one buffer can have an overlay arrow at - any given time. - - You can do the same job by creating an extent with a `begin-glyph' -property. *Note Extent Properties::. - - -File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display - -Temporary Displays -================== - - Temporary displays are used by commands to put output into a buffer -and then present it to the user for perusal rather than for editing. -Many of the help commands use this feature. - - - Special Form: with-output-to-temp-buffer buffer-name forms... - This function executes FORMS while arranging to insert any output - they print into the buffer named BUFFER-NAME. The buffer is then - shown in some window for viewing, displayed but not selected. - - The string BUFFER-NAME specifies the temporary buffer, which need - not already exist. The argument must be a string, not a buffer. - The buffer is erased initially (with no questions asked), and it is - marked as unmodified after `with-output-to-temp-buffer' exits. - - `with-output-to-temp-buffer' binds `standard-output' to the - temporary buffer, then it evaluates the forms in FORMS. Output - using the Lisp output functions within FORMS goes by default to - that buffer (but screen display and messages in the echo area, - although they are "output" in the general sense of the word, are - not affected). *Note Output Functions::. - - The value of the last form in FORMS is returned. - - ---------- Buffer: foo ---------- - This is the contents of foo. - ---------- Buffer: foo ---------- - - (with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) - => # - - ---------- Buffer: foo ---------- - 20 - - # - - ---------- Buffer: foo ---------- - - - Variable: temp-buffer-show-function - If this variable is non-`nil', `with-output-to-temp-buffer' calls - it as a function to do the job of displaying a help buffer. The - function gets one argument, which is the buffer it should display. - - In Emacs versions 18 and earlier, this variable was called - `temp-buffer-show-hook'. - - - Function: momentary-string-display string position &optional char - message - This function momentarily displays STRING in the current buffer at - POSITION. It has no effect on the undo list or on the buffer's - modification status. - - The momentary display remains until the next input event. If the - next input event is CHAR, `momentary-string-display' ignores it - and returns. Otherwise, that event remains buffered for - subsequent use as input. Thus, typing CHAR will simply remove the - string from the display, while typing (say) `C-f' will remove the - string from the display and later (presumably) move point forward. - The argument CHAR is a space by default. - - The return value of `momentary-string-display' is not meaningful. - - You can do the same job in a more general way by creating an extent - with a begin-glyph property. *Note Extent Properties::. - - If MESSAGE is non-`nil', it is displayed in the echo area while - STRING is displayed in the buffer. If it is `nil', a default - message says to type CHAR to continue. - - In this example, point is initially located at the beginning of the - second line: - - ---------- Buffer: foo ---------- - This is the contents of foo. - -!-Second line. - ---------- Buffer: foo ---------- - - (momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") - => t - - ---------- Buffer: foo ---------- - This is the contents of foo. - **** Important Message! ****Second line. - ---------- Buffer: foo ---------- - - ---------- Echo Area ---------- - Type RET when done reading - ---------- Echo Area ---------- - - This function works by actually changing the text in the buffer. - As a result, if you later undo in this buffer, you will see the - message come and go. - - -File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display - -Blinking Parentheses -==================== - - This section describes the mechanism by which XEmacs shows a matching -open parenthesis when the user inserts a close parenthesis. - - - Variable: blink-paren-function - The value of this variable should be a function (of no arguments) - to be called whenever a character with close parenthesis syntax is - inserted. The value of `blink-paren-function' may be `nil', in - which case nothing is done. - - *Please note:* This variable was named `blink-paren-hook' in - older Emacs versions, but since it is not called with the - standard convention for hooks, it was renamed to - `blink-paren-function' in version 19. - - - Variable: blink-matching-paren - If this variable is `nil', then `blink-matching-open' does nothing. - - - Variable: blink-matching-paren-distance - This variable specifies the maximum distance to scan for a matching - parenthesis before giving up. - - - Variable: blink-matching-paren-delay - This variable specifies the number of seconds for the cursor to - remain at the matching parenthesis. A fraction of a second often - gives good results, but the default is 1, which works on all - systems. - - - Function: blink-matching-open - This function is the default value of `blink-paren-function'. It - assumes that point follows a character with close parenthesis - syntax and moves the cursor momentarily to the matching opening - character. If that character is not already on the screen, it - displays the character's context in the echo area. To avoid long - delays, this function does not search farther than - `blink-matching-paren-distance' characters. - - Here is an example of calling this function explicitly. - - (defun interactive-blink-matching-open () - "Indicate momentarily the start of sexp before point." - (interactive) - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) - - -File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display - -Usual Display Conventions -========================= - - The usual display conventions define how to display each character -code. You can override these conventions by setting up a display table -(*note Display Tables::). Here are the usual display conventions: - - * Character codes 32 through 126 map to glyph codes 32 through 126. - Normally this means they display as themselves. - - * Character code 9 is a horizontal tab. It displays as whitespace - up to a position determined by `tab-width'. - - * Character code 10 is a newline. - - * All other codes in the range 0 through 31, and code 127, display - in one of two ways according to the value of `ctl-arrow'. If it is - non-`nil', these codes map to sequences of two glyphs, where the - first glyph is the ASCII code for `^'. (A display table can - specify a glyph to use instead of `^'.) Otherwise, these codes map - just like the codes in the range 128 to 255. - - * Character codes 128 through 255 map to sequences of four glyphs, - where the first glyph is the ASCII code for `\', and the others are - digit characters representing the code in octal. (A display table - can specify a glyph to use instead of `\'.) - - The usual display conventions apply even when there is a display -table, for any character whose entry in the active display table is -`nil'. Thus, when you set up a display table, you need only specify -the characters for which you want unusual behavior. - - These variables affect the way certain characters are displayed on -the screen. Since they change the number of columns the characters -occupy, they also affect the indentation functions. - - - User Option: ctl-arrow - This buffer-local variable controls how control characters are - displayed. If it is non-`nil', they are displayed as a caret - followed by the character: `^A'. If it is `nil', they are - displayed as a backslash followed by three octal digits: `\001'. - - - Variable: default-ctl-arrow - The value of this variable is the default value for `ctl-arrow' in - buffers that do not override it. *Note Default Value::. - - - User Option: tab-width - The value of this variable is the spacing between tab stops used - for displaying tab characters in Emacs buffers. The default is 8. - Note that this feature is completely independent from the - user-settable tab stops used by the command `tab-to-tab-stop'. - *Note Indent Tabs::. - - -File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display - -Display Tables -============== - - You can use the "display table" feature to control how all 256 -possible character codes display on the screen. This is useful for -displaying European languages that have letters not in the ASCII -character set. - - The display table maps each character code into a sequence of -"runes", each rune being an image that takes up one character position -on the screen. You can also define how to display each rune on your -terminal, using the "rune table". - -* Menu: - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How XEmacs selects a display table to use. -* Character Descriptors:: Format of an individual element of a - display table. - - -File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables - -Display Table Format --------------------- - - A display table is an array of 256 elements. (In FSF Emacs, a display -table is 262 elements. The six extra elements specify the truncation -and continuation glyphs, etc. This method is very kludgey, and in -XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are -used. *Note Truncation::.) - - - Function: make-display-table - This creates and returns a display table. The table initially has - `nil' in all elements. - - The 256 elements correspond to character codes; the Nth element says -how to display the character code N. The value should be `nil', a -string, a glyph, or a vector of strings and glyphs (*note Character -Descriptors::). If an element is `nil', it says to display that -character according to the usual display conventions (*note Usual -Display::). - - If you use the display table to change the display of newline -characters, the whole buffer will be displayed as one long "line." - - For example, here is how to construct a display table that mimics the -effect of setting `ctl-arrow' to a non-`nil' value: - - (setq disptab (make-display-table)) - (let ((i 0)) - (while (< i 32) - (or (= i ?\t) (= i ?\n) - (aset disptab i (concat "^" (char-to-string (+ i 64))))) - (setq i (1+ i))) - (aset disptab 127 "^?")) - - -File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables - -Active Display Table --------------------- - - The active display table is controlled by the variable -`current-display-table'. This is a specifier, which means that you can -specify separate values for it in individual buffers, windows, frames, -and devices, as well as a global value. It also means that you cannot -set this variable using `setq'; use `set-specifier' instead. *Note -Specifiers::. (FSF Emacs uses `window-display-table', -`buffer-display-table', `standard-display-table', etc. to control the -display table. However, specifiers are a cleaner and more powerful way -of doing the same thing. FSF Emacs also uses a different format for -the contents of a display table, using additional indirection to a -"glyph table" and such. Note that "glyph" has a different meaning in -XEmacs.) - - Individual faces can also specify an overriding display table; this -is set using `set-face-display-table'. *Note Faces::. - - If no display table can be determined for a particular window, then -XEmacs uses the usual display conventions. *Note Usual Display::. - - -File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables - -Character Descriptors ---------------------- - - Each element of the display-table vector describes how to display a -particular character and is called a "character descriptor". A -character descriptor can be: - -a string - Display this particular string wherever the character is to be - displayed. - -a glyph - Display this particular glyph wherever the character is to be - displayed. - -a vector - The vector may contain strings and/or glyphs. Display the - elements of the vector one after another wherever the character is - to be displayed. - -`nil' - Display according to the standard interpretation (*note Usual - Display::). - diff --git a/info/lispref.info-38 b/info/lispref.info-38 index 2ac7f8e..2300ace 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -50,6 +50,898 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display + +Truncation +========== + + When a line of text extends beyond the right edge of a window, the +line can either be truncated or continued on the next line. When a line +is truncated, this is normally shown with a `\' in the rightmost column +of the window on X displays, and with a `$' on TTY devices. When a +line is continued or "wrapped" onto the next line, this is shown with a +curved arrow in the rightmost column of the window (or with a `\' on +TTY devices). The additional screen lines used to display a long text +line are called "continuation" lines. + + Normally, whenever line truncation is in effect for a particular +window, a horizontal scrollbar is displayed in that window if the +device supports scrollbars. *Note Scrollbars::. + + Note that continuation is different from filling; continuation +happens on the screen only, not in the buffer contents, and it breaks a +line precisely at the right margin, not at a word boundary. *Note +Filling::. + + - User Option: truncate-lines + This buffer-local variable controls how XEmacs displays lines that + extend beyond the right edge of the window. If it is non-`nil', + then XEmacs does not display continuation lines; rather each line + of text occupies exactly one screen line, and a backslash appears + at the edge of any line that extends to or beyond the edge of the + window. The default is `nil'. + + If the variable `truncate-partial-width-windows' is non-`nil', + then truncation is always used for side-by-side windows (within one + frame) regardless of the value of `truncate-lines'. + + - User Option: default-truncate-lines + This variable is the default value for `truncate-lines', for + buffers that do not have local values for it. + + - User Option: truncate-partial-width-windows + This variable controls display of lines that extend beyond the + right edge of the window, in side-by-side windows (*note Splitting + Windows::). If it is non-`nil', these lines are truncated; + otherwise, `truncate-lines' says what to do with them. + + The backslash and curved arrow used to indicate truncated or +continued lines are only defaults, and can be changed. These images +are actually glyphs (*note Glyphs::). XEmacs provides a great deal of +flexibility in how glyphs can be controlled. (This differs from FSF +Emacs, which uses display tables to control these images.) + + For details, *Note Redisplay Glyphs::. + + +File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display + +The Echo Area +============= + + The "echo area" is used for displaying messages made with the +`message' primitive, and for echoing keystrokes. It is not the same as +the minibuffer, despite the fact that the minibuffer appears (when +active) in the same place on the screen as the echo area. The `XEmacs +Reference Manual' specifies the rules for resolving conflicts between +the echo area and the minibuffer for use of that screen space (*note +The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo +area; see *Note Errors::. + + You can write output in the echo area by using the Lisp printing +functions with `t' as the stream (*note Output Functions::), or as +follows: + + - Function: message string &rest arguments + This function displays a one-line message in the echo area. The + argument STRING is similar to a C language `printf' control + string. See `format' in *Note String Conversion::, for the details + on the conversion specifications. `message' returns the + constructed string. + + In batch mode, `message' prints the message text on the standard + error stream, followed by a newline. + + If STRING is `nil', `message' clears the echo area. If the + minibuffer is active, this brings the minibuffer contents back onto + the screen immediately. + + (message "Minibuffer depth is %d." + (minibuffer-depth)) + -| Minibuffer depth is 0. + => "Minibuffer depth is 0." + + ---------- Echo Area ---------- + Minibuffer depth is 0. + ---------- Echo Area ---------- + + In addition to only displaying a message, XEmacs allows you to +"label" your messages, giving you fine-grained control of their +display. Message label is a symbol denoting the message type. Some +standard labels are: + + * `message'--default label used by the `message' function; + + * `error'--default label used for reporting errors; + + * `progress'--progress indicators like `Converting... 45%' (not + logged by default); + + * `prompt'--prompt-like messages like `Isearch: foo' (not logged by + default); + + * `command'--helper command messages like `Mark set' (not logged by + default); + + * `no-log'--messages that should never be logged + + Several messages may be stacked in the echo area at once. Lisp +programs may access these messages, or remove them as appropriate, via +the message stack. + + - Function: display-message label message &optional frame stdout-p + This function displays MESSAGE (a string) labeled as LABEL, as + described above. + + The FRAME argument specifies the frame to whose minibuffer the + message should be printed. This is currently unimplemented. The + STDOUT-P argument is used internally. + + (display-message 'command "Mark set") + + - Function: lmessage label string &rest arguments + This function displays a message STRING with label LABEL. It is + similar to `message' in that it accepts a `printf'-like strings + and any number of arguments. + + ;; Display a command message. + (lmessage 'command "Comment column set to %d" comment-column) + + ;; Display a progress message. + (lmessage 'progress "Fontifying %s... (%d)" buffer percentage) + + ;; Display a message that should not be logged. + (lmessage 'no-log "Done") + + - Function: clear-message &optional label frame stdout-p no-restore + This function remove any message with the given LABEL from the + message-stack, erasing it from the echo area if it's currently + displayed there. + + If a message remains at the head of the message-stack and + NO-RESTORE is `nil', it will be displayed. The string which + remains in the echo area will be returned, or `nil' if the + message-stack is now empty. If LABEL is nil, the entire + message-stack is cleared. + + ;; Show a message, wait for 2 seconds, and restore old minibuffer + ;; contents. + (message "A message") + -| A message + => "A Message" + (lmessage 'my-label "Newsflash! Newsflash!") + -| Newsflash! Newsflash! + => "Newsflash! Newsflash!" + (sit-for 2) + (clear-message 'my-label) + -| A message + => "A message" + + Unless you need the return value or you need to specify a label, + you should just use `(message nil)'. + + - Function: current-message &optional frame + This function returns the current message in the echo area, or + `nil'. The FRAME argument is currently unused. + + Some of the messages displayed in the echo area are also recorded in +the ` *Message-Log*' buffer. Exactly which messages will be recorded +can be tuned using the following variables. + + - User Option: log-message-max-size + This variable specifies the maximum size of the ` *Message-log*' + buffer. + + - Variable: log-message-ignore-labels + This variable specifies the labels whose messages will not be + logged. It should be a list of symbols. + + - Variable: log-message-ignore-regexps + This variable specifies the regular expressions matching messages + that will not be logged. It should be a list of regular + expressions. + + Normally, packages that generate messages that might need to be + ignored should label them with `progress', `prompt', or `no-log', + so they can be filtered by `log-message-ignore-labels'. + + - Variable: echo-keystrokes + This variable determines how much time should elapse before command + characters echo. Its value must be a number, which specifies the + number of seconds to wait before echoing. If the user types a + prefix key (such as `C-x') and then delays this many seconds + before continuing, the prefix key is echoed in the echo area. Any + subsequent characters in the same command will be echoed as well. + + If the value is zero, then command input is not echoed. + + - Variable: cursor-in-echo-area + This variable controls where the cursor appears when a message is + displayed in the echo area. If it is non-`nil', then the cursor + appears at the end of the message. Otherwise, the cursor appears + at point--not in the echo area at all. + + The value is normally `nil'; Lisp programs bind it to `t' for + brief periods of time. + + +File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display + +Warnings +======== + + XEmacs contains a facility for unified display of various warnings. +Unlike errors, warnings are displayed in the situations when XEmacs +encounters a problem that is recoverable, but which should be fixed for +safe future operation. + + For example, warnings are printed by the startup code when it +encounters problems with X keysyms, when there is an error in `.emacs', +and in other problematic situations. Unlike messages, warnings are +displayed in a separate buffer, and include an explanatory message that +may span across several lines. Here is an example of how a warning is +displayed: + + (1) (initialization/error) An error has occurred while loading ~/.emacs: + + Symbol's value as variable is void: bogus-variable + + To ensure normal operation, you should investigate the cause of the error + in your initialization file and remove it. Use the `-debug-init' option + to XEmacs to view a complete error backtrace. + + Each warning has a "class" and a "priority level". The class is a +symbol describing what sort of warning this is, such as +`initialization', `resource' or `key-mapping'. + + The warning priority level specifies how important the warning is. +The recognized warning levels, in increased order of priority, are: +`debug', `info', `notice', `warning', `error', `critical', `alert' and +`emergency'. + + - Function: display-warning class message &optional level + This function displays a warning message MESSAGE (a string). + CLASS should be a warning class symbol, as described above, or a + list of such symbols. LEVEL describes the warning priority level. + If unspecified, it default to `warning'. + + (display-warning 'resource + "Bad resource specification encountered: + something like + + Emacs*foo: bar + + You should replace the * with a . in order to get proper behavior when + you use the specifier and/or `set-face-*' functions.") + + ---------- Warning buffer ---------- + (1) (resource/warning) Bad resource specification encountered: + something like + + Emacs*foo: bar + + You should replace the * with a . in order to get proper behavior when + you use the specifier and/or `set-face-*' functions. + ---------- Warning buffer ---------- + + - Function: lwarn class level message &rest args + This function displays a formatted labeled warning message. As + above, CLASS should be the warning class symbol, or a list of such + symbols, and LEVEL should specify the warning priority level + (`warning' by default). + + Unlike in `display-warning', MESSAGE may be a formatted message, + which will be, together with the rest of the arguments, passed to + `format'. + + (lwarn 'message-log 'warning + "Error caught in `remove-message-hook': %s" + (error-message-string e)) + + - Variable: log-warning-minimum-level + This variable specifies the minimum level of warnings that should + be generated. Warnings with level lower than defined by this + variable are completely ignored, as if they never happened. + + - Variable: display-warning-minimum-level + This variable specifies the minimum level of warnings that should + be displayed. Unlike `log-warning-minimum-level', setting this + function does not suppress warnings entirely--they are still + generated in the `*Warnings*' buffer, only they are not displayed + by default. + + - Variable: log-warning-suppressed-classes + This variable specifies a list of classes that should not be + logged or displayed. If any of the class symbols associated with + a warning is the same as any of the symbols listed here, the + warning will be completely ignored, as it they never happened. + + - Variable: display-warning-suppressed-classes + This variable specifies a list of classes that should not be + logged or displayed. If any of the class symbols associated with + a warning is the same as any of the symbols listed here, the + warning will not be displayed. The warning will still logged in + the *Warnings* buffer (unless also contained in + `log-warning-suppressed-classes'), but the buffer will not be + automatically popped up. + + +File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display + +Invisible Text +============== + + You can make characters "invisible", so that they do not appear on +the screen, with the `invisible' property. This can be either a text +property or a property of an overlay. + + In the simplest case, any non-`nil' `invisible' property makes a +character invisible. This is the default case--if you don't alter the +default value of `buffer-invisibility-spec', this is how the +`invisibility' property works. This feature is much like selective +display (*note Selective Display::), but more general and cleaner. + + More generally, you can use the variable `buffer-invisibility-spec' +to control which values of the `invisible' property make text +invisible. This permits you to classify the text into different subsets +in advance, by giving them different `invisible' values, and +subsequently make various subsets visible or invisible by changing the +value of `buffer-invisibility-spec'. + + Controlling visibility with `buffer-invisibility-spec' is especially +useful in a program to display the list of entries in a data base. It +permits the implementation of convenient filtering commands to view +just a part of the entries in the data base. Setting this variable is +very fast, much faster than scanning all the text in the buffer looking +for properties to change. + + - Variable: buffer-invisibility-spec + This variable specifies which kinds of `invisible' properties + actually make a character invisible. + + `t' + A character is invisible if its `invisible' property is + non-`nil'. This is the default. + + a list + Each element of the list makes certain characters invisible. + Ultimately, a character is invisible if any of the elements + of this list applies to it. The list can have two kinds of + elements: + + `ATOM' + A character is invisible if its `invisible' property + value is ATOM or if it is a list with ATOM as a member. + + `(ATOM . t)' + A character is invisible if its `invisible' property + value is ATOM or if it is a list with ATOM as a member. + Moreover, if this character is at the end of a line and + is followed by a visible newline, it displays an + ellipsis. + + Ordinarily, commands that operate on text or move point do not care +whether the text is invisible. However, the user-level line motion +commands explicitly ignore invisible newlines. + + +File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display + +Selective Display +================= + + "Selective display" is a pair of features that hide certain lines on +the screen. + + The first variant, explicit selective display, is designed for use in +a Lisp program. The program controls which lines are hidden by altering +the text. Outline mode has traditionally used this variant. It has +been partially replaced by the invisible text feature (*note Invisible +Text::); there is a new version of Outline mode which uses that instead. + + In the second variant, the choice of lines to hide is made +automatically based on indentation. This variant is designed to be a +user-level feature. + + The way you control explicit selective display is by replacing a +newline (control-j) with a carriage return (control-m). The text that +was formerly a line following that newline is now invisible. Strictly +speaking, it is temporarily no longer a line at all, since only newlines +can separate lines; it is now part of the previous line. + + Selective display does not directly affect editing commands. For +example, `C-f' (`forward-char') moves point unhesitatingly into +invisible text. However, the replacement of newline characters with +carriage return characters affects some editing commands. For example, +`next-line' skips invisible lines, since it searches only for newlines. +Modes that use selective display can also define commands that take +account of the newlines, or that make parts of the text visible or +invisible. + + When you write a selectively displayed buffer into a file, all the +control-m's are output as newlines. This means that when you next read +in the file, it looks OK, with nothing invisible. The selective display +effect is seen only within XEmacs. + + - Variable: selective-display + This buffer-local variable enables selective display. This means + that lines, or portions of lines, may be made invisible. + + * If the value of `selective-display' is `t', then any portion + of a line that follows a control-m is not displayed. + + * If the value of `selective-display' is a positive integer, + then lines that start with more than that many columns of + indentation are not displayed. + + When some portion of a buffer is invisible, the vertical movement + commands operate as if that portion did not exist, allowing a + single `next-line' command to skip any number of invisible lines. + However, character movement commands (such as `forward-char') do + not skip the invisible portion, and it is possible (if tricky) to + insert or delete text in an invisible portion. + + In the examples below, we show the _display appearance_ of the + buffer `foo', which changes with the value of `selective-display'. + The _contents_ of the buffer do not change. + + (setq selective-display nil) + => nil + + ---------- Buffer: foo ---------- + 1 on this column + 2on this column + 3n this column + 3n this column + 2on this column + 1 on this column + ---------- Buffer: foo ---------- + + (setq selective-display 2) + => 2 + + ---------- Buffer: foo ---------- + 1 on this column + 2on this column + 2on this column + 1 on this column + ---------- Buffer: foo ---------- + + - Variable: selective-display-ellipses + If this buffer-local variable is non-`nil', then XEmacs displays + `...' at the end of a line that is followed by invisible text. + This example is a continuation of the previous one. + + (setq selective-display-ellipses t) + => t + + ---------- Buffer: foo ---------- + 1 on this column + 2on this column ... + 2on this column + 1 on this column + ---------- Buffer: foo ---------- + + You can use a display table to substitute other text for the + ellipsis (`...'). *Note Display Tables::. + + +File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display + +The Overlay Arrow +================= + + The "overlay arrow" is useful for directing the user's attention to +a particular line in a buffer. For example, in the modes used for +interface to debuggers, the overlay arrow indicates the line of code +about to be executed. + + - Variable: overlay-arrow-string + This variable holds the string to display to call attention to a + particular line, or `nil' if the arrow feature is not in use. + Despite its name, the value of this variable can be either a string + or a glyph (*note Glyphs::). + + - Variable: overlay-arrow-position + This variable holds a marker that indicates where to display the + overlay arrow. It should point at the beginning of a line. The + arrow text appears at the beginning of that line, overlaying any + text that would otherwise appear. Since the arrow is usually + short, and the line usually begins with indentation, normally + nothing significant is overwritten. + + The overlay string is displayed only in the buffer that this marker + points into. Thus, only one buffer can have an overlay arrow at + any given time. + + You can do the same job by creating an extent with a `begin-glyph' +property. *Note Extent Properties::. + + +File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display + +Temporary Displays +================== + + Temporary displays are used by commands to put output into a buffer +and then present it to the user for perusal rather than for editing. +Many of the help commands use this feature. + + - Special Form: with-output-to-temp-buffer buffer-name forms... + This function executes FORMS while arranging to insert any output + they print into the buffer named BUFFER-NAME. The buffer is then + shown in some window for viewing, displayed but not selected. + + The string BUFFER-NAME specifies the temporary buffer, which need + not already exist. The argument must be a string, not a buffer. + The buffer is erased initially (with no questions asked), and it is + marked as unmodified after `with-output-to-temp-buffer' exits. + + `with-output-to-temp-buffer' binds `standard-output' to the + temporary buffer, then it evaluates the forms in FORMS. Output + using the Lisp output functions within FORMS goes by default to + that buffer (but screen display and messages in the echo area, + although they are "output" in the general sense of the word, are + not affected). *Note Output Functions::. + + The value of the last form in FORMS is returned. + + ---------- Buffer: foo ---------- + This is the contents of foo. + ---------- Buffer: foo ---------- + + (with-output-to-temp-buffer "foo" + (print 20) + (print standard-output)) + => # + + ---------- Buffer: foo ---------- + 20 + + # + + ---------- Buffer: foo ---------- + + - Variable: temp-buffer-show-function + If this variable is non-`nil', `with-output-to-temp-buffer' calls + it as a function to do the job of displaying a help buffer. The + function gets one argument, which is the buffer it should display. + + In Emacs versions 18 and earlier, this variable was called + `temp-buffer-show-hook'. + + - Function: momentary-string-display string position &optional char + message + This function momentarily displays STRING in the current buffer at + POSITION. It has no effect on the undo list or on the buffer's + modification status. + + The momentary display remains until the next input event. If the + next input event is CHAR, `momentary-string-display' ignores it + and returns. Otherwise, that event remains buffered for + subsequent use as input. Thus, typing CHAR will simply remove the + string from the display, while typing (say) `C-f' will remove the + string from the display and later (presumably) move point forward. + The argument CHAR is a space by default. + + The return value of `momentary-string-display' is not meaningful. + + You can do the same job in a more general way by creating an extent + with a begin-glyph property. *Note Extent Properties::. + + If MESSAGE is non-`nil', it is displayed in the echo area while + STRING is displayed in the buffer. If it is `nil', a default + message says to type CHAR to continue. + + In this example, point is initially located at the beginning of the + second line: + + ---------- Buffer: foo ---------- + This is the contents of foo. + -!-Second line. + ---------- Buffer: foo ---------- + + (momentary-string-display + "**** Important Message! ****" + (point) ?\r + "Type RET when done reading") + => t + + ---------- Buffer: foo ---------- + This is the contents of foo. + **** Important Message! ****Second line. + ---------- Buffer: foo ---------- + + ---------- Echo Area ---------- + Type RET when done reading + ---------- Echo Area ---------- + + This function works by actually changing the text in the buffer. + As a result, if you later undo in this buffer, you will see the + message come and go. + + +File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display + +Blinking Parentheses +==================== + + This section describes the mechanism by which XEmacs shows a matching +open parenthesis when the user inserts a close parenthesis. + + - Variable: blink-paren-function + The value of this variable should be a function (of no arguments) + to be called whenever a character with close parenthesis syntax is + inserted. The value of `blink-paren-function' may be `nil', in + which case nothing is done. + + *Please note:* This variable was named `blink-paren-hook' in + older Emacs versions, but since it is not called with the + standard convention for hooks, it was renamed to + `blink-paren-function' in version 19. + + - Variable: blink-matching-paren + If this variable is `nil', then `blink-matching-open' does nothing. + + - Variable: blink-matching-paren-distance + This variable specifies the maximum distance to scan for a matching + parenthesis before giving up. + + - Variable: blink-matching-paren-delay + This variable specifies the number of seconds for the cursor to + remain at the matching parenthesis. A fraction of a second often + gives good results, but the default is 1, which works on all + systems. + + - Function: blink-matching-open + This function is the default value of `blink-paren-function'. It + assumes that point follows a character with close parenthesis + syntax and moves the cursor momentarily to the matching opening + character. If that character is not already on the screen, it + displays the character's context in the echo area. To avoid long + delays, this function does not search farther than + `blink-matching-paren-distance' characters. + + Here is an example of calling this function explicitly. + + (defun interactive-blink-matching-open () + "Indicate momentarily the start of sexp before point." + (interactive) + (let ((blink-matching-paren-distance + (buffer-size)) + (blink-matching-paren t)) + (blink-matching-open))) + + +File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display + +Usual Display Conventions +========================= + + The usual display conventions define how to display each character +code. You can override these conventions by setting up a display table +(*note Display Tables::). Here are the usual display conventions: + + * Character codes 32 through 126 map to glyph codes 32 through 126. + Normally this means they display as themselves. + + * Character code 9 is a horizontal tab. It displays as whitespace + up to a position determined by `tab-width'. + + * Character code 10 is a newline. + + * All other codes in the range 0 through 31, and code 127, display + in one of two ways according to the value of `ctl-arrow'. If it is + non-`nil', these codes map to sequences of two glyphs, where the + first glyph is the ASCII code for `^'. (A display table can + specify a glyph to use instead of `^'.) Otherwise, these codes map + just like the codes in the range 128 to 255. + + * Character codes 128 through 255 map to sequences of four glyphs, + where the first glyph is the ASCII code for `\', and the others are + digit characters representing the code in octal. (A display table + can specify a glyph to use instead of `\'.) + + The usual display conventions apply even when there is a display +table, for any character whose entry in the active display table is +`nil'. Thus, when you set up a display table, you need only specify +the characters for which you want unusual behavior. + + These variables affect the way certain characters are displayed on +the screen. Since they change the number of columns the characters +occupy, they also affect the indentation functions. + + - User Option: ctl-arrow + This buffer-local variable controls how control characters are + displayed. If it is non-`nil', they are displayed as a caret + followed by the character: `^A'. If it is `nil', they are + displayed as a backslash followed by three octal digits: `\001'. + + - Variable: default-ctl-arrow + The value of this variable is the default value for `ctl-arrow' in + buffers that do not override it. *Note Default Value::. + + - User Option: tab-width + The value of this variable is the spacing between tab stops used + for displaying tab characters in Emacs buffers. The default is 8. + Note that this feature is completely independent from the + user-settable tab stops used by the command `tab-to-tab-stop'. + *Note Indent Tabs::. + + +File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display + +Display Tables +============== + + You can use the "display table" feature to control how all 256 +possible character codes display on the screen. This is useful for +displaying European languages that have letters not in the ASCII +character set. + + The display table maps each character code into a sequence of +"runes", each rune being an image that takes up one character position +on the screen. You can also define how to display each rune on your +terminal, using the "rune table". + +* Menu: + +* Display Table Format:: What a display table consists of. +* Active Display Table:: How XEmacs selects a display table to use. +* Character Descriptors:: Format of an individual element of a + display table. + + +File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables + +Display Table Format +-------------------- + + A display table is an array of 256 elements. (In FSF Emacs, a display +table is 262 elements. The six extra elements specify the truncation +and continuation glyphs, etc. This method is very kludgey, and in +XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are +used. *Note Truncation::.) + + - Function: make-display-table + This creates and returns a display table. The table initially has + `nil' in all elements. + + The 256 elements correspond to character codes; the Nth element says +how to display the character code N. The value should be `nil', a +string, a glyph, or a vector of strings and glyphs (*note Character +Descriptors::). If an element is `nil', it says to display that +character according to the usual display conventions (*note Usual +Display::). + + If you use the display table to change the display of newline +characters, the whole buffer will be displayed as one long "line." + + For example, here is how to construct a display table that mimics the +effect of setting `ctl-arrow' to a non-`nil' value: + + (setq disptab (make-display-table)) + (let ((i 0)) + (while (< i 32) + (or (= i ?\t) (= i ?\n) + (aset disptab i (concat "^" (char-to-string (+ i 64))))) + (setq i (1+ i))) + (aset disptab 127 "^?")) + + +File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables + +Active Display Table +-------------------- + + The active display table is controlled by the variable +`current-display-table'. This is a specifier, which means that you can +specify separate values for it in individual buffers, windows, frames, +and devices, as well as a global value. It also means that you cannot +set this variable using `setq'; use `set-specifier' instead. *Note +Specifiers::. (FSF Emacs uses `window-display-table', +`buffer-display-table', `standard-display-table', etc. to control the +display table. However, specifiers are a cleaner and more powerful way +of doing the same thing. FSF Emacs also uses a different format for +the contents of a display table, using additional indirection to a +"glyph table" and such. Note that "glyph" has a different meaning in +XEmacs.) + + - Variable: current-display-table + The display table currently in use. This is a specifier. + + Display tables are used to control how characters are displayed. + Each time that redisplay processes a character, it is looked up in + all the display tables that apply (obtained by calling + `specifier-instance' on `current-display-table' and any overriding + display tables specified in currently active faces). The first + entry found that matches the character determines how the + character is displayed. If there is no matching entry, the + default display method is used. (Non-control characters are + displayed as themselves and control characters are displayed + according to the buffer-local variable `ctl-arrow'. Control + characters are further affected by `control-arrow-glyph' and + `octal-escape-glyph'.) + + Each instantiator in this specifier and the display-table + specifiers in faces is a display table or a list of such tables. + If a list, each table will be searched in turn for an entry + matching a particular character. Each display table is one of + + * A vector, specifying values for characters starting at 0. + + * A char table, either of type `char' or `generic'. + + * A range table. + + Each entry in a display table should be one of + + * nil (this entry is ignored and the search continues). + + * A character (use this character; if it happens to be the same + as the original character, default processing happens, + otherwise redisplay attempts to display this character + directly; #### At some point recursive display-table lookup + will be implemented). + + * A string (display each character in the string directly; #### + At some point recursive display-table lookup will be + implemented). + + * A glyph (display the glyph; #### At some point recursive + display-table lookup will be implemented when a string glyph + is being processed). + + * A cons of the form (format "STRING") where STRING is a + printf-like spec used to process the character. #### + Unfortunately no formatting directives other than %% are + implemented. + + * A vector (each element of the vector is processed recursively; + in such a case, nil elements in the vector are simply + ignored). + + #### At some point in the near future, display tables are + likely to be expanded to include other features, such as + referencing characters in particular fonts and allowing the + character search to continue all the way up the chain of + specifier instantiators. These features are necessary to + properly display Unicode characters. + + Individual faces can also specify an overriding display table; this +is set using `set-face-display-table'. *Note Faces::. + + If no display table can be determined for a particular window, then +XEmacs uses the usual display conventions. *Note Usual Display::. + + +File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables + +Character Descriptors +--------------------- + + Each element of the display-table vector describes how to display a +particular character and is called a "character descriptor". A +character descriptor can be: + +a string + Display this particular string wherever the character is to be + displayed. + +a glyph + Display this particular glyph wherever the character is to be + displayed. + +a vector + The vector may contain strings and/or glyphs. Display the + elements of the vector one after another wherever the character is + to be displayed. + +`nil' + Display according to the standard interpretation (*note Usual + Display::). + + File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display Beeping @@ -348,898 +1240,3 @@ Working With Hash Tables FUNCTION may remhash or puthash the entry currently being processed by FUNCTION. - -File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables - -Weak Hash Tables -================ - - A "weak hash table" is a special variety of hash table whose -elements do not count as GC referents. For any key-value pair in such a -hash table, if either the key or value (or in some cases, if one -particular one of the two) has no references to it outside of weak hash -tables (and similar structures such as weak lists), the pair will be -removed from the table, and the key and value collected. A non-weak -hash table (or any other pointer) would prevent the objects from being -collected. - - Weak hash tables are useful for keeping track of information in a -non-obtrusive way, for example to implement caching. If the cache -contains objects such as buffers, markers, image instances, etc. that -will eventually disappear and get garbage-collected, using a weak hash -table ensures that these objects are collected normally rather than -remaining around forever, long past their actual period of use. -(Otherwise, you'd have to explicitly map over the hash table every so -often and remove unnecessary elements.) - - There are three types of weak hash tables: - -fully weak hash tables - In these hash tables, a pair disappears if either the key or the - value is unreferenced outside of the table. - -key-weak hash tables - In these hash tables, a pair disappears if the key is unreferenced - outside of the table, regardless of how the value is referenced. - -value-weak hash tables - In these hash tables, a pair disappears if the value is - unreferenced outside of the table, regardless of how the key is - referenced. - - Also see *Note Weak Lists::. - - Weak hash tables are created by specifying the `:weakness' keyword to -`make-hash-table'. - - -File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top - -Range Tables -************ - - A range table is a table that efficiently associated values with -ranges of integers. - - Note that range tables have a read syntax, like this: - - #s(range-table data ((-3 2) foo (5 20) bar)) - - This maps integers in the range (-3, 2) to `foo' and integers in the -range (5, 20) to `bar'. - - - Function: range-table-p object - Return non-`nil' if OBJECT is a range table. - -* Menu: - -* Introduction to Range Tables:: Range tables efficiently map ranges of - integers to values. -* Working With Range Tables:: Range table functions. - - -File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables - -Introduction to Range Tables -============================ - - - Function: make-range-table - Make a new, empty range table. - - - Function: copy-range-table old-table - Make a new range table which contains the same values for the same - ranges as the given table. The values will not themselves be - copied. - - -File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables - -Working With Range Tables -========================= - - - Function: get-range-table pos table &optional default - This function finds value for position POS in TABLE. If there is - no corresponding value, return DEFAULT (defaults to `nil'). - - - Function: put-range-table start end val table - This function sets the value for range (START, END) to be VAL in - TABLE. - - - Function: remove-range-table start end table - This function removes the value for range (START, END) in TABLE. - - - Function: clear-range-table table - This function flushes TABLE. - - - Function: map-range-table function table - This function maps FUNCTION over entries in TABLE, calling it with - three args, the beginning and end of the range and the - corresponding value. - - -File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top - -Databases -********* - - - Function: databasep object - This function returns non-`nil' if OBJECT is a database. - -* Menu: - -* Connecting to a Database:: -* Working With a Database:: -* Other Database Functions:: - - -File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases - -Connecting to a Database -======================== - - - Function: open-database file &optional type subtype access mode - This function opens database FILE, using database method TYPE and - SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS - can be any combination of `r' `w' and `+', for read, write, and - creation flags. - - TYPE can have the value `'dbm' or `'berkeley_db' to select the - type of database file to use. (Note: XEmacs may not support both - of these types.) - - For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by - `nil'. - - For a TYPE of `'berkeley_db', the following subtypes are - available: `'hash', `'btree', and `'recno'. See the manpages for - the Berkeley DB functions to more information about these types. - - - Function: close-database obj - This function closes database OBJ. - - - Function: database-live-p obj - This function returns `t' iff OBJ is an active database, else - `nil'. - - -File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases - -Working With a Database -======================= - - - Function: get-database key dbase &optional default - This function finds the value for KEY in DATABASE. If there is no - corresponding value, DEFAULT is returned (`nil' if DEFAULT is - omitted). - - - Function: map-database function dbase - This function maps FUNCTION over entries in DATABASE, calling it - with two args, each key and value in the database. - - - Function: put-database key val dbase &optional replace - This function stores KEY and VAL in DATABASE. If optional fourth - arg REPLACE is non-`nil', replace any existing entry in the - database. - - - Function: remove-database key dbase - This function removes KEY from DATABASE. - - -File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases - -Other Database Functions -======================== - - - Function: database-file-name obj - This function returns the filename associated with the database - OBJ. - - - Function: database-last-error &optional obj - This function returns the last error associated with database OBJ. - - - Function: database-subtype obj - This function returns the subtype of database OBJ, if any. - - - Function: database-type obj - This function returns the type of database OBJ. - - -File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top - -Processes -********* - - In the terminology of operating systems, a "process" is a space in -which a program can execute. XEmacs runs in a process. XEmacs Lisp -programs can invoke other programs in processes of their own. These are -called "subprocesses" or "child processes" of the XEmacs process, which -is their "parent process". - - A subprocess of XEmacs may be "synchronous" or "asynchronous", -depending on how it is created. When you create a synchronous -subprocess, the Lisp program waits for the subprocess to terminate -before continuing execution. When you create an asynchronous -subprocess, it can run in parallel with the Lisp program. This kind of -subprocess is represented within XEmacs by a Lisp object which is also -called a "process". Lisp programs can use this object to communicate -with the subprocess or to control it. For example, you can send -signals, obtain status information, receive output from the process, or -send input to it. - - - Function: processp object - This function returns `t' if OBJECT is a process, `nil' otherwise. - -* Menu: - -* Subprocess Creation:: Functions that start subprocesses. -* Synchronous Processes:: Details of using synchronous subprocesses. -* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary - for data sent to and from a subprocess. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Process Window Size:: Changing the logical window size of a process. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. - - -File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes - -Functions that Create Subprocesses -================================== - - There are three functions that create a new subprocess in which to -run a program. One of them, `start-process', creates an asynchronous -process and returns a process object (*note Asynchronous Processes::). -The other two, `call-process' and `call-process-region', create a -synchronous process and do not return a process object (*note -Synchronous Processes::). - - Synchronous and asynchronous processes are explained in following -sections. Since the three functions are all called in a similar -fashion, their common arguments are described here. - - In all cases, the function's PROGRAM argument specifies the program -to be run. An error is signaled if the file is not found or cannot be -executed. If the file name is relative, the variable `exec-path' -contains a list of directories to search. Emacs initializes -`exec-path' when it starts up, based on the value of the environment -variable `PATH'. The standard file name constructs, `~', `.', and -`..', are interpreted as usual in `exec-path', but environment variable -substitutions (`$HOME', etc.) are not recognized; use -`substitute-in-file-name' to perform them (*note File Name Expansion::). - - Each of the subprocess-creating functions has a BUFFER-OR-NAME -argument which specifies where the standard output from the program will -go. If BUFFER-OR-NAME is `nil', that says to discard the output unless -a filter function handles it. (*Note Filter Functions::, and *Note -Read and Print::.) Normally, you should avoid having multiple -processes send output to the same buffer because their output would be -intermixed randomly. - - All three of the subprocess-creating functions have a `&rest' -argument, ARGS. The ARGS must all be strings, and they are supplied to -PROGRAM as separate command line arguments. Wildcard characters and -other shell constructs are not allowed in these strings, since they are -passed directly to the specified program. - - *Please note:* The argument PROGRAM contains only the name of the -program; it may not contain any command-line arguments. You must use -ARGS to provide those. - - The subprocess gets its current directory from the value of -`default-directory' (*note File Name Expansion::). - - The subprocess inherits its environment from XEmacs; but you can -specify overrides for it with `process-environment'. *Note System -Environment::. - - - Variable: exec-directory - The value of this variable is the name of a directory (a string) - that contains programs that come with XEmacs, that are intended - for XEmacs to invoke. The program `wakeup' is an example of such - a program; the `display-time' command uses it to get a reminder - once per minute. - - - User Option: exec-path - The value of this variable is a list of directories to search for - programs to run in subprocesses. Each element is either the name - of a directory (i.e., a string), or `nil', which stands for the - default directory (which is the value of `default-directory'). - - The value of `exec-path' is used by `call-process' and - `start-process' when the PROGRAM argument is not an absolute file - name. - - -File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes - -Creating a Synchronous Process -============================== - - After a "synchronous process" is created, XEmacs waits for the -process to terminate before continuing. Starting Dired is an example of -this: it runs `ls' in a synchronous process, then modifies the output -slightly. Because the process is synchronous, the entire directory -listing arrives in the buffer before XEmacs tries to do anything with -it. - - While Emacs waits for the synchronous subprocess to terminate, the -user can quit by typing `C-g'. The first `C-g' tries to kill the -subprocess with a `SIGINT' signal; but it waits until the subprocess -actually terminates before quitting. If during that time the user -types another `C-g', that kills the subprocess instantly with `SIGKILL' -and quits immediately. *Note Quitting::. - - The synchronous subprocess functions returned `nil' in version 18. -In version 19, they return an indication of how the process terminated. - - - Function: call-process program &optional infile destination display - &rest args - This function calls PROGRAM in a separate process and waits for it - to finish. - - The standard input for the process comes from file INFILE if - INFILE is not `nil' and from `/dev/null' otherwise. The argument - DESTINATION says where to put the process output. Here are the - possibilities: - - a buffer - Insert the output in that buffer, before point. This - includes both the standard output stream and the standard - error stream of the process. - - a string - Find or create a buffer with that name, then insert the - output in that buffer, before point. - - `t' - Insert the output in the current buffer, before point. - - `nil' - Discard the output. - - 0 - Discard the output, and return immediately without waiting - for the subprocess to finish. - - In this case, the process is not truly synchronous, since it - can run in parallel with Emacs; but you can think of it as - synchronous in that Emacs is essentially finished with the - subprocess as soon as this function returns. - - (REAL-DESTINATION ERROR-DESTINATION) - Keep the standard output stream separate from the standard - error stream; deal with the ordinary output as specified by - REAL-DESTINATION, and dispose of the error output according - to ERROR-DESTINATION. The value `nil' means discard it, `t' - means mix it with the ordinary output, and a string specifies - a file name to redirect error output into. - - You can't directly specify a buffer to put the error output - in; that is too difficult to implement. But you can achieve - this result by sending the error output to a temporary file - and then inserting the file into a buffer. - - If DISPLAY is non-`nil', then `call-process' redisplays the buffer - as output is inserted. Otherwise the function does no redisplay, - and the results become visible on the screen only when XEmacs - redisplays that buffer in the normal course of events. - - The remaining arguments, ARGS, are strings that specify command - line arguments for the program. - - The value returned by `call-process' (unless you told it not to - wait) indicates the reason for process termination. A number - gives the exit status of the subprocess; 0 means success, and any - other value means failure. If the process terminated with a - signal, `call-process' returns a string describing the signal. - - In the examples below, the buffer `foo' is current. - - (call-process "pwd" nil t) - => nil - - ---------- Buffer: foo ---------- - /usr/user/lewis/manual - ---------- Buffer: foo ---------- - - (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - => nil - - ---------- Buffer: bar ---------- - lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh - - ---------- Buffer: bar ---------- - - The `insert-directory' function contains a good example of the use - of `call-process': - - (call-process insert-directory-program nil t nil switches - (if full-directory-p - (concat (file-name-as-directory file) ".") - file)) - - - Function: call-process-region start end program &optional delete - destination display &rest args - This function sends the text between START to END as standard - input to a process running PROGRAM. It deletes the text sent if - DELETE is non-`nil'; this is useful when BUFFER is `t', to insert - the output in the current buffer. - - The arguments DESTINATION and DISPLAY control what to do with the - output from the subprocess, and whether to update the display as - it comes in. For details, see the description of `call-process', - above. If DESTINATION is the integer 0, `call-process-region' - discards the output and returns `nil' immediately, without waiting - for the subprocess to finish. - - The remaining arguments, ARGS, are strings that specify command - line arguments for the program. - - The return value of `call-process-region' is just like that of - `call-process': `nil' if you told it to return without waiting; - otherwise, a number or string which indicates how the subprocess - terminated. - - In the following example, we use `call-process-region' to run the - `cat' utility, with standard input being the first five characters - in buffer `foo' (the word `input'). `cat' copies its standard - input into its standard output. Since the argument DESTINATION is - `t', this output is inserted in the current buffer. - - ---------- Buffer: foo ---------- - input-!- - ---------- Buffer: foo ---------- - - (call-process-region 1 6 "cat" nil t) - => nil - - ---------- Buffer: foo ---------- - inputinput-!- - ---------- Buffer: foo ---------- - - The `shell-command-on-region' command uses `call-process-region' - like this: - - (call-process-region - start end - shell-file-name ; Name of program. - nil ; Do not delete region. - buffer ; Send output to `buffer'. - nil ; No redisplay during output. - "-c" command) ; Arguments for the shell. - - -File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes - -MS-DOS Subprocesses -=================== - - On MS-DOS, you must indicate whether the data going to and from a -synchronous subprocess are text or binary. Text data requires -translation between the end-of-line convention used within Emacs (a -single newline character) and the convention used outside Emacs (the -two-character sequence, CRLF). - - The variable `binary-process-input' applies to input sent to the -subprocess, and `binary-process-output' applies to output received from -it. A non-`nil' value means the data is non-text; `nil' means the data -is text, and calls for conversion. - - - Variable: binary-process-input - If this variable is `nil', convert newlines to CRLF sequences in - the input to a synchronous subprocess. - - - Variable: binary-process-output - If this variable is `nil', convert CRLF sequences to newlines in - the output from a synchronous subprocess. - - *Note Files and MS-DOS::, for related information. - - -File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes - -Creating an Asynchronous Process -================================ - - After an "asynchronous process" is created, Emacs and the Lisp -program both continue running immediately. The process may thereafter -run in parallel with Emacs, and the two may communicate with each other -using the functions described in following sections. Here we describe -how to create an asynchronous process with `start-process'. - - - Function: start-process name buffer-or-name program &rest args - This function creates a new asynchronous subprocess and starts the - program PROGRAM running in it. It returns a process object that - stands for the new subprocess in Lisp. The argument NAME - specifies the name for the process object; if a process with this - name already exists, then NAME is modified (by adding `<1>', etc.) - to be unique. The buffer BUFFER-OR-NAME is the buffer to - associate with the process. - - The remaining arguments, ARGS, are strings that specify command - line arguments for the program. - - In the example below, the first process is started and runs - (rather, sleeps) for 100 seconds. Meanwhile, the second process - is started, and given the name `my-process<1>' for the sake of - uniqueness. It inserts the directory listing at the end of the - buffer `foo', before the first process finishes. Then it - finishes, and a message to that effect is inserted in the buffer. - Much later, the first process finishes, and another message is - inserted in the buffer for it. - - (start-process "my-process" "foo" "sleep" "100") - => # - - (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") - => #> - - ---------- Buffer: foo ---------- - total 2 - lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs - -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon - - Process my-process<1> finished - - Process my-process finished - ---------- Buffer: foo ---------- - - - Function: start-process-shell-command name buffer-or-name command - &rest command-args - This function is like `start-process' except that it uses a shell - to execute the specified command. The argument COMMAND is a shell - command name, and COMMAND-ARGS are the arguments for the shell - command. - - - Variable: process-connection-type - This variable controls the type of device used to communicate with - asynchronous subprocesses. If it is non-`nil', then PTYs are - used, when available. Otherwise, pipes are used. - - PTYs are usually preferable for processes visible to the user, as - in Shell mode, because they allow job control (`C-c', `C-z', etc.) - to work between the process and its children whereas pipes do not. - For subprocesses used for internal purposes by programs, it is - often better to use a pipe, because they are more efficient. In - addition, the total number of PTYs is limited on many systems and - it is good not to waste them. - - The value `process-connection-type' is used when `start-process' - is called. So you can specify how to communicate with one - subprocess by binding the variable around the call to - `start-process'. - - (let ((process-connection-type nil)) ; Use a pipe. - (start-process ...)) - - To determine whether a given subprocess actually got a pipe or a - PTY, use the function `process-tty-name' (*note Process - Information::). - - -File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes - -Deleting Processes -================== - - "Deleting a process" disconnects XEmacs immediately from the -subprocess, and removes it from the list of active processes. It sends -a signal to the subprocess to make the subprocess terminate, but this is -not guaranteed to happen immediately. The process object itself -continues to exist as long as other Lisp objects point to it. - - You can delete a process explicitly at any time. Processes are -deleted automatically after they terminate, but not necessarily right -away. If you delete a terminated process explicitly before it is -deleted automatically, no harm results. - - - Variable: delete-exited-processes - This variable controls automatic deletion of processes that have - terminated (due to calling `exit' or to a signal). If it is - `nil', then they continue to exist until the user runs - `list-processes'. Otherwise, they are deleted immediately after - they exit. - - - Function: delete-process name - This function deletes the process associated with NAME, killing it - with a `SIGHUP' signal. The argument NAME may be a process, the - name of a process, a buffer, or the name of a buffer. - - (delete-process "*shell*") - => nil - - - Function: process-kill-without-query process &optional - require-query-p - This function declares that XEmacs need not query the user if - PROCESS is still running when XEmacs is exited. The process will - be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs - _will_ query the user (this is the default). The return value is - `t' if a query was formerly required, and `nil' otherwise. - - (process-kill-without-query (get-process "shell")) - => t - - -File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes - -Process Information -=================== - - Several functions return information about processes. -`list-processes' is provided for interactive use. - - - Command: list-processes - This command displays a listing of all living processes. In - addition, it finally deletes any process whose status was `Exited' - or `Signaled'. It returns `nil'. - - - Function: process-list - This function returns a list of all processes that have not been - deleted. - - (process-list) - => (# #) - - - Function: get-process name - This function returns the process named NAME, or `nil' if there is - none. An error is signaled if NAME is not a string. - - (get-process "shell") - => # - - - Function: process-command process - This function returns the command that was executed to start - PROCESS. This is a list of strings, the first string being the - program executed and the rest of the strings being the arguments - that were given to the program. - - (process-command (get-process "shell")) - => ("/bin/csh" "-i") - - - Function: process-id process - This function returns the PID of PROCESS. This is an integer that - distinguishes the process PROCESS from all other processes running - on the same computer at the current time. The PID of a process is - chosen by the operating system kernel when the process is started - and remains constant as long as the process exists. - - - Function: process-name process - This function returns the name of PROCESS. - - - Function: process-status process-name - This function returns the status of PROCESS-NAME as a symbol. The - argument PROCESS-NAME must be a process, a buffer, a process name - (string) or a buffer name (string). - - The possible values for an actual subprocess are: - - `run' - for a process that is running. - - `stop' - for a process that is stopped but continuable. - - `exit' - for a process that has exited. - - `signal' - for a process that has received a fatal signal. - - `open' - for a network connection that is open. - - `closed' - for a network connection that is closed. Once a connection - is closed, you cannot reopen it, though you might be able to - open a new connection to the same place. - - `nil' - if PROCESS-NAME is not the name of an existing process. - - (process-status "shell") - => run - (process-status (get-buffer "*shell*")) - => run - x - => #> - (process-status x) - => exit - - For a network connection, `process-status' returns one of the - symbols `open' or `closed'. The latter means that the other side - closed the connection, or XEmacs did `delete-process'. - - In earlier Emacs versions (prior to version 19), the status of a - network connection was `run' if open, and `exit' if closed. - - - Function: process-kill-without-query-p process - This function returns whether PROCESS will be killed without - querying the user, if it is running when XEmacs is exited. The - default value is `nil'. - - - Function: process-exit-status process - This function returns the exit status of PROCESS or the signal - number that killed it. (Use the result of `process-status' to - determine which of those it is.) If PROCESS has not yet - terminated, the value is 0. - - - Function: process-tty-name process - This function returns the terminal name that PROCESS is using for - its communication with Emacs--or `nil' if it is using pipes - instead of a terminal (see `process-connection-type' in *Note - Asynchronous Processes::). - - -File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes - -Sending Input to Processes -========================== - - Asynchronous subprocesses receive input when it is sent to them by -XEmacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the "standard input" of the subprocess. - - Some operating systems have limited space for buffered input in a -PTY. On these systems, Emacs sends an EOF periodically amidst the -other characters, to force them through. For most programs, these EOFs -do no harm. - - - Function: process-send-string process-name string - This function sends PROCESS-NAME the contents of STRING as - standard input. The argument PROCESS-NAME must be a process or - the name of a process. If it is `nil', the current buffer's - process is used. - - The function returns `nil'. - - (process-send-string "shell<1>" "ls\n") - => nil - - - ---------- Buffer: *shell* ---------- - ... - introduction.texi syntax-tables.texi~ - introduction.texi~ text.texi - introduction.txt text.texi~ - ... - ---------- Buffer: *shell* ---------- - - - Command: process-send-region process-name start end - This function sends the text in the region defined by START and - END as standard input to PROCESS-NAME, which is a process or a - process name. (If it is `nil', the current buffer's process is - used.) - - An error is signaled unless both START and END are integers or - markers that indicate positions in the current buffer. (It is - unimportant which number is larger.) - - - Function: process-send-eof &optional process-name - This function makes PROCESS-NAME see an end-of-file in its input. - The EOF comes after any text already sent to it. - - If PROCESS-NAME is not supplied, or if it is `nil', then this - function sends the EOF to the current buffer's process. An error - is signaled if the current buffer has no process. - - The function returns PROCESS-NAME. - - (process-send-eof "shell") - => "shell" - - -File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes - -Sending Signals to Processes -============================ - - "Sending a signal" to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal `SIGINT' means that the user has typed -`C-c', or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop or resume execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - The set of signals and their names is defined by the operating -system; XEmacs has facilities for sending only a few of the signals -that are defined. XEmacs can send signals only to its own subprocesses. - - You can send signals explicitly by calling the functions in this -section. XEmacs also sends signals automatically at certain times: -killing a buffer sends a `SIGHUP' signal to all its associated -processes; killing XEmacs sends a `SIGHUP' signal to all remaining -processes. (`SIGHUP' is a signal that usually indicates that the user -hung up the phone.) - - Each of the signal-sending functions takes two optional arguments: -PROCESS-NAME and CURRENT-GROUP. - - The argument PROCESS-NAME must be either a process, the name of one, -or `nil'. If it is `nil', the process defaults to the process -associated with the current buffer. An error is signaled if -PROCESS-NAME does not identify a process. - - The argument CURRENT-GROUP is a flag that makes a difference when -you are running a job-control shell as an XEmacs subprocess. If it is -non-`nil', then the signal is sent to the current process-group of the -terminal that XEmacs uses to communicate with the subprocess. If the -process is a job-control shell, this means the shell's current subjob. -If it is `nil', the signal is sent to the process group of the -immediate subprocess of XEmacs. If the subprocess is a job-control -shell, this is the shell itself. - - The flag CURRENT-GROUP has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -`process-connection-type' in *Note Asynchronous Processes::. - - - Function: interrupt-process &optional process-name current-group - This function interrupts the process PROCESS-NAME by sending the - signal `SIGINT'. Outside of XEmacs, typing the "interrupt - character" (normally `C-c' on some systems, and `DEL' on others) - sends this signal. When the argument CURRENT-GROUP is non-`nil', - you can think of this function as "typing `C-c'" on the terminal - by which XEmacs talks to the subprocess. - - - Function: kill-process &optional process-name current-group - This function kills the process PROCESS-NAME by sending the signal - `SIGKILL'. This signal kills the subprocess immediately, and - cannot be handled by the subprocess. - - - Function: quit-process &optional process-name current-group - This function sends the signal `SIGQUIT' to the process - PROCESS-NAME. This signal is the one sent by the "quit character" - (usually `C-b' or `C-\') when you are not inside XEmacs. - - - Function: stop-process &optional process-name current-group - This function stops the process PROCESS-NAME by sending the signal - `SIGTSTP'. Use `continue-process' to resume its execution. - - On systems with job control, the "stop character" (usually `C-z') - sends this signal (outside of XEmacs). When CURRENT-GROUP is - non-`nil', you can think of this function as "typing `C-z'" on the - terminal XEmacs uses to communicate with the subprocess. - - - Function: continue-process &optional process-name current-group - This function resumes execution of the process PROCESS by sending - it the signal `SIGCONT'. This presumes that PROCESS-NAME was - stopped previously. - - - Function: signal-process pid signal - This function sends a signal to process PID, which need not be a - child of XEmacs. The argument SIGNAL specifies which signal to - send; it should be an integer. - - -File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes - -Receiving Output from Processes -=============================== - - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process, or a function -called the "filter function" can be called to act on the output. If -the process has no buffer and no filter function, its output is -discarded. - -* Menu: - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Accepting Output:: Explicitly permitting subprocess output. - Waiting for subprocess output. - diff --git a/info/lispref.info-39 b/info/lispref.info-39 index 9a6e077..d11996e 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -50,6 +50,901 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables + +Weak Hash Tables +================ + + A "weak hash table" is a special variety of hash table whose +elements do not count as GC referents. For any key-value pair in such a +hash table, if either the key or value (or in some cases, if one +particular one of the two) has no references to it outside of weak hash +tables (and similar structures such as weak lists), the pair will be +removed from the table, and the key and value collected. A non-weak +hash table (or any other pointer) would prevent the objects from being +collected. + + Weak hash tables are useful for keeping track of information in a +non-obtrusive way, for example to implement caching. If the cache +contains objects such as buffers, markers, image instances, etc. that +will eventually disappear and get garbage-collected, using a weak hash +table ensures that these objects are collected normally rather than +remaining around forever, long past their actual period of use. +(Otherwise, you'd have to explicitly map over the hash table every so +often and remove unnecessary elements.) + + There are three types of weak hash tables: + +fully weak hash tables + In these hash tables, a pair disappears if either the key or the + value is unreferenced outside of the table. + +key-weak hash tables + In these hash tables, a pair disappears if the key is unreferenced + outside of the table, regardless of how the value is referenced. + +value-weak hash tables + In these hash tables, a pair disappears if the value is + unreferenced outside of the table, regardless of how the key is + referenced. + + Also see *Note Weak Lists::. + + Weak hash tables are created by specifying the `:weakness' keyword to +`make-hash-table'. + + +File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top + +Range Tables +************ + + A range table is a table that efficiently associated values with +ranges of integers. + + Note that range tables have a read syntax, like this: + + #s(range-table data ((-3 2) foo (5 20) bar)) + + This maps integers in the range (-3, 2) to `foo' and integers in the +range (5, 20) to `bar'. + + - Function: range-table-p object + Return non-`nil' if OBJECT is a range table. + +* Menu: + +* Introduction to Range Tables:: Range tables efficiently map ranges of + integers to values. +* Working With Range Tables:: Range table functions. + + +File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables + +Introduction to Range Tables +============================ + + - Function: make-range-table + Make a new, empty range table. + + - Function: copy-range-table old-table + Make a new range table which contains the same values for the same + ranges as the given table. The values will not themselves be + copied. + + +File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables + +Working With Range Tables +========================= + + - Function: get-range-table pos table &optional default + This function finds value for position POS in TABLE. If there is + no corresponding value, return DEFAULT (defaults to `nil'). + + - Function: put-range-table start end val table + This function sets the value for range (START, END) to be VAL in + TABLE. + + - Function: remove-range-table start end table + This function removes the value for range (START, END) in TABLE. + + - Function: clear-range-table table + This function flushes TABLE. + + - Function: map-range-table function table + This function maps FUNCTION over entries in TABLE, calling it with + three args, the beginning and end of the range and the + corresponding value. + + +File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top + +Databases +********* + + - Function: databasep object + This function returns non-`nil' if OBJECT is a database. + +* Menu: + +* Connecting to a Database:: +* Working With a Database:: +* Other Database Functions:: + + +File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases + +Connecting to a Database +======================== + + - Function: open-database file &optional type subtype access mode + This function opens database FILE, using database method TYPE and + SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS + can be any combination of `r' `w' and `+', for read, write, and + creation flags. + + TYPE can have the value `'dbm' or `'berkeley_db' to select the + type of database file to use. (Note: XEmacs may not support both + of these types.) + + For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be + `nil'. + + For a TYPE of `'berkeley_db', the following subtypes are + available: `'hash', `'btree', and `'recno'. See the manpages for + the Berkeley DB functions to more information about these types. + + - Function: close-database obj + This function closes database OBJ. + + - Function: database-live-p obj + This function returns `t' iff OBJ is an active database, else + `nil'. + + +File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases + +Working With a Database +======================= + + - Function: get-database key dbase &optional default + This function finds the value for KEY in DATABASE. If there is no + corresponding value, DEFAULT is returned (`nil' if DEFAULT is + omitted). + + - Function: map-database function dbase + This function maps FUNCTION over entries in DATABASE, calling it + with two args, each key and value in the database. + + - Function: put-database key val dbase &optional replace + This function stores KEY and VAL in DATABASE. If optional fourth + arg REPLACE is non-`nil', replace any existing entry in the + database. + + - Function: remove-database key dbase + This function removes KEY from DATABASE. + + +File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases + +Other Database Functions +======================== + + - Function: database-file-name obj + This function returns the filename associated with the database + OBJ. + + - Function: database-last-error &optional obj + This function returns the last error associated with database OBJ. + + - Function: database-subtype obj + This function returns the subtype of database OBJ, if any. + + - Function: database-type obj + This function returns the type of database OBJ. + + +File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top + +Processes +********* + + In the terminology of operating systems, a "process" is a space in +which a program can execute. XEmacs runs in a process. XEmacs Lisp +programs can invoke other programs in processes of their own. These are +called "subprocesses" or "child processes" of the XEmacs process, which +is their "parent process". + + A subprocess of XEmacs may be "synchronous" or "asynchronous", +depending on how it is created. When you create a synchronous +subprocess, the Lisp program waits for the subprocess to terminate +before continuing execution. When you create an asynchronous +subprocess, it can run in parallel with the Lisp program. This kind of +subprocess is represented within XEmacs by a Lisp object which is also +called a "process". Lisp programs can use this object to communicate +with the subprocess or to control it. For example, you can send +signals, obtain status information, receive output from the process, or +send input to it. + + - Function: processp object + This function returns `t' if OBJECT is a process, `nil' otherwise. + +* Menu: + +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary + for data sent to and from a subprocess. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Process Window Size:: Changing the logical window size of a process. +* Transaction Queues:: Transaction-based communication with subprocesses. +* Network:: Opening network connections. + + +File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes + +Functions that Create Subprocesses +================================== + + There are three functions that create a new subprocess in which to +run a program. One of them, `start-process', creates an asynchronous +process and returns a process object (*note Asynchronous Processes::). +The other two, `call-process' and `call-process-region', create a +synchronous process and do not return a process object (*note +Synchronous Processes::). + + Synchronous and asynchronous processes are explained in following +sections. Since the three functions are all called in a similar +fashion, their common arguments are described here. + + In all cases, the function's PROGRAM argument specifies the program +to be run. An error is signaled if the file is not found or cannot be +executed. If the file name is relative, the variable `exec-path' +contains a list of directories to search. Emacs initializes +`exec-path' when it starts up, based on the value of the environment +variable `PATH'. The standard file name constructs, `~', `.', and +`..', are interpreted as usual in `exec-path', but environment variable +substitutions (`$HOME', etc.) are not recognized; use +`substitute-in-file-name' to perform them (*note File Name Expansion::). + + Each of the subprocess-creating functions has a BUFFER-OR-NAME +argument which specifies where the standard output from the program will +go. If BUFFER-OR-NAME is `nil', that says to discard the output unless +a filter function handles it. (*Note Filter Functions::, and *Note +Read and Print::.) Normally, you should avoid having multiple +processes send output to the same buffer because their output would be +intermixed randomly. + + All three of the subprocess-creating functions have a `&rest' +argument, ARGS. The ARGS must all be strings, and they are supplied to +PROGRAM as separate command line arguments. Wildcard characters and +other shell constructs are not allowed in these strings, since they are +passed directly to the specified program. + + *Please note:* The argument PROGRAM contains only the name of the +program; it may not contain any command-line arguments. You must use +ARGS to provide those. + + The subprocess gets its current directory from the value of +`default-directory' (*note File Name Expansion::). + + The subprocess inherits its environment from XEmacs; but you can +specify overrides for it with `process-environment'. *Note System +Environment::. + + - Variable: exec-directory + The value of this variable is the name of a directory (a string) + that contains programs that come with XEmacs, that are intended + for XEmacs to invoke. The program `wakeup' is an example of such + a program; the `display-time' command uses it to get a reminder + once per minute. + + - User Option: exec-path + The value of this variable is a list of directories to search for + programs to run in subprocesses. Each element is either the name + of a directory (i.e., a string), or `nil', which stands for the + default directory (which is the value of `default-directory'). + + The value of `exec-path' is used by `call-process' and + `start-process' when the PROGRAM argument is not an absolute file + name. + + +File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes + +Creating a Synchronous Process +============================== + + After a "synchronous process" is created, XEmacs waits for the +process to terminate before continuing. Starting Dired is an example of +this: it runs `ls' in a synchronous process, then modifies the output +slightly. Because the process is synchronous, the entire directory +listing arrives in the buffer before XEmacs tries to do anything with +it. + + While Emacs waits for the synchronous subprocess to terminate, the +user can quit by typing `C-g'. The first `C-g' tries to kill the +subprocess with a `SIGINT' signal; but it waits until the subprocess +actually terminates before quitting. If during that time the user +types another `C-g', that kills the subprocess instantly with `SIGKILL' +and quits immediately. *Note Quitting::. + + The synchronous subprocess functions returned `nil' in version 18. +In version 19, they return an indication of how the process terminated. + + - Function: call-process program &optional infile destination display + &rest args + This function calls PROGRAM in a separate process and waits for it + to finish. + + The standard input for the process comes from file INFILE if + INFILE is not `nil' and from `/dev/null' otherwise. The argument + DESTINATION says where to put the process output. Here are the + possibilities: + + a buffer + Insert the output in that buffer, before point. This + includes both the standard output stream and the standard + error stream of the process. + + a string + Find or create a buffer with that name, then insert the + output in that buffer, before point. + + `t' + Insert the output in the current buffer, before point. + + `nil' + Discard the output. + + 0 + Discard the output, and return immediately without waiting + for the subprocess to finish. + + In this case, the process is not truly synchronous, since it + can run in parallel with Emacs; but you can think of it as + synchronous in that Emacs is essentially finished with the + subprocess as soon as this function returns. + + (REAL-DESTINATION ERROR-DESTINATION) + Keep the standard output stream separate from the standard + error stream; deal with the ordinary output as specified by + REAL-DESTINATION, and dispose of the error output according + to ERROR-DESTINATION. The value `nil' means discard it, `t' + means mix it with the ordinary output, and a string specifies + a file name to redirect error output into. + + You can't directly specify a buffer to put the error output + in; that is too difficult to implement. But you can achieve + this result by sending the error output to a temporary file + and then inserting the file into a buffer. + + If DISPLAY is non-`nil', then `call-process' redisplays the buffer + as output is inserted. Otherwise the function does no redisplay, + and the results become visible on the screen only when XEmacs + redisplays that buffer in the normal course of events. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + The value returned by `call-process' (unless you told it not to + wait) indicates the reason for process termination. A number + gives the exit status of the subprocess; 0 means success, and any + other value means failure. If the process terminated with a + signal, `call-process' returns a string describing the signal. + + In the examples below, the buffer `foo' is current. + + (call-process "pwd" nil t) + => nil + + ---------- Buffer: foo ---------- + /usr/user/lewis/manual + ---------- Buffer: foo ---------- + + (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") + => nil + + ---------- Buffer: bar ---------- + lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh + + ---------- Buffer: bar ---------- + + The `insert-directory' function contains a good example of the use + of `call-process': + + (call-process insert-directory-program nil t nil switches + (if full-directory-p + (concat (file-name-as-directory file) ".") + file)) + + - Function: call-process-region start end program &optional delete + destination display &rest args + This function sends the text between START to END as standard + input to a process running PROGRAM. It deletes the text sent if + DELETE is non-`nil'; this is useful when BUFFER is `t', to insert + the output in the current buffer. + + The arguments DESTINATION and DISPLAY control what to do with the + output from the subprocess, and whether to update the display as + it comes in. For details, see the description of `call-process', + above. If DESTINATION is the integer 0, `call-process-region' + discards the output and returns `nil' immediately, without waiting + for the subprocess to finish. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + The return value of `call-process-region' is just like that of + `call-process': `nil' if you told it to return without waiting; + otherwise, a number or string which indicates how the subprocess + terminated. + + In the following example, we use `call-process-region' to run the + `cat' utility, with standard input being the first five characters + in buffer `foo' (the word `input'). `cat' copies its standard + input into its standard output. Since the argument DESTINATION is + `t', this output is inserted in the current buffer. + + ---------- Buffer: foo ---------- + input-!- + ---------- Buffer: foo ---------- + + (call-process-region 1 6 "cat" nil t) + => nil + + ---------- Buffer: foo ---------- + inputinput-!- + ---------- Buffer: foo ---------- + + The `shell-command-on-region' command uses `call-process-region' + like this: + + (call-process-region + start end + shell-file-name ; Name of program. + nil ; Do not delete region. + buffer ; Send output to `buffer'. + nil ; No redisplay during output. + "-c" command) ; Arguments for the shell. + + +File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes + +MS-DOS Subprocesses +=================== + + On MS-DOS, you must indicate whether the data going to and from a +synchronous subprocess are text or binary. Text data requires +translation between the end-of-line convention used within Emacs (a +single newline character) and the convention used outside Emacs (the +two-character sequence, CRLF). + + The variable `binary-process-input' applies to input sent to the +subprocess, and `binary-process-output' applies to output received from +it. A non-`nil' value means the data is non-text; `nil' means the data +is text, and calls for conversion. + + - Variable: binary-process-input + If this variable is `nil', convert newlines to CRLF sequences in + the input to a synchronous subprocess. + + - Variable: binary-process-output + If this variable is `nil', convert CRLF sequences to newlines in + the output from a synchronous subprocess. + + *Note Files and MS-DOS::, for related information. + + +File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes + +Creating an Asynchronous Process +================================ + + After an "asynchronous process" is created, Emacs and the Lisp +program both continue running immediately. The process may thereafter +run in parallel with Emacs, and the two may communicate with each other +using the functions described in following sections. Here we describe +how to create an asynchronous process with `start-process'. + + - Function: start-process name buffer-or-name program &rest args + This function creates a new asynchronous subprocess and starts the + program PROGRAM running in it. It returns a process object that + stands for the new subprocess in Lisp. The argument NAME + specifies the name for the process object; if a process with this + name already exists, then NAME is modified (by adding `<1>', etc.) + to be unique. The buffer BUFFER-OR-NAME is the buffer to + associate with the process. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + In the example below, the first process is started and runs + (rather, sleeps) for 100 seconds. Meanwhile, the second process + is started, and given the name `my-process<1>' for the sake of + uniqueness. It inserts the directory listing at the end of the + buffer `foo', before the first process finishes. Then it + finishes, and a message to that effect is inserted in the buffer. + Much later, the first process finishes, and another message is + inserted in the buffer for it. + + (start-process "my-process" "foo" "sleep" "100") + => # + + (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") + => #> + + ---------- Buffer: foo ---------- + total 2 + lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs + -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon + + Process my-process<1> finished + + Process my-process finished + ---------- Buffer: foo ---------- + + - Function: start-process-shell-command name buffer-or-name command + &rest command-args + This function is like `start-process' except that it uses a shell + to execute the specified command. The argument COMMAND is a shell + command name, and COMMAND-ARGS are the arguments for the shell + command. + + - Variable: process-connection-type + This variable controls the type of device used to communicate with + asynchronous subprocesses. If it is non-`nil', then PTYs are + used, when available. Otherwise, pipes are used. + + PTYs are usually preferable for processes visible to the user, as + in Shell mode, because they allow job control (`C-c', `C-z', etc.) + to work between the process and its children whereas pipes do not. + For subprocesses used for internal purposes by programs, it is + often better to use a pipe, because they are more efficient. In + addition, the total number of PTYs is limited on many systems and + it is good not to waste them. + + The value `process-connection-type' is used when `start-process' + is called. So you can specify how to communicate with one + subprocess by binding the variable around the call to + `start-process'. + + (let ((process-connection-type nil)) ; Use a pipe. + (start-process ...)) + + To determine whether a given subprocess actually got a pipe or a + PTY, use the function `process-tty-name' (*note Process + Information::). + + +File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes + +Deleting Processes +================== + + "Deleting a process" disconnects XEmacs immediately from the +subprocess, and removes it from the list of active processes. It sends +a signal to the subprocess to make the subprocess terminate, but this is +not guaranteed to happen immediately. The process object itself +continues to exist as long as other Lisp objects point to it. + + You can delete a process explicitly at any time. Processes are +deleted automatically after they terminate, but not necessarily right +away. If you delete a terminated process explicitly before it is +deleted automatically, no harm results. + + - Variable: delete-exited-processes + This variable controls automatic deletion of processes that have + terminated (due to calling `exit' or to a signal). If it is + `nil', then they continue to exist until the user runs + `list-processes'. Otherwise, they are deleted immediately after + they exit. + + - Function: delete-process name + This function deletes the process associated with NAME, killing it + with a `SIGHUP' signal. The argument NAME may be a process, the + name of a process, a buffer, or the name of a buffer. + + (delete-process "*shell*") + => nil + + - Function: process-kill-without-query process &optional + require-query-p + This function declares that XEmacs need not query the user if + PROCESS is still running when XEmacs is exited. The process will + be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs + _will_ query the user (this is the default). The return value is + `t' if a query was formerly required, and `nil' otherwise. + + (process-kill-without-query (get-process "shell")) + => t + + +File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes + +Process Information +=================== + + Several functions return information about processes. +`list-processes' is provided for interactive use. + + - Command: list-processes + This command displays a listing of all living processes. In + addition, it finally deletes any process whose status was `Exited' + or `Signaled'. It returns `nil'. + + - Function: process-list + This function returns a list of all processes that have not been + deleted. + + (process-list) + => (# #) + + - Function: get-process name + This function returns the process named NAME, or `nil' if there is + none. An error is signaled if NAME is not a string. + + (get-process "shell") + => # + + - Function: process-command process + This function returns the command that was executed to start + PROCESS. This is a list of strings, the first string being the + program executed and the rest of the strings being the arguments + that were given to the program. + + (process-command (get-process "shell")) + => ("/bin/csh" "-i") + + - Function: process-id process + This function returns the PID of PROCESS. This is an integer that + distinguishes the process PROCESS from all other processes running + on the same computer at the current time. The PID of a process is + chosen by the operating system kernel when the process is started + and remains constant as long as the process exists. + + - Function: process-name process + This function returns the name of PROCESS. + + - Function: process-status process-name + This function returns the status of PROCESS-NAME as a symbol. The + argument PROCESS-NAME must be a process, a buffer, a process name + (string) or a buffer name (string). + + The possible values for an actual subprocess are: + + `run' + for a process that is running. + + `stop' + for a process that is stopped but continuable. + + `exit' + for a process that has exited. + + `signal' + for a process that has received a fatal signal. + + `open' + for a network connection that is open. + + `closed' + for a network connection that is closed. Once a connection + is closed, you cannot reopen it, though you might be able to + open a new connection to the same place. + + `nil' + if PROCESS-NAME is not the name of an existing process. + + (process-status "shell") + => run + (process-status (get-buffer "*shell*")) + => run + x + => #> + (process-status x) + => exit + + For a network connection, `process-status' returns one of the + symbols `open' or `closed'. The latter means that the other side + closed the connection, or XEmacs did `delete-process'. + + In earlier Emacs versions (prior to version 19), the status of a + network connection was `run' if open, and `exit' if closed. + + - Function: process-kill-without-query-p process + This function returns whether PROCESS will be killed without + querying the user, if it is running when XEmacs is exited. The + default value is `nil'. + + - Function: process-exit-status process + This function returns the exit status of PROCESS or the signal + number that killed it. (Use the result of `process-status' to + determine which of those it is.) If PROCESS has not yet + terminated, the value is 0. + + - Function: process-tty-name process + This function returns the terminal name that PROCESS is using for + its communication with Emacs--or `nil' if it is using pipes + instead of a terminal (see `process-connection-type' in *Note + Asynchronous Processes::). + + +File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes + +Sending Input to Processes +========================== + + Asynchronous subprocesses receive input when it is sent to them by +XEmacs, which is done with the functions in this section. You must +specify the process to send input to, and the input data to send. The +data appears on the "standard input" of the subprocess. + + Some operating systems have limited space for buffered input in a +PTY. On these systems, Emacs sends an EOF periodically amidst the +other characters, to force them through. For most programs, these EOFs +do no harm. + + - Function: process-send-string process-name string + This function sends PROCESS-NAME the contents of STRING as + standard input. The argument PROCESS-NAME must be a process or + the name of a process. If it is `nil', the current buffer's + process is used. + + The function returns `nil'. + + (process-send-string "shell<1>" "ls\n") + => nil + + + ---------- Buffer: *shell* ---------- + ... + introduction.texi syntax-tables.texi~ + introduction.texi~ text.texi + introduction.txt text.texi~ + ... + ---------- Buffer: *shell* ---------- + + - Command: process-send-region process-name start end + This function sends the text in the region defined by START and + END as standard input to PROCESS-NAME, which is a process or a + process name. (If it is `nil', the current buffer's process is + used.) + + An error is signaled unless both START and END are integers or + markers that indicate positions in the current buffer. (It is + unimportant which number is larger.) + + - Function: process-send-eof &optional process-name + This function makes PROCESS-NAME see an end-of-file in its input. + The EOF comes after any text already sent to it. + + If PROCESS-NAME is not supplied, or if it is `nil', then this + function sends the EOF to the current buffer's process. An error + is signaled if the current buffer has no process. + + The function returns PROCESS-NAME. + + (process-send-eof "shell") + => "shell" + + +File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes + +Sending Signals to Processes +============================ + + "Sending a signal" to a subprocess is a way of interrupting its +activities. There are several different signals, each with its own +meaning. The set of signals and their names is defined by the operating +system. For example, the signal `SIGINT' means that the user has typed +`C-c', or that some analogous thing has happened. + + Each signal has a standard effect on the subprocess. Most signals +kill the subprocess, but some stop or resume execution instead. Most +signals can optionally be handled by programs; if the program handles +the signal, then we can say nothing in general about its effects. + + The set of signals and their names is defined by the operating +system; XEmacs has facilities for sending only a few of the signals +that are defined. XEmacs can send signals only to its own subprocesses. + + You can send signals explicitly by calling the functions in this +section. XEmacs also sends signals automatically at certain times: +killing a buffer sends a `SIGHUP' signal to all its associated +processes; killing XEmacs sends a `SIGHUP' signal to all remaining +processes. (`SIGHUP' is a signal that usually indicates that the user +hung up the phone.) + + Each of the signal-sending functions takes two optional arguments: +PROCESS-NAME and CURRENT-GROUP. + + The argument PROCESS-NAME must be either a process, the name of one, +or `nil'. If it is `nil', the process defaults to the process +associated with the current buffer. An error is signaled if +PROCESS-NAME does not identify a process. + + The argument CURRENT-GROUP is a flag that makes a difference when +you are running a job-control shell as an XEmacs subprocess. If it is +non-`nil', then the signal is sent to the current process-group of the +terminal that XEmacs uses to communicate with the subprocess. If the +process is a job-control shell, this means the shell's current subjob. +If it is `nil', the signal is sent to the process group of the +immediate subprocess of XEmacs. If the subprocess is a job-control +shell, this is the shell itself. + + The flag CURRENT-GROUP has no effect when a pipe is used to +communicate with the subprocess, because the operating system does not +support the distinction in the case of pipes. For the same reason, +job-control shells won't work when a pipe is used. See +`process-connection-type' in *Note Asynchronous Processes::. + + - Function: interrupt-process &optional process-name current-group + This function interrupts the process PROCESS-NAME by sending the + signal `SIGINT'. Outside of XEmacs, typing the "interrupt + character" (normally `C-c' on some systems, and `DEL' on others) + sends this signal. When the argument CURRENT-GROUP is non-`nil', + you can think of this function as "typing `C-c'" on the terminal + by which XEmacs talks to the subprocess. + + - Function: kill-process &optional process-name current-group + This function kills the process PROCESS-NAME by sending the signal + `SIGKILL'. This signal kills the subprocess immediately, and + cannot be handled by the subprocess. + + - Function: quit-process &optional process-name current-group + This function sends the signal `SIGQUIT' to the process + PROCESS-NAME. This signal is the one sent by the "quit character" + (usually `C-b' or `C-\') when you are not inside XEmacs. + + - Function: stop-process &optional process-name current-group + This function stops the process PROCESS-NAME by sending the signal + `SIGTSTP'. Use `continue-process' to resume its execution. + + On systems with job control, the "stop character" (usually `C-z') + sends this signal (outside of XEmacs). When CURRENT-GROUP is + non-`nil', you can think of this function as "typing `C-z'" on the + terminal XEmacs uses to communicate with the subprocess. + + - Function: continue-process &optional process-name current-group + This function resumes execution of the process PROCESS by sending + it the signal `SIGCONT'. This presumes that PROCESS-NAME was + stopped previously. + + - Function: signal-process pid signal + This function sends a signal to process PID, which need not be a + child of XEmacs. The argument SIGNAL specifies which signal to + send; it should be an integer. + + +File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes + +Receiving Output from Processes +=============================== + + There are two ways to receive the output that a subprocess writes to +its standard output stream. The output can be inserted in a buffer, +which is called the associated buffer of the process, or a function +called the "filter function" can be called to act on the output. If +the process has no buffer and no filter function, its output is +discarded. + +* Menu: + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: Explicitly permitting subprocess output. + Waiting for subprocess output. + + File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes Process Buffers @@ -267,929 +1162,3 @@ until output arrives from a process. get some output, or `nil' if the timeout expired before output arrived. - -File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes - -Sentinels: Detecting Process Status Changes -=========================================== - - A "process sentinel" is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by XEmacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is also -called if the process exits. The sentinel receives two arguments: the -process for which the event occurred, and a string describing the type -of event. - - The string describing the event looks like one of the following: - - * `"finished\n"'. - - * `"exited abnormally with code EXITCODE\n"'. - - * `"NAME-OF-SIGNAL\n"'. - - * `"NAME-OF-SIGNAL (core dumped)\n"'. - - A sentinel runs only while XEmacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running them at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling `sit-for' or `sleep-for' (*note -Waiting::), or `accept-process-output' (*note Accepting Output::). -Emacs is also waiting when the command loop is reading input. - - Quitting is normally inhibited within a sentinel--otherwise, the -effect of typing `C-g' at command level or to quit a user command would -be unpredictable. If you want to permit quitting inside a sentinel, -bind `inhibit-quit' to `nil'. *Note Quitting::. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -`(buffer-name (process-buffer PROCESS))' returns `nil'. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -`debug-on-error' is non-`nil', the error-catching is turned off. This -makes it possible to use the Lisp debugger to debug the sentinel. -*Note Debugger::. - - In earlier Emacs versions, every sentinel that did regexp searching -or matching had to explicitly save and restore the match data. Now -Emacs does this automatically; sentinels never need to do it explicitly. -*Note Match Data::. - - - Function: set-process-sentinel process sentinel - This function associates SENTINEL with PROCESS. If SENTINEL is - `nil', then the process will have no sentinel. The default - behavior when there is no sentinel is to insert a message in the - process's buffer when the process status changes. - - (defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) - (set-process-sentinel (get-process "shell") 'msg-me) - => msg-me - (kill-process (get-process "shell")) - -| Process: # had the event `killed' - => # - - - Function: process-sentinel process - This function returns the sentinel of PROCESS, or `nil' if it has - none. - - - Function: waiting-for-user-input-p - While a sentinel or filter function is running, this function - returns non-`nil' if XEmacs was waiting for keyboard input from - the user at the time the sentinel or filter function was called, - `nil' if it was not. - - -File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes - -Process Window Size -=================== - - - Function: set-process-window-size process height width - This function tells PROCESS that its logical window size is HEIGHT - by WIDTH characters. This is principally useful with pty's. - - -File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes - -Transaction Queues -================== - - You can use a "transaction queue" for more convenient communication -with subprocesses using transactions. First use `tq-create' to create -a transaction queue communicating with a specified process. Then you -can call `tq-enqueue' to send a transaction. - - - Function: tq-create process - This function creates and returns a transaction queue - communicating with PROCESS. The argument PROCESS should be a - subprocess capable of sending and receiving streams of bytes. It - may be a child process, or it may be a TCP connection to a server, - possibly on another machine. - - - Function: tq-enqueue queue question regexp closure fn - This function sends a transaction to queue QUEUE. Specifying the - queue has the effect of specifying the subprocess to talk to. - - The argument QUESTION is the outgoing message that starts the - transaction. The argument FN is the function to call when the - corresponding answer comes back; it is called with two arguments: - CLOSURE, and the answer received. - - The argument REGEXP is a regular expression that should match the - entire answer, but nothing less; that's how `tq-enqueue' determines - where the answer ends. - - The return value of `tq-enqueue' itself is not meaningful. - - - Function: tq-close queue - Shut down transaction queue QUEUE, waiting for all pending - transactions to complete, and then terminate the connection or - child process. - - Transaction queues are implemented by means of a filter function. -*Note Filter Functions::. - - -File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes - -Network Connections -=================== - - XEmacs Lisp programs can open TCP network connections to other -processes on the same machine or other machines. A network connection -is handled by Lisp much like a subprocess, and is represented by a -process object. However, the process you are communicating with is not -a child of the XEmacs process, so you can't kill it or send it signals. -All you can do is send and receive data. `delete-process' closes the -connection, but does not kill the process at the other end; that -process must decide what to do about closure of the connection. - - You can distinguish process objects representing network connections -from those representing subprocesses with the `process-status' -function. It always returns either `open' or `closed' for a network -connection, and it never returns either of those values for a real -subprocess. *Note Process Information::. - - - Function: open-network-stream name buffer-or-name host service - This function opens a TCP connection for a service to a host. It - returns a process object to represent the connection. - - The NAME argument specifies the name for the process object. It - is modified as necessary to make it unique. - - The BUFFER-OR-NAME argument is the buffer to associate with the - connection. Output from the connection is inserted in the buffer, - unless you specify a filter function to handle the output. If - BUFFER-OR-NAME is `nil', it means that the connection is not - associated with any buffer. - - The arguments HOST and SERVICE specify where to connect to; HOST - is the host name or IP address (a string), and SERVICE is the name - of a defined network service (a string) or a port number (an - integer). - - -File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top - -Operating System Interface -************************** - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output, -and flow control. - - *Note Building XEmacs::, for related information. See also *Note -Display::, for additional operating system status information -pertaining to the terminal and the screen. - -* Menu: - -* Starting Up:: Customizing XEmacs start-up processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to a string, or - to calendrical data (or vice versa). -* Timers:: Setting a timer to call a function at a certain time. -* Terminal Input:: Recording terminal input for debugging. -* Terminal Output:: Recording terminal output for debugging. -* Flow Control:: How to turn output flow control on or off. -* Batch Mode:: Running XEmacs without terminal interaction. - - -File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface - -Starting Up XEmacs -================== - - This section describes what XEmacs does when it is started, and how -you can customize these actions. - -* Menu: - -* Start-up Summary:: Sequence of actions XEmacs performs at start-up. -* Init File:: Details on reading the init file (`.emacs'). -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command Line Arguments:: How command line arguments are processed, - and how you can customize them. - - -File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up - -Summary: Sequence of Actions at Start Up ----------------------------------------- - - The order of operations performed (in `startup.el') by XEmacs when -it is started up is as follows: - - 1. It loads the initialization library for the window system, if you - are using a window system. This library's name is - `term/WINDOWSYSTEM-win.el'. - - 2. It processes the initial options. (Some of them are handled even - earlier than this.) - - 3. It initializes the X window frame and faces, if appropriate. - - 4. It runs the normal hook `before-init-hook'. - - 5. It loads the library `site-start', unless the option - `-no-site-file' was specified. The library's file name is usually - `site-start.el'. - - 6. It loads the file `~/.emacs' unless `-q' was specified on the - command line. (This is not done in `-batch' mode.) The `-u' - option can specify the user name whose home directory should be - used instead of `~'. - - 7. It loads the library `default' unless `inhibit-default-init' is - non-`nil'. (This is not done in `-batch' mode or if `-q' was - specified on the command line.) The library's file name is - usually `default.el'. - - 8. It runs the normal hook `after-init-hook'. - - 9. It sets the major mode according to `initial-major-mode', provided - the buffer `*scratch*' is still current and still in Fundamental - mode. - - 10. It loads the terminal-specific Lisp file, if any, except when in - batch mode or using a window system. - - 11. It displays the initial echo area message, unless you have - suppressed that with `inhibit-startup-echo-area-message'. - - 12. It processes the action arguments from the command line. - - 13. It runs `term-setup-hook'. - - 14. It calls `frame-notice-user-settings', which modifies the - parameters of the selected frame according to whatever the init - files specify. - - 15. It runs `window-setup-hook'. *Note Terminal-Specific::. - - 16. It displays copyleft, nonwarranty, and basic use information, - provided there were no remaining command line arguments (a few - steps above) and the value of `inhibit-startup-message' is `nil'. - - - User Option: inhibit-startup-message - This variable inhibits the initial startup messages (the - nonwarranty, etc.). If it is non-`nil', then the messages are not - printed. - - This variable exists so you can set it in your personal init file, - once you are familiar with the contents of the startup message. - Do not set this variable in the init file of a new user, or in a - way that affects more than one user, because that would prevent - new users from receiving the information they are supposed to see. - - - User Option: inhibit-startup-echo-area-message - This variable controls the display of the startup echo area - message. You can suppress the startup echo area message by adding - text with this form to your `.emacs' file: - - (setq inhibit-startup-echo-area-message - "YOUR-LOGIN-NAME") - - Simply setting `inhibit-startup-echo-area-message' to your login - name is not sufficient to inhibit the message; Emacs explicitly - checks whether `.emacs' contains an expression as shown above. - Your login name must appear in the expression as a Lisp string - constant. - - This way, you can easily inhibit the message for yourself if you - wish, but thoughtless copying of your `.emacs' file will not - inhibit the message for someone else. - - -File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up - -The Init File: `.emacs' ------------------------ - - When you start XEmacs, it normally attempts to load the file -`.emacs' from your home directory. This file, if it exists, must -contain Lisp code. It is called your "init file". The command line -switches `-q' and `-u' affect the use of the init file; `-q' says not -to load an init file, and `-u' says to load a specified user's init -file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs. - - A site may have a "default init file", which is the library named -`default.el'. XEmacs finds the `default.el' file through the standard -search path for libraries (*note How Programs Do Loading::). The -XEmacs distribution does not come with this file; sites may provide one -for local customizations. If the default init file exists, it is -loaded whenever you start Emacs, except in batch mode or if `-q' is -specified. But your own personal init file, if any, is loaded first; if -it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does -not subsequently load the `default.el' file. - - Another file for site-customization is `site-start.el'. Emacs loads -this _before_ the user's init file. You can inhibit the loading of -this file with the option `-no-site-file'. - - - Variable: site-run-file - This variable specifies the site-customization file to load before - the user's init file. Its normal value is `"site-start"'. - - If there is a great deal of code in your `.emacs' file, you should -move it into another file named `SOMETHING.el', byte-compile it (*note -Byte Compilation::), and make your `.emacs' file load the other file -using `load' (*note Loading::). - - *Note Init File Examples: (xemacs)Init File Examples, for examples -of how to make various commonly desired customizations in your `.emacs' -file. - - - User Option: inhibit-default-init - This variable prevents XEmacs from loading the default - initialization library file for your session of XEmacs. If its - value is non-`nil', then the default library is not loaded. The - default value is `nil'. - - - Variable: before-init-hook - - Variable: after-init-hook - These two normal hooks are run just before, and just after, - loading of the user's init file, `default.el', and/or - `site-start.el'. - - -File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up - -Terminal-Specific Initialization --------------------------------- - - Each terminal type can have its own Lisp library that XEmacs loads -when run on that type of terminal. For a terminal type named TERMTYPE, -the library is called `term/TERMTYPE'. XEmacs finds the file by -searching the `load-path' directories as it does for other files, and -trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp -library is located in `emacs/lisp/term', a subdirectory of the -`emacs/lisp' directory in which most XEmacs Lisp libraries are kept. - - The library's name is constructed by concatenating the value of the -variable `term-file-prefix' and the terminal type. Normally, -`term-file-prefix' has the value `"term/"'; changing this is not -recommended. - - The usual function of a terminal-specific library is to enable -special keys to send sequences that XEmacs can recognize. It may also -need to set or add to `function-key-map' if the Termcap entry does not -specify all the terminal's function keys. *Note Terminal Input::. - - When the name of the terminal type contains a hyphen, only the part -of the name before the first hyphen is significant in choosing the -library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use -the `term/aaa' library. If necessary, the library can evaluate -`(getenv "TERM")' to find the full name of the terminal type. - - Your `.emacs' file can prevent the loading of the terminal-specific -library by setting the variable `term-file-prefix' to `nil'. This -feature is useful when experimenting with your own peculiar -customizations. - - You can also arrange to override some of the actions of the -terminal-specific library by setting the variable `term-setup-hook'. -This is a normal hook which XEmacs runs using `run-hooks' at the end of -XEmacs initialization, after loading both your `.emacs' file and any -terminal-specific libraries. You can use this variable to define -initializations for terminals that do not have their own libraries. -*Note Hooks::. - - - Variable: term-file-prefix - If the `term-file-prefix' variable is non-`nil', XEmacs loads a - terminal-specific initialization file as follows: - - (load (concat term-file-prefix (getenv "TERM"))) - - You may set the `term-file-prefix' variable to `nil' in your - `.emacs' file if you do not wish to load the - terminal-initialization file. To do this, put the following in - your `.emacs' file: `(setq term-file-prefix nil)'. - - - Variable: term-setup-hook - This variable is a normal hook that XEmacs runs after loading your - `.emacs' file, the default initialization file (if any) and the - terminal-specific Lisp file. - - You can use `term-setup-hook' to override the definitions made by a - terminal-specific file. - - - Variable: window-setup-hook - This variable is a normal hook which XEmacs runs after loading your - `.emacs' file and the default initialization file (if any), after - loading terminal-specific Lisp code, and after running the hook - `term-setup-hook'. - - -File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up - -Command Line Arguments ----------------------- - - You can use command line arguments to request various actions when -you start XEmacs. Since you do not need to start XEmacs more than once -per day, and will often leave your XEmacs session running longer than -that, command line arguments are hardly ever used. As a practical -matter, it is best to avoid making the habit of using them, since this -habit would encourage you to kill and restart XEmacs unnecessarily -often. These options exist for two reasons: to be compatible with -other editors (for invocation by other programs) and to enable shell -scripts to run specific Lisp programs. - - This section describes how Emacs processes command line arguments, -and how you can customize them. - - - Function: command-line - This function parses the command line that XEmacs was called with, - processes it, loads the user's `.emacs' file and displays the - startup messages. - - - Variable: command-line-processed - The value of this variable is `t' once the command line has been - processed. - - If you redump XEmacs by calling `dump-emacs', you may wish to set - this variable to `nil' first in order to cause the new dumped - XEmacs to process its new command line arguments. - - - Variable: command-switch-alist - The value of this variable is an alist of user-defined command-line - options and associated handler functions. This variable exists so - you can add elements to it. - - A "command line option" is an argument on the command line of the - form: - - -OPTION - - The elements of the `command-switch-alist' look like this: - - (OPTION . HANDLER-FUNCTION) - - The HANDLER-FUNCTION is called to handle OPTION and receives the - option name as its sole argument. - - In some cases, the option is followed in the command line by an - argument. In these cases, the HANDLER-FUNCTION can find all the - remaining command-line arguments in the variable - `command-line-args-left'. (The entire list of command-line - arguments is in `command-line-args'.) - - The command line arguments are parsed by the `command-line-1' - function in the `startup.el' file. See also *Note Command Line - Switches and Arguments: (xemacs)Command Switches. - - - Variable: command-line-args - The value of this variable is the list of command line arguments - passed to XEmacs. - - - Variable: command-line-functions - This variable's value is a list of functions for handling an - unrecognized command-line argument. Each time the next argument - to be processed has no special meaning, the functions in this list - are called, in order of appearance, until one of them returns a - non-`nil' value. - - These functions are called with no arguments. They can access the - command-line argument under consideration through the variable - `argi'. The remaining arguments (not including the current one) - are in the variable `command-line-args-left'. - - When a function recognizes and processes the argument in `argi', it - should return a non-`nil' value to say it has dealt with that - argument. If it has also dealt with some of the following - arguments, it can indicate that by deleting them from - `command-line-args-left'. - - If all of these functions return `nil', then the argument is used - as a file name to visit. - - -File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface - -Getting out of XEmacs -===================== - - There are two ways to get out of XEmacs: you can kill the XEmacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the XEmacs process later. As a practical matter, you seldom -kill XEmacs--only when you are about to log out. Suspending is much -more common. - -* Menu: - -* Killing XEmacs:: Exiting XEmacs irreversibly. -* Suspending XEmacs:: Exiting XEmacs reversibly. - - -File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out - -Killing XEmacs --------------- - - Killing XEmacs means ending the execution of the XEmacs process. The -parent process normally resumes control. The low-level primitive for -killing XEmacs is `kill-emacs'. - - - Function: kill-emacs &optional exit-data - This function exits the XEmacs process and kills it. - - If EXIT-DATA is an integer, then it is used as the exit status of - the XEmacs process. (This is useful primarily in batch operation; - see *Note Batch Mode::.) - - If EXIT-DATA is a string, its contents are stuffed into the - terminal input buffer so that the shell (or whatever program next - reads input) can read them. - - All the information in the XEmacs process, aside from files that have -been saved, is lost when the XEmacs is killed. Because killing XEmacs -inadvertently can lose a lot of work, XEmacs queries for confirmation -before actually terminating if you have buffers that need saving or -subprocesses that are running. This is done in the function -`save-buffers-kill-emacs'. - - - Variable: kill-emacs-query-functions - After asking the standard questions, `save-buffers-kill-emacs' - calls the functions in the list `kill-buffer-query-functions', in - order of appearance, with no arguments. These functions can ask - for additional confirmation from the user. If any of them returns - non-`nil', XEmacs is not killed. - - - Variable: kill-emacs-hook - This variable is a normal hook; once `save-buffers-kill-emacs' is - finished with all file saving and confirmation, it runs the - functions in this hook. - - -File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out - -Suspending XEmacs ------------------ - - "Suspending XEmacs" means stopping XEmacs temporarily and returning -control to its superior process, which is usually the shell. This -allows you to resume editing later in the same XEmacs process, with the -same buffers, the same kill ring, the same undo history, and so on. To -resume XEmacs, use the appropriate command in the parent shell--most -likely `fg'. - - Some operating systems do not support suspension of jobs; on these -systems, "suspension" actually creates a new shell temporarily as a -subprocess of XEmacs. Then you would exit the shell to return to -XEmacs. - - Suspension is not useful with window systems such as X, because the -XEmacs job may not have a parent that can resume it again, and in any -case you can give input to some other job such as a shell merely by -moving to a different window. Therefore, suspending is not allowed -when XEmacs is an X client. - - - Function: suspend-emacs string - This function stops XEmacs and returns control to the superior - process. If and when the superior process resumes XEmacs, - `suspend-emacs' returns `nil' to its caller in Lisp. - - If STRING is non-`nil', its characters are sent to be read as - terminal input by XEmacs's superior shell. The characters in - STRING are not echoed by the superior shell; only the results - appear. - - Before suspending, `suspend-emacs' runs the normal hook - `suspend-hook'. In Emacs version 18, `suspend-hook' was not a - normal hook; its value was a single function, and if its value was - non-`nil', then `suspend-emacs' returned immediately without - actually suspending anything. - - After the user resumes XEmacs, `suspend-emacs' runs the normal hook - `suspend-resume-hook'. *Note Hooks::. - - The next redisplay after resumption will redraw the entire screen, - unless the variable `no-redraw-on-reenter' is non-`nil' (*note - Refresh Screen::). - - In the following example, note that `pwd' is not echoed after - XEmacs is suspended. But it is read and executed by the shell. - - (suspend-emacs) - => nil - - (add-hook 'suspend-hook - (function (lambda () - (or (y-or-n-p - "Really suspend? ") - (error "Suspend cancelled"))))) - => (lambda nil - (or (y-or-n-p "Really suspend? ") - (error "Suspend cancelled"))) - (add-hook 'suspend-resume-hook - (function (lambda () (message "Resumed!")))) - => (lambda nil (message "Resumed!")) - (suspend-emacs "pwd") - => nil - ---------- Buffer: Minibuffer ---------- - Really suspend? y - ---------- Buffer: Minibuffer ---------- - - ---------- Parent Shell ---------- - lewis@slug[23] % /user/lewis/manual - lewis@slug[24] % fg - - ---------- Echo Area ---------- - Resumed! - - - Variable: suspend-hook - This variable is a normal hook run before suspending. - - - Variable: suspend-resume-hook - This variable is a normal hook run after suspending. - - -File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface - -Operating System Environment -============================ - - XEmacs provides access to variables in the operating system -environment through various functions. These variables include the -name of the system, the user's UID, and so on. - - - Variable: system-type - The value of this variable is a symbol indicating the type of - operating system XEmacs is operating on. Here is a table of the - possible values: - - `aix-v3' - AIX. - - `berkeley-unix' - Berkeley BSD. - - `dgux' - Data General DGUX operating system. - - `gnu' - A GNU system using the GNU HURD and Mach. - - `hpux' - Hewlett-Packard HPUX operating system. - - `irix' - Silicon Graphics Irix system. - - `linux' - A GNU system using the Linux kernel. - - `ms-dos' - Microsoft MS-DOS "operating system." - - `next-mach' - NeXT Mach-based system. - - `rtu' - Masscomp RTU, UCB universe. - - `unisoft-unix' - UniSoft UniPlus. - - `usg-unix-v' - AT&T System V. - - `vax-vms' - VAX VMS. - - `windows-nt' - Microsoft windows NT. - - `xenix' - SCO Xenix 386. - - We do not wish to add new symbols to make finer distinctions - unless it is absolutely necessary! In fact, we hope to eliminate - some of these alternatives in the future. We recommend using - `system-configuration' to distinguish between different operating - systems. - - - Variable: system-configuration - This variable holds the three-part configuration name for the - hardware/software configuration of your system, as a string. The - convenient way to test parts of this string is with `string-match'. - - - Function: system-name - This function returns the name of the machine you are running on. - (system-name) - => "prep.ai.mit.edu" - - The symbol `system-name' is a variable as well as a function. In -fact, the function returns whatever value the variable `system-name' -currently holds. Thus, you can set the variable `system-name' in case -Emacs is confused about the name of your system. The variable is also -useful for constructing frame titles (*note Frame Titles::). - - - Variable: mail-host-address - If this variable is non-`nil', it is used instead of `system-name' - for purposes of generating email addresses. For example, it is - used when constructing the default value of `user-mail-address'. - *Note User Identification::. (Since this is done when XEmacs - starts up, the value actually used is the one saved when XEmacs - was dumped. *Note Building XEmacs::.) - - - Function: getenv var - This function returns the value of the environment variable VAR, - as a string. Within XEmacs, the environment variable values are - kept in the Lisp variable `process-environment'. - - (getenv "USER") - => "lewis" - - lewis@slug[10] % printenv - PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin - USER=lewis - TERM=ibmapa16 - SHELL=/bin/csh - HOME=/user/lewis - - - Command: setenv variable value - This command sets the value of the environment variable named - VARIABLE to VALUE. Both arguments should be strings. This - function works by modifying `process-environment'; binding that - variable with `let' is also reasonable practice. - - - Variable: process-environment - This variable is a list of strings, each describing one environment - variable. The functions `getenv' and `setenv' work by means of - this variable. - - process-environment - => ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") - - - Variable: path-separator - This variable holds a string which says which character separates - directories in a search path (as found in an environment - variable). Its value is `":"' for Unix and GNU systems, and `";"' - for MS-DOS and Windows NT. - - - Variable: invocation-name - This variable holds the program name under which Emacs was - invoked. The value is a string, and does not include a directory - name. - - - Variable: invocation-directory - This variable holds the directory from which the Emacs executable - was invoked, or perhaps `nil' if that directory cannot be - determined. - - - Variable: installation-directory - If non-`nil', this is a directory within which to look for the - `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs - can't find those directories in their standard installed - locations, but can find them in a directory related somehow to the - one containing the Emacs executable. - - - Function: load-average &optional use-floats - This function returns a list of the current 1-minute, 5-minute and - 15-minute load averages. The values are integers that are 100 - times the system load averages. (The load averages indicate the - number of processes trying to run.) - - When USE-FLOATS is non-`nil', floats will be returned instead of - integers. These floats are not multiplied by 100. - - (load-average) - => (169 158 164) - (load-average t) - => (1.69921875 1.58984375 1.640625) - - lewis@rocky[5] % uptime - 8:06pm up 16 day(s), 21:57, 40 users, - load average: 1.68, 1.59, 1.64 - - If the 5-minute or 15-minute load averages are not available, - return a shortened list, containing only those averages which are - available. - - On some systems, this function may require special privileges to - run, or it may be unimplemented for the particular system type. - In that case, the function will signal an error. - - - Function: emacs-pid - This function returns the process ID of the Emacs process. - - - Function: setprv privilege-name &optional setp getprv - This function sets or resets a VMS privilege. (It does not exist - on Unix.) The first arg is the privilege name, as a string. The - second argument, SETP, is `t' or `nil', indicating whether the - privilege is to be turned on or off. Its default is `nil'. The - function returns `t' if successful, `nil' otherwise. - - If the third argument, GETPRV, is non-`nil', `setprv' does not - change the privilege, but returns `t' or `nil' indicating whether - the privilege is currently enabled. - - -File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface - -User Identification -=================== - - - Variable: user-mail-address - This holds the nominal email address of the user who is using - Emacs. When Emacs starts up, it computes a default value that is - usually right, but users often set this themselves when the - default value is not right. - - - Function: user-login-name &optional uid - If you don't specify UID, this function returns the name under - which the user is logged in. If the environment variable `LOGNAME' - is set, that value is used. Otherwise, if the environment variable - `USER' is set, that value is used. Otherwise, the value is based - on the effective UID, not the real UID. - - If you specify UID, the value is the user name that corresponds to - UID (which should be an integer). - - (user-login-name) - => "lewis" - - - Function: user-real-login-name - This function returns the user name corresponding to Emacs's real - UID. This ignores the effective UID and ignores the environment - variables `LOGNAME' and `USER'. - - - Variable: user-full-name - This variable holds the name of the user running this Emacs. It is - initialized at startup time from the value of `NAME' environment - variable. You can change the value of this variable to alter the - result of the `user-full-name' function. - - - Function: user-full-name &optional user - This function returns the full name of USER. If USER is `nil', it - defaults to the user running this Emacs. In that case, the value - of `user-full-name' variable, if non-`nil', will be used. - - If USER is specified explicitly, `user-full-name' variable is - ignored. - - (user-full-name) - => "Hrvoje Niksic" - (setq user-full-name "Hrvoje \"Niksa\" Niksic") - (user-full-name) - => "Hrvoje \"Niksa\" Niksic" - (user-full-name "hniksic") - => "Hrvoje Niksic" - - The symbols `user-login-name', `user-real-login-name' and -`user-full-name' are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to "fake out" Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (*note Frame -Titles::). - - - Function: user-real-uid - This function returns the real UID of the user. - - (user-real-uid) - => 19 - - - Function: user-uid - This function returns the effective UID of the user. - - - Function: user-home-directory - This function returns the "`HOME'" directory of the user, and is - intended to replace occurrences of "`(getenv "HOME")'". Under - Unix systems, the following is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. Return "/", as a fallback, but issue a warning. (Future - versions of XEmacs will also attempt to lookup the `HOME' - directory via `getpwent()', but this has not yet been - implemented.) - - Under MS Windows, this is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are - both set, return the concatenation (the following description - uses MS Windows environment variable substitution syntax): - `%HOMEDRIVE%%HOMEDIR%'. - - 3. Return "C:\", as a fallback, but issue a warning. - diff --git a/info/lispref.info-40 b/info/lispref.info-40 index 69a170a..5c82aef 100644 --- a/info/lispref.info-40 +++ b/info/lispref.info-40 @@ -50,6 +50,932 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes + +Sentinels: Detecting Process Status Changes +=========================================== + + A "process sentinel" is a function that is called whenever the +associated process changes status for any reason, including signals +(whether sent by XEmacs or caused by the process's own actions) that +terminate, stop, or continue the process. The process sentinel is also +called if the process exits. The sentinel receives two arguments: the +process for which the event occurred, and a string describing the type +of event. + + The string describing the event looks like one of the following: + + * `"finished\n"'. + + * `"exited abnormally with code EXITCODE\n"'. + + * `"NAME-OF-SIGNAL\n"'. + + * `"NAME-OF-SIGNAL (core dumped)\n"'. + + A sentinel runs only while XEmacs is waiting (e.g., for terminal +input, or for time to elapse, or for process output). This avoids the +timing errors that could result from running them at random places in +the middle of other Lisp programs. A program can wait, so that +sentinels will run, by calling `sit-for' or `sleep-for' (*note +Waiting::), or `accept-process-output' (*note Accepting Output::). +Emacs is also waiting when the command loop is reading input. + + Quitting is normally inhibited within a sentinel--otherwise, the +effect of typing `C-g' at command level or to quit a user command would +be unpredictable. If you want to permit quitting inside a sentinel, +bind `inhibit-quit' to `nil'. *Note Quitting::. + + A sentinel that writes the output into the buffer of the process +should check whether the buffer is still alive. If it tries to insert +into a dead buffer, it will get an error. If the buffer is dead, +`(buffer-name (process-buffer PROCESS))' returns `nil'. + + If an error happens during execution of a sentinel, it is caught +automatically, so that it doesn't stop the execution of whatever +programs was running when the sentinel was started. However, if +`debug-on-error' is non-`nil', the error-catching is turned off. This +makes it possible to use the Lisp debugger to debug the sentinel. +*Note Debugger::. + + In earlier Emacs versions, every sentinel that did regexp searching +or matching had to explicitly save and restore the match data. Now +Emacs does this automatically; sentinels never need to do it explicitly. +*Note Match Data::. + + - Function: set-process-sentinel process sentinel + This function associates SENTINEL with PROCESS. If SENTINEL is + `nil', then the process will have no sentinel. The default + behavior when there is no sentinel is to insert a message in the + process's buffer when the process status changes. + + (defun msg-me (process event) + (princ + (format "Process: %s had the event `%s'" process event))) + (set-process-sentinel (get-process "shell") 'msg-me) + => msg-me + (kill-process (get-process "shell")) + -| Process: # had the event `killed' + => # + + - Function: process-sentinel process + This function returns the sentinel of PROCESS, or `nil' if it has + none. + + - Function: waiting-for-user-input-p + While a sentinel or filter function is running, this function + returns non-`nil' if XEmacs was waiting for keyboard input from + the user at the time the sentinel or filter function was called, + `nil' if it was not. + + +File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes + +Process Window Size +=================== + + - Function: set-process-window-size process height width + This function tells PROCESS that its logical window size is HEIGHT + by WIDTH characters. This is principally useful with pty's. + + +File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes + +Transaction Queues +================== + + You can use a "transaction queue" for more convenient communication +with subprocesses using transactions. First use `tq-create' to create +a transaction queue communicating with a specified process. Then you +can call `tq-enqueue' to send a transaction. + + - Function: tq-create process + This function creates and returns a transaction queue + communicating with PROCESS. The argument PROCESS should be a + subprocess capable of sending and receiving streams of bytes. It + may be a child process, or it may be a TCP connection to a server, + possibly on another machine. + + - Function: tq-enqueue queue question regexp closure fn + This function sends a transaction to queue QUEUE. Specifying the + queue has the effect of specifying the subprocess to talk to. + + The argument QUESTION is the outgoing message that starts the + transaction. The argument FN is the function to call when the + corresponding answer comes back; it is called with two arguments: + CLOSURE, and the answer received. + + The argument REGEXP is a regular expression that should match the + entire answer, but nothing less; that's how `tq-enqueue' determines + where the answer ends. + + The return value of `tq-enqueue' itself is not meaningful. + + - Function: tq-close queue + Shut down transaction queue QUEUE, waiting for all pending + transactions to complete, and then terminate the connection or + child process. + + Transaction queues are implemented by means of a filter function. +*Note Filter Functions::. + + +File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes + +Network Connections +=================== + + XEmacs Lisp programs can open TCP network connections to other +processes on the same machine or other machines. A network connection +is handled by Lisp much like a subprocess, and is represented by a +process object. However, the process you are communicating with is not +a child of the XEmacs process, so you can't kill it or send it signals. +All you can do is send and receive data. `delete-process' closes the +connection, but does not kill the process at the other end; that +process must decide what to do about closure of the connection. + + You can distinguish process objects representing network connections +from those representing subprocesses with the `process-status' +function. It always returns either `open' or `closed' for a network +connection, and it never returns either of those values for a real +subprocess. *Note Process Information::. + + - Function: open-network-stream name buffer-or-name host service + This function opens a TCP connection for a service to a host. It + returns a process object to represent the connection. + + The NAME argument specifies the name for the process object. It + is modified as necessary to make it unique. + + The BUFFER-OR-NAME argument is the buffer to associate with the + connection. Output from the connection is inserted in the buffer, + unless you specify a filter function to handle the output. If + BUFFER-OR-NAME is `nil', it means that the connection is not + associated with any buffer. + + The arguments HOST and SERVICE specify where to connect to; HOST + is the host name or IP address (a string), and SERVICE is the name + of a defined network service (a string) or a port number (an + integer). + + +File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top + +Operating System Interface +************************** + + This chapter is about starting and getting out of Emacs, access to +values in the operating system environment, and terminal input, output, +and flow control. + + *Note Building XEmacs::, for related information. See also *Note +Display::, for additional operating system status information +pertaining to the terminal and the screen. + +* Menu: + +* Starting Up:: Customizing XEmacs start-up processing. +* Getting Out:: How exiting works (permanent or temporary). +* System Environment:: Distinguish the name and kind of system. +* User Identification:: Finding the name and user id of the user. +* Time of Day:: Getting the current time. +* Time Conversion:: Converting a time from numeric form to a string, or + to calendrical data (or vice versa). +* Timers:: Setting a timer to call a function at a certain time. +* Terminal Input:: Recording terminal input for debugging. +* Terminal Output:: Recording terminal output for debugging. +* Flow Control:: How to turn output flow control on or off. +* Batch Mode:: Running XEmacs without terminal interaction. + + +File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface + +Starting Up XEmacs +================== + + This section describes what XEmacs does when it is started, and how +you can customize these actions. + +* Menu: + +* Start-up Summary:: Sequence of actions XEmacs performs at start-up. +* Init File:: Details on reading the init file (`.emacs'). +* Terminal-Specific:: How the terminal-specific Lisp file is read. +* Command Line Arguments:: How command line arguments are processed, + and how you can customize them. + + +File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up + +Summary: Sequence of Actions at Start Up +---------------------------------------- + + The order of operations performed (in `startup.el') by XEmacs when +it is started up is as follows: + + 1. It loads the initialization library for the window system, if you + are using a window system. This library's name is + `term/WINDOWSYSTEM-win.el'. + + 2. It processes the initial options. (Some of them are handled even + earlier than this.) + + 3. It initializes the X window frame and faces, if appropriate. + + 4. It runs the normal hook `before-init-hook'. + + 5. It loads the library `site-start', unless the option + `-no-site-file' was specified. The library's file name is usually + `site-start.el'. + + 6. It loads the file `~/.emacs' unless `-q' was specified on the + command line. (This is not done in `-batch' mode.) The `-u' + option can specify the user name whose home directory should be + used instead of `~'. + + 7. It loads the library `default' unless `inhibit-default-init' is + non-`nil'. (This is not done in `-batch' mode or if `-q' was + specified on the command line.) The library's file name is + usually `default.el'. + + 8. It runs the normal hook `after-init-hook'. + + 9. It sets the major mode according to `initial-major-mode', provided + the buffer `*scratch*' is still current and still in Fundamental + mode. + + 10. It loads the terminal-specific Lisp file, if any, except when in + batch mode or using a window system. + + 11. It displays the initial echo area message, unless you have + suppressed that with `inhibit-startup-echo-area-message'. + + 12. It processes the action arguments from the command line. + + 13. It runs `term-setup-hook'. + + 14. It calls `frame-notice-user-settings', which modifies the + parameters of the selected frame according to whatever the init + files specify. + + 15. It runs `window-setup-hook'. *Note Terminal-Specific::. + + 16. It displays copyleft, nonwarranty, and basic use information, + provided there were no remaining command line arguments (a few + steps above) and the value of `inhibit-startup-message' is `nil'. + + - User Option: inhibit-startup-message + This variable inhibits the initial startup messages (the + nonwarranty, etc.). If it is non-`nil', then the messages are not + printed. + + This variable exists so you can set it in your personal init file, + once you are familiar with the contents of the startup message. + Do not set this variable in the init file of a new user, or in a + way that affects more than one user, because that would prevent + new users from receiving the information they are supposed to see. + + - User Option: inhibit-startup-echo-area-message + This variable controls the display of the startup echo area + message. You can suppress the startup echo area message by adding + text with this form to your `.emacs' file: + + (setq inhibit-startup-echo-area-message + "YOUR-LOGIN-NAME") + + Simply setting `inhibit-startup-echo-area-message' to your login + name is not sufficient to inhibit the message; Emacs explicitly + checks whether `.emacs' contains an expression as shown above. + Your login name must appear in the expression as a Lisp string + constant. + + This way, you can easily inhibit the message for yourself if you + wish, but thoughtless copying of your `.emacs' file will not + inhibit the message for someone else. + + +File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up + +The Init File: `.emacs' +----------------------- + + When you start XEmacs, it normally attempts to load the file +`.emacs' from your home directory. This file, if it exists, must +contain Lisp code. It is called your "init file". The command line +switches `-q' and `-u' affect the use of the init file; `-q' says not +to load an init file, and `-u' says to load a specified user's init +file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs. + + A site may have a "default init file", which is the library named +`default.el'. XEmacs finds the `default.el' file through the standard +search path for libraries (*note How Programs Do Loading::). The +XEmacs distribution does not come with this file; sites may provide one +for local customizations. If the default init file exists, it is +loaded whenever you start Emacs, except in batch mode or if `-q' is +specified. But your own personal init file, if any, is loaded first; if +it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does +not subsequently load the `default.el' file. + + Another file for site-customization is `site-start.el'. Emacs loads +this _before_ the user's init file. You can inhibit the loading of +this file with the option `-no-site-file'. + + - Variable: site-run-file + This variable specifies the site-customization file to load before + the user's init file. Its normal value is `"site-start"'. + + If there is a great deal of code in your `.emacs' file, you should +move it into another file named `SOMETHING.el', byte-compile it (*note +Byte Compilation::), and make your `.emacs' file load the other file +using `load' (*note Loading::). + + *Note Init File Examples: (xemacs)Init File Examples, for examples +of how to make various commonly desired customizations in your `.emacs' +file. + + - User Option: inhibit-default-init + This variable prevents XEmacs from loading the default + initialization library file for your session of XEmacs. If its + value is non-`nil', then the default library is not loaded. The + default value is `nil'. + + - Variable: before-init-hook + - Variable: after-init-hook + These two normal hooks are run just before, and just after, + loading of the user's init file, `default.el', and/or + `site-start.el'. + + +File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up + +Terminal-Specific Initialization +-------------------------------- + + Each terminal type can have its own Lisp library that XEmacs loads +when run on that type of terminal. For a terminal type named TERMTYPE, +the library is called `term/TERMTYPE'. XEmacs finds the file by +searching the `load-path' directories as it does for other files, and +trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp +library is located in `emacs/lisp/term', a subdirectory of the +`emacs/lisp' directory in which most XEmacs Lisp libraries are kept. + + The library's name is constructed by concatenating the value of the +variable `term-file-prefix' and the terminal type. Normally, +`term-file-prefix' has the value `"term/"'; changing this is not +recommended. + + The usual function of a terminal-specific library is to enable +special keys to send sequences that XEmacs can recognize. It may also +need to set or add to `function-key-map' if the Termcap entry does not +specify all the terminal's function keys. *Note Terminal Input::. + + When the name of the terminal type contains a hyphen, only the part +of the name before the first hyphen is significant in choosing the +library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use +the `term/aaa' library. If necessary, the library can evaluate +`(getenv "TERM")' to find the full name of the terminal type. + + Your `.emacs' file can prevent the loading of the terminal-specific +library by setting the variable `term-file-prefix' to `nil'. This +feature is useful when experimenting with your own peculiar +customizations. + + You can also arrange to override some of the actions of the +terminal-specific library by setting the variable `term-setup-hook'. +This is a normal hook which XEmacs runs using `run-hooks' at the end of +XEmacs initialization, after loading both your `.emacs' file and any +terminal-specific libraries. You can use this variable to define +initializations for terminals that do not have their own libraries. +*Note Hooks::. + + - Variable: term-file-prefix + If the `term-file-prefix' variable is non-`nil', XEmacs loads a + terminal-specific initialization file as follows: + + (load (concat term-file-prefix (getenv "TERM"))) + + You may set the `term-file-prefix' variable to `nil' in your + `.emacs' file if you do not wish to load the + terminal-initialization file. To do this, put the following in + your `.emacs' file: `(setq term-file-prefix nil)'. + + - Variable: term-setup-hook + This variable is a normal hook that XEmacs runs after loading your + `.emacs' file, the default initialization file (if any) and the + terminal-specific Lisp file. + + You can use `term-setup-hook' to override the definitions made by a + terminal-specific file. + + - Variable: window-setup-hook + This variable is a normal hook which XEmacs runs after loading your + `.emacs' file and the default initialization file (if any), after + loading terminal-specific Lisp code, and after running the hook + `term-setup-hook'. + + +File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up + +Command Line Arguments +---------------------- + + You can use command line arguments to request various actions when +you start XEmacs. Since you do not need to start XEmacs more than once +per day, and will often leave your XEmacs session running longer than +that, command line arguments are hardly ever used. As a practical +matter, it is best to avoid making the habit of using them, since this +habit would encourage you to kill and restart XEmacs unnecessarily +often. These options exist for two reasons: to be compatible with +other editors (for invocation by other programs) and to enable shell +scripts to run specific Lisp programs. + + This section describes how Emacs processes command line arguments, +and how you can customize them. + + - Function: command-line + This function parses the command line that XEmacs was called with, + processes it, loads the user's `.emacs' file and displays the + startup messages. + + - Variable: command-line-processed + The value of this variable is `t' once the command line has been + processed. + + If you redump XEmacs by calling `dump-emacs', you may wish to set + this variable to `nil' first in order to cause the new dumped + XEmacs to process its new command line arguments. + + - Variable: command-switch-alist + The value of this variable is an alist of user-defined command-line + options and associated handler functions. This variable exists so + you can add elements to it. + + A "command line option" is an argument on the command line of the + form: + + -OPTION + + The elements of the `command-switch-alist' look like this: + + (OPTION . HANDLER-FUNCTION) + + The HANDLER-FUNCTION is called to handle OPTION and receives the + option name as its sole argument. + + In some cases, the option is followed in the command line by an + argument. In these cases, the HANDLER-FUNCTION can find all the + remaining command-line arguments in the variable + `command-line-args-left'. (The entire list of command-line + arguments is in `command-line-args'.) + + The command line arguments are parsed by the `command-line-1' + function in the `startup.el' file. See also *Note Command Line + Switches and Arguments: (xemacs)Command Switches. + + - Variable: command-line-args + The value of this variable is the list of command line arguments + passed to XEmacs. + + - Variable: command-line-functions + This variable's value is a list of functions for handling an + unrecognized command-line argument. Each time the next argument + to be processed has no special meaning, the functions in this list + are called, in order of appearance, until one of them returns a + non-`nil' value. + + These functions are called with no arguments. They can access the + command-line argument under consideration through the variable + `argi'. The remaining arguments (not including the current one) + are in the variable `command-line-args-left'. + + When a function recognizes and processes the argument in `argi', it + should return a non-`nil' value to say it has dealt with that + argument. If it has also dealt with some of the following + arguments, it can indicate that by deleting them from + `command-line-args-left'. + + If all of these functions return `nil', then the argument is used + as a file name to visit. + + +File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface + +Getting out of XEmacs +===================== + + There are two ways to get out of XEmacs: you can kill the XEmacs job, +which exits permanently, or you can suspend it, which permits you to +reenter the XEmacs process later. As a practical matter, you seldom +kill XEmacs--only when you are about to log out. Suspending is much +more common. + +* Menu: + +* Killing XEmacs:: Exiting XEmacs irreversibly. +* Suspending XEmacs:: Exiting XEmacs reversibly. + + +File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out + +Killing XEmacs +-------------- + + Killing XEmacs means ending the execution of the XEmacs process. The +parent process normally resumes control. The low-level primitive for +killing XEmacs is `kill-emacs'. + + - Function: kill-emacs &optional exit-data + This function exits the XEmacs process and kills it. + + If EXIT-DATA is an integer, then it is used as the exit status of + the XEmacs process. (This is useful primarily in batch operation; + see *Note Batch Mode::.) + + If EXIT-DATA is a string, its contents are stuffed into the + terminal input buffer so that the shell (or whatever program next + reads input) can read them. + + All the information in the XEmacs process, aside from files that have +been saved, is lost when the XEmacs is killed. Because killing XEmacs +inadvertently can lose a lot of work, XEmacs queries for confirmation +before actually terminating if you have buffers that need saving or +subprocesses that are running. This is done in the function +`save-buffers-kill-emacs'. + + - Variable: kill-emacs-query-functions + After asking the standard questions, `save-buffers-kill-emacs' + calls the functions in the list `kill-buffer-query-functions', in + order of appearance, with no arguments. These functions can ask + for additional confirmation from the user. If any of them returns + non-`nil', XEmacs is not killed. + + - Variable: kill-emacs-hook + This variable is a normal hook; once `save-buffers-kill-emacs' is + finished with all file saving and confirmation, it runs the + functions in this hook. + + +File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out + +Suspending XEmacs +----------------- + + "Suspending XEmacs" means stopping XEmacs temporarily and returning +control to its superior process, which is usually the shell. This +allows you to resume editing later in the same XEmacs process, with the +same buffers, the same kill ring, the same undo history, and so on. To +resume XEmacs, use the appropriate command in the parent shell--most +likely `fg'. + + Some operating systems do not support suspension of jobs; on these +systems, "suspension" actually creates a new shell temporarily as a +subprocess of XEmacs. Then you would exit the shell to return to +XEmacs. + + Suspension is not useful with window systems such as X, because the +XEmacs job may not have a parent that can resume it again, and in any +case you can give input to some other job such as a shell merely by +moving to a different window. Therefore, suspending is not allowed +when XEmacs is an X client. + + - Function: suspend-emacs string + This function stops XEmacs and returns control to the superior + process. If and when the superior process resumes XEmacs, + `suspend-emacs' returns `nil' to its caller in Lisp. + + If STRING is non-`nil', its characters are sent to be read as + terminal input by XEmacs's superior shell. The characters in + STRING are not echoed by the superior shell; only the results + appear. + + Before suspending, `suspend-emacs' runs the normal hook + `suspend-hook'. In Emacs version 18, `suspend-hook' was not a + normal hook; its value was a single function, and if its value was + non-`nil', then `suspend-emacs' returned immediately without + actually suspending anything. + + After the user resumes XEmacs, `suspend-emacs' runs the normal hook + `suspend-resume-hook'. *Note Hooks::. + + The next redisplay after resumption will redraw the entire screen, + unless the variable `no-redraw-on-reenter' is non-`nil' (*note + Refresh Screen::). + + In the following example, note that `pwd' is not echoed after + XEmacs is suspended. But it is read and executed by the shell. + + (suspend-emacs) + => nil + + (add-hook 'suspend-hook + (function (lambda () + (or (y-or-n-p + "Really suspend? ") + (error "Suspend cancelled"))))) + => (lambda nil + (or (y-or-n-p "Really suspend? ") + (error "Suspend cancelled"))) + (add-hook 'suspend-resume-hook + (function (lambda () (message "Resumed!")))) + => (lambda nil (message "Resumed!")) + (suspend-emacs "pwd") + => nil + ---------- Buffer: Minibuffer ---------- + Really suspend? y + ---------- Buffer: Minibuffer ---------- + + ---------- Parent Shell ---------- + lewis@slug[23] % /user/lewis/manual + lewis@slug[24] % fg + + ---------- Echo Area ---------- + Resumed! + + - Variable: suspend-hook + This variable is a normal hook run before suspending. + + - Variable: suspend-resume-hook + This variable is a normal hook run after suspending. + + +File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface + +Operating System Environment +============================ + + XEmacs provides access to variables in the operating system +environment through various functions. These variables include the +name of the system, the user's UID, and so on. + + - Variable: system-type + The value of this variable is a symbol indicating the type of + operating system XEmacs is operating on. Here is a table of the + possible values: + + `aix-v3' + AIX. + + `berkeley-unix' + Berkeley BSD. + + `dgux' + Data General DGUX operating system. + + `gnu' + A GNU system using the GNU HURD and Mach. + + `hpux' + Hewlett-Packard HPUX operating system. + + `irix' + Silicon Graphics Irix system. + + `linux' + A GNU system using the Linux kernel. + + `ms-dos' + Microsoft MS-DOS "operating system." + + `next-mach' + NeXT Mach-based system. + + `rtu' + Masscomp RTU, UCB universe. + + `unisoft-unix' + UniSoft UniPlus. + + `usg-unix-v' + AT&T System V. + + `vax-vms' + VAX VMS. + + `windows-nt' + Microsoft windows NT. + + `xenix' + SCO Xenix 386. + + We do not wish to add new symbols to make finer distinctions + unless it is absolutely necessary! In fact, we hope to eliminate + some of these alternatives in the future. We recommend using + `system-configuration' to distinguish between different operating + systems. + + - Variable: system-configuration + This variable holds the three-part configuration name for the + hardware/software configuration of your system, as a string. The + convenient way to test parts of this string is with `string-match'. + + - Function: system-name + This function returns the name of the machine you are running on. + (system-name) + => "prep.ai.mit.edu" + + The symbol `system-name' is a variable as well as a function. In +fact, the function returns whatever value the variable `system-name' +currently holds. Thus, you can set the variable `system-name' in case +Emacs is confused about the name of your system. The variable is also +useful for constructing frame titles (*note Frame Titles::). + + - Variable: mail-host-address + If this variable is non-`nil', it is used instead of `system-name' + for purposes of generating email addresses. For example, it is + used when constructing the default value of `user-mail-address'. + *Note User Identification::. (Since this is done when XEmacs + starts up, the value actually used is the one saved when XEmacs + was dumped. *Note Building XEmacs::.) + + - Function: getenv var + This function returns the value of the environment variable VAR, + as a string. Within XEmacs, the environment variable values are + kept in the Lisp variable `process-environment'. + + (getenv "USER") + => "lewis" + + lewis@slug[10] % printenv + PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin + USER=lewis + TERM=ibmapa16 + SHELL=/bin/csh + HOME=/user/lewis + + - Command: setenv variable value + This command sets the value of the environment variable named + VARIABLE to VALUE. Both arguments should be strings. This + function works by modifying `process-environment'; binding that + variable with `let' is also reasonable practice. + + - Variable: process-environment + This variable is a list of strings, each describing one environment + variable. The functions `getenv' and `setenv' work by means of + this variable. + + process-environment + => ("l=/usr/stanford/lib/gnuemacs/lisp" + "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" + "USER=lewis" + "TERM=ibmapa16" + "SHELL=/bin/csh" + "HOME=/user/lewis") + + - Variable: path-separator + This variable holds a string which says which character separates + directories in a search path (as found in an environment + variable). Its value is `":"' for Unix and GNU systems, and `";"' + for MS-DOS and Windows NT. + + - Variable: invocation-name + This variable holds the program name under which Emacs was + invoked. The value is a string, and does not include a directory + name. + + - Variable: invocation-directory + This variable holds the directory from which the Emacs executable + was invoked, or perhaps `nil' if that directory cannot be + determined. + + - Variable: installation-directory + If non-`nil', this is a directory within which to look for the + `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs + can't find those directories in their standard installed + locations, but can find them in a directory related somehow to the + one containing the Emacs executable. + + - Function: load-average &optional use-floats + This function returns a list of the current 1-minute, 5-minute and + 15-minute load averages. The values are integers that are 100 + times the system load averages. (The load averages indicate the + number of processes trying to run.) + + When USE-FLOATS is non-`nil', floats will be returned instead of + integers. These floats are not multiplied by 100. + + (load-average) + => (169 158 164) + (load-average t) + => (1.69921875 1.58984375 1.640625) + + lewis@rocky[5] % uptime + 8:06pm up 16 day(s), 21:57, 40 users, + load average: 1.68, 1.59, 1.64 + + If the 5-minute or 15-minute load averages are not available, + return a shortened list, containing only those averages which are + available. + + On some systems, this function may require special privileges to + run, or it may be unimplemented for the particular system type. + In that case, the function will signal an error. + + - Function: emacs-pid + This function returns the process ID of the Emacs process. + + - Function: setprv privilege-name &optional setp getprv + This function sets or resets a VMS privilege. (It does not exist + on Unix.) The first arg is the privilege name, as a string. The + second argument, SETP, is `t' or `nil', indicating whether the + privilege is to be turned on or off. Its default is `nil'. The + function returns `t' if successful, `nil' otherwise. + + If the third argument, GETPRV, is non-`nil', `setprv' does not + change the privilege, but returns `t' or `nil' indicating whether + the privilege is currently enabled. + + +File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface + +User Identification +=================== + + - Variable: user-mail-address + This holds the nominal email address of the user who is using + Emacs. When Emacs starts up, it computes a default value that is + usually right, but users often set this themselves when the + default value is not right. + + - Function: user-login-name &optional uid + If you don't specify UID, this function returns the name under + which the user is logged in. If the environment variable `LOGNAME' + is set, that value is used. Otherwise, if the environment variable + `USER' is set, that value is used. Otherwise, the value is based + on the effective UID, not the real UID. + + If you specify UID, the value is the user name that corresponds to + UID (which should be an integer). + + (user-login-name) + => "lewis" + + - Function: user-real-login-name + This function returns the user name corresponding to Emacs's real + UID. This ignores the effective UID and ignores the environment + variables `LOGNAME' and `USER'. + + - Variable: user-full-name + This variable holds the name of the user running this Emacs. It is + initialized at startup time from the value of `NAME' environment + variable. You can change the value of this variable to alter the + result of the `user-full-name' function. + + - Function: user-full-name &optional user + This function returns the full name of USER. If USER is `nil', it + defaults to the user running this Emacs. In that case, the value + of `user-full-name' variable, if non-`nil', will be used. + + If USER is specified explicitly, `user-full-name' variable is + ignored. + + (user-full-name) + => "Hrvoje Niksic" + (setq user-full-name "Hrvoje \"Niksa\" Niksic") + (user-full-name) + => "Hrvoje \"Niksa\" Niksic" + (user-full-name "hniksic") + => "Hrvoje Niksic" + + The symbols `user-login-name', `user-real-login-name' and +`user-full-name' are variables as well as functions. The functions +return the same values that the variables hold. These variables allow +you to "fake out" Emacs by telling the functions what to return. The +variables are also useful for constructing frame titles (*note Frame +Titles::). + + - Function: user-real-uid + This function returns the real UID of the user. + + (user-real-uid) + => 19 + + - Function: user-uid + This function returns the effective UID of the user. + + - Function: user-home-directory + This function returns the "`HOME'" directory of the user, and is + intended to replace occurrences of "`(getenv "HOME")'". Under + Unix systems, the following is done: + + 1. Return the value of "`(getenv "HOME")'", if set. + + 2. Return "/", as a fallback, but issue a warning. (Future + versions of XEmacs will also attempt to lookup the `HOME' + directory via `getpwent()', but this has not yet been + implemented.) + + Under MS Windows, this is done: + + 1. Return the value of "`(getenv "HOME")'", if set. + + 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are + both set, return the concatenation (the following description + uses MS Windows environment variable substitution syntax): + `%HOMEDRIVE%%HOMEDIR%'. + + 3. Return "C:\", as a fallback, but issue a warning. + + File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface Time of Day @@ -354,802 +1280,3 @@ functions. into others. * Recording Input:: Saving histories of recent or all input events. - -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'. - - -File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input - -Translating Input Events ------------------------- - - 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) - - The `iso-transl' library uses this feature to provide a way of -inputting non-ASCII Latin-1 characters. - - -File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input - -Recording Input ---------------- - - - 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. - - 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.) - - 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'. - - - 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. - - - Function: set-recent-keys-ring-size size - This function changes the number of events stored by XEmacs and - returned by `recent-keys'. - - 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. - - - 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 `<...>'. - - You close the dribble file by calling this function with an - argument of `nil'. - - This function is normally used to record the input necessary to - trigger an XEmacs bug, for the sake of a bug report. - - (open-dribble-file "~/dribble") - => nil - - See also the `open-termscript' function (*note Terminal Output::). - - -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 - - -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::. - - -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: 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. - - -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.) - - -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. - - -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". - - -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.) - - -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. - - -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 - - -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:: - - -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. - - -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:: - - -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)) - diff --git a/info/lispref.info-41 b/info/lispref.info-41 index a0cdfc2..c4ba9dd 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -50,6 +50,805 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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'. + + +File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input + +Translating Input Events +------------------------ + + 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) + + The `iso-transl' library uses this feature to provide a way of +inputting non-ASCII Latin-1 characters. + + +File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input + +Recording Input +--------------- + + - 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. + + 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.) + + 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'. + + - 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. + + - Function: set-recent-keys-ring-size size + This function changes the number of events stored by XEmacs and + returned by `recent-keys'. + + 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. + + - 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 `<...>'. + + You close the dribble file by calling this function with an + argument of `nil'. + + This function is normally used to record the input necessary to + trigger an XEmacs bug, for the sake of a bug report. + + (open-dribble-file "~/dribble") + => nil + + See also the `open-termscript' function (*note Terminal Output::). + + +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 + + +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::. + + +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: 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. + + +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.) + + +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. + + +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". + + +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.) + + +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. + + +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 + + +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:: + + +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. + + +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:: + + +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)) + + File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages Elisp Interface for Sending Messages @@ -370,584 +1169,3 @@ and ensuring compliance with LDAP internationalization rules and formats * The Low-Level LDAP API:: Low-level LDAP lisp primitives * LDAP Internationalization:: I18n variables and functions - -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=ACME, c=US" 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 `cn=Babs Jensen,o=ACME,c=US', 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. - - - Variable: ldap-verbose - If non-`nil', LDAP operations will echo progress messages. - Defaults to `nil'. - - -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 ------------------------ - - The following functions provide the most convenient interface to -perform LDAP operations. All of them open a connection to a host, -perform an operation (add/search/modify/delete) on one or several -entries and cleanly close 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::. - - Note that `ldap-search' which used to be the name of the high-level -search function in XEmacs 21.1 is now obsolete. For consistency in the -naming as well as backward compatibility, that function now acts as a -wrapper that calls either `ldap-search-basic' (low-level search -function) or `ldap-search-entries' (high-level search function) -according to the actual parameters. A direct call to one of these two -functions is preferred since it is faster and unambiguous. - - - Function: ldap-search-entries filter &optional host attributes - attrsonly withdn - 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. If WITHDN is - non-`nil' each entry in the result will be prepended with its - distinguished name DN. Additional search parameters can be - specified through `ldap-host-parameters-alist'. The function - returns a list of matching entries. Each entry is itself an alist - of attribute/value pairs optionally preceded by the DN of the - entry according to the value of WITHDN. - - - Function: ldap-add-entries entries &optional host binddn passwd - Add entries to an LDAP directory. ENTRIES is a list of entry - specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' - where DN the distinguished name of an entry to add, the following - are cons cells containing attribute/value string pairs. HOST is - the LDAP host, defaulting to `ldap-default-host' BINDDN is the DN - to bind as to the server PASSWD is the corresponding password. - - - Function: ldap-modify-entries entry-mods &optional host binddn passwd - Modify entries of an LDAP directory. ENTRY_MODS is a list of - entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)' - where DN is the distinguished name of the entry to modify, the - following are modification specifications. A modification - specification is itself a list of the form `(MOD-OP ATTR VALUE1 - VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional - depending on MOD-OP. MOD-OP is the type of modification, one of - the symbols `add', `delete' or `replace'. ATTR is the LDAP - attribute type to modify. HOST is the LDAP host, defaulting to - `ldap-default-host' BINDDN is the DN to bind as to the server - PASSWD is the corresponding password" - - - Function: ldap-delete-entries dn &optional host binddn passwd - Delete an entry from an LDAP directory. DN is the distinguished - name of an entry to delete or a list of those. HOST is the LDAP - host, defaulting to `ldap-default-host' BINDDN is the DN to bind - as to the server PASSWD is the corresponding password. - - -File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API - -The Low-Level LDAP API ----------------------- - - The low-level API should be used directly for very specific purposes -(such as multiple operations on a connection) only. The higher-level -functions provide a more convenient way to access LDAP directories -hiding the subtleties of handling the connection, translating arguments -and ensuring compliance with LDAP internationalization rules and formats -(currently partly implemented only). See *note The High-Level LDAP API:: - - Note that the former functions `ldap-*-internal' functions have been -renamed in XEmacs 21.2 - -* Menu: - -* The LDAP Lisp Object:: -* Opening and Closing a LDAP Connection:: -* Low-level Operations on a LDAP Server:: - - -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 - - -File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, 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=com, o=Acme, cn=Babs Jensen', 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 - - -File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API - -Low-level Operations on a LDAP Server -..................................... - - `ldap-search-basic' 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-basic 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 - If `withdn' is non-`nil' then each entry in the result is - prepended with its distinguished name DN If `verbose' is non-`nil' - then progress messages are echoed The function returns a list of - matching entries. Each entry is itself an alist of - attribute/value pairs optionally preceded by the DN of the entry - according to the value of `withdn'. - - - Function: ldap-add ldap dn entry - Add ENTRY to a LDAP directory which a connection LDAP has been - opened to with `ldap-open'. DN is the distinguished name of the - entry to add. ENTRY is an entry specification, i.e., a list of - cons cells containing attribute/value string pairs. - - - Function: ldap-modify ldap dn mods - Modify an entry in an LDAP directory. LDAP is an LDAP connection - object created with `ldap-open'. DN is the distinguished name of - the entry to modify. MODS is a list of modifications to apply. A - modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2 - ...)' MOD-OP and ATTR are mandatory, VALUES are optional - depending on MOD-OP. MOD-OP is the type of modification, one of - the symbols `add', `delete' or `replace'. ATTR is the LDAP - attribute type to modify - - - Function: ldap-delete ldap dn - Delete an entry to an LDAP directory. LDAP is an LDAP connection - object created with `ldap-open'. DN is the distinguished name of - the entry to delete - - -File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API - -LDAP Internationalization -------------------------- - - The XEmacs LDAP API provides basic internationalization features -based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 -Attribute Syntax Definitions"). Unfortunately since there is currently -no free LDAP v3 server software, this part has not received much -testing and should be considered experimental. The framework is in -place though. - - - Function: ldap-decode-attribute attr - Decode the attribute/value pair ATTR according to LDAP rules. The - attribute name is looked up in `ldap-attribute-syntaxes-alist' and - the corresponding decoder is then retrieved from - `ldap-attribute-syntax-decoders'' and applied on the value(s). - -* Menu: - -* LDAP Internationalization Variables:: -* Encoder/Decoder Functions:: - - -File: lispref.info, Node: LDAP Internationalization Variables, Next: Encoder/Decoder Functions, Prev: LDAP Internationalization, Up: LDAP Internationalization - -LDAP Internationalization Variables -................................... - - - Variable: ldap-ignore-attribute-codings - If non-`nil', no encoding/decoding will be performed LDAP - attribute values - - - Variable: ldap-coding-system - Coding system of LDAP string values. LDAP v3 specifies the coding - system of strings to be UTF-8. You need an XEmacs with Mule - support for this. - - - Variable: ldap-default-attribute-decoder - Decoder function to use for attributes whose syntax is unknown. - Such a function receives an encoded attribute value as a string - and should return the decoded value as a string - - - Variable: ldap-attribute-syntax-encoders - A vector of functions used to encode LDAP attribute values. The - sequence of functions corresponds to the sequence of LDAP - attribute syntax object identifiers of the form - 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. - As of this writing, only a few encoder functions are available. - - - Variable: ldap-attribute-syntax-decoders - A vector of functions used to decode LDAP attribute values. The - sequence of functions corresponds to the sequence of LDAP - attribute syntax object identifiers of the form - 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. - As of this writing, only a few decoder functions are available. - - - Variable: ldap-attribute-syntaxes-alist - A map of LDAP attribute names to their type object id minor number. - This table is built from RFC2252 Section 5 and RFC2256 Section 5 - - -File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization - -Encoder/Decoder Functions -......................... - - - Function: ldap-encode-boolean bool - A function that encodes an elisp boolean BOOL into a LDAP boolean - string representation - - - Function: ldap-decode-boolean str - A function that decodes a LDAP boolean string representation STR - into an elisp boolean - - - Function: ldap-decode-string str - Decode a string STR according to `ldap-coding-system' - - - Function: ldap-encode-string str - Encode a string STR according to `ldap-coding-system' - - - Function: ldap-decode-address str - Decode an address STR according to `ldap-coding-system' and - replacing $ signs with newlines as specified by LDAP encoding - rules for addresses - - - Function: ldap-encode-address str - Encode an address STR according to `ldap-coding-system' and - replacing newlines with $ signs as specified by LDAP encoding - rules for addresses - - -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: - - ( ) - - `' is an attribute name such as `cn' for Common Name, `o' for -Organization, etc... - - `' 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 `(=*' 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'. - - -File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top - -PostgreSQL Support -****************** - - XEmacs can be linked with PostgreSQL libpq run-time support to -provide relational database access from Emacs Lisp code. - -* Menu: - -* Building XEmacs with PostgreSQL support:: -* XEmacs PostgreSQL libpq API:: -* XEmacs PostgreSQL libpq Examples:: - - -File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support - -Building XEmacs with PostgreSQL support -======================================= - - XEmacs PostgreSQL support requires linking to the PostgreSQL libpq.so -library. Describing how to build and install PostgreSQL is beyond the -scope of this document, see the PostgreSQL manual for details. - - If you have installed XEmacs from one of the binary kits on -(), or are using an XEmacs binary from a CD ROM, -you should have XEmacs PostgreSQL support by default. If you are -building XEmacs from source on a Linux system with PostgreSQL installed -into the default location, it should be autodetected when you run -configure. If you have installed PostgreSQL into its non-Linux default -location, `/usr/local/pgsql', you must specify -`--site-prefixes=/usr/local/pgsql' when you run configure. If you -installed PostgreSQL into another location, use that instead of -`/usr/local/pgsql' when specifying `--site-prefixes'. - - As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported. -XEmacs Lisp support for V7.0 is somewhat more extensive than support for -V6.5. In particular, asynchronous queries are supported. - - -File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support - -XEmacs PostgreSQL libpq API -=========================== - - XEmacs PostgreSQL API is intended to be a policy-free, low-level -binding to libpq. The intent is to provide all the basic functionality -and then let high level Lisp code decide its own policies. - - This documentation assumes that the reader has knowledge of SQL, but -requires no prior knowledge of libpq. - - There are many examples in this manual and some setup will be -required. In order to run most of the following examples, the -following code needs to be executed. In addition to the data is in -this table, nearly all of the examples will assume that the free -variable `P' refers to this database connection. The examples in the -original edition of this manual were run against Postgres 7.0beta1. - - (progn - (setq P (pq-connectdb "")) - ;; id is the primary key, shikona is a Japanese word that - ;; means `the professional name of a Sumo wrestler', and - ;; rank is the Sumo rank name. - (pq-exec P (concat "CREATE TABLE xemacs_test" - " (id int, shikona text, rank text);")) - (pq-exec P "COPY xemacs_test FROM stdin;") - (pq-put-line P "1\tMusashimaru\tYokuzuna\n") - (pq-put-line P "2\tDejima\tOozeki\n") - (pq-put-line P "3\tMusoyama\tSekiwake\n") - (pq-put-line P "4\tMiyabiyama\tSekiwake\n") - (pq-put-line P "5\tWakanoyama\tMaegashira\n") - (pq-put-line P "\\.\n") - (pq-end-copy P)) - => nil - -* Menu: - -* libpq Lisp Variables:: -* libpq Lisp Symbols and DataTypes:: -* Synchronous Interface Functions:: -* Asynchronous Interface Functions:: -* Large Object Support:: -* Other libpq Functions:: -* Unimplemented libpq Functions:: - - -File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API - -libpq Lisp Variables --------------------- - - Various Unix environment variables are used by libpq to provide -defaults to the many different parameters. In the XEmacs Lisp API, -these environment variables are bound to Lisp variables to provide more -convenient access to Lisp Code. These variables are passed to the -backend database server during the establishment of a database -connection and when the `pq-setenv' call is made. - - - Variable: pg:host - Initialized from the PGHOST environment variable. The default - host to connect to. - - - Variable: pg:user - Initialized from the PGUSER environment variable. The default - database user name. - - - Variable: pg:options - Initialized from the PGOPTIONS environment variable. Default - additional server options. - - - Variable: pg:port - Initialized from the PGPORT environment variable. The default TCP - port to connect to. - - - Variable: pg:tty - Initialized from the PGTTY environment variable. The default - debugging TTY. - - Compatibility note: Debugging TTYs are turned off in the XEmacs - Lisp binding. - - - Variable: pg:database - Initialized from the PGDATABASE environment variable. The default - database to connect to. - - - Variable: pg:realm - Initialized from the PGREALM environment variable. The default - Kerberos realm. - - - Variable: pg:client-encoding - Initialized from the PGCLIENTENCODING environment variable. The - default client encoding. - - Compatibility note: This variable is not present in non-Mule - XEmacsen. This variable is not present in versions of libpq prior - to 7.0. In the current implementation, client encoding is - equivalent to the `file-name-coding-system' format. - - - Variable: pg:authtype - Initialized from the PGAUTHTYPE environment variable. The default - authentication scheme used. - - Compatibility note: This variable is unused in versions of libpq - after 6.5. It is not implemented at all in the XEmacs Lisp - binding. - - - Variable: pg:geqo - Initialized from the PGGEQO environment variable. Genetic - optimizer options. - - - Variable: pg:cost-index - Initialized from the PGCOSTINDEX environment variable. Cost index - options. - - - Variable: pg:cost-heap - Initialized from the PGCOSTHEAP environment variable. Cost heap - options. - - - Variable: pg:tz - Initialized from the PGTZ environment variable. Default timezone. - - - Variable: pg:date-style - Initialized from the PGDATESTYLE environment variable. Default - date style in returned date objects. - - - Variable: pg-coding-system - This is a variable controlling which coding system is used to - encode non-ASCII strings sent to the database. - - Compatibility Note: This variable is not present in InfoDock. - diff --git a/info/lispref.info-42 b/info/lispref.info-42 index 4481943..d2188b4 100644 --- a/info/lispref.info-42 +++ b/info/lispref.info-42 @@ -50,6 +50,587 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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=ACME, c=US" 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 `cn=Babs Jensen,o=ACME,c=US', 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. + + - Variable: ldap-verbose + If non-`nil', LDAP operations will echo progress messages. + Defaults to `nil'. + + +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 +----------------------- + + The following functions provide the most convenient interface to +perform LDAP operations. All of them open a connection to a host, +perform an operation (add/search/modify/delete) on one or several +entries and cleanly close 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::. + + Note that `ldap-search' which used to be the name of the high-level +search function in XEmacs 21.1 is now obsolete. For consistency in the +naming as well as backward compatibility, that function now acts as a +wrapper that calls either `ldap-search-basic' (low-level search +function) or `ldap-search-entries' (high-level search function) +according to the actual parameters. A direct call to one of these two +functions is preferred since it is faster and unambiguous. + + - Function: ldap-search-entries filter &optional host attributes + attrsonly withdn + 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. If WITHDN is + non-`nil' each entry in the result will be prepended with its + distinguished name DN. Additional search parameters can be + specified through `ldap-host-parameters-alist'. The function + returns a list of matching entries. Each entry is itself an alist + of attribute/value pairs optionally preceded by the DN of the + entry according to the value of WITHDN. + + - Function: ldap-add-entries entries &optional host binddn passwd + Add entries to an LDAP directory. ENTRIES is a list of entry + specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' + where DN the distinguished name of an entry to add, the following + are cons cells containing attribute/value string pairs. HOST is + the LDAP host, defaulting to `ldap-default-host' BINDDN is the DN + to bind as to the server PASSWD is the corresponding password. + + - Function: ldap-modify-entries entry-mods &optional host binddn passwd + Modify entries of an LDAP directory. ENTRY_MODS is a list of + entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)' + where DN is the distinguished name of the entry to modify, the + following are modification specifications. A modification + specification is itself a list of the form `(MOD-OP ATTR VALUE1 + VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional + depending on MOD-OP. MOD-OP is the type of modification, one of + the symbols `add', `delete' or `replace'. ATTR is the LDAP + attribute type to modify. HOST is the LDAP host, defaulting to + `ldap-default-host' BINDDN is the DN to bind as to the server + PASSWD is the corresponding password" + + - Function: ldap-delete-entries dn &optional host binddn passwd + Delete an entry from an LDAP directory. DN is the distinguished + name of an entry to delete or a list of those. HOST is the LDAP + host, defaulting to `ldap-default-host' BINDDN is the DN to bind + as to the server PASSWD is the corresponding password. + + +File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API + +The Low-Level LDAP API +---------------------- + + The low-level API should be used directly for very specific purposes +(such as multiple operations on a connection) only. The higher-level +functions provide a more convenient way to access LDAP directories +hiding the subtleties of handling the connection, translating arguments +and ensuring compliance with LDAP internationalization rules and formats +(currently partly implemented only). See *note The High-Level LDAP API:: + + Note that the former functions `ldap-*-internal' functions have been +renamed in XEmacs 21.2 + +* Menu: + +* The LDAP Lisp Object:: +* Opening and Closing a LDAP Connection:: +* Low-level Operations on a LDAP Server:: + + +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 + + +File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, 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=com, o=Acme, cn=Babs Jensen', 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 + + +File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API + +Low-level Operations on a LDAP Server +..................................... + + `ldap-search-basic' 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-basic 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 + If `withdn' is non-`nil' then each entry in the result is + prepended with its distinguished name DN If `verbose' is non-`nil' + then progress messages are echoed The function returns a list of + matching entries. Each entry is itself an alist of + attribute/value pairs optionally preceded by the DN of the entry + according to the value of `withdn'. + + - Function: ldap-add ldap dn entry + Add ENTRY to a LDAP directory which a connection LDAP has been + opened to with `ldap-open'. DN is the distinguished name of the + entry to add. ENTRY is an entry specification, i.e., a list of + cons cells containing attribute/value string pairs. + + - Function: ldap-modify ldap dn mods + Modify an entry in an LDAP directory. LDAP is an LDAP connection + object created with `ldap-open'. DN is the distinguished name of + the entry to modify. MODS is a list of modifications to apply. A + modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2 + ...)' MOD-OP and ATTR are mandatory, VALUES are optional + depending on MOD-OP. MOD-OP is the type of modification, one of + the symbols `add', `delete' or `replace'. ATTR is the LDAP + attribute type to modify + + - Function: ldap-delete ldap dn + Delete an entry to an LDAP directory. LDAP is an LDAP connection + object created with `ldap-open'. DN is the distinguished name of + the entry to delete + + +File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API + +LDAP Internationalization +------------------------- + + The XEmacs LDAP API provides basic internationalization features +based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 +Attribute Syntax Definitions"). Unfortunately since there is currently +no free LDAP v3 server software, this part has not received much +testing and should be considered experimental. The framework is in +place though. + + - Function: ldap-decode-attribute attr + Decode the attribute/value pair ATTR according to LDAP rules. The + attribute name is looked up in `ldap-attribute-syntaxes-alist' and + the corresponding decoder is then retrieved from + `ldap-attribute-syntax-decoders'' and applied on the value(s). + +* Menu: + +* LDAP Internationalization Variables:: +* Encoder/Decoder Functions:: + + +File: lispref.info, Node: LDAP Internationalization Variables, Next: Encoder/Decoder Functions, Prev: LDAP Internationalization, Up: LDAP Internationalization + +LDAP Internationalization Variables +................................... + + - Variable: ldap-ignore-attribute-codings + If non-`nil', no encoding/decoding will be performed LDAP + attribute values + + - Variable: ldap-coding-system + Coding system of LDAP string values. LDAP v3 specifies the coding + system of strings to be UTF-8. You need an XEmacs with Mule + support for this. + + - Variable: ldap-default-attribute-decoder + Decoder function to use for attributes whose syntax is unknown. + Such a function receives an encoded attribute value as a string + and should return the decoded value as a string + + - Variable: ldap-attribute-syntax-encoders + A vector of functions used to encode LDAP attribute values. The + sequence of functions corresponds to the sequence of LDAP + attribute syntax object identifiers of the form + 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. + As of this writing, only a few encoder functions are available. + + - Variable: ldap-attribute-syntax-decoders + A vector of functions used to decode LDAP attribute values. The + sequence of functions corresponds to the sequence of LDAP + attribute syntax object identifiers of the form + 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. + As of this writing, only a few decoder functions are available. + + - Variable: ldap-attribute-syntaxes-alist + A map of LDAP attribute names to their type object id minor number. + This table is built from RFC2252 Section 5 and RFC2256 Section 5 + + +File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization + +Encoder/Decoder Functions +......................... + + - Function: ldap-encode-boolean bool + A function that encodes an elisp boolean BOOL into a LDAP boolean + string representation + + - Function: ldap-decode-boolean str + A function that decodes a LDAP boolean string representation STR + into an elisp boolean + + - Function: ldap-decode-string str + Decode a string STR according to `ldap-coding-system' + + - Function: ldap-encode-string str + Encode a string STR according to `ldap-coding-system' + + - Function: ldap-decode-address str + Decode an address STR according to `ldap-coding-system' and + replacing $ signs with newlines as specified by LDAP encoding + rules for addresses + + - Function: ldap-encode-address str + Encode an address STR according to `ldap-coding-system' and + replacing newlines with $ signs as specified by LDAP encoding + rules for addresses + + +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: + + ( ) + + `' is an attribute name such as `cn' for Common Name, `o' for +Organization, etc... + + `' 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 `(=*' 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'. + + +File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top + +PostgreSQL Support +****************** + + XEmacs can be linked with PostgreSQL libpq run-time support to +provide relational database access from Emacs Lisp code. + +* Menu: + +* Building XEmacs with PostgreSQL support:: +* XEmacs PostgreSQL libpq API:: +* XEmacs PostgreSQL libpq Examples:: + + +File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support + +Building XEmacs with PostgreSQL support +======================================= + + XEmacs PostgreSQL support requires linking to the PostgreSQL libpq.so +library. Describing how to build and install PostgreSQL is beyond the +scope of this document, see the PostgreSQL manual for details. + + If you have installed XEmacs from one of the binary kits on +(), or are using an XEmacs binary from a CD ROM, +you should have XEmacs PostgreSQL support by default. If you are +building XEmacs from source on a Linux system with PostgreSQL installed +into the default location, it should be autodetected when you run +configure. If you have installed PostgreSQL into its non-Linux default +location, `/usr/local/pgsql', you must specify +`--site-prefixes=/usr/local/pgsql' when you run configure. If you +installed PostgreSQL into another location, use that instead of +`/usr/local/pgsql' when specifying `--site-prefixes'. + + As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported. +XEmacs Lisp support for V7.0 is somewhat more extensive than support for +V6.5. In particular, asynchronous queries are supported. + + +File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support + +XEmacs PostgreSQL libpq API +=========================== + + XEmacs PostgreSQL API is intended to be a policy-free, low-level +binding to libpq. The intent is to provide all the basic functionality +and then let high level Lisp code decide its own policies. + + This documentation assumes that the reader has knowledge of SQL, but +requires no prior knowledge of libpq. + + There are many examples in this manual and some setup will be +required. In order to run most of the following examples, the +following code needs to be executed. In addition to the data is in +this table, nearly all of the examples will assume that the free +variable `P' refers to this database connection. The examples in the +original edition of this manual were run against Postgres 7.0beta1. + + (progn + (setq P (pq-connectdb "")) + ;; id is the primary key, shikona is a Japanese word that + ;; means `the professional name of a Sumo wrestler', and + ;; rank is the Sumo rank name. + (pq-exec P (concat "CREATE TABLE xemacs_test" + " (id int, shikona text, rank text);")) + (pq-exec P "COPY xemacs_test FROM stdin;") + (pq-put-line P "1\tMusashimaru\tYokuzuna\n") + (pq-put-line P "2\tDejima\tOozeki\n") + (pq-put-line P "3\tMusoyama\tSekiwake\n") + (pq-put-line P "4\tMiyabiyama\tSekiwake\n") + (pq-put-line P "5\tWakanoyama\tMaegashira\n") + (pq-put-line P "\\.\n") + (pq-end-copy P)) + => nil + +* Menu: + +* libpq Lisp Variables:: +* libpq Lisp Symbols and DataTypes:: +* Synchronous Interface Functions:: +* Asynchronous Interface Functions:: +* Large Object Support:: +* Other libpq Functions:: +* Unimplemented libpq Functions:: + + +File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API + +libpq Lisp Variables +-------------------- + + Various Unix environment variables are used by libpq to provide +defaults to the many different parameters. In the XEmacs Lisp API, +these environment variables are bound to Lisp variables to provide more +convenient access to Lisp Code. These variables are passed to the +backend database server during the establishment of a database +connection and when the `pq-setenv' call is made. + + - Variable: pg:host + Initialized from the PGHOST environment variable. The default + host to connect to. + + - Variable: pg:user + Initialized from the PGUSER environment variable. The default + database user name. + + - Variable: pg:options + Initialized from the PGOPTIONS environment variable. Default + additional server options. + + - Variable: pg:port + Initialized from the PGPORT environment variable. The default TCP + port to connect to. + + - Variable: pg:tty + Initialized from the PGTTY environment variable. The default + debugging TTY. + + Compatibility note: Debugging TTYs are turned off in the XEmacs + Lisp binding. + + - Variable: pg:database + Initialized from the PGDATABASE environment variable. The default + database to connect to. + + - Variable: pg:realm + Initialized from the PGREALM environment variable. The default + Kerberos realm. + + - Variable: pg:client-encoding + Initialized from the PGCLIENTENCODING environment variable. The + default client encoding. + + Compatibility note: This variable is not present in non-Mule + XEmacsen. This variable is not present in versions of libpq prior + to 7.0. In the current implementation, client encoding is + equivalent to the `file-name-coding-system' format. + + - Variable: pg:authtype + Initialized from the PGAUTHTYPE environment variable. The default + authentication scheme used. + + Compatibility note: This variable is unused in versions of libpq + after 6.5. It is not implemented at all in the XEmacs Lisp + binding. + + - Variable: pg:geqo + Initialized from the PGGEQO environment variable. Genetic + optimizer options. + + - Variable: pg:cost-index + Initialized from the PGCOSTINDEX environment variable. Cost index + options. + + - Variable: pg:cost-heap + Initialized from the PGCOSTHEAP environment variable. Cost heap + options. + + - Variable: pg:tz + Initialized from the PGTZ environment variable. Default timezone. + + - Variable: pg:date-style + Initialized from the PGDATESTYLE environment variable. Default + date style in returned date objects. + + - Variable: pg-coding-system + This is a variable controlling which coding system is used to + encode non-ASCII strings sent to the database. + + Compatibility Note: This variable is not present in InfoDock. + + File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API libpq Lisp Symbols and Datatypes @@ -707,510 +1288,3 @@ Other libpq Functions The data is returned as a list of lists, where each sublist contains info regarding a single option. - -File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API - -Unimplemented libpq Functions ------------------------------ - - - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char - *pgport, char *pgoptions, char *pgtty, char *dbName, char - *login, char *pwd) - Synchronous database connection. PGHOST is the hostname of the - PostgreSQL backend to connect to. PGPORT is the TCP port number - to use. PGOPTIONS specifies other backend options. PGTTY - specifies the debugging tty to use. DBNAME specifies the database - name to use. LOGIN specifies the database user name. PWD - specifies the database user's password. - - This routine is deprecated as of libpq-7.0, and its functionality - can be replaced by external Lisp code if needed. - - - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport, - char *pgoptions, char *pgtty, char *dbName) - Synchronous database connection. PGHOST is the hostname of the - PostgreSQL backend to connect to. PGPORT is the TCP port number - to use. PGOPTIONS specifies other backend options. PGTTY - specifies the debugging tty to use. DBNAME specifies the database - name to use. - - This routine was deprecated in libpq-6.5. - - - Unimplemented Function: int PQsocket (PGconn *conn) - Return socket file descriptor to a backend database process. CONN - database connection object. - - - Unimplemented Function: void PQprint (FILE *fout, PGresult *res, - PGprintOpt *ps) - Print out the results of a query to a designated C stream. FOUT C - stream to print to RES the query result object to print PS the - print options structure. - - This routine is deprecated as of libpq-7.0 and cannot be sensibly - exported to XEmacs Lisp. - - - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE - *fp, int fillAlign, char *fieldSep, int printHeader, int - quiet) - RES query result object to print FP C stream to print to FILLALIGN - pad the fields with spaces FIELDSEP field separator PRINTHEADER - display headers? QUIET - - This routine was deprecated in libpq-6.5. - - - Unimplemented Function: void PQprintTuples (PGresult *res, FILE - *fout, int printAttName, int terseOutput, int width) - RES query result object to print FOUT C stream to print to - PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars - WIDTH width of column, if 0, use variable width - - This routine was deprecated in libpq-6.5. - - - Unimplemented Function: int PQmblen (char *s, int encoding) - Determine length of a multibyte encoded char at `*s'. S encoded - string ENCODING type of encoding - - Compatibility note: This function was introduced in libpq-7.0. - - - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port) - Enable tracing on `debug_port'. CONN database connection object. - DEBUG_PORT C output stream to use. - - - Unimplemented Function: void PQuntrace (PGconn *conn) - Disable tracing. CONN database connection object. - - - Unimplemented Function: char *PQoidStatus (PGconn *conn) - Return the object id as a string of the last tuple inserted. CONN - database connection object. - - Compatibility note: This function is deprecated in libpq-7.0, - however it is used internally by the XEmacs binding code when - linked against versions prior to 7.0. - - - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int - *result_buf, int *result_len, int result_is_int, PQArgBlock - *args, int nargs) - "Fast path" interface -- not really recommended for application use - CONN A database connection object. FNID RESULT_BUF RESULT_LEN - RESULT_IS_INT ARGS NARGS - - The following set of very low level large object functions aren't -appropriate to be exported to Lisp. - - - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid, - int mode) - CONN a database connection object. LOBJID a large object ID. - MODE opening modes. - - - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd) - CONN a database connection object. FD a large object file - descriptor - - - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char - *buf, int len) - CONN a database connection object. FD a large object file - descriptor. BUF buffer to read into. LEN size of buffer. - - - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char - *buf, size_t len) - CONN a database connection object. FD a large object file - descriptor. BUF buffer to write from. LEN size of buffer. - - - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int - offset, int whence) - CONN a database connection object. FD a large object file - descriptor. OFFSET WHENCE - - - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode) - CONN a database connection object. MODE opening modes. - - - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd) - CONN a database connection object. FD a large object file - descriptor. - - - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid) - CONN a database connection object. LBOJID a large object ID. - - -File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support - -XEmacs PostgreSQL libpq Examples -================================ - - This is an example of one method of establishing an asynchronous -connection. - - (defun database-poller (P) - (message "%S before poll" (pq-pgconn P 'pq::status)) - (pq-connect-poll P) - (message "%S after poll" (pq-pgconn P 'pq::status)) - (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) - (message "Done!") - (add-timeout .1 'database-poller P))) - => database-poller - (progn - (setq P (pq-connect-start "")) - (add-timeout .1 'database-poller P)) - => pg::connection-started before poll - => pg::connection-made after poll - => pg::connection-made before poll - => pg::connection-awaiting-response after poll - => pg::connection-awaiting-response before poll - => pg::connection-auth-ok after poll - => pg::connection-auth-ok before poll - => pg::connection-setenv after poll - => pg::connection-setenv before poll - => pg::connection-ok after poll - => Done! - P - => # - - Here is an example of one method of doing an asynchronous reset. - - (defun database-poller (P) - (let (PS) - (message "%S before poll" (pq-pgconn P 'pq::status)) - (setq PS (pq-reset-poll P)) - (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS) - (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) - (message "Done!") - (add-timeout .1 'database-poller P)))) - => database-poller - (progn - (pq-reset-start P) - (add-timeout .1 'database-poller P)) - => pg::connection-started before poll - => pg::connection-made after poll [pgres::polling-writing] - => pg::connection-made before poll - => pg::connection-awaiting-response after poll [pgres::polling-reading] - => pg::connection-awaiting-response before poll - => pg::connection-setenv after poll [pgres::polling-reading] - => pg::connection-setenv before poll - => pg::connection-ok after poll [pgres::polling-ok] - => Done! - P - => # - - And finally, an asynchronous query. - - (defun database-poller (P) - (let (R) - (pq-consume-input P) - (if (pq-is-busy P) - (add-timeout .1 'database-poller P) - (setq R (pq-get-result P)) - (if R - (progn - (push R result-list) - (add-timeout .1 'database-poller P)))))) - => database-poller - (when (pq-send-query P "SELECT * FROM xemacs_test;") - (setq result-list nil) - (add-timeout .1 'database-poller P)) - => 885 - ;; wait a moment - result-list - => (#) - - Here is an example showing how multiple SQL statements in a single -query can have all their results collected. - ;; Using the same `database-poller' function from the previous example - (when (pq-send-query P "SELECT * FROM xemacs_test; - SELECT * FROM pg_database; - SELECT * FROM pg_user;") - (setq result-list nil) - (add-timeout .1 'database-poller P)) - => 1782 - ;; wait a moment - result-list - => (# # #) - - Here is an example which illustrates collecting all data from a -query, including the field names. - - (defun pg-util-query-results (results) - "Retrieve results of last SQL query into a list structure." - (let ((i (1- (pq-ntuples R))) - j l1 l2) - (while (>= i 0) - (setq j (1- (pq-nfields R))) - (setq l2 nil) - (while (>= j 0) - (push (pq-get-value R i j) l2) - (decf j)) - (push l2 l1) - (decf i)) - (setq j (1- (pq-nfields R))) - (setq l2 nil) - (while (>= j 0) - (push (pq-fname R j) l2) - (decf j)) - (push l2 l1) - l1)) - => pg-util-query-results - (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;")) - => # - (pg-util-query-results R) - => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1")) - - Here is an example of a query that uses a database cursor. - - (let (data R) - (setq R (pq-exec P "BEGIN;")) - (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;")) - - (setq R (pq-exec P "FETCH k_cursor;")) - (while (eq (pq-ntuples R) 1) - (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data) - (setq R (pq-exec P "FETCH k_cursor;"))) - (setq R (pq-exec P "END;")) - data) - => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1")) - - Here's another example of cursors, this time with a Lisp macro to -implement a mapping function over a table. - - (defmacro map-db (P table condition callout) - `(let (R) - (pq-exec ,P "BEGIN;") - (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM " - ,table - " " - ,condition - " ORDER BY f1 DESC;")) - (setq R (pq-exec P "FETCH k_cursor;")) - (while (eq (pq-ntuples R) 1) - (,callout (pq-get-value R 0 0) (pq-get-value R 0 1)) - (setq R (pq-exec P "FETCH k_cursor;"))) - (pq-exec P "END;"))) - => map-db - (defun callback (arg1 arg2) - (message "arg1 = %s, arg2 = %s" arg1 arg2)) - => callback - (map-db P "xemacs_test" "WHERE field2 > 10" callback) - => arg1 = stuff, arg2 = 42 - => arg1 = b, arg2 = 97 - => arg1 = a string, arg2 = 12 - => arg1 = a, arg2 = 97 - => # - - -File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL 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. - - -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. - - -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:: - - -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. - - -File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3 - -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: - - (defun foo (arg) "Doc string" (domain "emacs-foo") ...) - - 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'. - - - 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'. - - -File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3 - -Dynamic Messaging ------------------ - - 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. - - -File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3 - -Domain Specification --------------------- - - 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: - - (dgettext "emacs-gorilla" "What gorilla?") - - 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: - - (defun scratch (location) - "Scratch the specified location." - (domain "emacs-gorilla") - (interactive "sScratch: ") - ... ) - - It is most efficient to specify the domain in the first line of the -function body, before the `interactive' form. - - For variables and constants which have documentation strings, -specify the domain after the documentation. - - - Special Form: defvar symbol [value [doc-string [domain]]] - Example: - (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") - - - Special Form: defconst symbol [value [doc-string [domain]]] - Example: - (defconst limbs 4 "Number of limbs" "emacs-gorilla") - - 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: - - - Function: autoload symbol filename &optional docstring interactive - macro domain - Example: - (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") - - -File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3 - -Documentation String Extraction -------------------------------- - - 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. - - (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.) - - -File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization - -I18N Level 4 -============ - - The Asian-language support in XEmacs is called "MULE". *Note MULE::. - - -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 is an extension and -complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese -word for "Japan"), which 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. -* 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. - diff --git a/info/lispref.info-43 b/info/lispref.info-43 index d39722d..b2766a5 100644 --- a/info/lispref.info-43 +++ b/info/lispref.info-43 @@ -50,6 +50,513 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API + +Unimplemented libpq Functions +----------------------------- + + - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char + *pgport, char *pgoptions, char *pgtty, char *dbName, char + *login, char *pwd) + Synchronous database connection. PGHOST is the hostname of the + PostgreSQL backend to connect to. PGPORT is the TCP port number + to use. PGOPTIONS specifies other backend options. PGTTY + specifies the debugging tty to use. DBNAME specifies the database + name to use. LOGIN specifies the database user name. PWD + specifies the database user's password. + + This routine is deprecated as of libpq-7.0, and its functionality + can be replaced by external Lisp code if needed. + + - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport, + char *pgoptions, char *pgtty, char *dbName) + Synchronous database connection. PGHOST is the hostname of the + PostgreSQL backend to connect to. PGPORT is the TCP port number + to use. PGOPTIONS specifies other backend options. PGTTY + specifies the debugging tty to use. DBNAME specifies the database + name to use. + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: int PQsocket (PGconn *conn) + Return socket file descriptor to a backend database process. CONN + database connection object. + + - Unimplemented Function: void PQprint (FILE *fout, PGresult *res, + PGprintOpt *ps) + Print out the results of a query to a designated C stream. FOUT C + stream to print to RES the query result object to print PS the + print options structure. + + This routine is deprecated as of libpq-7.0 and cannot be sensibly + exported to XEmacs Lisp. + + - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE + *fp, int fillAlign, char *fieldSep, int printHeader, int + quiet) + RES query result object to print FP C stream to print to FILLALIGN + pad the fields with spaces FIELDSEP field separator PRINTHEADER + display headers? QUIET + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: void PQprintTuples (PGresult *res, FILE + *fout, int printAttName, int terseOutput, int width) + RES query result object to print FOUT C stream to print to + PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars + WIDTH width of column, if 0, use variable width + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: int PQmblen (char *s, int encoding) + Determine length of a multibyte encoded char at `*s'. S encoded + string ENCODING type of encoding + + Compatibility note: This function was introduced in libpq-7.0. + + - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port) + Enable tracing on `debug_port'. CONN database connection object. + DEBUG_PORT C output stream to use. + + - Unimplemented Function: void PQuntrace (PGconn *conn) + Disable tracing. CONN database connection object. + + - Unimplemented Function: char *PQoidStatus (PGconn *conn) + Return the object id as a string of the last tuple inserted. CONN + database connection object. + + Compatibility note: This function is deprecated in libpq-7.0, + however it is used internally by the XEmacs binding code when + linked against versions prior to 7.0. + + - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int + *result_buf, int *result_len, int result_is_int, PQArgBlock + *args, int nargs) + "Fast path" interface -- not really recommended for application use + CONN A database connection object. FNID RESULT_BUF RESULT_LEN + RESULT_IS_INT ARGS NARGS + + The following set of very low level large object functions aren't +appropriate to be exported to Lisp. + + - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid, + int mode) + CONN a database connection object. LOBJID a large object ID. + MODE opening modes. + + - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd) + CONN a database connection object. FD a large object file + descriptor + + - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char + *buf, int len) + CONN a database connection object. FD a large object file + descriptor. BUF buffer to read into. LEN size of buffer. + + - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char + *buf, size_t len) + CONN a database connection object. FD a large object file + descriptor. BUF buffer to write from. LEN size of buffer. + + - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int + offset, int whence) + CONN a database connection object. FD a large object file + descriptor. OFFSET WHENCE + + - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode) + CONN a database connection object. MODE opening modes. + + - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd) + CONN a database connection object. FD a large object file + descriptor. + + - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid) + CONN a database connection object. LBOJID a large object ID. + + +File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support + +XEmacs PostgreSQL libpq Examples +================================ + + This is an example of one method of establishing an asynchronous +connection. + + (defun database-poller (P) + (message "%S before poll" (pq-pgconn P 'pq::status)) + (pq-connect-poll P) + (message "%S after poll" (pq-pgconn P 'pq::status)) + (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) + (message "Done!") + (add-timeout .1 'database-poller P))) + => database-poller + (progn + (setq P (pq-connect-start "")) + (add-timeout .1 'database-poller P)) + => pg::connection-started before poll + => pg::connection-made after poll + => pg::connection-made before poll + => pg::connection-awaiting-response after poll + => pg::connection-awaiting-response before poll + => pg::connection-auth-ok after poll + => pg::connection-auth-ok before poll + => pg::connection-setenv after poll + => pg::connection-setenv before poll + => pg::connection-ok after poll + => Done! + P + => # + + Here is an example of one method of doing an asynchronous reset. + + (defun database-poller (P) + (let (PS) + (message "%S before poll" (pq-pgconn P 'pq::status)) + (setq PS (pq-reset-poll P)) + (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS) + (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) + (message "Done!") + (add-timeout .1 'database-poller P)))) + => database-poller + (progn + (pq-reset-start P) + (add-timeout .1 'database-poller P)) + => pg::connection-started before poll + => pg::connection-made after poll [pgres::polling-writing] + => pg::connection-made before poll + => pg::connection-awaiting-response after poll [pgres::polling-reading] + => pg::connection-awaiting-response before poll + => pg::connection-setenv after poll [pgres::polling-reading] + => pg::connection-setenv before poll + => pg::connection-ok after poll [pgres::polling-ok] + => Done! + P + => # + + And finally, an asynchronous query. + + (defun database-poller (P) + (let (R) + (pq-consume-input P) + (if (pq-is-busy P) + (add-timeout .1 'database-poller P) + (setq R (pq-get-result P)) + (if R + (progn + (push R result-list) + (add-timeout .1 'database-poller P)))))) + => database-poller + (when (pq-send-query P "SELECT * FROM xemacs_test;") + (setq result-list nil) + (add-timeout .1 'database-poller P)) + => 885 + ;; wait a moment + result-list + => (#) + + Here is an example showing how multiple SQL statements in a single +query can have all their results collected. + ;; Using the same `database-poller' function from the previous example + (when (pq-send-query P "SELECT * FROM xemacs_test; + SELECT * FROM pg_database; + SELECT * FROM pg_user;") + (setq result-list nil) + (add-timeout .1 'database-poller P)) + => 1782 + ;; wait a moment + result-list + => (# # #) + + Here is an example which illustrates collecting all data from a +query, including the field names. + + (defun pg-util-query-results (results) + "Retrieve results of last SQL query into a list structure." + (let ((i (1- (pq-ntuples R))) + j l1 l2) + (while (>= i 0) + (setq j (1- (pq-nfields R))) + (setq l2 nil) + (while (>= j 0) + (push (pq-get-value R i j) l2) + (decf j)) + (push l2 l1) + (decf i)) + (setq j (1- (pq-nfields R))) + (setq l2 nil) + (while (>= j 0) + (push (pq-fname R j) l2) + (decf j)) + (push l2 l1) + l1)) + => pg-util-query-results + (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;")) + => # + (pg-util-query-results R) + => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1")) + + Here is an example of a query that uses a database cursor. + + (let (data R) + (setq R (pq-exec P "BEGIN;")) + (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;")) + + (setq R (pq-exec P "FETCH k_cursor;")) + (while (eq (pq-ntuples R) 1) + (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data) + (setq R (pq-exec P "FETCH k_cursor;"))) + (setq R (pq-exec P "END;")) + data) + => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1")) + + Here's another example of cursors, this time with a Lisp macro to +implement a mapping function over a table. + + (defmacro map-db (P table condition callout) + `(let (R) + (pq-exec ,P "BEGIN;") + (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM " + ,table + " " + ,condition + " ORDER BY f1 DESC;")) + (setq R (pq-exec P "FETCH k_cursor;")) + (while (eq (pq-ntuples R) 1) + (,callout (pq-get-value R 0 0) (pq-get-value R 0 1)) + (setq R (pq-exec P "FETCH k_cursor;"))) + (pq-exec P "END;"))) + => map-db + (defun callback (arg1 arg2) + (message "arg1 = %s, arg2 = %s" arg1 arg2)) + => callback + (map-db P "xemacs_test" "WHERE field2 > 10" callback) + => arg1 = stuff, arg2 = 42 + => arg1 = b, arg2 = 97 + => arg1 = a string, arg2 = 12 + => arg1 = a, arg2 = 97 + => # + + +File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL 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. + + +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. + + +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:: + + +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. + + +File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3 + +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: + + (defun foo (arg) "Doc string" (domain "emacs-foo") ...) + + 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'. + + - 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'. + + +File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3 + +Dynamic Messaging +----------------- + + 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. + + +File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3 + +Domain Specification +-------------------- + + 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: + + (dgettext "emacs-gorilla" "What gorilla?") + + 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: + + (defun scratch (location) + "Scratch the specified location." + (domain "emacs-gorilla") + (interactive "sScratch: ") + ... ) + + It is most efficient to specify the domain in the first line of the +function body, before the `interactive' form. + + For variables and constants which have documentation strings, +specify the domain after the documentation. + + - Special Form: defvar symbol [value [doc-string [domain]]] + Example: + (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") + + - Special Form: defconst symbol [value [doc-string [domain]]] + Example: + (defconst limbs 4 "Number of limbs" "emacs-gorilla") + + 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: + + - Function: autoload symbol filename &optional docstring interactive + macro domain + Example: + (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") + + +File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3 + +Documentation String Extraction +------------------------------- + + 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. + + (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.) + + +File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization + +I18N Level 4 +============ + + The Asian-language support in XEmacs is called "MULE". *Note MULE::. + + +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 is an extension and +complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese +word for "Japan"), which 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. +* 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: Internationalization Terminology, Next: Charsets, Up: MULE Internationalization Terminology @@ -639,396 +1146,3 @@ charsets work.) encodings. * Predefined Coding Systems:: Coding systems implemented by MULE. - -File: lispref.info, Node: Coding System Types, Next: ISO 2022, Up: Coding Systems - -Coding System Types -------------------- - - The coding system type determines the basic algorithm XEmacs will -use to decode or encode a data stream. Character encodings will be -converted to the MULE encoding, escape sequences processed, and newline -sequences converted to XEmacs's internal representation. There are -three basic classes of coding system type: no-conversion, ISO-2022, and -special. - - No conversion allows you to look at the file's internal -representation. Since XEmacs is basically a text editor, "no -conversion" does convert newline conventions by default. (Use the -'binary coding-system if this is not desired.) - - ISO 2022 (*note ISO 2022::) is the basic international standard -regulating use of "coded character sets for the exchange of data", ie, -text streams. ISO 2022 contains functions that make it possible to -encode text streams to comply with restrictions of the Internet mail -system and de facto restrictions of most file systems (eg, use of the -separator character in file names). Coding systems which are not ISO -2022 conformant can be difficult to handle. Perhaps more important, -they are not adaptable to multilingual information interchange, with -the obvious exception of ISO 10646 (Unicode). (Unicode is partially -supported by XEmacs with the addition of the Lisp package ucs-conv.) - - The special class of coding systems includes automatic detection, -CCL (a "little language" embedded as an interpreter, useful for -translating between variants of a single character set), -non-ISO-2022-conformant encodings like Unicode, Shift JIS, and Big5, -and MULE internal coding. (NB: this list is based on XEmacs 21.2. -Terminology may vary slightly for other versions of XEmacs and for GNU -Emacs 20.) - -`no-conversion' - No conversion, for binary files, and a few special cases of - non-ISO-2022 coding systems where conversion is done by hook - functions (usually implemented in CCL). 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.) - -`iso2022' - Any ISO-2022-compliant encoding. Among others, 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. - -`ucs-4' - ISO 10646 UCS-4 encoding. A 31-bit fixed-width superset of - Unicode. - -`utf-8' - ISO 10646 UTF-8 encoding. A "file system safe" transformation - format that can be used with both UCS-4 and Unicode. - -`undecided' - Automatic conversion. XEmacs attempts to detect the coding system - used in the file. - -`shift-jis' - Shift-JIS (a Japanese encoding commonly used in PC operating - systems). - -`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. For example, CCL is used to map KOI8-R characters - (an encoding for Russian Cyrillic) to ISO8859-5 (the form used - internally by MULE). - -`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. - - -File: lispref.info, Node: ISO 2022, Next: EOL Conversion, Prev: Coding System Types, Up: Coding Systems - -ISO 2022 -======== - - This section briefly describes the ISO 2022 encoding standard. A -more thorough treatment is available in the original document of ISO -2022 as well as various national standards (such as JIS X 0202). - - Character sets ("charsets") are classified into the following four -categories, according to the number of characters in the charset: -94-charset, 96-charset, 94x94-charset, and 96x96-charset. This means -that although an ISO 2022 coding system may have variable width -characters, each charset used is fixed-width (in contrast to the MULE -character set and UTF-8, for example). - - ISO 2022 provides for switching between character sets via escape -sequences. This switching is somewhat complicated, because ISO 2022 -provides for both legacy applications like Internet mail that accept -only 7 significant bits in some contexts (RFC 822 headers, for example), -and more modern "8-bit clean" applications. It also provides for -compact and transparent representation of languages like Japanese which -mix ASCII and a national script (even outside of computer programs). - - First, ISO 2022 codified prevailing practice by dividing the code -space into "control" and "graphic" regions. The code points 0x00-0x1F -and 0x80-0x9F are reserved for "control characters", while "graphic -characters" must be assigned to code points in the regions 0x20-0x7F and -0xA0-0xFF. The positions 0x20 and 0x7F are special, and under some -circumstances must be assigned the graphic character "ASCII SPACE" and -the control character "ASCII DEL" respectively. - - The various regions are given the name C0 (0x00-0x1F), GL -(0x20-0x7F), C1 (0x80-0x9F), and GR (0xA0-0xFF). GL and GR stand for -"graphic left" and "graphic right", respectively, because of the -standard method of displaying graphic character sets in tables with the -high byte indexing columns and the low byte indexing rows. I don't -find it very intuitive, but these are called "registers". - - An ISO 2022-conformant encoding for a graphic character set must use -a fixed number of bytes per character, and the values must fit into a -single register; that is, each byte must range over either 0x20-0x7F, or -0xA0-0xFF. It is not allowed to extend the range of the repertoire of a -character set by using both ranges at the same. This is why a standard -character set such as ISO 8859-1 is actually considered by ISO 2022 to -be an aggregation of two character sets, ASCII and LATIN-1, and why it -is technically incorrect to refer to ISO 8859-1 as "Latin 1". Also, a -single character's bytes must all be drawn from the same register; this -is why Shift JIS (for Japanese) and Big 5 (for Chinese) are not ISO -2022-compatible encodings. - - The reason for this restriction becomes clear when you attempt to -define an efficient, robust encoding for a language like Japanese. -Like ISO 8859, Japanese encodings are aggregations of several character -sets. In practice, the vast majority of characters are drawn from the -"JIS Roman" character set (a derivative of ASCII; it won't hurt to -think of it as ASCII) and the JIS X 0208 standard "basic Japanese" -character set including not only ideographic characters ("kanji") but -syllabic Japanese characters ("kana"), a wide variety of symbols, and -many alphabetic characters (Roman, Greek, and Cyrillic) as well. -Although JIS X 0208 includes the whole Roman alphabet, as a 2-byte code -it is not suited to programming; thus the inclusion of ASCII in the -standard Japanese encodings. - - For normal Japanese text such as in newspapers, a broad repertoire of -approximately 3000 characters is used. Evidently this won't fit into -one byte; two must be used. But much of the text processed by Japanese -computers is computer source code, nearly all of which is ASCII. A not -insignificant portion of ordinary text is English (as such or as -borrowed Japanese vocabulary) or other languages which can represented -at least approximately in ASCII, as well. It seems reasonable then to -represent ASCII in one byte, and JIS X 0208 in two. And this is exactly -what the Extended Unix Code for Japanese (EUC-JP) does. ASCII is -invoked to the GL register, and JIS X 0208 is invoked to the GR -register. Thus, each byte can be tested for its character set by -looking at the high bit; if set, it is Japanese, if clear, it is ASCII. -Furthermore, since control characters like newline can never be part of -a graphic character, even in the case of corruption in transmission the -stream will be resynchronized at every line break, on the order of 60-80 -bytes. This coding system requires no escape sequences or special -control codes to represent 99.9% of all Japanese text. - - Note carefully the distinction between the character sets (ASCII and -JIS X 0208), the encoding (EUC-JP), and the coding system (ISO 2022). -The JIS X 0208 character set is used in three different encodings for -Japanese, but in ISO-2022-JP it is invoked into GL (so the high bit is -always clear), in EUC-JP it is invoked into GR (setting the high bit in -the process), and in Shift JIS the high bit may be set or reset, and the -significant bits are shifted within the 16-bit character so that the two -main character sets can coexist with a third (the "halfwidth katakana" -of JIS X 0201). As the name implies, the ISO-2022-JP encoding is also a -version of the ISO-2022 coding system. - - In order to systematically treat subsidiary character sets (like the -"halfwidth katakana" already mentioned, and the "supplementary kanji" of -JIS X 0212), four further registers are defined: G0, G1, G2, and G3. -Unlike GL and GR, they are not logically distinguished by internal -format. Instead, the process of "invocation" mentioned earlier is -broken into two steps: first, a character set is "designated" to one of -the registers G0-G3 by use of an "escape sequence" of the form: - - ESC [I] I F - - where I is an intermediate character or characters in the range 0x20 -- 0x3F, and F, from the range 0x30-0x7Fm is the final character -identifying this charset. (Final characters in the range 0x30-0x3F are -reserved for private use and will never have a publically registered -meaning.) - - Then that register is "invoked" to either GL or GR, either -automatically (designations to G0 normally involve invocation to GL as -well), or by use of shifting (affecting only the following character in -the data stream) or locking (effective until the next designation or -locking) control sequences. An encoding conformant to ISO 2022 is -typically defined by designating the initial contents of the G0-G3 -registers, specifying an 7 or 8 bit environment, and specifying whether -further designations will be recognized. - - Some examples of character sets and the registered final characters -F used to designate them: - -94-charset - ASCII (B), left (J) and right (I) half of JIS X 0201, ... - -96-charset - Latin-1 (A), Latin-2 (B), Latin-3 (C), ... - -94x94-charset - GB2312 (A), JIS X 0208 (B), KSC5601 (C), ... - -96x96-charset - none for the moment - - The meanings of the various characters in these sequences, where not -specified by the ISO 2022 standard (such as the ESC character), are -assigned by "ECMA", the European Computer Manufacturers Association. - - The meaning of intermediate characters are: - - $ [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. - , [0x2C]: designate to G0 a 96-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. - - The comma may be used in files read and written only by MULE, as a -MULE extension, but this is illegal in ISO 2022. (The reason is that -in ISO 2022 G0 must be a 94-member character set, with 0x20 assigned -the value SPACE, and 0x7F assigned the value DEL.) - - Here are examples of designations: - - 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 - - (The short forms used to designate GB2312 and JIS X 0208 are for -backwards compatibility; the long forms are preferred.) - - 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). - - Locking Shift is done as follows: - - 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 - - Single Shift is done as follows: - - SS2 or ESC N: invoke G2 into GL - SS3 or ESC O: invoke G3 into GL - - The shift functions (such as LS1R and SS3) are represented by control -characters (from C1) in 8 bit environments and by escape sequences in 7 -bit environments. - - (#### 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.) - - Evidently 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. - - In MULE, we characterize a version of ISO 2022 by the following -attributes: - - 1. The character sets initially designated to G0 thru G3. - - 2. Whether short form designations are allowed for Japanese and - Chinese. - - 3. Whether ASCII should be designated to G0 before control characters. - - 4. Whether ASCII should be designated to G0 at the end of line. - - 5. 7-bit environment or 8-bit environment. - - 6. Whether Locking Shifts are used or not. - - 7. Whether to use ASCII or the variant JIS X 0201-1976-Roman. - - 8. Whether to use JIS X 0208-1983 or the older version JIS X - 0208-1976. - - (The last two are only for Japanese.) - - By specifying these attributes, you can create any variant of ISO -2022. - - Here are several examples: - - ISO-2022-JP -- Coding system used in Japanese email (RFC 1463 #### check). - 1. G0 <- ASCII, G1..3 <- never used - 2. Yes. - 3. Yes. - 4. Yes. - 5. 7-bit environment - 6. No. - 7. Use ASCII - 8. Use JIS X 0208-1983 - - ctext -- X11 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 JIS X 0208-1983. - - euc-china -- Chinese EUC. Often called the "GB encoding", but that is - technically incorrect. - 1. G0 <- ASCII, G1 <- GB 2312, G2,3 <- never used. - 2. No. - 3. Yes. - 4. Yes. - 5. 8-bit environment. - 6. No. - 7. Use ASCII. - 8. Use JIS X 0208-1983. - - ISO-2022-KR -- Coding system used in Korean email. - 1. G0 <- ASCII, G1 <- KSC 5601, G2,3 <- never used. - 2. No. - 3. Yes. - 4. Yes. - 5. 7-bit environment. - 6. Yes. - 7. Use ASCII. - 8. Use JIS X 0208-1983. - - MULE creates all of these coding systems by default. - - -File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: ISO 2022, 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. - -`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. - -`cr' - The end of a line is marked externally using ASCII CR. This is the - standard format for Macintosh text files. - -`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'.) - diff --git a/info/lispref.info-44 b/info/lispref.info-44 index ace6584..d539962 100644 --- a/info/lispref.info-44 +++ b/info/lispref.info-44 @@ -50,6 +50,399 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Coding System Types, Next: ISO 2022, Up: Coding Systems + +Coding System Types +------------------- + + The coding system type determines the basic algorithm XEmacs will +use to decode or encode a data stream. Character encodings will be +converted to the MULE encoding, escape sequences processed, and newline +sequences converted to XEmacs's internal representation. There are +three basic classes of coding system type: no-conversion, ISO-2022, and +special. + + No conversion allows you to look at the file's internal +representation. Since XEmacs is basically a text editor, "no +conversion" does convert newline conventions by default. (Use the +'binary coding-system if this is not desired.) + + ISO 2022 (*note ISO 2022::) is the basic international standard +regulating use of "coded character sets for the exchange of data", ie, +text streams. ISO 2022 contains functions that make it possible to +encode text streams to comply with restrictions of the Internet mail +system and de facto restrictions of most file systems (eg, use of the +separator character in file names). Coding systems which are not ISO +2022 conformant can be difficult to handle. Perhaps more important, +they are not adaptable to multilingual information interchange, with +the obvious exception of ISO 10646 (Unicode). (Unicode is partially +supported by XEmacs with the addition of the Lisp package ucs-conv.) + + The special class of coding systems includes automatic detection, +CCL (a "little language" embedded as an interpreter, useful for +translating between variants of a single character set), +non-ISO-2022-conformant encodings like Unicode, Shift JIS, and Big5, +and MULE internal coding. (NB: this list is based on XEmacs 21.2. +Terminology may vary slightly for other versions of XEmacs and for GNU +Emacs 20.) + +`no-conversion' + No conversion, for binary files, and a few special cases of + non-ISO-2022 coding systems where conversion is done by hook + functions (usually implemented in CCL). 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.) + +`iso2022' + Any ISO-2022-compliant encoding. Among others, 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. + +`ucs-4' + ISO 10646 UCS-4 encoding. A 31-bit fixed-width superset of + Unicode. + +`utf-8' + ISO 10646 UTF-8 encoding. A "file system safe" transformation + format that can be used with both UCS-4 and Unicode. + +`undecided' + Automatic conversion. XEmacs attempts to detect the coding system + used in the file. + +`shift-jis' + Shift-JIS (a Japanese encoding commonly used in PC operating + systems). + +`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. For example, CCL is used to map KOI8-R characters + (an encoding for Russian Cyrillic) to ISO8859-5 (the form used + internally by MULE). + +`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. + + +File: lispref.info, Node: ISO 2022, Next: EOL Conversion, Prev: Coding System Types, Up: Coding Systems + +ISO 2022 +======== + + This section briefly describes the ISO 2022 encoding standard. A +more thorough treatment is available in the original document of ISO +2022 as well as various national standards (such as JIS X 0202). + + Character sets ("charsets") are classified into the following four +categories, according to the number of characters in the charset: +94-charset, 96-charset, 94x94-charset, and 96x96-charset. This means +that although an ISO 2022 coding system may have variable width +characters, each charset used is fixed-width (in contrast to the MULE +character set and UTF-8, for example). + + ISO 2022 provides for switching between character sets via escape +sequences. This switching is somewhat complicated, because ISO 2022 +provides for both legacy applications like Internet mail that accept +only 7 significant bits in some contexts (RFC 822 headers, for example), +and more modern "8-bit clean" applications. It also provides for +compact and transparent representation of languages like Japanese which +mix ASCII and a national script (even outside of computer programs). + + First, ISO 2022 codified prevailing practice by dividing the code +space into "control" and "graphic" regions. The code points 0x00-0x1F +and 0x80-0x9F are reserved for "control characters", while "graphic +characters" must be assigned to code points in the regions 0x20-0x7F and +0xA0-0xFF. The positions 0x20 and 0x7F are special, and under some +circumstances must be assigned the graphic character "ASCII SPACE" and +the control character "ASCII DEL" respectively. + + The various regions are given the name C0 (0x00-0x1F), GL +(0x20-0x7F), C1 (0x80-0x9F), and GR (0xA0-0xFF). GL and GR stand for +"graphic left" and "graphic right", respectively, because of the +standard method of displaying graphic character sets in tables with the +high byte indexing columns and the low byte indexing rows. I don't +find it very intuitive, but these are called "registers". + + An ISO 2022-conformant encoding for a graphic character set must use +a fixed number of bytes per character, and the values must fit into a +single register; that is, each byte must range over either 0x20-0x7F, or +0xA0-0xFF. It is not allowed to extend the range of the repertoire of a +character set by using both ranges at the same. This is why a standard +character set such as ISO 8859-1 is actually considered by ISO 2022 to +be an aggregation of two character sets, ASCII and LATIN-1, and why it +is technically incorrect to refer to ISO 8859-1 as "Latin 1". Also, a +single character's bytes must all be drawn from the same register; this +is why Shift JIS (for Japanese) and Big 5 (for Chinese) are not ISO +2022-compatible encodings. + + The reason for this restriction becomes clear when you attempt to +define an efficient, robust encoding for a language like Japanese. +Like ISO 8859, Japanese encodings are aggregations of several character +sets. In practice, the vast majority of characters are drawn from the +"JIS Roman" character set (a derivative of ASCII; it won't hurt to +think of it as ASCII) and the JIS X 0208 standard "basic Japanese" +character set including not only ideographic characters ("kanji") but +syllabic Japanese characters ("kana"), a wide variety of symbols, and +many alphabetic characters (Roman, Greek, and Cyrillic) as well. +Although JIS X 0208 includes the whole Roman alphabet, as a 2-byte code +it is not suited to programming; thus the inclusion of ASCII in the +standard Japanese encodings. + + For normal Japanese text such as in newspapers, a broad repertoire of +approximately 3000 characters is used. Evidently this won't fit into +one byte; two must be used. But much of the text processed by Japanese +computers is computer source code, nearly all of which is ASCII. A not +insignificant portion of ordinary text is English (as such or as +borrowed Japanese vocabulary) or other languages which can represented +at least approximately in ASCII, as well. It seems reasonable then to +represent ASCII in one byte, and JIS X 0208 in two. And this is exactly +what the Extended Unix Code for Japanese (EUC-JP) does. ASCII is +invoked to the GL register, and JIS X 0208 is invoked to the GR +register. Thus, each byte can be tested for its character set by +looking at the high bit; if set, it is Japanese, if clear, it is ASCII. +Furthermore, since control characters like newline can never be part of +a graphic character, even in the case of corruption in transmission the +stream will be resynchronized at every line break, on the order of 60-80 +bytes. This coding system requires no escape sequences or special +control codes to represent 99.9% of all Japanese text. + + Note carefully the distinction between the character sets (ASCII and +JIS X 0208), the encoding (EUC-JP), and the coding system (ISO 2022). +The JIS X 0208 character set is used in three different encodings for +Japanese, but in ISO-2022-JP it is invoked into GL (so the high bit is +always clear), in EUC-JP it is invoked into GR (setting the high bit in +the process), and in Shift JIS the high bit may be set or reset, and the +significant bits are shifted within the 16-bit character so that the two +main character sets can coexist with a third (the "halfwidth katakana" +of JIS X 0201). As the name implies, the ISO-2022-JP encoding is also a +version of the ISO-2022 coding system. + + In order to systematically treat subsidiary character sets (like the +"halfwidth katakana" already mentioned, and the "supplementary kanji" of +JIS X 0212), four further registers are defined: G0, G1, G2, and G3. +Unlike GL and GR, they are not logically distinguished by internal +format. Instead, the process of "invocation" mentioned earlier is +broken into two steps: first, a character set is "designated" to one of +the registers G0-G3 by use of an "escape sequence" of the form: + + ESC [I] I F + + where I is an intermediate character or characters in the range 0x20 +- 0x3F, and F, from the range 0x30-0x7Fm is the final character +identifying this charset. (Final characters in the range 0x30-0x3F are +reserved for private use and will never have a publically registered +meaning.) + + Then that register is "invoked" to either GL or GR, either +automatically (designations to G0 normally involve invocation to GL as +well), or by use of shifting (affecting only the following character in +the data stream) or locking (effective until the next designation or +locking) control sequences. An encoding conformant to ISO 2022 is +typically defined by designating the initial contents of the G0-G3 +registers, specifying an 7 or 8 bit environment, and specifying whether +further designations will be recognized. + + Some examples of character sets and the registered final characters +F used to designate them: + +94-charset + ASCII (B), left (J) and right (I) half of JIS X 0201, ... + +96-charset + Latin-1 (A), Latin-2 (B), Latin-3 (C), ... + +94x94-charset + GB2312 (A), JIS X 0208 (B), KSC5601 (C), ... + +96x96-charset + none for the moment + + The meanings of the various characters in these sequences, where not +specified by the ISO 2022 standard (such as the ESC character), are +assigned by "ECMA", the European Computer Manufacturers Association. + + The meaning of intermediate characters are: + + $ [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. + , [0x2C]: designate to G0 a 96-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. + + The comma may be used in files read and written only by MULE, as a +MULE extension, but this is illegal in ISO 2022. (The reason is that +in ISO 2022 G0 must be a 94-member character set, with 0x20 assigned +the value SPACE, and 0x7F assigned the value DEL.) + + Here are examples of designations: + + 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 + + (The short forms used to designate GB2312 and JIS X 0208 are for +backwards compatibility; the long forms are preferred.) + + 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). + + Locking Shift is done as follows: + + 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 + + Single Shift is done as follows: + + SS2 or ESC N: invoke G2 into GL + SS3 or ESC O: invoke G3 into GL + + The shift functions (such as LS1R and SS3) are represented by control +characters (from C1) in 8 bit environments and by escape sequences in 7 +bit environments. + + (#### 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.) + + Evidently 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. + + In MULE, we characterize a version of ISO 2022 by the following +attributes: + + 1. The character sets initially designated to G0 thru G3. + + 2. Whether short form designations are allowed for Japanese and + Chinese. + + 3. Whether ASCII should be designated to G0 before control characters. + + 4. Whether ASCII should be designated to G0 at the end of line. + + 5. 7-bit environment or 8-bit environment. + + 6. Whether Locking Shifts are used or not. + + 7. Whether to use ASCII or the variant JIS X 0201-1976-Roman. + + 8. Whether to use JIS X 0208-1983 or the older version JIS X + 0208-1976. + + (The last two are only for Japanese.) + + By specifying these attributes, you can create any variant of ISO +2022. + + Here are several examples: + + ISO-2022-JP -- Coding system used in Japanese email (RFC 1463 #### check). + 1. G0 <- ASCII, G1..3 <- never used + 2. Yes. + 3. Yes. + 4. Yes. + 5. 7-bit environment + 6. No. + 7. Use ASCII + 8. Use JIS X 0208-1983 + + ctext -- X11 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 JIS X 0208-1983. + + euc-china -- Chinese EUC. Often called the "GB encoding", but that is + technically incorrect. + 1. G0 <- ASCII, G1 <- GB 2312, G2,3 <- never used. + 2. No. + 3. Yes. + 4. Yes. + 5. 8-bit environment. + 6. No. + 7. Use ASCII. + 8. Use JIS X 0208-1983. + + ISO-2022-KR -- Coding system used in Korean email. + 1. G0 <- ASCII, G1 <- KSC 5601, G2,3 <- never used. + 2. No. + 3. Yes. + 4. Yes. + 5. 7-bit environment. + 6. Yes. + 7. Use ASCII. + 8. Use JIS X 0208-1983. + + MULE creates all of these coding systems by default. + + +File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: ISO 2022, 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. + +`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. + +`cr' + The end of a line is marked externally using ASCII CR. This is the + standard format for Macintosh text files. + +`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'.) + + File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems Coding System Properties @@ -885,199 +1278,3 @@ but can modify the register status. successfully, and returns to caller (which may be a CCL program). It does not alter the status of the registers. - -File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL - -CCL Expressions ---------------- - - CCL, unlike Lisp, uses infix expressions. The simplest CCL -expressions consist of a single OPERAND, either a register (one of `r0', -..., `r0') or an integer. Complex expressions are lists of the form `( -EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not -expressions. - - In the following table, X is the target resister for a "set". In -subexpressions, this is implicitly `r7'. This means that `>8', `//', -`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since -they return parts of their values in `r7'. Y may be an expression, -register, or integer, while Z must be a register or an integer. - -Name Operator Code C-like Description -CCL_PLUS `+' 0x00 X = Y + Z -CCL_MINUS `-' 0x01 X = Y - Z -CCL_MUL `*' 0x02 X = Y * Z -CCL_DIV `/' 0x03 X = Y / Z -CCL_MOD `%' 0x04 X = Y % Z -CCL_AND `&' 0x05 X = Y & Z -CCL_OR `|' 0x06 X = Y | Z -CCL_XOR `^' 0x07 X = Y ^ Z -CCL_LSH `<<' 0x08 X = Y << Z -CCL_RSH `>>' 0x09 X = Y >> Z -CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z -CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF -CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z -CCL_LS `<' 0x10 X = (X < Y) -CCL_GT `>' 0x11 X = (X > Y) -CCL_EQ `==' 0x12 X = (X == Y) -CCL_LE `<=' 0x13 X = (X <= Y) -CCL_GE `>=' 0x14 X = (X >= Y) -CCL_NE `!=' 0x15 X = (X != Y) -CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z)) - r[7] = LOWER_BYTE (SJIS (Y, Z) -CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z)) - r[7] = LOWER_BYTE (DE-SJIS (Y, Z)) - - The CCL operators are as in C, with the addition of CCL_LSH8, -CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The -CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes -as the high and low bytes of a two-byte character code. (SJIS stands -for Shift JIS, an encoding of Japanese characters used by Microsoft. -CCL_ENCODE_SJIS is a complicated transformation of the Japanese -standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.) -It is somewhat odd to represent the SJIS operations in infix form. - - -File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL - -Calling CCL ------------ - - CCL programs are called automatically during Emacs buffer I/O when -the external representation has a coding system type of `shift-jis', -`big5', or `ccl'. The program is specified by the coding system (*note -Coding Systems::). You can also call CCL programs from other CCL -programs, and from Lisp using these functions: - - - Function: ccl-execute ccl-program status - Execute CCL-PROGRAM with registers initialized by STATUS. - CCL-PROGRAM is a vector of compiled CCL code created by - `ccl-compile'. It is an error for the program to try to execute a - CCL I/O command. STATUS must be a vector of nine values, - specifying the initial value for the R0, R1 .. R7 registers and - for the instruction counter IC. A `nil' value for a register - initializer causes the register to be set to 0. A `nil' value for - the IC initializer causes execution to start at the beginning of - the program. When the program is done, STATUS is modified (by - side-effect) to contain the ending values for the corresponding - registers and IC. - - - Function: ccl-execute-on-string ccl-program status str &optional - continue - Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is - a vector of compiled CCL code created by `ccl-compile'. STATUS - must be a vector of nine values, specifying the initial value for - the R0, R1 .. R7 registers and for the instruction counter IC. A - `nil' value for a register initializer causes the register to be - set to 0. A `nil' value for the IC initializer causes execution - to start at the beginning of the program. An optional fourth - argument CONTINUE, if non-nil, causes the IC to remain on the - unsatisfied read operation if the program terminates due to - exhaustion of the input buffer. Otherwise the IC is set to the end - of the program. When the program is done, STATUS is modified (by - side-effect) to contain the ending values for the corresponding - registers and IC. Returns the resulting string. - - To call a CCL program from another CCL program, it must first be -registered: - - - Function: register-ccl-program name ccl-program - Register NAME for CCL program PROGRAM in `ccl-program-table'. - PROGRAM should be the compiled form of a CCL program, or nil. - Return index number of the registered CCL program. - - Information about the processor time used by the CCL interpreter can -be obtained using these functions: - - - Function: ccl-elapsed-time - Returns the elapsed processor time of the CCL interpreter as cons - of user and system time, as floating point numbers measured in - seconds. If only one overall value can be determined, the return - value will be a cons of that value and 0. - - - Function: ccl-reset-elapsed-time - Resets the CCL interpreter's internal elapsed time registers. - - -File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL - -CCL Examples ------------- - - This section is not yet written. - - -File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE - -Category Tables -=============== - - A category table is a type of char table used for keeping track of -categories. Categories are used for classifying characters for use in -regexps--you can refer to a category rather than having to use a -complicated [] expression (and category lookups are significantly -faster). - - There are 95 different categories available, one for each printable -character (including space) in the ASCII charset. Each category is -designated by one such character, called a "category designator". They -are specified in a regexp using the syntax `\cX', where X is a category -designator. (This is not yet implemented.) - - A category table specifies, for each character, the categories that -the character is in. Note that a character can be in more than one -category. More specifically, a category table maps from a character to -either the value `nil' (meaning the character is in no categories) or a -95-element bit vector, specifying for each of the 95 categories whether -the character is in that category. - - Special Lisp functions are provided that abstract this, so you do not -have to directly manipulate bit vectors. - - - Function: category-table-p obj - This function returns `t' if ARG is a category table. - - - Function: category-table &optional buffer - This function returns the current category table. This is the one - specified by the current buffer, or by BUFFER if it is non-`nil'. - - - Function: standard-category-table - This function returns the standard category table. This is the - one used for new buffers. - - - Function: copy-category-table &optional table - This function constructs a new category table and return it. It - is a copy of the TABLE, which defaults to the standard category - table. - - - Function: set-category-table table &optional buffer - This function selects a new category table for BUFFER. One - argument, a category table. BUFFER defaults to the current buffer - if omitted. - - - Function: category-designator-p obj - This function returns `t' if ARG is a category designator (a char - in the range `' '' to `'~''). - - - Function: category-table-value-p obj - This function returns `t' if ARG is a category table value. Valid - values are `nil' or a bit vector of size 95. - - -File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top - -Tips and Standards -****************** - - This chapter describes no additional features of XEmacs Lisp. -Instead it gives advice on making effective use of the features -described in the previous chapters. - -* Menu: - -* Style Tips:: Writing clean and robust programs. -* Compilation Tips:: Making compiled code run fast. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - diff --git a/info/lispref.info-45 b/info/lispref.info-45 index 3a84e99..f5017ba 100644 --- a/info/lispref.info-45 +++ b/info/lispref.info-45 @@ -50,6 +50,202 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL + +CCL Expressions +--------------- + + CCL, unlike Lisp, uses infix expressions. The simplest CCL +expressions consist of a single OPERAND, either a register (one of `r0', +..., `r0') or an integer. Complex expressions are lists of the form `( +EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not +expressions. + + In the following table, X is the target resister for a "set". In +subexpressions, this is implicitly `r7'. This means that `>8', `//', +`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since +they return parts of their values in `r7'. Y may be an expression, +register, or integer, while Z must be a register or an integer. + +Name Operator Code C-like Description +CCL_PLUS `+' 0x00 X = Y + Z +CCL_MINUS `-' 0x01 X = Y - Z +CCL_MUL `*' 0x02 X = Y * Z +CCL_DIV `/' 0x03 X = Y / Z +CCL_MOD `%' 0x04 X = Y % Z +CCL_AND `&' 0x05 X = Y & Z +CCL_OR `|' 0x06 X = Y | Z +CCL_XOR `^' 0x07 X = Y ^ Z +CCL_LSH `<<' 0x08 X = Y << Z +CCL_RSH `>>' 0x09 X = Y >> Z +CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z +CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF +CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z +CCL_LS `<' 0x10 X = (X < Y) +CCL_GT `>' 0x11 X = (X > Y) +CCL_EQ `==' 0x12 X = (X == Y) +CCL_LE `<=' 0x13 X = (X <= Y) +CCL_GE `>=' 0x14 X = (X >= Y) +CCL_NE `!=' 0x15 X = (X != Y) +CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z)) + r[7] = LOWER_BYTE (SJIS (Y, Z) +CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z)) + r[7] = LOWER_BYTE (DE-SJIS (Y, Z)) + + The CCL operators are as in C, with the addition of CCL_LSH8, +CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The +CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes +as the high and low bytes of a two-byte character code. (SJIS stands +for Shift JIS, an encoding of Japanese characters used by Microsoft. +CCL_ENCODE_SJIS is a complicated transformation of the Japanese +standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.) +It is somewhat odd to represent the SJIS operations in infix form. + + +File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL + +Calling CCL +----------- + + CCL programs are called automatically during Emacs buffer I/O when +the external representation has a coding system type of `shift-jis', +`big5', or `ccl'. The program is specified by the coding system (*note +Coding Systems::). You can also call CCL programs from other CCL +programs, and from Lisp using these functions: + + - Function: ccl-execute ccl-program status + Execute CCL-PROGRAM with registers initialized by STATUS. + CCL-PROGRAM is a vector of compiled CCL code created by + `ccl-compile'. It is an error for the program to try to execute a + CCL I/O command. STATUS must be a vector of nine values, + specifying the initial value for the R0, R1 .. R7 registers and + for the instruction counter IC. A `nil' value for a register + initializer causes the register to be set to 0. A `nil' value for + the IC initializer causes execution to start at the beginning of + the program. When the program is done, STATUS is modified (by + side-effect) to contain the ending values for the corresponding + registers and IC. + + - Function: ccl-execute-on-string ccl-program status str &optional + continue + Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is + a vector of compiled CCL code created by `ccl-compile'. STATUS + must be a vector of nine values, specifying the initial value for + the R0, R1 .. R7 registers and for the instruction counter IC. A + `nil' value for a register initializer causes the register to be + set to 0. A `nil' value for the IC initializer causes execution + to start at the beginning of the program. An optional fourth + argument CONTINUE, if non-nil, causes the IC to remain on the + unsatisfied read operation if the program terminates due to + exhaustion of the input buffer. Otherwise the IC is set to the end + of the program. When the program is done, STATUS is modified (by + side-effect) to contain the ending values for the corresponding + registers and IC. Returns the resulting string. + + To call a CCL program from another CCL program, it must first be +registered: + + - Function: register-ccl-program name ccl-program + Register NAME for CCL program PROGRAM in `ccl-program-table'. + PROGRAM should be the compiled form of a CCL program, or nil. + Return index number of the registered CCL program. + + Information about the processor time used by the CCL interpreter can +be obtained using these functions: + + - Function: ccl-elapsed-time + Returns the elapsed processor time of the CCL interpreter as cons + of user and system time, as floating point numbers measured in + seconds. If only one overall value can be determined, the return + value will be a cons of that value and 0. + + - Function: ccl-reset-elapsed-time + Resets the CCL interpreter's internal elapsed time registers. + + +File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL + +CCL Examples +------------ + + This section is not yet written. + + +File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE + +Category Tables +=============== + + A category table is a type of char table used for keeping track of +categories. Categories are used for classifying characters for use in +regexps--you can refer to a category rather than having to use a +complicated [] expression (and category lookups are significantly +faster). + + There are 95 different categories available, one for each printable +character (including space) in the ASCII charset. Each category is +designated by one such character, called a "category designator". They +are specified in a regexp using the syntax `\cX', where X is a category +designator. (This is not yet implemented.) + + A category table specifies, for each character, the categories that +the character is in. Note that a character can be in more than one +category. More specifically, a category table maps from a character to +either the value `nil' (meaning the character is in no categories) or a +95-element bit vector, specifying for each of the 95 categories whether +the character is in that category. + + Special Lisp functions are provided that abstract this, so you do not +have to directly manipulate bit vectors. + + - Function: category-table-p obj + This function returns `t' if ARG is a category table. + + - Function: category-table &optional buffer + This function returns the current category table. This is the one + specified by the current buffer, or by BUFFER if it is non-`nil'. + + - Function: standard-category-table + This function returns the standard category table. This is the + one used for new buffers. + + - Function: copy-category-table &optional table + This function constructs a new category table and return it. It + is a copy of the TABLE, which defaults to the standard category + table. + + - Function: set-category-table table &optional buffer + This function selects a new category table for BUFFER. One + argument, a category table. BUFFER defaults to the current buffer + if omitted. + + - Function: category-designator-p obj + This function returns `t' if ARG is a category designator (a char + in the range `' '' to `'~''). + + - Function: category-table-value-p obj + This function returns `t' if ARG is a category table value. Valid + values are `nil' or a bit vector of size 95. + + +File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top + +Tips and Standards +****************** + + This chapter describes no additional features of XEmacs Lisp. +Instead it gives advice on making effective use of the features +described in the previous chapters. + +* Menu: + +* Style Tips:: Writing clean and robust programs. +* Compilation Tips:: Making compiled code run fast. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Library Headers:: Standard headers for library packages. + + File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips Writing Clean Lisp Programs @@ -801,402 +997,3 @@ ones. You should not change this flag in a running XEmacs. - -File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation - -Garbage Collection -================== - - When a program creates a list or the user defines a new function -(such as by loading a library), that data is placed in normal storage. -If normal storage runs low, then XEmacs asks the operating system to -allocate more memory in blocks of 2k bytes. Each block is used for one -type of Lisp object, so symbols, cons cells, markers, etc., are -segregated in distinct blocks in memory. (Vectors, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small strings are -packed into blocks of 8k bytes. [More correctly, a string is allocated -in two sections: a fixed size chunk containing the length, list of -extents, etc.; and a chunk containing the actual characters in the -string. It is this latter chunk that is either allocated individually -or packed into 8k blocks. The fixed size chunk is packed into 2k -blocks, as for conses, markers, etc.]) - - It is quite common to use some storage for a while, then release it -by (for example) killing a buffer or deleting the last pointer to an -object. XEmacs provides a "garbage collector" to reclaim this -abandoned storage. (This name is traditional, but "garbage recycler" -might be a more intuitive metaphor for this facility.) - - The garbage collector operates by finding and marking all Lisp -objects that are still accessible to Lisp programs. To begin with, it -assumes all the symbols, their values and associated function -definitions, and any data presently on the stack, are accessible. Any -objects that can be reached indirectly through other accessible objects -are also accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -("sweep") phase of the garbage collector arranges to reuse them. - - The sweep phase puts unused cons cells onto a "free list" for future -allocation; likewise for symbols, markers, extents, events, floats, -compiled-function objects, and the fixed-size portion of strings. It -compacts the accessible small string-chars chunks so they occupy fewer -8k blocks; then it frees the other 8k blocks. Vectors, buffers, -windows, and other large objects are individually allocated and freed -using `malloc' and `free'. - - Common Lisp note: unlike other Lisps, XEmacs Lisp does not call - the garbage collector when the free list is empty. Instead, it - simply requests the operating system to allocate more storage, and - processing continues until `gc-cons-threshold' bytes have been - used. - - This means that you can make sure that the garbage collector will - not run during a certain portion of a Lisp program by calling the - garbage collector explicitly just before it (provided that portion - of the program does not use so much space as to force a second - garbage collection). - - - Command: garbage-collect - This command runs a garbage collection, and returns information on - the amount of space in use. (Garbage collection can also occur - spontaneously if you use more than `gc-cons-threshold' bytes of - Lisp data since the previous garbage collection.) - - `garbage-collect' returns a list containing the following - information: - - ((USED-CONSES . FREE-CONSES) - (USED-SYMS . FREE-SYMS) - (USED-MARKERS . FREE-MARKERS) - USED-STRING-CHARS - USED-VECTOR-SLOTS - (PLIST)) - - => ((73362 . 8325) (13718 . 164) - (5089 . 5098) 949121 118677 - (conses-used 73362 conses-free 8329 cons-storage 658168 - symbols-used 13718 symbols-free 164 symbol-storage 335216 - bit-vectors-used 0 bit-vectors-total-length 0 - bit-vector-storage 0 vectors-used 7882 - vectors-total-length 118677 vector-storage 537764 - compiled-functions-used 1336 compiled-functions-free 37 - compiled-function-storage 44440 short-strings-used 28829 - long-strings-used 2 strings-free 7722 - short-strings-total-length 916657 short-string-storage 1179648 - long-strings-total-length 32464 string-header-storage 441504 - floats-used 3 floats-free 43 float-storage 2044 markers-used 5089 - markers-free 5098 marker-storage 245280 events-used 103 - events-free 835 event-storage 110656 extents-used 10519 - extents-free 2718 extent-storage 372736 - extent-auxiliarys-used 111 extent-auxiliarys-freed 3 - extent-auxiliary-storage 4440 window-configurations-used 39 - window-configurations-on-free-list 5 - window-configurations-freed 10 window-configuration-storage 9492 - popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62 - toolbar-button-storage 4960 toolbar-datas-used 12 - toolbar-data-storage 240 symbol-value-buffer-locals-used 182 - symbol-value-buffer-local-storage 5824 - symbol-value-lisp-magics-used 22 - symbol-value-lisp-magic-storage 1496 - symbol-value-varaliases-used 43 - symbol-value-varalias-storage 1032 opaque-lists-used 2 - opaque-list-storage 48 color-instances-used 12 - color-instance-storage 288 font-instances-used 5 - font-instance-storage 180 opaques-used 11 opaque-storage 312 - range-tables-used 1 range-table-storage 16 faces-used 34 - face-storage 2584 glyphs-used 124 glyph-storage 4464 - specifiers-used 775 specifier-storage 43869 weak-lists-used 786 - weak-list-storage 18864 char-tables-used 40 - char-table-storage 41920 buffers-used 25 buffer-storage 7000 - extent-infos-used 457 extent-infos-freed 73 - extent-info-storage 9140 keymaps-used 275 keymap-storage 12100 - consoles-used 4 console-storage 384 command-builders-used 2 - command-builder-storage 120 devices-used 2 device-storage 344 - frames-used 3 frame-storage 624 image-instances-used 47 - image-instance-storage 3008 windows-used 27 windows-freed 2 - window-storage 9180 lcrecord-lists-used 15 - lcrecord-list-storage 360 hash-tables-used 631 - hash-table-storage 25240 streams-used 1 streams-on-free-list 3 - streams-freed 12 stream-storage 91)) - - Here is a table explaining each element: - - USED-CONSES - The number of cons cells in use. - - FREE-CONSES - The number of cons cells for which space has been obtained - from the operating system, but that are not currently being - used. - - USED-SYMS - The number of symbols in use. - - FREE-SYMS - The number of symbols for which space has been obtained from - the operating system, but that are not currently being used. - - USED-MARKERS - The number of markers in use. - - FREE-MARKERS - The number of markers for which space has been obtained from - the operating system, but that are not currently being used. - - USED-STRING-CHARS - The total size of all strings, in characters. - - USED-VECTOR-SLOTS - The total number of elements of existing vectors. - - PLIST - A list of alternating keyword/value pairs providing more - detailed information. (As you can see above, quite a lot of - information is provided.) - - - User Option: gc-cons-threshold - The value of this variable is the number of bytes of storage that - must be allocated for Lisp objects after one garbage collection in - order to trigger another garbage collection. A cons cell counts - as eight bytes, a string as one byte per character plus a few - bytes of overhead, and so on; space allocated to the contents of - buffers does not count. Note that the subsequent garbage - collection does not happen immediately when the threshold is - exhausted, but only the next time the Lisp evaluator is called. - - The initial threshold value is 500,000. If you specify a larger - value, garbage collection will happen less often. This reduces the - amount of time spent garbage collecting, but increases total - memory use. You may want to do this when running a program that - creates lots of Lisp data. - - You can make collections more frequent by specifying a smaller - value, down to 10,000. A value less than 10,000 will remain in - effect only until the subsequent garbage collection, at which time - `garbage-collect' will set the threshold back to 10,000. (This does - not apply if XEmacs was configured with `--debug'. Therefore, be - careful when setting `gc-cons-threshold' in that case!) - - - Function: memory-limit - This function returns the address of the last byte XEmacs has - allocated, divided by 1024. We divide the value by 1024 to make - sure it fits in a Lisp integer. - - You can use this to get a general idea of how your actions affect - the memory usage. - - - Variable: pre-gc-hook - This is a normal hook to be run just before each garbage - collection. Interrupts, garbage collection, and errors are - inhibited while this hook runs, so be extremely careful in what - you add here. In particular, avoid consing, and do not interact - with the user. - - - Variable: post-gc-hook - This is a normal hook to be run just after each garbage collection. - Interrupts, garbage collection, and errors are inhibited while - this hook runs, so be extremely careful in what you add here. In - particular, avoid consing, and do not interact with the user. - - - Variable: gc-message - This is a string to print to indicate that a garbage collection is - in progress. This is printed in the echo area. If the selected - frame is on a window system and `gc-pointer-glyph' specifies a - value (i.e. a pointer image instance) in the domain of the - selected frame, the mouse cursor will change instead of this - message being printed. - - - Glyph: gc-pointer-glyph - This holds the pointer glyph used to indicate that a garbage - collection is in progress. If the selected window is on a window - system and this glyph specifies a value (i.e. a pointer image - instance) in the domain of the selected window, the cursor will be - changed as specified during garbage collection. Otherwise, a - message will be printed in the echo area, as controlled by - `gc-message'. *Note Glyphs::. - - If XEmacs was configured with `--debug', you can set the following -two variables to get direct information about all the allocation that -is happening in a segment of Lisp code. - - - Variable: debug-allocation - If non-zero, print out information to stderr about all objects - allocated. - - - Variable: debug-allocation-backtrace - Length (in stack frames) of short backtrace printed out by - `debug-allocation'. - - -File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top - -Standard Errors -*************** - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -`error-message' property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an `error-conditions' property that is a list -of symbols. Normally this list includes the error symbol itself and -the symbol `error'. Occasionally it includes additional symbols, which -are intermediate classifications, narrower than `error' but broader -than a single error symbol. For example, all the errors in accessing -files have the condition `file-error'. - - As a special exception, the error symbol `quit' does not have the -condition `error', because quitting is not considered an error. - - *Note Errors::, for an explanation of how errors are generated and -handled. - -`SYMBOL' - STRING; REFERENCE. - -`error' - `"error"' - *Note Errors::. - -`quit' - `"Quit"' - *Note Quitting::. - -`args-out-of-range' - `"Args out of range"' - *Note Sequences Arrays Vectors::. - -`arith-error' - `"Arithmetic error"' - See `/' and `%' in *Note Numbers::. - -`beginning-of-buffer' - `"Beginning of buffer"' - *Note Motion::. - -`buffer-read-only' - `"Buffer is read-only"' - *Note Read Only Buffers::. - -`cyclic-function-indirection' - `"Symbol's chain of function indirections contains a loop"' - *Note Function Indirection::. - -`domain-error' - `"Arithmetic domain error"' -`end-of-buffer' - `"End of buffer"' - *Note Motion::. - -`end-of-file' - `"End of file during parsing"' - This is not a `file-error'. - *Note Input Functions::. - -`file-error' - This error and its subcategories do not have error-strings, - because the error message is constructed from the data items alone - when the error condition `file-error' is present. - *Note Files::. - -`file-locked' - This is a `file-error'. - *Note File Locks::. - -`file-already-exists' - This is a `file-error'. - *Note Writing to Files::. - -`file-supersession' - This is a `file-error'. - *Note Modification Time::. - -`invalid-byte-code' - `"Invalid byte code"' - *Note Byte Compilation::. - -`invalid-function' - `"Invalid function"' - *Note Classifying Lists::. - -`invalid-read-syntax' - `"Invalid read syntax"' - *Note Input Functions::. - -`invalid-regexp' - `"Invalid regexp"' - *Note Regular Expressions::. - -`mark-inactive' - `"The mark is not active now"' -`no-catch' - `"No catch for tag"' - *Note Catch and Throw::. - -`overflow-error' - `"Arithmetic overflow error"' -`protected-field' - `"Attempt to modify a protected field"' -`range-error' - `"Arithmetic range error"' -`search-failed' - `"Search failed"' - *Note Searching and Matching::. - -`setting-constant' - `"Attempt to set a constant symbol"' - *Note Variables that Never Change: Constant Variables. - -`singularity-error' - `"Arithmetic singularity error"' -`tooltalk-error' - `"ToolTalk error"' - *Note ToolTalk Support::. - -`undefined-keystroke-sequence' - `"Undefined keystroke sequence"' -`void-function' - `"Symbol's function definition is void"' - *Note Function Cells::. - -`void-variable' - `"Symbol's value as variable is void"' - *Note Accessing Variables::. - -`wrong-number-of-arguments' - `"Wrong number of arguments"' - *Note Classifying Lists::. - -`wrong-type-argument' - `"Wrong type argument"' - *Note Type Predicates::. - - These error types, which are all classified as special cases of -`arith-error', can occur on certain systems for invalid use of -mathematical functions. - -`domain-error' - `"Arithmetic domain error"' - *Note Math Functions::. - -`overflow-error' - `"Arithmetic overflow error"' - *Note Math Functions::. - -`range-error' - `"Arithmetic range error"' - *Note Math Functions::. - -`singularity-error' - `"Arithmetic singularity error"' - *Note Math Functions::. - -`underflow-error' - `"Arithmetic underflow error"' - *Note Math Functions::. - diff --git a/info/lispref.info-46 b/info/lispref.info-46 index 7a6e6ca..a1767fa 100644 --- a/info/lispref.info-46 +++ b/info/lispref.info-46 @@ -50,6 +50,405 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation + +Garbage Collection +================== + + When a program creates a list or the user defines a new function +(such as by loading a library), that data is placed in normal storage. +If normal storage runs low, then XEmacs asks the operating system to +allocate more memory in blocks of 2k bytes. Each block is used for one +type of Lisp object, so symbols, cons cells, markers, etc., are +segregated in distinct blocks in memory. (Vectors, long strings, +buffers and certain other editing types, which are fairly large, are +allocated in individual blocks, one per object, while small strings are +packed into blocks of 8k bytes. [More correctly, a string is allocated +in two sections: a fixed size chunk containing the length, list of +extents, etc.; and a chunk containing the actual characters in the +string. It is this latter chunk that is either allocated individually +or packed into 8k blocks. The fixed size chunk is packed into 2k +blocks, as for conses, markers, etc.]) + + It is quite common to use some storage for a while, then release it +by (for example) killing a buffer or deleting the last pointer to an +object. XEmacs provides a "garbage collector" to reclaim this +abandoned storage. (This name is traditional, but "garbage recycler" +might be a more intuitive metaphor for this facility.) + + The garbage collector operates by finding and marking all Lisp +objects that are still accessible to Lisp programs. To begin with, it +assumes all the symbols, their values and associated function +definitions, and any data presently on the stack, are accessible. Any +objects that can be reached indirectly through other accessible objects +are also accessible. + + When marking is finished, all objects still unmarked are garbage. No +matter what the Lisp program or the user does, it is impossible to refer +to them, since there is no longer a way to reach them. Their space +might as well be reused, since no one will miss them. The second +("sweep") phase of the garbage collector arranges to reuse them. + + The sweep phase puts unused cons cells onto a "free list" for future +allocation; likewise for symbols, markers, extents, events, floats, +compiled-function objects, and the fixed-size portion of strings. It +compacts the accessible small string-chars chunks so they occupy fewer +8k blocks; then it frees the other 8k blocks. Vectors, buffers, +windows, and other large objects are individually allocated and freed +using `malloc' and `free'. + + Common Lisp note: unlike other Lisps, XEmacs Lisp does not call + the garbage collector when the free list is empty. Instead, it + simply requests the operating system to allocate more storage, and + processing continues until `gc-cons-threshold' bytes have been + used. + + This means that you can make sure that the garbage collector will + not run during a certain portion of a Lisp program by calling the + garbage collector explicitly just before it (provided that portion + of the program does not use so much space as to force a second + garbage collection). + + - Command: garbage-collect + This command runs a garbage collection, and returns information on + the amount of space in use. (Garbage collection can also occur + spontaneously if you use more than `gc-cons-threshold' bytes of + Lisp data since the previous garbage collection.) + + `garbage-collect' returns a list containing the following + information: + + ((USED-CONSES . FREE-CONSES) + (USED-SYMS . FREE-SYMS) + (USED-MARKERS . FREE-MARKERS) + USED-STRING-CHARS + USED-VECTOR-SLOTS + (PLIST)) + + => ((73362 . 8325) (13718 . 164) + (5089 . 5098) 949121 118677 + (conses-used 73362 conses-free 8329 cons-storage 658168 + symbols-used 13718 symbols-free 164 symbol-storage 335216 + bit-vectors-used 0 bit-vectors-total-length 0 + bit-vector-storage 0 vectors-used 7882 + vectors-total-length 118677 vector-storage 537764 + compiled-functions-used 1336 compiled-functions-free 37 + compiled-function-storage 44440 short-strings-used 28829 + long-strings-used 2 strings-free 7722 + short-strings-total-length 916657 short-string-storage 1179648 + long-strings-total-length 32464 string-header-storage 441504 + floats-used 3 floats-free 43 float-storage 2044 markers-used 5089 + markers-free 5098 marker-storage 245280 events-used 103 + events-free 835 event-storage 110656 extents-used 10519 + extents-free 2718 extent-storage 372736 + extent-auxiliarys-used 111 extent-auxiliarys-freed 3 + extent-auxiliary-storage 4440 window-configurations-used 39 + window-configurations-on-free-list 5 + window-configurations-freed 10 window-configuration-storage 9492 + popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62 + toolbar-button-storage 4960 toolbar-datas-used 12 + toolbar-data-storage 240 symbol-value-buffer-locals-used 182 + symbol-value-buffer-local-storage 5824 + symbol-value-lisp-magics-used 22 + symbol-value-lisp-magic-storage 1496 + symbol-value-varaliases-used 43 + symbol-value-varalias-storage 1032 opaque-lists-used 2 + opaque-list-storage 48 color-instances-used 12 + color-instance-storage 288 font-instances-used 5 + font-instance-storage 180 opaques-used 11 opaque-storage 312 + range-tables-used 1 range-table-storage 16 faces-used 34 + face-storage 2584 glyphs-used 124 glyph-storage 4464 + specifiers-used 775 specifier-storage 43869 weak-lists-used 786 + weak-list-storage 18864 char-tables-used 40 + char-table-storage 41920 buffers-used 25 buffer-storage 7000 + extent-infos-used 457 extent-infos-freed 73 + extent-info-storage 9140 keymaps-used 275 keymap-storage 12100 + consoles-used 4 console-storage 384 command-builders-used 2 + command-builder-storage 120 devices-used 2 device-storage 344 + frames-used 3 frame-storage 624 image-instances-used 47 + image-instance-storage 3008 windows-used 27 windows-freed 2 + window-storage 9180 lcrecord-lists-used 15 + lcrecord-list-storage 360 hash-tables-used 631 + hash-table-storage 25240 streams-used 1 streams-on-free-list 3 + streams-freed 12 stream-storage 91)) + + Here is a table explaining each element: + + USED-CONSES + The number of cons cells in use. + + FREE-CONSES + The number of cons cells for which space has been obtained + from the operating system, but that are not currently being + used. + + USED-SYMS + The number of symbols in use. + + FREE-SYMS + The number of symbols for which space has been obtained from + the operating system, but that are not currently being used. + + USED-MARKERS + The number of markers in use. + + FREE-MARKERS + The number of markers for which space has been obtained from + the operating system, but that are not currently being used. + + USED-STRING-CHARS + The total size of all strings, in characters. + + USED-VECTOR-SLOTS + The total number of elements of existing vectors. + + PLIST + A list of alternating keyword/value pairs providing more + detailed information. (As you can see above, quite a lot of + information is provided.) + + - User Option: gc-cons-threshold + The value of this variable is the number of bytes of storage that + must be allocated for Lisp objects after one garbage collection in + order to trigger another garbage collection. A cons cell counts + as eight bytes, a string as one byte per character plus a few + bytes of overhead, and so on; space allocated to the contents of + buffers does not count. Note that the subsequent garbage + collection does not happen immediately when the threshold is + exhausted, but only the next time the Lisp evaluator is called. + + The initial threshold value is 500,000. If you specify a larger + value, garbage collection will happen less often. This reduces the + amount of time spent garbage collecting, but increases total + memory use. You may want to do this when running a program that + creates lots of Lisp data. + + You can make collections more frequent by specifying a smaller + value, down to 10,000. A value less than 10,000 will remain in + effect only until the subsequent garbage collection, at which time + `garbage-collect' will set the threshold back to 10,000. (This does + not apply if XEmacs was configured with `--debug'. Therefore, be + careful when setting `gc-cons-threshold' in that case!) + + - Function: memory-limit + This function returns the address of the last byte XEmacs has + allocated, divided by 1024. We divide the value by 1024 to make + sure it fits in a Lisp integer. + + You can use this to get a general idea of how your actions affect + the memory usage. + + - Variable: pre-gc-hook + This is a normal hook to be run just before each garbage + collection. Interrupts, garbage collection, and errors are + inhibited while this hook runs, so be extremely careful in what + you add here. In particular, avoid consing, and do not interact + with the user. + + - Variable: post-gc-hook + This is a normal hook to be run just after each garbage collection. + Interrupts, garbage collection, and errors are inhibited while + this hook runs, so be extremely careful in what you add here. In + particular, avoid consing, and do not interact with the user. + + - Variable: gc-message + This is a string to print to indicate that a garbage collection is + in progress. This is printed in the echo area. If the selected + frame is on a window system and `gc-pointer-glyph' specifies a + value (i.e. a pointer image instance) in the domain of the + selected frame, the mouse cursor will change instead of this + message being printed. + + - Glyph: gc-pointer-glyph + This holds the pointer glyph used to indicate that a garbage + collection is in progress. If the selected window is on a window + system and this glyph specifies a value (i.e. a pointer image + instance) in the domain of the selected window, the cursor will be + changed as specified during garbage collection. Otherwise, a + message will be printed in the echo area, as controlled by + `gc-message'. *Note Glyphs::. + + If XEmacs was configured with `--debug', you can set the following +two variables to get direct information about all the allocation that +is happening in a segment of Lisp code. + + - Variable: debug-allocation + If non-zero, print out information to stderr about all objects + allocated. + + - Variable: debug-allocation-backtrace + Length (in stack frames) of short backtrace printed out by + `debug-allocation'. + + +File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top + +Standard Errors +*************** + + Here is the complete list of the error symbols in standard Emacs, +grouped by concept. The list includes each symbol's message (on the +`error-message' property of the symbol) and a cross reference to a +description of how the error can occur. + + Each error symbol has an `error-conditions' property that is a list +of symbols. Normally this list includes the error symbol itself and +the symbol `error'. Occasionally it includes additional symbols, which +are intermediate classifications, narrower than `error' but broader +than a single error symbol. For example, all the errors in accessing +files have the condition `file-error'. + + As a special exception, the error symbol `quit' does not have the +condition `error', because quitting is not considered an error. + + *Note Errors::, for an explanation of how errors are generated and +handled. + +`SYMBOL' + STRING; REFERENCE. + +`error' + `"error"' + *Note Errors::. + +`quit' + `"Quit"' + *Note Quitting::. + +`args-out-of-range' + `"Args out of range"' + *Note Sequences Arrays Vectors::. + +`arith-error' + `"Arithmetic error"' + See `/' and `%' in *Note Numbers::. + +`beginning-of-buffer' + `"Beginning of buffer"' + *Note Motion::. + +`buffer-read-only' + `"Buffer is read-only"' + *Note Read Only Buffers::. + +`cyclic-function-indirection' + `"Symbol's chain of function indirections contains a loop"' + *Note Function Indirection::. + +`domain-error' + `"Arithmetic domain error"' +`end-of-buffer' + `"End of buffer"' + *Note Motion::. + +`end-of-file' + `"End of file during parsing"' + This is not a `file-error'. + *Note Input Functions::. + +`file-error' + This error and its subcategories do not have error-strings, + because the error message is constructed from the data items alone + when the error condition `file-error' is present. + *Note Files::. + +`file-locked' + This is a `file-error'. + *Note File Locks::. + +`file-already-exists' + This is a `file-error'. + *Note Writing to Files::. + +`file-supersession' + This is a `file-error'. + *Note Modification Time::. + +`invalid-byte-code' + `"Invalid byte code"' + *Note Byte Compilation::. + +`invalid-function' + `"Invalid function"' + *Note Classifying Lists::. + +`invalid-read-syntax' + `"Invalid read syntax"' + *Note Input Functions::. + +`invalid-regexp' + `"Invalid regexp"' + *Note Regular Expressions::. + +`mark-inactive' + `"The mark is not active now"' +`no-catch' + `"No catch for tag"' + *Note Catch and Throw::. + +`overflow-error' + `"Arithmetic overflow error"' +`protected-field' + `"Attempt to modify a protected field"' +`range-error' + `"Arithmetic range error"' +`search-failed' + `"Search failed"' + *Note Searching and Matching::. + +`setting-constant' + `"Attempt to set a constant symbol"' + *Note Variables that Never Change: Constant Variables. + +`singularity-error' + `"Arithmetic singularity error"' +`tooltalk-error' + `"ToolTalk error"' + *Note ToolTalk Support::. + +`undefined-keystroke-sequence' + `"Undefined keystroke sequence"' +`void-function' + `"Symbol's function definition is void"' + *Note Function Cells::. + +`void-variable' + `"Symbol's value as variable is void"' + *Note Accessing Variables::. + +`wrong-number-of-arguments' + `"Wrong number of arguments"' + *Note Classifying Lists::. + +`wrong-type-argument' + `"Wrong type argument"' + *Note Type Predicates::. + + These error types, which are all classified as special cases of +`arith-error', can occur on certain systems for invalid use of +mathematical functions. + +`domain-error' + `"Arithmetic domain error"' + *Note Math Functions::. + +`overflow-error' + `"Arithmetic overflow error"' + *Note Math Functions::. + +`range-error' + `"Arithmetic range error"' + *Note Math Functions::. + +`singularity-error' + `"Arithmetic singularity error"' + *Note Math Functions::. + +`underflow-error' + `"Arithmetic underflow error"' + *Note Math Functions::. + + File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top Buffer-Local Variables diff --git a/info/lispref.info-47 b/info/lispref.info-47 index 4f23472..b04ca6b 100644 --- a/info/lispref.info-47 +++ b/info/lispref.info-47 @@ -789,6 +789,7 @@ Index * current-buffer: Current Buffer. * current-case-table: Case Tables. * current-column: Columns. +* current-display-table: Active Display Table. * current-fill-column: Margins. * current-frame-configuration: Frame Configurations. * current-global-map: Active Keymaps. @@ -1639,6 +1640,7 @@ Index * image specifiers: Image Specifiers. * image-instance-background: Image Instance Functions. * image-instance-depth: Image Instance Functions. +* image-instance-domain: Image Instance Functions. * image-instance-file-name: Image Instance Functions. * image-instance-foreground: Image Instance Functions. * image-instance-height: Image Instance Functions. @@ -2023,35 +2025,46 @@ Index * make-backup-file-name: Backup Names. * make-backup-files: Making Backups. * make-bit-vector: Bit Vector Functions. +* make-boolean-specifier: Creating Specifiers. * make-byte-code: Compiled-Function Objects. * make-char: MULE Characters. * make-char-table: Working With Char Tables. * make-charset: Basic Charset Functions. * make-coding-system: Basic Coding System Functions. +* make-color-specifier: Color Specifiers. * make-composite-char: Composite Characters. * make-device: Connecting to a Console or Device. * make-directory: Create/Delete Dirs. * make-display-table: Display Table Format. +* make-display-table-specifier: Creating Specifiers. * make-event: Working With Events. * make-extent: Creating and Modifying Extents. * make-face: Basic Face Functions. +* make-face-boolean-specifier: Color Specifiers. * make-file-part: Creating a Partial File. * make-font-instance: Font Instances. +* make-font-specifier: Font Specifiers. * make-frame: Creating Frames. * make-frame-invisible: Visibility of Frames. * make-frame-visible: Visibility of Frames. +* make-generic-specifier: Creating Specifiers. * make-glyph: Creating Glyphs. * make-glyph-internal: Creating Glyphs. +* make-gutter-size-specifier: Creating Gutter. +* make-gutter-specifier: Creating Gutter. +* make-gutter-visible-specifier: Creating Gutter. * make-hash-table: Introduction to Hash Tables. * make-icon-glyph: Creating Glyphs. * make-image-instance: Image Instance Functions. * make-image-specifier: Image Specifiers. * make-indirect-buffer: Indirect Buffers. +* make-integer-specifier: Creating Specifiers. * make-keymap: Creating Keymaps. * make-list: Building Lists. * make-local-hook: Hooks. * make-local-variable: Creating Buffer-Local. * make-marker: Creating Markers. +* make-natnum-specifier: Creating Specifiers. * make-obsolete: Obsoleteness. * make-obsolete-variable: Obsoleteness. * make-pointer-glyph: Creating Glyphs. @@ -2065,6 +2078,7 @@ Index * make-symbolic-link: Changing File Attributes. * make-syntax-table: Syntax Table Functions. * make-temp-name: Unique File Names. +* make-toolbar-specifier: Creating Toolbar. * make-tooltalk-message: Elisp Interface for Sending Messages. * make-tooltalk-pattern: Elisp Interface for Receiving Messages. * make-tty-device: Connecting to a Console or Device. @@ -3359,6 +3373,7 @@ Index * whitespace character: Syntax Class Table. * widen: Narrowing. * widening: Narrowing. +* widget-image-instance-p: Image Instance Types. * window: Basic Windows. * window configuration (Edebug): Edebug Display Update. * window configurations: Window Configurations. diff --git a/info/xemacs.info-10 b/info/xemacs.info-10 index f888910..8ee5310 100644 --- a/info/xemacs.info-10 +++ b/info/xemacs.info-10 @@ -30,6 +30,116 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode + +TeX Printing Commands +..................... + + You can invoke TeX as an inferior of Emacs on either the entire +contents of the buffer or just a region at a time. Running TeX in this +way on just one chapter is a good way to see what your changes look +like without taking the time to format the entire file. + +`C-c C-r' + Invoke TeX on the current region, plus the buffer's header + (`tex-region'). + +`C-c C-b' + Invoke TeX on the entire current buffer (`tex-buffer'). + +`C-c C-l' + Recenter the window showing output from the inferior TeX so that + the last line can be seen (`tex-recenter-output-buffer'). + +`C-c C-k' + Kill the inferior TeX (`tex-kill-job'). + +`C-c C-p' + Print the output from the last `C-c C-r' or `C-c C-b' command + (`tex-print'). + +`C-c C-q' + Show the printer queue (`tex-show-print-queue'). + + You can pass the current buffer through an inferior TeX using `C-c +C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp'; +to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q' +(`tex-show-print-queue') to view the progress of your output towards +being printed. + + The console output from TeX, including any error messages, appears +in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch +to this buffer and feed it input (this works as in Shell mode; *note +Interactive Shell::). Without switching to this buffer, you can scroll +it so that its last line is visible by typing `C-c C-l'. + + Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see +that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also +kills any TeX process still running. + + You can pass an arbitrary region through an inferior TeX by typing +`C-c C-r' (`tex-region'). This is tricky, however, because most files +of TeX input contain commands at the beginning to set parameters and +define macros. Without them, no later part of the file will format +correctly. To solve this problem, `C-c C-r' allows you to designate a +part of the file as containing essential commands; it is included +before the specified region as part of the input to TeX. The +designated part of the file is called the "header". + + To indicate the bounds of the header in Plain TeX mode, insert two +special strings in the file: `%**start of header' before the header, +and `%**end of header' after it. Each string must appear entirely on +one line, but there may be other text on the line before or after. The +lines containing the two strings are included in the header. If +`%**start of header' does not appear within the first 100 lines of the +buffer, `C-c C-r' assumes there is no header. + + In LaTeX mode, the header begins with `\documentstyle' and ends with +`\begin{document}'. These are commands that LaTeX requires you to use, +so you don't need to do anything special to identify the header. + + When you enter either kind of TeX mode, Emacs calls with no +arguments the value of the variable `text-mode-hook', if that value +exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook' +and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same +conditions. + + +File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode + +Outline Mode +------------ + + Outline mode is a major mode similar to Text mode but intended for +editing outlines. It allows you to make parts of the text temporarily +invisible so that you can see just the overall structure of the +outline. Type `M-x outline-mode' to turn on Outline mode in the +current buffer. + + When you enter Outline mode, Emacs calls with no arguments the value +of the variable `text-mode-hook', if that value exists and is not +`nil'; then it does the same with the variable `outline-mode-hook'. + + When a line is invisible in outline mode, it does not appear on the +screen. The screen appears exactly as if the invisible line were +deleted, except that an ellipsis (three periods in a row) appears at +the end of the previous visible line (only one ellipsis no matter how +many invisible lines follow). + + All editing commands treat the text of the invisible line as part of +the previous visible line. For example, `C-n' moves onto the next +visible line. Killing an entire visible line, including its +terminating newline, really kills all the following invisible lines as +well; yanking everything back yanks the invisible lines and they remain +invisible. + +* Menu: + +* Format: Outline Format. What the text of an outline looks like. +* Motion: Outline Motion. Special commands for moving through outlines. +* Visibility: Outline Visibility. Commands to control what is visible. + + File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode Format of Outlines @@ -1075,77 +1185,3 @@ in C mode. mark. The command `C-M-\' (`indent-region') applies to every line whose first character is between point and mark. - -File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding - -Customizing Lisp Indentation ----------------------------- - - The indentation pattern for a Lisp expression can depend on the -function called by the expression. For each Lisp function, you can -choose among several predefined patterns of indentation, or define an -arbitrary one with a Lisp program. - - The standard pattern of indentation is as follows: the second line -of the expression is indented under the first argument, if that is on -the same line as the beginning of the expression; otherwise, the second -line is indented underneath the function name. Each following line is -indented under the previous line whose nesting depth is the same. - - If the variable `lisp-indent-offset' is non-`nil', it overrides the -usual indentation pattern for the second line of an expression, so that -such lines are always indented `lisp-indent-offset' more columns than -the containing list. - - Certain functions override the standard pattern. Functions whose -names start with `def' always indent the second line by -`lisp-body-indention' extra columns beyond the open-parenthesis -starting the expression. - - Individual functions can override the standard pattern in various -ways, according to the `lisp-indent-function' property of the function -name. (Note: `lisp-indent-function' was formerly called -`lisp-indent-hook'). There are four possibilities for this property: - -`nil' - This is the same as no property; the standard indentation pattern - is used. - -`defun' - The pattern used for function names that start with `def' is used - for this function also. - -a number, NUMBER - The first NUMBER arguments of the function are "distinguished" - arguments; the rest are considered the "body" of the expression. - A line in the expression is indented according to whether the - first argument on it is distinguished or not. If the argument is - part of the body, the line is indented `lisp-body-indent' more - columns than the open-parenthesis starting the containing - expression. If the argument is distinguished and is either the - first or second argument, it is indented twice that many extra - columns. If the argument is distinguished and not the first or - second argument, the standard pattern is followed for that line. - -a symbol, SYMBOL - SYMBOL should be a function name; that function is called to - calculate the indentation of a line within this expression. The - function receives two arguments: - STATE - The value returned by `parse-partial-sexp' (a Lisp primitive - for indentation and nesting computation) when it parses up to - the beginning of this line. - - POS - The position at which the line being indented begins. - - It should return either a number, which is the number of columns of - indentation for that line, or a list whose first element is such a - number. The difference between returning a number and returning a - list is that a number says that all following lines at the same - nesting level should be indented just like this one; a list says - that following lines might call for different indentations. This - makes a difference when the indentation is computed by `C-M-q'; if - the value is a number, `C-M-q' need not recalculate indentation - for the following lines until the end of the list. - diff --git a/info/xemacs.info-11 b/info/xemacs.info-11 index e6173be..f4416a5 100644 --- a/info/xemacs.info-11 +++ b/info/xemacs.info-11 @@ -30,6 +30,80 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding + +Customizing Lisp Indentation +---------------------------- + + The indentation pattern for a Lisp expression can depend on the +function called by the expression. For each Lisp function, you can +choose among several predefined patterns of indentation, or define an +arbitrary one with a Lisp program. + + The standard pattern of indentation is as follows: the second line +of the expression is indented under the first argument, if that is on +the same line as the beginning of the expression; otherwise, the second +line is indented underneath the function name. Each following line is +indented under the previous line whose nesting depth is the same. + + If the variable `lisp-indent-offset' is non-`nil', it overrides the +usual indentation pattern for the second line of an expression, so that +such lines are always indented `lisp-indent-offset' more columns than +the containing list. + + Certain functions override the standard pattern. Functions whose +names start with `def' always indent the second line by +`lisp-body-indention' extra columns beyond the open-parenthesis +starting the expression. + + Individual functions can override the standard pattern in various +ways, according to the `lisp-indent-function' property of the function +name. (Note: `lisp-indent-function' was formerly called +`lisp-indent-hook'). There are four possibilities for this property: + +`nil' + This is the same as no property; the standard indentation pattern + is used. + +`defun' + The pattern used for function names that start with `def' is used + for this function also. + +a number, NUMBER + The first NUMBER arguments of the function are "distinguished" + arguments; the rest are considered the "body" of the expression. + A line in the expression is indented according to whether the + first argument on it is distinguished or not. If the argument is + part of the body, the line is indented `lisp-body-indent' more + columns than the open-parenthesis starting the containing + expression. If the argument is distinguished and is either the + first or second argument, it is indented twice that many extra + columns. If the argument is distinguished and not the first or + second argument, the standard pattern is followed for that line. + +a symbol, SYMBOL + SYMBOL should be a function name; that function is called to + calculate the indentation of a line within this expression. The + function receives two arguments: + STATE + The value returned by `parse-partial-sexp' (a Lisp primitive + for indentation and nesting computation) when it parses up to + the beginning of this line. + + POS + The position at which the line being indented begins. + + It should return either a number, which is the number of columns of + indentation for that line, or a list whose first element is such a + number. The difference between returning a number and returning a + list is that a number says that all following lines at the same + nesting level should be indented just like this one; a list says + that following lines might call for different indentations. This + makes a difference when the indentation is computed by `C-M-q'; if + the value is a number, `C-M-q' need not recalculate indentation + for the following lines until the end of the list. + + File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding Customizing C Indentation @@ -1120,79 +1194,3 @@ killing it or moving it. Move to beginning of current or previous statement (`fortran- previous-statement'). - -File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran - -Fortran Indentation -------------------- - - Special commands and features are available for indenting Fortran -code. They make sure various syntactic entities (line numbers, comment -line indicators, and continuation line flags) appear in the columns -that are required for standard Fortran. - -* Menu: - -* Commands: ForIndent Commands. Commands for indenting Fortran. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. - - -File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent - -Fortran Indentation Commands -............................ - -`' - Indent the current line (`fortran-indent-line'). - -`M-' - Break the current line and set up a continuation line. - -`C-M-q' - Indent all the lines of the subprogram point is in - (`fortran-indent-subprogram'). - - is redefined by Fortran mode to reindent the current line for -Fortran (`fortran-indent-line'). Line numbers and continuation markers -are indented to their required columns, and the body of the statement -is independently indented, based on its nesting in the program. - - The key `C-M-q' is redefined as `fortran-indent-subprogram', a -command that reindents all the lines of the Fortran subprogram -(function or subroutine) containing point. - - The key `M-' is redefined as `fortran-split-line', a command to -split a line in the appropriate fashion for Fortran. In a non-comment -line, the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - - -File: xemacs.info, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent - -Line Numbers and Continuation -............................. - - If a number is the first non-whitespace in the line, it is assumed -to be a line number and is moved to columns 0 through 4. (Columns are -always counted from 0 in XEmacs.) If the text on the line starts with -the conventional Fortran continuation marker `$', it is moved to column -5. If the text begins with any non whitespace character in column 5, -it is assumed to be an unconventional continuation marker and remains -in column 5. - - Line numbers of four digits or less are normally indented one space. -This amount is controlled by the variable `fortran-line-number-indent', -which is the maximum indentation a line number can have. Line numbers -are indented to right-justify them to end in column 4 unless that would -require more than the maximum indentation. The default value of the -variable is 1. - - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -`fortran-electric-line-number' to `nil'. Then inserting line numbers -is like inserting anything else. - diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index 644ad3c..7fb18f7 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -30,6 +30,82 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran + +Fortran Indentation +------------------- + + Special commands and features are available for indenting Fortran +code. They make sure various syntactic entities (line numbers, comment +line indicators, and continuation line flags) appear in the columns +that are required for standard Fortran. + +* Menu: + +* Commands: ForIndent Commands. Commands for indenting Fortran. +* Numbers: ForIndent Num. How line numbers auto-indent. +* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. +* Vars: ForIndent Vars. Variables controlling Fortran indent style. + + +File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent + +Fortran Indentation Commands +............................ + +`' + Indent the current line (`fortran-indent-line'). + +`M-' + Break the current line and set up a continuation line. + +`C-M-q' + Indent all the lines of the subprogram point is in + (`fortran-indent-subprogram'). + + is redefined by Fortran mode to reindent the current line for +Fortran (`fortran-indent-line'). Line numbers and continuation markers +are indented to their required columns, and the body of the statement +is independently indented, based on its nesting in the program. + + The key `C-M-q' is redefined as `fortran-indent-subprogram', a +command that reindents all the lines of the Fortran subprogram +(function or subroutine) containing point. + + The key `M-' is redefined as `fortran-split-line', a command to +split a line in the appropriate fashion for Fortran. In a non-comment +line, the second half becomes a continuation line and is indented +accordingly. In a comment line, both halves become separate comment +lines. + + +File: xemacs.info, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent + +Line Numbers and Continuation +............................. + + If a number is the first non-whitespace in the line, it is assumed +to be a line number and is moved to columns 0 through 4. (Columns are +always counted from 0 in XEmacs.) If the text on the line starts with +the conventional Fortran continuation marker `$', it is moved to column +5. If the text begins with any non whitespace character in column 5, +it is assumed to be an unconventional continuation marker and remains +in column 5. + + Line numbers of four digits or less are normally indented one space. +This amount is controlled by the variable `fortran-line-number-indent', +which is the maximum indentation a line number can have. Line numbers +are indented to right-justify them to end in column 4 unless that would +require more than the maximum indentation. The default value of the +variable is 1. + + Simply inserting a line number is enough to indent it according to +these rules. As each digit is inserted, the indentation is recomputed. +To turn off this feature, set the variable +`fortran-electric-line-number' to `nil'. Then inserting line numbers +is like inserting anything else. + + File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent Syntactic Conventions @@ -917,242 +993,3 @@ appropriate in regular packages) source code plus all of the files necessary to build distribution tarballs (Unix Tar format files, gzipped for space savings). - -File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages - -Getting Started ---------------- - - When you first download XEmacs 21, you will usually first grab the -"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the -21.0 by the current version number.) The core distribution contains -the sources of XEmacs and a minimal set of Emacs Lisp files, which are -in the subdirectory named `lisp'. This subdirectory used to contain -all Emacs Lisp files distributed with XEmacs. Now, to conserve disk -space, most non-essential packages were made optional. - -Choosing the Packages You Need ------------------------------- - - The available packages can currently be found in the same ftp -directory where you grabbed the core distribution from, and are located -in the subdirectory `packages/binary-packages'. Package file names -follow the naming convention `--pkg.tar.gz'. - - If you have EFS *Note (EFS)::, packages can be installed over the -network. Alternatively, if you have copies of the packages locally, -you can install packages from a local disk or CDROM. - - The file `etc/PACKAGES' in the core distribution contains a list of -the packages available at the time of the XEmacs release. Packages are -also listed on the `Options' menu under: - - Options->Customize->Emacs->Packages - - However, don't select any of these menu picks unless you actually -want to install the given package (and have properly configured your -system to do so). - - You can also get a list of available packages, and whether or not -they are installed, using the visual package browser and installer. -You can access it via the menus: - - Options->Manage Packages->List & Install - - Or, you can get to it via the keyboard: - - M-x pui-list-packages - - Hint to system administrators of multi-user systems: it might be a -good idea to install all packages and not interfere with the wishes of -your users. - - If you can't find which package provides the feature you require, try -using the `package-get-package-provider' function. Eg., if you know -that you need `thingatpt', type: - - M-x package-get-package-provider RET thingatpt - - which will return something like (fsf-compat "1.06"). You can the use -one of the methods above for installing the package you want. - -XEmacs and Installing Packages ------------------------------- - - Normally, packages are installed over the network, using EFS *Note -(EFS)::. However, you may not have network access, or you may already -have some or all of the packages on a local disk, such as a CDROM. If -you want to install from a local disk, you must first tell XEmacs where -to find the package binaries. This is done by adding a line like the -following to your `.emacs' file: - - (setq package-get-remote (cons (list nil "/my/path/to/package/binaries") - package-get-remote)) - - Here, you'd change `/my/path/to/package/binaries' to be the path to -your local package binaries. Next, restart XEmacs, and you're ready to -go (advanced users can just re-evaluate the sexp). - - If you are installing from a temporary, one-time directory, you can -also add these directory names to `package-get-remote' using: - - M-x pui-add-install-directory - - Note, however, that any directories added using this function are not -saved; this information will be lost when you quit XEmacs. - - If you're going to install over the network, you only have to insure -that EFS *Note (EFS):: works, and that it can get outside a firewall, if -you happen to be behind one. You shouldn't have to do anything else; -XEmacs already knows where to go. However you can add your own mirrors -to this list. See `package-get-remote'. - - The easiest way to install a package is to use the visual package -browser and installer, using the menu pick: - - Options->Manage Packages->List & Install - or - Options->Manage Packages->Using Custom->Select-> ... - - You can also access it using the keyboard: - - M-x pui-list-packages - - The visual package browser will then display a list of all packages. -Help information will be displayed at the very bottom of the buffer; you -may have to scroll down to see it. You can also press `?' to get the -same help. From this buffer, you can tell the package status by the -character in the first column: - -`-' - The package has not been installed. - -`*' - The package has been installed, but a newer version is available. - The current version is out-of-date. - -`+' - The package has been marked for installation/update. - - If there is no character in the first column, the package has been -installed and is up-to-date. - - From here, you can select or unselect packages for installation using -the key, the `Mouse-2' button or selecting "Select" from the -(Popup) Menu. Once you've finished selecting the packages, you can -press the `x' key (or use the menu) to actually install the packages. -Note that you will have to restart XEmacs for XEmacs to recognize any -new packages. - - Key summary: - -`?' - Display simple help. - -`' -`' - Toggle between selecting and unselecting a package for - installation. - -`x' - Install selected packages. - -`' - View, in the minibuffer, additional information about the package, - such as the package date (not the build date) and the package - author. Moving the mouse over a package name will also do the - same thing. - -`v' - Toggle between verbose and non-verbose package display. - -`g' - Refresh the package display. - -`q' - Kill the package buffer. - - Moving the mouse over a package will also cause additional -information about the package to be displayed in the minibuffer. - -Other package installation interfaces -------------------------------------- - - For an alternative package interface, you can select packages from -the customize menus, under: - - Options->Customize->Emacs->Packages-> ... - or - Options->Manage Packages->Using Custom->Select-> ... - - Set their state to on, and then do: - - Options->Manage Packages->Using Custom->Update Packages - - This will automatically retrieve the packages you have selected from -the XEmacs ftp site or your local disk, and install them into XEmacs. -Additionally it will update any packages you already have installed to -the newest version. Note that if a package is newly installed you will -have to restart XEmacs for the change to take effect. - - You can also install packages using a semi-manual interface: - - M-x package-get-all - - Enter the name of the package (e.g., `prog-modes'), and XEmacs will -search for the latest version (as listed in the lisp file -`lisp/package-get-base.el'), and install it and any packages that it -depends upon. - -Manual Binary Package Installation ----------------------------------- - - Pre-compiled, binary packages can be installed in either a system -package directory (this is determined when XEmacs is compiled), or in -one of the following subdirectories of your `$HOME' directory: - - ~/.xemacs/mule-packages - ~/.xemacs/xemacs-packages - - Packages in the former directory will only be found by a Mule-enabled -XEmacs. - - XEmacs does not have to be running to install binary packages, -although XEmacs will not know about any newly-installed packages until -you restart XEmacs. Note, however, that installing a newer version of a -package while XEmacs is running could cause strange errors in XEmacs; -it's best to exit XEmacs before upgrading an existing package. - - To install binary packages manually: - - 1. Download the package(s) that you want to install. Each binary - package will typically be a gzip'd tarball. - - 2. Decide where to install the packages: in the system package - directory, or in `~/.xemacs/mule-packages' or - `~/.xemacs/xemacs-packages', respectively. If you want to install - the packages in the system package directory, make sure you can - write into that directory. If you want to install in your `$HOME' - directory, create the directory, `~/.xemacs/mule-packages' or - `~/.xemacs/xemacs-packages', respectively. - - 3. Next, `cd' to the directory under which you want to install the - package(s). - - 4. From this directory, uncompress and extract each of the gzip'd - tarballs that you downloaded in step 1. Unix and Cygnus cygwin - users will typically do this using the commands: - - gunzip < package.tar.gz | tar xvf - - - Above, replace `package.tar.gz' with the filename of the package - that you downloaded in step 1. - - Of course, if you use GNU `tar', you could also use: - - tar xvzf package.tar.gz - - 5. That's it. Quit and restart XEmacs to get it to recognize any new - or changed packages. - - diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index 11cb619..2430a9e 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -30,6 +30,245 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages + +Getting Started +--------------- + + When you first download XEmacs 21, you will usually first grab the +"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the +21.0 by the current version number.) The core distribution contains +the sources of XEmacs and a minimal set of Emacs Lisp files, which are +in the subdirectory named `lisp'. This subdirectory used to contain +all Emacs Lisp files distributed with XEmacs. Now, to conserve disk +space, most non-essential packages were made optional. + +Choosing the Packages You Need +------------------------------ + + The available packages can currently be found in the same ftp +directory where you grabbed the core distribution from, and are located +in the subdirectory `packages/binary-packages'. Package file names +follow the naming convention `--pkg.tar.gz'. + + If you have EFS *Note (EFS)::, packages can be installed over the +network. Alternatively, if you have copies of the packages locally, +you can install packages from a local disk or CDROM. + + The file `etc/PACKAGES' in the core distribution contains a list of +the packages available at the time of the XEmacs release. Packages are +also listed on the `Options' menu under: + + Options->Customize->Emacs->Packages + + However, don't select any of these menu picks unless you actually +want to install the given package (and have properly configured your +system to do so). + + You can also get a list of available packages, and whether or not +they are installed, using the visual package browser and installer. +You can access it via the menus: + + Options->Manage Packages->List & Install + + Or, you can get to it via the keyboard: + + M-x pui-list-packages + + Hint to system administrators of multi-user systems: it might be a +good idea to install all packages and not interfere with the wishes of +your users. + + If you can't find which package provides the feature you require, try +using the `package-get-package-provider' function. Eg., if you know +that you need `thingatpt', type: + + M-x package-get-package-provider RET thingatpt + + which will return something like (fsf-compat "1.06"). You can the use +one of the methods above for installing the package you want. + +XEmacs and Installing Packages +------------------------------ + + Normally, packages are installed over the network, using EFS *Note +(EFS)::. However, you may not have network access, or you may already +have some or all of the packages on a local disk, such as a CDROM. If +you want to install from a local disk, you must first tell XEmacs where +to find the package binaries. This is done by adding a line like the +following to your `.emacs' file: + + (setq package-get-remote (cons (list nil "/my/path/to/package/binaries") + package-get-remote)) + + Here, you'd change `/my/path/to/package/binaries' to be the path to +your local package binaries. Next, restart XEmacs, and you're ready to +go (advanced users can just re-evaluate the sexp). + + If you are installing from a temporary, one-time directory, you can +also add these directory names to `package-get-remote' using: + + M-x pui-add-install-directory + + Note, however, that any directories added using this function are not +saved; this information will be lost when you quit XEmacs. + + If you're going to install over the network, you only have to insure +that EFS *Note (EFS):: works, and that it can get outside a firewall, if +you happen to be behind one. You shouldn't have to do anything else; +XEmacs already knows where to go. However you can add your own mirrors +to this list. See `package-get-remote'. + + The easiest way to install a package is to use the visual package +browser and installer, using the menu pick: + + Options->Manage Packages->List & Install + or + Options->Manage Packages->Using Custom->Select-> ... + + You can also access it using the keyboard: + + M-x pui-list-packages + + The visual package browser will then display a list of all packages. +Help information will be displayed at the very bottom of the buffer; you +may have to scroll down to see it. You can also press `?' to get the +same help. From this buffer, you can tell the package status by the +character in the first column: + +`-' + The package has not been installed. + +`*' + The package has been installed, but a newer version is available. + The current version is out-of-date. + +`+' + The package has been marked for installation/update. + + If there is no character in the first column, the package has been +installed and is up-to-date. + + From here, you can select or unselect packages for installation using +the key, the `Mouse-2' button or selecting "Select" from the +(Popup) Menu. Once you've finished selecting the packages, you can +press the `x' key (or use the menu) to actually install the packages. +Note that you will have to restart XEmacs for XEmacs to recognize any +new packages. + + Key summary: + +`?' + Display simple help. + +`' +`' + Toggle between selecting and unselecting a package for + installation. + +`x' + Install selected packages. + +`' + View, in the minibuffer, additional information about the package, + such as the package date (not the build date) and the package + author. Moving the mouse over a package name will also do the + same thing. + +`v' + Toggle between verbose and non-verbose package display. + +`g' + Refresh the package display. + +`q' + Kill the package buffer. + + Moving the mouse over a package will also cause additional +information about the package to be displayed in the minibuffer. + +Other package installation interfaces +------------------------------------- + + For an alternative package interface, you can select packages from +the customize menus, under: + + Options->Customize->Emacs->Packages-> ... + or + Options->Manage Packages->Using Custom->Select-> ... + + Set their state to on, and then do: + + Options->Manage Packages->Using Custom->Update Packages + + This will automatically retrieve the packages you have selected from +the XEmacs ftp site or your local disk, and install them into XEmacs. +Additionally it will update any packages you already have installed to +the newest version. Note that if a package is newly installed you will +have to restart XEmacs for the change to take effect. + + You can also install packages using a semi-manual interface: + + M-x package-get-all + + Enter the name of the package (e.g., `prog-modes'), and XEmacs will +search for the latest version (as listed in the lisp file +`lisp/package-get-base.el'), and install it and any packages that it +depends upon. + +Manual Binary Package Installation +---------------------------------- + + Pre-compiled, binary packages can be installed in either a system +package directory (this is determined when XEmacs is compiled), or in +one of the following subdirectories of your `$HOME' directory: + + ~/.xemacs/mule-packages + ~/.xemacs/xemacs-packages + + Packages in the former directory will only be found by a Mule-enabled +XEmacs. + + XEmacs does not have to be running to install binary packages, +although XEmacs will not know about any newly-installed packages until +you restart XEmacs. Note, however, that installing a newer version of a +package while XEmacs is running could cause strange errors in XEmacs; +it's best to exit XEmacs before upgrading an existing package. + + To install binary packages manually: + + 1. Download the package(s) that you want to install. Each binary + package will typically be a gzip'd tarball. + + 2. Decide where to install the packages: in the system package + directory, or in `~/.xemacs/mule-packages' or + `~/.xemacs/xemacs-packages', respectively. If you want to install + the packages in the system package directory, make sure you can + write into that directory. If you want to install in your `$HOME' + directory, create the directory, `~/.xemacs/mule-packages' or + `~/.xemacs/xemacs-packages', respectively. + + 3. Next, `cd' to the directory under which you want to install the + package(s). + + 4. From this directory, uncompress and extract each of the gzip'd + tarballs that you downloaded in step 1. Unix and Cygnus cygwin + users will typically do this using the commands: + + gunzip < package.tar.gz | tar xvf - + + Above, replace `package.tar.gz' with the filename of the package + that you downloaded in step 1. + + Of course, if you use GNU `tar', you could also use: + + tar xvzf package.tar.gz + + 5. That's it. Quit and restart XEmacs to get it to recognize any new + or changed packages. + + + File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages Source packages are available from the `packages/source-packages' @@ -990,240 +1229,3 @@ diary. * Diary:: Displaying events from your diary. * Calendar Customization:: Altering the behavior of the features above. - -File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary - -Movement in the Calendar ------------------------- - - Calendar mode lets you move through the calendar in logical units of -time such as days, weeks, months, and years. If you move outside the -three months originally displayed, the calendar display "scrolls" -automatically through time to make the selected date visible. Moving to -a date lets you view its holidays or diary entries, or convert it to -other calendars; moving longer time periods is also useful simply to -scroll the calendar. - -* Menu: - -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. - - -File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion - -Motion by Integral Days, Weeks, Months, Years -............................................. - - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. - -`C-f' - Move point one day forward (`calendar-forward-day'). - -`C-b' - Move point one day backward (`calendar-backward-day'). - -`C-n' - Move point one week forward (`calendar-forward-week'). - -`C-p' - Move point one week backward (`calendar-backward-week'). - -`M-}' - Move point one month forward (`calendar-forward-month'). - -`M-{' - Move point one month backward (`calendar-backward-month'). - -`C-x ]' - Move point one year forward (`calendar-forward-year'). - -`C-x [' - Move point one year backward (`calendar-backward-year'). - - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as `C-n' usually -moves to the same column in the following line, in Calendar mode it -moves to the same day in the following week. And `C-p' moves to the -same day in the previous week. - - The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just -as they normally are in other modes. - - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands `M-}' and `M-{' -move forward or backward by an entire month's time. The year commands -`C-x ]' and `C-x [' move forward or backward a whole year. - - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But the -commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, whereas -these month and year commands move by an entire month or an entire -year, which usually involves skipping across the end of a month or year. - - All these commands accept a numeric argument as a repeat count. For -convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -`100 C-f' moves point 100 days forward from its present location. - - -File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion - -Beginning or End of Week, Month or Year -....................................... - - A week (or month, or year) is not just a quantity of days; we think -of weeks (months, years) as starting on particular dates. So Calendar -mode provides commands to move to the beginning or end of a week, month -or year: - -`C-a' - Move point to start of week (`calendar-beginning-of-week'). - -`C-e' - Move point to end of week (`calendar-end-of-week'). - -`M-a' - Move point to start of month (`calendar-beginning-of-month'). - -`M-e' - Move point to end of month (`calendar-end-of-month'). - -`M-<' - Move point to start of year (`calendar-beginning-of-year'). - -`M->' - Move point to end of year (`calendar-end-of-year'). - - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. - - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable `calendar-week-start-day' to 1. - - -File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion - -Particular Dates -................ - - Calendar mode provides commands for moving to a particular date -specified in various ways. - -`g d' - Move point to specified date (`calendar-goto-date'). - -`o' - Center calendar around specified month (`calendar-other-month'). - -`.' - Move point to today's date (`calendar-goto-today'). - - `g d' (`calendar-goto-date') prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar -includes all dates from the beginning of the current era, you must type -the year in its entirety; that is, type `1990', not `90'. - - `o' (`calendar-other-month') prompts for a month and year, then -centers the three-month calendar around that month. - - You can return to today's date with `.' (`calendar-goto-today'). - - -File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary - -Scrolling the Calendar through Time ------------------------------------ - - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling it means moving the strip so that new -months become visible in the window. - -`C-x <' - Scroll calendar one month forward (`scroll-calendar-left'). - -`C-x >' - Scroll calendar one month backward (`scroll-calendar-right'). - -`C-v' -`' - Scroll calendar three months forward - (`scroll-calendar-left-three-months'). - -`M-v' -`' - Scroll calendar three months backward - (`scroll-calendar-right-three-months'). - - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. `C-x <' scrolls the -calendar contents one month to the left; that is, it moves the display -forward in time. `C-x >' scrolls the contents to the right, which -moves backwards in time. - - The commands `C-v' and `M-v' scroll the calendar by an entire -"screenful"--three months--in analogy with the usual meaning of these -commands. `C-v' makes later dates visible and `M-v' makes earlier -dates visible. These commands take a numeric argument as a repeat -count; in particular, since `C-u' multiplies the next command by four, -typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u -M-v' scrolls the calendar backward by a year. - - The function keys and are equivalent to `C-v' and -`M-v', just as they are in other modes. - - -File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary - -The Mark and the Region ------------------------ - - The concept of the mark applies to the calendar just as to any other -buffer, but it marks a _date_, not a _position_ in the buffer. The -region consists of the days between the mark and point (including the -starting and stopping dates). - -`C-SPC' - Set the mark to today's date (`calendar-set-mark'). - -`C-@' - The same. - -`C-x C-x' - Interchange mark and point (`calendar-exchange-point-and-mark'). - -`M-=' - Display the number of days in the current region - (`calendar-count-days-region'). - - You set the mark in the calendar, as in any other buffer, by using -`C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date -with the command `C-x C-x' (`calendar-exchange-point-and-mark') which -puts the mark where point was and point where mark was. The calendar -is scrolled as necessary, if the marked date was not visible on the -screen. This does not change the extent of the region. - - To determine the number of days in the region, type `M-=' -(`calendar-count-days-region'). The numbers of days printed is -_inclusive_; that is, it includes the days specified by mark and point. - - The main use of the mark in the calendar is to remember dates that -you may want to go back to. To make this feature more useful, the mark -ring (*note Mark Ring::) operates exactly as in other buffers: Emacs -remembers 16 previous locations of the mark. To return to a marked -date, type `C-u C-SPC' (or `C-u C-@'); this is the command -`calendar-set-mark' given a numeric argument. It moves point to where -the mark was, restores the mark from the ring of former marks, and -stores the previous point at the end of the mark ring. So, repeated -use of this command moves point through all the old marks on the ring, -one by one. - diff --git a/info/xemacs.info-14 b/info/xemacs.info-14 index 828a37c..447d49b 100644 --- a/info/xemacs.info-14 +++ b/info/xemacs.info-14 @@ -30,6 +30,243 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary + +Movement in the Calendar +------------------------ + + Calendar mode lets you move through the calendar in logical units of +time such as days, weeks, months, and years. If you move outside the +three months originally displayed, the calendar display "scrolls" +automatically through time to make the selected date visible. Moving to +a date lets you view its holidays or diary entries, or convert it to +other calendars; moving longer time periods is also useful simply to +scroll the calendar. + +* Menu: + +* Calendar Unit Motion:: Moving by days, weeks, months, and years. +* Move to Beginning or End:: Moving to start/end of weeks, months, and years. +* Specified Dates:: Moving to the current date or another + specific date. + + +File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion + +Motion by Integral Days, Weeks, Months, Years +............................................. + + The commands for movement in the calendar buffer parallel the +commands for movement in text. You can move forward and backward by +days, weeks, months, and years. + +`C-f' + Move point one day forward (`calendar-forward-day'). + +`C-b' + Move point one day backward (`calendar-backward-day'). + +`C-n' + Move point one week forward (`calendar-forward-week'). + +`C-p' + Move point one week backward (`calendar-backward-week'). + +`M-}' + Move point one month forward (`calendar-forward-month'). + +`M-{' + Move point one month backward (`calendar-backward-month'). + +`C-x ]' + Move point one year forward (`calendar-forward-year'). + +`C-x [' + Move point one year backward (`calendar-backward-year'). + + The day and week commands are natural analogues of the usual Emacs +commands for moving by characters and by lines. Just as `C-n' usually +moves to the same column in the following line, in Calendar mode it +moves to the same day in the following week. And `C-p' moves to the +same day in the previous week. + + The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just +as they normally are in other modes. + + The commands for motion by months and years work like those for +weeks, but move a larger distance. The month commands `M-}' and `M-{' +move forward or backward by an entire month's time. The year commands +`C-x ]' and `C-x [' move forward or backward a whole year. + + The easiest way to remember these commands is to consider months and +years analogous to paragraphs and pages of text, respectively. But the +commands themselves are not quite analogous. The ordinary Emacs +paragraph commands move to the beginning or end of a paragraph, whereas +these month and year commands move by an entire month or an entire +year, which usually involves skipping across the end of a month or year. + + All these commands accept a numeric argument as a repeat count. For +convenience, the digit keys and the minus sign specify numeric +arguments in Calendar mode even without the Meta modifier. For example, +`100 C-f' moves point 100 days forward from its present location. + + +File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion + +Beginning or End of Week, Month or Year +....................................... + + A week (or month, or year) is not just a quantity of days; we think +of weeks (months, years) as starting on particular dates. So Calendar +mode provides commands to move to the beginning or end of a week, month +or year: + +`C-a' + Move point to start of week (`calendar-beginning-of-week'). + +`C-e' + Move point to end of week (`calendar-end-of-week'). + +`M-a' + Move point to start of month (`calendar-beginning-of-month'). + +`M-e' + Move point to end of month (`calendar-end-of-month'). + +`M-<' + Move point to start of year (`calendar-beginning-of-year'). + +`M->' + Move point to end of year (`calendar-end-of-year'). + + These commands also take numeric arguments as repeat counts, with the +repeat count indicating how many weeks, months, or years to move +backward or forward. + + By default, weeks begin on Sunday. To make them begin on Monday +instead, set the variable `calendar-week-start-day' to 1. + + +File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion + +Particular Dates +................ + + Calendar mode provides commands for moving to a particular date +specified in various ways. + +`g d' + Move point to specified date (`calendar-goto-date'). + +`o' + Center calendar around specified month (`calendar-other-month'). + +`.' + Move point to today's date (`calendar-goto-today'). + + `g d' (`calendar-goto-date') prompts for a year, a month, and a day +of the month, and then moves to that date. Because the calendar +includes all dates from the beginning of the current era, you must type +the year in its entirety; that is, type `1990', not `90'. + + `o' (`calendar-other-month') prompts for a month and year, then +centers the three-month calendar around that month. + + You can return to today's date with `.' (`calendar-goto-today'). + + +File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary + +Scrolling the Calendar through Time +----------------------------------- + + The calendar display scrolls automatically through time when you +move out of the visible portion. You can also scroll it manually. +Imagine that the calendar window contains a long strip of paper with +the months on it. Scrolling it means moving the strip so that new +months become visible in the window. + +`C-x <' + Scroll calendar one month forward (`scroll-calendar-left'). + +`C-x >' + Scroll calendar one month backward (`scroll-calendar-right'). + +`C-v' +`' + Scroll calendar three months forward + (`scroll-calendar-left-three-months'). + +`M-v' +`' + Scroll calendar three months backward + (`scroll-calendar-right-three-months'). + + The most basic calendar scroll commands scroll by one month at a +time. This means that there are two months of overlap between the +display before the command and the display after. `C-x <' scrolls the +calendar contents one month to the left; that is, it moves the display +forward in time. `C-x >' scrolls the contents to the right, which +moves backwards in time. + + The commands `C-v' and `M-v' scroll the calendar by an entire +"screenful"--three months--in analogy with the usual meaning of these +commands. `C-v' makes later dates visible and `M-v' makes earlier +dates visible. These commands take a numeric argument as a repeat +count; in particular, since `C-u' multiplies the next command by four, +typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u +M-v' scrolls the calendar backward by a year. + + The function keys and are equivalent to `C-v' and +`M-v', just as they are in other modes. + + +File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary + +The Mark and the Region +----------------------- + + The concept of the mark applies to the calendar just as to any other +buffer, but it marks a _date_, not a _position_ in the buffer. The +region consists of the days between the mark and point (including the +starting and stopping dates). + +`C-SPC' + Set the mark to today's date (`calendar-set-mark'). + +`C-@' + The same. + +`C-x C-x' + Interchange mark and point (`calendar-exchange-point-and-mark'). + +`M-=' + Display the number of days in the current region + (`calendar-count-days-region'). + + You set the mark in the calendar, as in any other buffer, by using +`C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date +with the command `C-x C-x' (`calendar-exchange-point-and-mark') which +puts the mark where point was and point where mark was. The calendar +is scrolled as necessary, if the marked date was not visible on the +screen. This does not change the extent of the region. + + To determine the number of days in the region, type `M-=' +(`calendar-count-days-region'). The numbers of days printed is +_inclusive_; that is, it includes the days specified by mark and point. + + The main use of the mark in the calendar is to remember dates that +you may want to go back to. To make this feature more useful, the mark +ring (*note Mark Ring::) operates exactly as in other buffers: Emacs +remembers 16 previous locations of the mark. To return to a marked +date, type `C-u C-SPC' (or `C-u C-@'); this is the command +`calendar-set-mark' given a numeric argument. It moves point to where +the mark was, restores the mark from the ring of former marks, and +stores the previous point at the end of the mark ring. So, repeated +use of this command moves point through all the old marks on the ring, +one by one. + + File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary Miscellaneous Calendar Commands @@ -1027,100 +1264,3 @@ gives the Gregorian date for which the diary entries are being found. If the value of the sexp is `t', the entry applies to that date. If the sexp evaluates to `nil', the entry does _not_ apply to that date. - -File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary - -Customizing the Calendar and Diary ----------------------------------- - - There are many customizations that you can use to make the calendar -and diary suit your personal tastes. - -* Menu: - -* Calendar Customizing:: Defaults you can set. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Daylight Savings:: Changing the default. -* Diary Customizing:: Defaults you can set. -* Hebrew/Islamic Entries:: How to obtain them. -* Fancy Diary Display:: Enhancing the diary display, sorting entries. -* Included Diary Files:: Sharing a common diary file. -* Sexp Diary Entries:: Fancy things you can do. -* Appt Customizing:: Customizing appointment reminders. - - -File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization - -Customizing the Calendar -........................ - - If you set the variable `view-diary-entries-initially' to `t', -calling up the calendar automatically displays the diary entries for -the current date as well. The diary dates appear only if the current -date is visible. If you add both of the following lines to your -`.emacs' file: - - (setq view-diary-entries-initially t) - (calendar) - -this displays both the calendar and diary windows whenever you start -Emacs. - - Similarly, if you set the variable -`view-calendar-holidays-initially' to `t', entering the calendar -automatically displays a list of holidays for the current three-month -period. The holiday list appears in a separate window. - - You can set the variable `mark-diary-entries-in-calendar' to `t' in -order to mark any dates with diary entries. This takes effect whenever -the calendar window contents are recomputed. There are two ways of -marking these dates: by changing the face (*note Faces::), if the -display supports that, or by placing a plus sign (`+') beside the date -otherwise. - - Similarly, setting the variable `mark-holidays-in-calendar' to `t' -marks holiday dates, either with a change of face or with an asterisk -(`*'). - - The variable `calendar-holiday-marker' specifies how to mark a date -as being a holiday. Its value may be a character to insert next to the -date, or a face name to use for displaying the date. Likewise, the -variable `diary-entry-marker' specifies how to mark a date that has -diary entries. The calendar creates faces named `holiday-face' and -`diary-face' for these purposes; those symbols are the default values -of these variables, when Emacs supports multiple faces on your terminal. - - The variable `calendar-load-hook' is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - - Starting the calendar runs the normal hook -`initial-calendar-window-hook'. Recomputation of the calendar display -does not run this hook. But if you leave the calendar with the `q' -command and reenter it, the hook runs again. - - The variable `today-visible-calendar-hook' is a normal hook run -after the calendar buffer has been prepared with the calendar when the -current date is visible in the window. One use of this hook is to -replace today's date with asterisks; to do that, use the hook function -`calendar-star-date'. - - (add-hook 'today-visible-calendar-hook 'calendar-star-date) - -Another standard hook function marks the current date, either by -changing its face or by adding an asterisk. Here's how to use it: - - (add-hook 'today-visible-calendar-hook 'calendar-mark-today) - -The variable `calendar-today-marker' specifies how to mark today's -date. Its value should be a character to insert next to the date or a -face name to use for displaying the date. A face named -`calendar-today-face' is provided for this purpose; that symbol is the -default for this variable when Emacs supports multiple faces on your -terminal. - -A similar normal hook, `today-invisible-calendar-hook' is run if the -current date is _not_ visible in the window. - diff --git a/info/xemacs.info-15 b/info/xemacs.info-15 index cb56172..d9656f6 100644 --- a/info/xemacs.info-15 +++ b/info/xemacs.info-15 @@ -30,6 +30,103 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary + +Customizing the Calendar and Diary +---------------------------------- + + There are many customizations that you can use to make the calendar +and diary suit your personal tastes. + +* Menu: + +* Calendar Customizing:: Defaults you can set. +* Holiday Customizing:: Defining your own holidays. +* Date Display Format:: Changing the format. +* Time Display Format:: Changing the format. +* Daylight Savings:: Changing the default. +* Diary Customizing:: Defaults you can set. +* Hebrew/Islamic Entries:: How to obtain them. +* Fancy Diary Display:: Enhancing the diary display, sorting entries. +* Included Diary Files:: Sharing a common diary file. +* Sexp Diary Entries:: Fancy things you can do. +* Appt Customizing:: Customizing appointment reminders. + + +File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization + +Customizing the Calendar +........................ + + If you set the variable `view-diary-entries-initially' to `t', +calling up the calendar automatically displays the diary entries for +the current date as well. The diary dates appear only if the current +date is visible. If you add both of the following lines to your +`.emacs' file: + + (setq view-diary-entries-initially t) + (calendar) + +this displays both the calendar and diary windows whenever you start +Emacs. + + Similarly, if you set the variable +`view-calendar-holidays-initially' to `t', entering the calendar +automatically displays a list of holidays for the current three-month +period. The holiday list appears in a separate window. + + You can set the variable `mark-diary-entries-in-calendar' to `t' in +order to mark any dates with diary entries. This takes effect whenever +the calendar window contents are recomputed. There are two ways of +marking these dates: by changing the face (*note Faces::), if the +display supports that, or by placing a plus sign (`+') beside the date +otherwise. + + Similarly, setting the variable `mark-holidays-in-calendar' to `t' +marks holiday dates, either with a change of face or with an asterisk +(`*'). + + The variable `calendar-holiday-marker' specifies how to mark a date +as being a holiday. Its value may be a character to insert next to the +date, or a face name to use for displaying the date. Likewise, the +variable `diary-entry-marker' specifies how to mark a date that has +diary entries. The calendar creates faces named `holiday-face' and +`diary-face' for these purposes; those symbols are the default values +of these variables, when Emacs supports multiple faces on your terminal. + + The variable `calendar-load-hook' is a normal hook run when the +calendar package is first loaded (before actually starting to display +the calendar). + + Starting the calendar runs the normal hook +`initial-calendar-window-hook'. Recomputation of the calendar display +does not run this hook. But if you leave the calendar with the `q' +command and reenter it, the hook runs again. + + The variable `today-visible-calendar-hook' is a normal hook run +after the calendar buffer has been prepared with the calendar when the +current date is visible in the window. One use of this hook is to +replace today's date with asterisks; to do that, use the hook function +`calendar-star-date'. + + (add-hook 'today-visible-calendar-hook 'calendar-star-date) + +Another standard hook function marks the current date, either by +changing its face or by adding an asterisk. Here's how to use it: + + (add-hook 'today-visible-calendar-hook 'calendar-mark-today) + +The variable `calendar-today-marker' specifies how to mark today's +date. Its value should be a character to insert next to the date or a +face name to use for displaying the date. A face named +`calendar-today-face' is provided for this purpose; that symbol is the +default for this variable when Emacs supports multiple faces on your +terminal. + +A similar normal hook, `today-invisible-calendar-hook' is run if the +current date is _not_ visible in the window. + + File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization Customizing the Holidays @@ -1107,97 +1204,3 @@ the Term escape character, normally `C-c'. For example, `C-c C-x o' invokes the global binding of `C-x o', which is normally `other-window'. - -File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell - -Paging in the terminal emulator -------------------------------- - - Term mode has a pager feature. When the pager is enabled, term mode -will pause at the end of each screenful. - -`C-c C-q' - Toggles the pager feature: Disables the pager if it is enabled, - and vice versa. This works in both line and char modes. If the - pager enabled, the mode-line contains the word `page'. - - If the pager is enabled, and Term receives more than a screenful of -output since your last input, Term will enter More break mode. This is -indicated by `**MORE**' in the mode-line. Type a `Space' to display -the next screenful of output. Type `?' to see your other options. The -interface is similar to the Unix `more' program. - - -File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top - -Narrowing -========= - - "Narrowing" means focusing in on some portion of the buffer, making -the rest temporarily invisible and inaccessible. Cancelling the -narrowing and making the entire buffer once again visible is called -"widening". The amount of narrowing in effect in a buffer at any time -is called the buffer's "restriction". - -`C-x n n' - Narrow down to between point and mark (`narrow-to-region'). - -`C-x n w' - Widen to make the entire buffer visible again (`widen'). - - Narrowing sometimes makes it easier to concentrate on a single -subroutine or paragraph by eliminating clutter. It can also be used to -restrict the range of operation of a replace command or repeating -keyboard macro. The word `Narrow' appears in the mode line whenever -narrowing is in effect. When you have narrowed to a part of the -buffer, that part appears to be all there is. You can't see the rest, -can't move into it (motion commands won't go outside the visible part), -and can't change it in any way. However, the invisible text is not -gone; if you save the file, it will be saved. - - The primary narrowing command is `C-x n n' (`narrow-to-region'). It -sets the current buffer's restrictions so that the text in the current -region remains visible but all text before the region or after the -region is invisible. Point and mark do not change. - - Because narrowing can easily confuse users who do not understand it, -`narrow-to-region' is normally a disabled command. Attempting to use -this command asks for confirmation and gives you the option of enabling -it; once you enable the command, confirmation will no longer be -required. *Note Disabling::. - - To undo narrowing, use `C-x n w' (`widen'). This makes all text in -the buffer accessible again. - - Use the `C-x =' command to get information on what part of the -buffer you narrowed down. *Note Position Info::. - - -File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top - -Hardcopy Output -=============== - - The XEmacs commands for making hardcopy derive their names from the -Unix commands `print' and `lpr'. - -`M-x print-buffer' - Print hardcopy of current buffer using Unix command `print' - (`lpr -p'). This command adds page headings containing the file - name and page number. - -`M-x lpr-buffer' - Print hardcopy of current buffer using Unix command `lpr'. This - command does not add page headings. - -`M-x print-region' - Like `print-buffer', but prints only the current region. - -`M-x lpr-region' - Like `lpr-buffer', but prints only the current region. - - All the hardcopy commands pass extra switches to the `lpr' program -based on the value of the variable `lpr-switches'. Its value should be -a list of strings, each string a switch starting with `-'. For -example, the value could be `("-Pfoo")' to print on printer `foo'. - diff --git a/info/xemacs.info-16 b/info/xemacs.info-16 index d9f4b8b..65c07fe 100644 --- a/info/xemacs.info-16 +++ b/info/xemacs.info-16 @@ -30,6 +30,100 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell + +Paging in the terminal emulator +------------------------------- + + Term mode has a pager feature. When the pager is enabled, term mode +will pause at the end of each screenful. + +`C-c C-q' + Toggles the pager feature: Disables the pager if it is enabled, + and vice versa. This works in both line and char modes. If the + pager enabled, the mode-line contains the word `page'. + + If the pager is enabled, and Term receives more than a screenful of +output since your last input, Term will enter More break mode. This is +indicated by `**MORE**' in the mode-line. Type a `Space' to display +the next screenful of output. Type `?' to see your other options. The +interface is similar to the Unix `more' program. + + +File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top + +Narrowing +========= + + "Narrowing" means focusing in on some portion of the buffer, making +the rest temporarily invisible and inaccessible. Cancelling the +narrowing and making the entire buffer once again visible is called +"widening". The amount of narrowing in effect in a buffer at any time +is called the buffer's "restriction". + +`C-x n n' + Narrow down to between point and mark (`narrow-to-region'). + +`C-x n w' + Widen to make the entire buffer visible again (`widen'). + + Narrowing sometimes makes it easier to concentrate on a single +subroutine or paragraph by eliminating clutter. It can also be used to +restrict the range of operation of a replace command or repeating +keyboard macro. The word `Narrow' appears in the mode line whenever +narrowing is in effect. When you have narrowed to a part of the +buffer, that part appears to be all there is. You can't see the rest, +can't move into it (motion commands won't go outside the visible part), +and can't change it in any way. However, the invisible text is not +gone; if you save the file, it will be saved. + + The primary narrowing command is `C-x n n' (`narrow-to-region'). It +sets the current buffer's restrictions so that the text in the current +region remains visible but all text before the region or after the +region is invisible. Point and mark do not change. + + Because narrowing can easily confuse users who do not understand it, +`narrow-to-region' is normally a disabled command. Attempting to use +this command asks for confirmation and gives you the option of enabling +it; once you enable the command, confirmation will no longer be +required. *Note Disabling::. + + To undo narrowing, use `C-x n w' (`widen'). This makes all text in +the buffer accessible again. + + Use the `C-x =' command to get information on what part of the +buffer you narrowed down. *Note Position Info::. + + +File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top + +Hardcopy Output +=============== + + The XEmacs commands for making hardcopy derive their names from the +Unix commands `print' and `lpr'. + +`M-x print-buffer' + Print hardcopy of current buffer using Unix command `print' + (`lpr -p'). This command adds page headings containing the file + name and page number. + +`M-x lpr-buffer' + Print hardcopy of current buffer using Unix command `lpr'. This + command does not add page headings. + +`M-x print-region' + Like `print-buffer', but prints only the current region. + +`M-x lpr-region' + Like `lpr-buffer', but prints only the current region. + + All the hardcopy commands pass extra switches to the `lpr' program +based on the value of the variable `lpr-switches'. Its value should be +a list of strings, each string a switch starting with `-'. For +example, the value could be `("-Pfoo")' to print on printer `foo'. + + File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top Recursive Editing Levels @@ -1083,62 +1177,3 @@ additional Lisp code to record the keys (if any) that you have bound to the keyboard macro, so that the macro is reassigned the same keys when you load the file. - -File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros - -Executing Macros With Variations --------------------------------- - - You can use `C-x q' (`kbd-macro-query'), to get an effect similar to -that of `query-replace'. The macro asks you each time whether to make -a change. When you are defining the macro, type `C-x q' at the point -where you want the query to occur. During macro definition, the `C-x -q' does nothing, but when you invoke the macro, `C-x q' reads a -character from the terminal to decide whether to continue. - - The special answers to a `C-x q' query are , , `C-d', -`C-l', and `C-r'. Any other character terminates execution of the -keyboard macro and is then read as a command. means to continue. - means to skip the remainder of this repetition of the macro, -starting again from the beginning in the next repetition. `C-d' means -to skip the remainder of this repetition and cancel further repetition. -`C-l' redraws the frame and asks you again for a character to specify -what to do. `C-r' enters a recursive editing level, in which you can -perform editing that is not part of the macro. When you exit the -recursive edit using `C-M-c', you are asked again how to continue with -the keyboard macro. If you type a at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you want. - - `C-u C-x q', which is `C-x q' with a numeric argument, performs a -different function. It enters a recursive edit reading input from the -keyboard, both when you type it during the definition of the macro and -when it is executed from the macro. During definition, the editing you -do inside the recursive edit does not become part of the macro. During -macro execution, the recursive edit gives you a chance to do some -particularized editing. *Note Recursive Edit::. - - -File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization - -Customizing Key Bindings -======================== - - This section deals with the "keymaps" that define the bindings -between keys and functions, and shows how you can customize these -bindings. - - A command is a Lisp function whose definition provides for -interactive use. Like every Lisp function, a command has a function -name, which is a Lisp symbol whose name usually consists of lower case -letters and hyphens. - -* Menu: - -* Keymaps:: Definition of the keymap data structure. - Names of Emacs's standard keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. - diff --git a/info/xemacs.info-17 b/info/xemacs.info-17 index beafba4..f4c723b 100644 --- a/info/xemacs.info-17 +++ b/info/xemacs.info-17 @@ -30,6 +30,65 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros + +Executing Macros With Variations +-------------------------------- + + You can use `C-x q' (`kbd-macro-query'), to get an effect similar to +that of `query-replace'. The macro asks you each time whether to make +a change. When you are defining the macro, type `C-x q' at the point +where you want the query to occur. During macro definition, the `C-x +q' does nothing, but when you invoke the macro, `C-x q' reads a +character from the terminal to decide whether to continue. + + The special answers to a `C-x q' query are , , `C-d', +`C-l', and `C-r'. Any other character terminates execution of the +keyboard macro and is then read as a command. means to continue. + means to skip the remainder of this repetition of the macro, +starting again from the beginning in the next repetition. `C-d' means +to skip the remainder of this repetition and cancel further repetition. +`C-l' redraws the frame and asks you again for a character to specify +what to do. `C-r' enters a recursive editing level, in which you can +perform editing that is not part of the macro. When you exit the +recursive edit using `C-M-c', you are asked again how to continue with +the keyboard macro. If you type a at this time, the rest of the +macro definition is executed. It is up to you to leave point and the +text in a state such that the rest of the macro will do what you want. + + `C-u C-x q', which is `C-x q' with a numeric argument, performs a +different function. It enters a recursive edit reading input from the +keyboard, both when you type it during the definition of the macro and +when it is executed from the macro. During definition, the editing you +do inside the recursive edit does not become part of the macro. During +macro execution, the recursive edit gives you a chance to do some +particularized editing. *Note Recursive Edit::. + + +File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization + +Customizing Key Bindings +======================== + + This section deals with the "keymaps" that define the bindings +between keys and functions, and shows how you can customize these +bindings. + + A command is a Lisp function whose definition provides for +interactive use. Like every Lisp function, a command has a function +name, which is a Lisp symbol whose name usually consists of lower case +letters and hyphens. + +* Menu: + +* Keymaps:: Definition of the keymap data structure. + Names of Emacs's standard keymaps. +* Rebinding:: How to redefine one key's meaning conveniently. +* Disabling:: Disabling a command means confirmation is required + before it can be executed. This is done to protect + beginners from surprises. + + File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings Keymaps @@ -1135,148 +1194,3 @@ to the first frame created regardless of its name. However, it is possible to set the iconic flag on particular frames (by name) by using the `Emacs*FRAME-NAME.iconic' resource. - -File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources - -Resource List -------------- - - Emacs frames accept the following resources: - -`geometry' (class `Geometry'): string - Initial geometry for the frame. *Note Geometry Resources::, for a - complete discussion of how this works. - -`iconic' (class `Iconic'): boolean - Whether this frame should appear in the iconified state. - -`internalBorderWidth' (class `InternalBorderWidth'): int - How many blank pixels to leave between the text and the edge of the - window. - -`interline' (class `Interline'): int - How many pixels to leave between each line (may not be - implemented). - -`menubar' (class `Menubar'): boolean - Whether newly-created frames should initially have a menubar. Set - to true by default. - -`initiallyUnmapped' (class `InitiallyUnmapped'): boolean - Whether XEmacs should leave the initial frame unmapped when it - starts up. This is useful if you are starting XEmacs as a server - (e.g. in conjunction with gnuserv or the external client widget). - You can also control this with the `-unmapped' command-line option. - -`barCursor' (class `BarColor'): boolean - Whether the cursor should be displayed as a bar, or the - traditional box. - -`cursorColor' (class `CursorColor'): color-name - The color of the text cursor. - -`scrollBarWidth' (class `ScrollBarWidth'): integer - How wide the vertical scrollbars should be, in pixels; 0 means no - vertical scrollbars. You can also use a resource specification of - the form `*scrollbar.width', or the usual toolkit scrollbar - resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width' - (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend - that you use the toolkit resources, though, because they're - dependent on how exactly your particular build of XEmacs was - configured. - -`scrollBarHeight' (class `ScrollBarHeight'): integer - How high the horizontal scrollbars should be, in pixels; 0 means no - horizontal scrollbars. You can also use a resource specification - of the form `*scrollbar.height', or the usual toolkit scrollbar - resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height' - (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend - that you use the toolkit resources, though, because they're - dependent on how exactly your particular build of XEmacs was - configured. - -`scrollBarPlacement' (class `ScrollBarPlacement'): string - Where the horizontal and vertical scrollbars should be positioned. - This should be one of the four strings `BOTTOM_LEFT', - `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is - `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and - `BOTTOM_LEFT' for the Athena scrollbars. - -`topToolBarHeight' (class `TopToolBarHeight'): integer -`bottomToolBarHeight' (class `BottomToolBarHeight'): integer -`leftToolBarWidth' (class `LeftToolBarWidth'): integer -`rightToolBarWidth' (class `RightToolBarWidth'): integer - Height and width of the four possible toolbars. - -`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name -`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name - Color of the top and bottom shadows for the toolbars. NOTE: These - resources do _not_ have anything to do with the top and bottom - toolbars (i.e. the toolbars at the top and bottom of the frame)! - Rather, they affect the top and bottom shadows around the edges of - all four kinds of toolbars. - -`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name -`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name - Pixmap of the top and bottom shadows for the toolbars. If set, - these resources override the corresponding color resources. NOTE: - These resources do _not_ have anything to do with the top and - bottom toolbars (i.e. the toolbars at the top and bottom of the - frame)! Rather, they affect the top and bottom shadows around the - edges of all four kinds of toolbars. - -`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer - Thickness of the shadows around the toolbars, in pixels. - -`visualBell' (class `VisualBell'): boolean - Whether XEmacs should flash the screen rather than making an - audible beep. - -`bellVolume' (class `BellVolume'): integer - Volume of the audible beep. - -`useBackingStore' (class `UseBackingStore'): boolean - Whether XEmacs should set the backing-store attribute of the X - windows it creates. This increases the memory usage of the X - server but decreases the amount of X traffic necessary to update - the screen, and is useful when the connection to the X server goes - over a low-bandwidth line such as a modem connection. - - Emacs devices accept the following resources: - -`textPointer' (class `Cursor'): cursor-name - The cursor to use when the mouse is over text. This resource is - used to initialize the variable `x-pointer-shape'. - -`selectionPointer' (class `Cursor'): cursor-name - The cursor to use when the mouse is over a selectable text region - (an extent with the `highlight' property; for example, an Info - cross-reference). This resource is used to initialize the variable - `x-selection-pointer-shape'. - -`spacePointer' (class `Cursor'): cursor-name - The cursor to use when the mouse is over a blank space in a buffer - (that is, after the end of a line or after the end-of-file). This - resource is used to initialize the variable - `x-nontext-pointer-shape'. - -`modeLinePointer' (class `Cursor'): cursor-name - The cursor to use when the mouse is over a modeline. This - resource is used to initialize the variable `x-mode-pointer-shape'. - -`gcPointer' (class `Cursor'): cursor-name - The cursor to display when a garbage-collection is in progress. - This resource is used to initialize the variable - `x-gc-pointer-shape'. - -`scrollbarPointer' (class `Cursor'): cursor-name - The cursor to use when the mouse is over the scrollbar. This - resource is used to initialize the variable - `x-scrollbar-pointer-shape'. - -`pointerColor' (class `Foreground'): color-name -`pointerBackground' (class `Background'): color-name - The foreground and background colors of the mouse cursor. These - resources are used to initialize the variables - `x-pointer-foreground-color' and `x-pointer-background-color'. - diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index f770b9b..5be7d83 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -30,6 +30,151 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources + +Resource List +------------- + + Emacs frames accept the following resources: + +`geometry' (class `Geometry'): string + Initial geometry for the frame. *Note Geometry Resources::, for a + complete discussion of how this works. + +`iconic' (class `Iconic'): boolean + Whether this frame should appear in the iconified state. + +`internalBorderWidth' (class `InternalBorderWidth'): int + How many blank pixels to leave between the text and the edge of the + window. + +`interline' (class `Interline'): int + How many pixels to leave between each line (may not be + implemented). + +`menubar' (class `Menubar'): boolean + Whether newly-created frames should initially have a menubar. Set + to true by default. + +`initiallyUnmapped' (class `InitiallyUnmapped'): boolean + Whether XEmacs should leave the initial frame unmapped when it + starts up. This is useful if you are starting XEmacs as a server + (e.g. in conjunction with gnuserv or the external client widget). + You can also control this with the `-unmapped' command-line option. + +`barCursor' (class `BarColor'): boolean + Whether the cursor should be displayed as a bar, or the + traditional box. + +`cursorColor' (class `CursorColor'): color-name + The color of the text cursor. + +`scrollBarWidth' (class `ScrollBarWidth'): integer + How wide the vertical scrollbars should be, in pixels; 0 means no + vertical scrollbars. You can also use a resource specification of + the form `*scrollbar.width', or the usual toolkit scrollbar + resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarHeight' (class `ScrollBarHeight'): integer + How high the horizontal scrollbars should be, in pixels; 0 means no + horizontal scrollbars. You can also use a resource specification + of the form `*scrollbar.height', or the usual toolkit scrollbar + resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarPlacement' (class `ScrollBarPlacement'): string + Where the horizontal and vertical scrollbars should be positioned. + This should be one of the four strings `BOTTOM_LEFT', + `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is + `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and + `BOTTOM_LEFT' for the Athena scrollbars. + +`topToolBarHeight' (class `TopToolBarHeight'): integer +`bottomToolBarHeight' (class `BottomToolBarHeight'): integer +`leftToolBarWidth' (class `LeftToolBarWidth'): integer +`rightToolBarWidth' (class `RightToolBarWidth'): integer + Height and width of the four possible toolbars. + +`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name +`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name + Color of the top and bottom shadows for the toolbars. NOTE: These + resources do _not_ have anything to do with the top and bottom + toolbars (i.e. the toolbars at the top and bottom of the frame)! + Rather, they affect the top and bottom shadows around the edges of + all four kinds of toolbars. + +`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name +`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name + Pixmap of the top and bottom shadows for the toolbars. If set, + these resources override the corresponding color resources. NOTE: + These resources do _not_ have anything to do with the top and + bottom toolbars (i.e. the toolbars at the top and bottom of the + frame)! Rather, they affect the top and bottom shadows around the + edges of all four kinds of toolbars. + +`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer + Thickness of the shadows around the toolbars, in pixels. + +`visualBell' (class `VisualBell'): boolean + Whether XEmacs should flash the screen rather than making an + audible beep. + +`bellVolume' (class `BellVolume'): integer + Volume of the audible beep. + +`useBackingStore' (class `UseBackingStore'): boolean + Whether XEmacs should set the backing-store attribute of the X + windows it creates. This increases the memory usage of the X + server but decreases the amount of X traffic necessary to update + the screen, and is useful when the connection to the X server goes + over a low-bandwidth line such as a modem connection. + + Emacs devices accept the following resources: + +`textPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over text. This resource is + used to initialize the variable `x-pointer-shape'. + +`selectionPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a selectable text region + (an extent with the `highlight' property; for example, an Info + cross-reference). This resource is used to initialize the variable + `x-selection-pointer-shape'. + +`spacePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a blank space in a buffer + (that is, after the end of a line or after the end-of-file). This + resource is used to initialize the variable + `x-nontext-pointer-shape'. + +`modeLinePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a modeline. This + resource is used to initialize the variable `x-mode-pointer-shape'. + +`gcPointer' (class `Cursor'): cursor-name + The cursor to display when a garbage-collection is in progress. + This resource is used to initialize the variable + `x-gc-pointer-shape'. + +`scrollbarPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over the scrollbar. This + resource is used to initialize the variable + `x-scrollbar-pointer-shape'. + +`pointerColor' (class `Foreground'): color-name +`pointerBackground' (class `Background'): color-name + The foreground and background colors of the mouse cursor. These + resources are used to initialize the variables + `x-pointer-foreground-color' and `x-pointer-background-color'. + + File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources Face Resources diff --git a/info/xemacs.info-20 b/info/xemacs.info-20 index 0711fc3..3a4d9ea 100644 --- a/info/xemacs.info-20 +++ b/info/xemacs.info-20 @@ -523,6 +523,7 @@ Key (Character) Index * ? (Calendar mode): General Calendar. * ^ (query-replace): Query Replace. * a (Calendar mode): Holidays. +* BS: Inserting Text. * button1: Intro to Keystrokes. * button1up: Intro to Keystrokes. * button2: Intro to Keystrokes. @@ -536,9 +537,9 @@ Key (Character) Index * C-] <1>: Quitting. * C-]: Recursive Edit. * C-_: Undo. -* C-a: Basic. +* C-a: Moving Point. * C-a (Calendar mode): Move to Beginning or End. -* C-b: Basic. +* C-b: Moving Point. * C-b (Calendar mode): Calendar Unit Motion. * C-c: Key Sequences. * C-c ' (Picture mode): Insert in Picture. @@ -605,10 +606,10 @@ Key (Character) Index * C-c } (TeX mode): TeX Editing. * C-d: Killing. * C-d (Shell mode): Shell Mode. -* C-e: Basic. +* C-e: Moving Point. * C-e (Calendar mode): Move to Beginning or End. -* C-END: Basic. -* C-f: Basic. +* C-END: Moving Point. +* C-f: Moving Point. * C-f (Calendar mode): Calendar Unit Motion. * C-g <1>: Quitting. * C-g: Minibuffer. @@ -645,12 +646,12 @@ Key (Character) Index * C-h v <2>: Documentation. * C-h v: Name Help. * C-h w: Name Help. -* C-HOME: Basic. +* C-HOME: Moving Point. * C-k: Killing. * C-l <1>: Scrolling. -* C-l: Basic. +* C-l: Moving Point. * C-l (query-replace): Query Replace. -* C-LEFT: Basic. +* C-LEFT: Moving Point. * C-M-@ <1>: Lists. * C-M-@: Marking Objects. * C-M-\ <1>: Multi-line Indent. @@ -681,23 +682,23 @@ Key (Character) Index * C-M-w: Appending Kills. * C-M-x <1>: External Lisp. * C-M-x: Lisp Eval. -* C-n: Basic. +* C-n: Moving Point. * C-n (Calendar mode): Calendar Unit Motion. * C-o: Blank Lines. -* C-p: Basic. +* C-p: Moving Point. * C-p (Calendar mode): Calendar Unit Motion. -* C-q: Basic. +* C-q: Inserting Text. * C-q (isearch-mode): Incremental Search. * C-r: Incremental Search. * C-r (isearch-mode): Incremental Search. * C-r (query-replace): Query Replace. -* C-RIGHT: Basic. +* C-RIGHT: Moving Point. * C-s: Incremental Search. * C-s (isearch-mode): Incremental Search. * C-SPC: Setting Mark. * C-SPC (Calendar mode): Mark and Region. * C-t <1>: Transpose. -* C-t: Basic. +* C-t: Moving Point. * C-u: Arguments. * C-u - C-x ;: Comments. * C-u C-@: Mark Ring. @@ -705,7 +706,7 @@ Key (Character) Index * C-u C-x v v: Editing with VC. * C-u TAB: Multi-line Indent. * C-v <1>: Scrolling. -* C-v: Basic. +* C-v: Moving Point. * C-v (Calendar mode): Scroll Calendar. * C-w: Killing. * C-w (isearch-mode): Incremental Search. @@ -819,12 +820,11 @@ Key (Character) Index * DEL <1>: Program Modes. * DEL <2>: Major Modes. * DEL <3>: Kill Errors. -* DEL <4>: Killing. -* DEL: Basic. +* DEL: Killing. * DEL (isearch-mode): Incremental Search. * DEL (query-replace): Query Replace. -* DOWN: Basic. -* END: Basic. +* DOWN: Moving Point. +* END: Moving Point. * ESC <1>: Meta Key. * ESC: Key Sequences. * ESC (query-replace): Query Replace. @@ -834,7 +834,7 @@ Key (Character) Index * g m l (Calendar mode): Mayan Calendar. * h (Calendar mode): Holidays. * Help: Help. -* HOME: Basic. +* HOME: Moving Point. * hyper key <1>: Super and Hyper Keys. * hyper key <2>: Representing Keystrokes. * hyper key: Intro to Keystrokes. @@ -845,7 +845,7 @@ Key (Character) Index * i m (Calendar mode): Adding to Diary. * i w (Calendar mode): Adding to Diary. * i y (Calendar mode): Adding to Diary. -* LEFT: Basic. +* LEFT: Moving Point. * LFD <1>: Basic Indent. * LFD <2>: Major Modes. * LFD: String Key Sequences. @@ -867,11 +867,11 @@ Key (Character) Index * M-/: Dynamic Abbrevs. * M-1: Arguments. * M-;: Comments. -* M-<: Basic. +* M-<: Moving Point. * M-< (Calendar mode): Move to Beginning or End. * M-=: Position Info. * M-= (Calendar mode): Mark and Region. -* M->: Basic. +* M->: Moving Point. * M-> (Calendar mode): Move to Beginning or End. * M-?: Nroff Mode. * M-@ <1>: Words. @@ -917,7 +917,7 @@ Key (Character) Index * M-p (minibuffer history): Minibuffer History. * M-p (Shell mode): Shell Mode. * M-q: Fill Commands. -* M-r: Basic. +* M-r: Moving Point. * M-r (minibuffer history): Minibuffer History. * M-s: Fill Commands. * M-s (minibuffer history): Minibuffer History. @@ -930,7 +930,7 @@ Key (Character) Index * M-TAB (isearch-mode): Incremental Search. * M-u: Case. * M-v <1>: Scrolling. -* M-v: Basic. +* M-v: Moving Point. * M-v (Calendar mode): Scroll Calendar. * M-w: Kill Ring. * M-x: M-x. @@ -947,15 +947,15 @@ Key (Character) Index * p (Calendar mode): To Other Calendar. * p d (Calendar mode): General Calendar. * pgdn: Scrolling. -* PGDN: Basic. +* PGDN: Moving Point. * pgup: Scrolling. -* PGUP: Basic. +* PGUP: Moving Point. * prior: Scrolling. * q (Calendar mode): General Calendar. -* RET: Basic. +* RET: Inserting Text. * RET (isearch-mode): Incremental Search. * RET (Shell mode): Shell Mode. -* RIGHT: Basic. +* RIGHT: Moving Point. * s (Calendar mode): Diary Commands. * S (Calendar mode): Sunrise/Sunset. * S-TAB (customization buffer): Changing an Option. @@ -977,6 +977,6 @@ Key (Character) Index * TAB (Shell mode): Shell Mode. * u (Calendar mode) <1>: Diary Commands. * u (Calendar mode): Holidays. -* UP: Basic. +* UP: Moving Point. * x (Calendar mode): Holidays. diff --git a/info/xemacs.info-21 b/info/xemacs.info-21 index fe387af..fe8b724 100644 --- a/info/xemacs.info-21 +++ b/info/xemacs.info-21 @@ -61,7 +61,7 @@ Command and Function Index * auto-fill-mode: Auto Fill. * auto-save-mode: Auto Save Control. * back-to-indentation: Indentation Commands. -* backward-char: Basic. +* backward-char: Moving Point. * backward-delete-char-untabify: Program Modes. * backward-kill-sentence <1>: Sentences. * backward-kill-sentence <2>: Kill Errors. @@ -70,6 +70,7 @@ Command and Function Index * backward-kill-word <2>: Kill Errors. * backward-kill-word: Killing. * backward-list: Lists. +* backward-or-forward-delete-char: Inserting Text. * backward-page: Pages. * backward-paragraph: Paragraphs. * backward-sentence: Sentences. @@ -78,10 +79,10 @@ Command and Function Index * backward-up-list: Lists. * backward-word: Words. * batch-byte-compile: Compiling Libraries. -* beginning-of-buffer: Basic. +* beginning-of-buffer: Moving Point. * beginning-of-defun: Defuns. * beginning-of-fortran-subprogram: Fortran Motion. -* beginning-of-line: Basic. +* beginning-of-line: Moving Point. * bookmark-delete: Bookmarks. * bookmark-insert: Bookmarks. * bookmark-insert-location: Bookmarks. @@ -200,8 +201,7 @@ Command and Function Index * define-key <1>: Programmatic Rebinding. * define-key: Interactive Rebinding. * delete-backward-char <1>: Kill Errors. -* delete-backward-char <2>: Killing. -* delete-backward-char: Basic. +* delete-backward-char: Killing. * delete-blank-lines <1>: Killing. * delete-blank-lines: Blank Lines. * delete-char <1>: Basic Picture. @@ -289,10 +289,10 @@ Command and Function Index * enable-command: Disabling. * enable-menu-item: Menu Customization. * end-kbd-macro: Basic Kbd Macro. -* end-of-buffer: Basic. +* end-of-buffer: Moving Point. * end-of-defun: Defuns. * end-of-fortran-subprogram: Fortran Motion. -* end-of-line: Basic. +* end-of-line: Moving Point. * enlarge-window: Change Window. * enlarge-window-horizontally: Change Window. * european-calendar: Date Formats. @@ -333,7 +333,7 @@ Command and Function Index * fortran-previous-statement: Fortran Motion. * fortran-split-line: ForIndent Commands. * fortran-window-create: Fortran Columns. -* forward-char: Basic. +* forward-char: Moving Point. * forward-list: Lists. * forward-page: Pages. * forward-paragraph: Paragraphs. @@ -344,8 +344,8 @@ Command and Function Index * frame-configuration-to-register: RegConfig. * global-set-key <1>: Programmatic Rebinding. * global-set-key: Interactive Rebinding. -* goto-char: Basic. -* goto-line: Basic. +* goto-char: Moving Point. +* goto-line: Moving Point. * hanoi: Amusements. * help-command: Help. * help-for-help: Help. @@ -525,16 +525,16 @@ Command and Function Index * mouse-track-and-copy-to-cutbuffer: Additional Mouse Operations. * mouse-track-delete-and-insert: Additional Mouse Operations. * move-over-close-and-reindent: Balanced Editing. -* move-to-window-line: Basic. +* move-to-window-line: Moving Point. * name-last-kbd-macro: Save Kbd Macro. * narrow-to-region: Narrowing. * negative-argument: Arguments. -* newline: Basic. +* newline: Inserting Text. * newline-and-indent: Basic Indent. * next-complex-command: Repetition. * next-error: Compilation. * next-history-element: Minibuffer History. -* next-line: Basic. +* next-line: Moving Point. * next-list-mode-item: Completion Commands. * next-matching-history-element: Minibuffer History. * not-modified: Saving. @@ -588,7 +588,7 @@ Command and Function Index * prepend-to-buffer: Accumulating Text. * previous-complex-command: Repetition. * previous-history-element: Minibuffer History. -* previous-line: Basic. +* previous-line: Moving Point. * previous-list-mode-item: Completion Commands. * previous-matching-history-element: Minibuffer History. * print-buffer: Hardcopy. @@ -600,13 +600,13 @@ Command and Function Index * query-replace-regexp: Query Replace. * quietly-read-abbrev-file: Saving Abbrevs. * quit-shell-subjob: Shell Mode. -* quoted-insert: Basic. +* quoted-insert: Inserting Text. * re-search-backward: Regexp Search. * re-search-forward: Regexp Search. * read-abbrev-file: Saving Abbrevs. * read-key-sequence: Representing Keystrokes. * recenter <1>: Scrolling. -* recenter: Basic. +* recenter: Moving Point. * recover-file: Recover. * redraw-calendar: General Calendar. * relabel-menu-item: Menu Customization. @@ -634,7 +634,7 @@ Command and Function Index * search-backward: Non-Incremental Search. * search-forward: Non-Incremental Search. * select-input-method: Select Input Method. -* self-insert: Basic. +* self-insert: Inserting Text. * send-shell-input: Shell Mode. * set-buffer-file-coding-system: Specify Coding. * set-buffer-process-coding-system: Specify Coding. @@ -648,7 +648,7 @@ Command and Function Index * set-fill-column: Fill Commands. * set-fill-prefix: Fill Prefix. * set-gnu-bindings: Emulation. -* set-goal-column: Basic. +* set-goal-column: Moving Point. * set-gosmacs-bindings: Emulation. * set-keyboard-coding-system: Specify Coding. * set-language-environment: Language Environments. @@ -694,6 +694,7 @@ Command and Function Index * switch-to-buffer-other-frame: XEmacs under X. * switch-to-buffer-other-window <1>: Pop Up Window. * switch-to-buffer-other-window: Select Buffer. +* switch-to-completions: Completion Commands. * switch-to-other-buffer: Select Buffer. * tab-to-tab-stop <1>: Text Mode. * tab-to-tab-stop: Tab Stops. @@ -723,7 +724,7 @@ Command and Function Index * top-level <1>: Quitting. * top-level: Recursive Edit. * transpose-chars <1>: Transpose. -* transpose-chars: Basic. +* transpose-chars: Moving Point. * transpose-lines: Transpose. * transpose-sexps <1>: Lists. * transpose-sexps: Transpose. diff --git a/info/xemacs.info-22 b/info/xemacs.info-22 index 912f44b..7b22577 100644 --- a/info/xemacs.info-22 +++ b/info/xemacs.info-22 @@ -152,7 +152,6 @@ Variable Index * emacs-roots: Startup Paths. * EMACSDATA: Startup Paths. * EMACSLOADPATH: Startup Paths. -* EMACSLOCKDIR: Startup Paths. * EMACSPATH: Startup Paths. * enable-local-variables: File Variables. * enable-recursive-minibuffers: Minibuffer Edit. @@ -220,7 +219,6 @@ Variable Index * load-path <1>: Loading. * load-path: Startup Paths. * local-holidays: Holiday Customizing. -* lock-directory: Startup Paths. * lpr-switches: Hardcopy. * mail-abbrev-mailrc-file: Mail Headers. * mail-abbrev-mode-regexp: Mail Headers. @@ -245,6 +243,7 @@ Variable Index * mode-line-inverse-video: Mode Line. * modeline-pointer-glyph: Mouse Selection. * muddle-mode-hook: Program Modes. +* next-line-add-newlines: Moving Point. * next-screen-context-lines: Scrolling. * no-redraw-on-reenter: Display Vars. * nongregorian-diary-listing-hook: Hebrew/Islamic Entries. @@ -281,7 +280,6 @@ Variable Index * shell-prompt-pattern: Shell Mode. * shell-pushd-regexp: Interactive Shell. * sound-alist: Audible Bell. -* superlock-file: Startup Paths. * tab-stop-list: Tab Stops. * tab-width: Display Vars. * tag-mark-stack-max: Find Tag. @@ -298,7 +296,7 @@ Variable Index * text-pointer-glyph: Mouse Selection. * today-invisible-calendar-hook: Calendar Customizing. * today-visible-calendar-hook: Calendar Customizing. -* track-eol: Basic. +* track-eol: Moving Point. * truncate-lines: Continuation Lines. * truncate-partial-width-windows: Split Window. * vc-command-messages: Variables for Check-in/out. @@ -347,6 +345,7 @@ Concept Index * apropos: Apropos. * architecture-specific directories: Startup Paths. * arguments (from shell): Command Switches. +* arrow keys: Moving Point. * ASCII: Intro to Keystrokes. * Asm mode: Asm Mode. * astronomical day numbers: Calendar Systems. @@ -423,8 +422,9 @@ Concept Index * creating files: Visiting. * current buffer: Buffers. * current stack frame: Lisp Debug. -* cursor <1>: Basic. +* cursor <1>: Inserting Text. * cursor: Point. +* cursor motion: Moving Point. * customization <1>: Customization. * customization <2>: Lisp Indent. * customization: Commands. @@ -440,9 +440,11 @@ Concept Index * default argument: Minibuffer. * defuns: Defuns. * Delete Frame menu item: File Menu. +* deleting blank lines: Blank Lines. +* deleting characters and lines: Erasing. * deleting menu items: Menu Customization. * deletion <1>: Killing. -* deletion: Basic. +* deletion: Inserting Text. * deletion (of files) <1>: Misc File Ops. * deletion (of files): Dired. * diary: Diary. @@ -474,9 +476,9 @@ Concept Index * enabling menu items: Menu Customization. * encoding of characters: Mule. * End Macro Recording menu item: Edit Menu. -* entering Emacs: Entering Emacs. * entering XEmacs: Entering Emacs. * environment: Single Shell. +* erasing characters and lines: Erasing. * error log: Compilation. * etags program: Create Tags Table. * Ethiopic calendar: Calendar Systems. @@ -494,7 +496,7 @@ Concept Index * file protection: Interlocking. * files <1>: Visiting. * files <2>: Files. -* files: Basic. +* files: Basic Files. * fill prefix: Fill Prefix. * filling: Filling. * Font menu item: Options Menu. @@ -506,9 +508,10 @@ Concept Index * function <1>: Key Bindings. * function: Commands. * General Public License: License. +* getting help with keys: Basic Help. * global keymap: Keymaps. * global substitution: Replace. -* graphic characters: Basic. +* graphic characters: Inserting Text. * Greek: Mule. * Gregorian calendar: Other Calendars. * grinding: Grinding. @@ -526,6 +529,7 @@ Concept Index * holiday forms: Holiday Customizing. * holidays: Holidays. * horizontal scrolling: Horizontal Scrolling. +* Icomplete mode: Completion Options. * ignoriginal: Dissociated Press. * indentation <1>: Comments. * indentation <2>: Grinding. @@ -535,7 +539,8 @@ Concept Index * init file: Init File. * input methods: Input Methods. * Insert File... menu item: File Menu. -* insertion: Basic. +* inserting blank lines: Blank Lines. +* insertion: Inserting Text. * international scripts: Mule. * interval operator (in regexps): Etags Regexps. * invisible lines: Outline Mode. @@ -559,15 +564,18 @@ Concept Index * Kill Buffer menu item: File Menu. * kill ring: Yanking. * killing: Killing. +* killing characters and lines: Erasing. * killing Emacs: Exiting. * Korean: Mule. * language environments: Language Environments. * last package hierarchies: Startup Paths. * late package hierarchies: Startup Paths. * LaTeX: TeX Mode. +* leaving Emacs: Exiting. * libraries: Lisp Libraries. * license to copy XEmacs: License. * line number: Position Info. +* line wrapping: Continuation Lines. * Lisp: Programs. * Lisp mode: Program Modes. * list: Lists. @@ -617,15 +625,18 @@ Concept Index * moon, phases of: Lunar Phases. * mouse operations: Additional Mouse Operations. * mouse selection: Mouse Selection. +* movement: Moving Point. * moving inside the calendar: Calendar Motion. +* moving point: Moving Point. * moving text: Yanking. +* moving the cursor: Moving Point. * MULE: Mule. * multi-frame XEmacs: XEmacs under X. * multibyte characters: Mule. * named configurations (RCS): Snapshot Caveats. * narrowing: Narrowing. * New Frame menu item: File Menu. -* newline: Basic. +* newline: Inserting Text. * non-incremental search: Non-Incremental Search. * nroff: Nroff Mode. * numeric arguments: Arguments. @@ -659,7 +670,7 @@ Concept Index * Persian calendar: Calendar Systems. * phases of the moon: Lunar Phases. * pictures: Picture. -* point <1>: Basic. +* point <1>: Inserting Text. * point: Point. * pointer face: Mouse Selection. * pointer shapes: Mouse Selection. @@ -674,7 +685,8 @@ Concept Index * query replace: Query Replace. * quitting: Quitting. * quitting (in search): Incremental Search. -* quoting: Basic. +* quitting Emacs: Exiting. +* quoting: Inserting Text. * random sentences: CONX. * RCS: Concepts of VC. * Read Only menu item: Options Menu. @@ -736,6 +748,7 @@ Concept Index * spelling: Spelling. * Split Frame: File Menu. * Start Macro Recording menu item: Edit Menu. +* starting XEmacs: Entering Emacs. * startup paths: Startup Paths. * string substitution: Replace. * subshell: Shell. @@ -787,6 +800,7 @@ Concept Index * words <2>: Words. * words: Fixing Case. * work file: Concepts of VC. +* wrapping: Continuation Lines. * X resources: X Resources. * yahrzeits <1>: Sexp Diary Entries. * yahrzeits: From Other Calendar. diff --git a/info/xemacs.info-5 b/info/xemacs.info-5 index 22cba33..54b0a81 100644 --- a/info/xemacs.info-5 +++ b/info/xemacs.info-5 @@ -30,6 +30,90 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Mark Ring, Prev: Marking Objects, Up: Mark + +The Mark Ring +------------- + + Aside from delimiting the region, the mark is also useful for marking +a spot that you may want to go back to. To make this feature more +useful, Emacs remembers 16 previous locations of the mark in the "mark +ring". Most commands that set the mark push the old mark onto this +ring. To return to a marked location, use `C-u C-' (or `C-u +C-@'); this is the command `set-mark-command' given a numeric argument. +The command moves point to where the mark was, and restores the mark +from the ring of former marks. Repeated use of this command moves point +to all the old marks on the ring, one by one. The marks you have seen +go to the end of the ring, so no marks are lost. + + Each buffer has its own mark ring. All editing commands use the +current buffer's mark ring. In particular, `C-u C-' always stays +in the same buffer. + + Many commands that can move long distances, such as `M-<' +(`beginning-of-buffer'), start by setting the mark and saving the old +mark on the mark ring. This makes it easier for you to move back +later. Searches set the mark, unless they do not actually move point. +When a command sets the mark, `Mark Set' is printed in the echo area. + + The variable `mark-ring-max' is the maximum number of entries to +keep in the mark ring. If that many entries exist and another entry is +added, the last entry in the list is discarded. Repeating `C-u +C-' circulates through the entries that are currently in the ring. + + The variable `mark-ring' holds the mark ring itself, as a list of +marker objects in the order most recent first. This variable is local +in every buffer. + + +File: xemacs.info, Node: Mouse Selection, Next: Additional Mouse Operations, Prev: Mark, Up: Top + +Selecting Text with the Mouse +============================= + + If you are using XEmacs under X, you can use the mouse pointer to +select text. (The normal mouse pointer is an I-beam, the same pointer +that `xterm' uses.) + + The glyph variable `text-pointer-glyph' controls the shape of the +mouse pointer when over text. You can also control the shape of the +mouse pointer when over nontext using `nontext-pointer-glyph', and the +shape of the mouse pointer when over the modeline using +`modeline-pointer-glyph'. (Remember, you should use `set-glyph-image', +not `setq', to set one of these variables.) + + If you want to get fancy, you can set the foreground and background +colors of the mouse pointer by setting the `pointer' face. + + There are two ways to select a region of text with the mouse: + + To select a word in text, double-click with the left mouse button +while the mouse cursor is over the word. The word is highlighted when +selected. On monochrome monitors, a stippled background indicates that a +region of text has been highlighted. On color monitors, a color +background indicates highlighted text. You can triple-click to select +whole lines. + + To select an arbitrary region of text: + + 1. Move the mouse cursor over the character at the beginning of the + region of text you want to select. + + 2. Press and hold the left mouse button. + + 3. While holding the left mouse button down, drag the cursor to the + character at the end of the region of text you want to select. + + 4. Release the left mouse button. + The selected region of text is highlighted. + + Once a region of text is selected, it becomes the primary X selection +(*note Using X Selections::) as well as the Emacs selected region. You +can paste it into other X applications and use the options from the +Edit pull-down menu on it. Since it is also the Emacs region, you can +use Emacs region commands on it. + + File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top Additional Mouse Operations @@ -1152,94 +1236,3 @@ commands allow you to specify which part of the text you want to see. * Selective Display:: Hiding lines with lots of indentation. * Display Vars:: Information on variables for customizing display. - -File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display - -Scrolling -========= - - If a buffer contains text that is too large to fit entirely within -the window that is displaying the buffer, XEmacs shows a contiguous -section of the text. The section shown always contains point. - - "Scrolling" means moving text up or down in the window so that -different parts of the text are visible. Scrolling forward means that -text moves up, and new text appears at the bottom. Scrolling backward -moves text down and new text appears at the top. - - Scrolling happens automatically if you move point past the bottom or -top of the window. You can also explicitly request scrolling with the -commands in this section. - -`C-l' - Clear frame and redisplay, scrolling the selected window to center - point vertically within it (`recenter'). - -`C-v' -`pgdn' -`next' - Scroll forward (a windowful or a specified number of lines) - (`scroll-up'). - -`M-v' -`pgup' -`prior' - Scroll backward (`scroll-down'). - -`ARG C-l' - Scroll so point is on line ARG (`recenter'). - - The most basic scrolling command is `C-l' (`recenter') with no -argument. It clears the entire frame and redisplays all windows. In -addition, it scrolls the selected window so that point is halfway down -from the top of the window. - - The scrolling commands `C-v' and `M-v' let you move all the text in -the window up or down a few lines. `C-v' (`scroll-up') with an -argument shows you that many more lines at the bottom of the window, -moving the text and point up together as `C-l' might. `C-v' with a -negative argument shows you more lines at the top of the window. -`Meta-v' (`scroll-down') is like `C-v', but moves in the opposite -direction. - - To read the buffer a windowful at a time, use `C-v' with no -argument. `C-v' takes the last two lines at the bottom of the window -and puts them at the top, followed by nearly a whole windowful of lines -not previously visible. Point moves to the new top of the window if it -was in the text scrolled off the top. `M-v' with no argument moves -backward with similar overlap. The number of lines of overlap across a -`C-v' or `M-v' is controlled by the variable -`next-screen-context-lines'; by default, it is two. - - Another way to scroll is using `C-l' with a numeric argument. `C-l' -does not clear the frame when given an argument; it only scrolls the -selected window. With a positive argument N, `C-l' repositions text to -put point N lines down from the top. An argument of zero puts point on -the very top line. Point does not move with respect to the text; -rather, the text and point move rigidly on the frame. `C-l' with a -negative argument puts point that many lines from the bottom of the -window. For example, `C-u - 1 C-l' puts point on the bottom line, and -`C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as -argument, as in `C-u C-l', scrolls point to the center of the frame. - - Scrolling happens automatically if point has moved out of the visible -portion of the text when it is time to display. Usually scrolling is -done to put point vertically centered within the window. However, if -the variable `scroll-step' has a non-zero value, an attempt is made to -scroll the buffer by that many lines; if that is enough to bring point -back into visibility, that is what happens. - - Scrolling happens automatically if point has moved out of the visible -portion of the text when it is time to display. Usually scrolling is -done to put point vertically centered within the window. However, if -the variable `scroll-step' has a non-zero value, an attempt is made to -scroll the buffer by that many lines; if that is enough to bring point -back into visibility, that is what happens. - - If you set `scroll-step' to a small value because you want to use -arrow keys to scroll the screen without recentering, the redisplay -preemption will likely make XEmacs keep recentering the screen when -scrolling fast, regardless of `scroll-step'. To prevent this, set -`scroll-conservatively' to a small value, which will have the result of -overriding the redisplay preemption. - diff --git a/info/xemacs.info-6 b/info/xemacs.info-6 index 37d661e..dbf16a3 100644 --- a/info/xemacs.info-6 +++ b/info/xemacs.info-6 @@ -30,6 +30,97 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display + +Scrolling +========= + + If a buffer contains text that is too large to fit entirely within +the window that is displaying the buffer, XEmacs shows a contiguous +section of the text. The section shown always contains point. + + "Scrolling" means moving text up or down in the window so that +different parts of the text are visible. Scrolling forward means that +text moves up, and new text appears at the bottom. Scrolling backward +moves text down and new text appears at the top. + + Scrolling happens automatically if you move point past the bottom or +top of the window. You can also explicitly request scrolling with the +commands in this section. + +`C-l' + Clear frame and redisplay, scrolling the selected window to center + point vertically within it (`recenter'). + +`C-v' +`pgdn' +`next' + Scroll forward (a windowful or a specified number of lines) + (`scroll-up'). + +`M-v' +`pgup' +`prior' + Scroll backward (`scroll-down'). + +`ARG C-l' + Scroll so point is on line ARG (`recenter'). + + The most basic scrolling command is `C-l' (`recenter') with no +argument. It clears the entire frame and redisplays all windows. In +addition, it scrolls the selected window so that point is halfway down +from the top of the window. + + The scrolling commands `C-v' and `M-v' let you move all the text in +the window up or down a few lines. `C-v' (`scroll-up') with an +argument shows you that many more lines at the bottom of the window, +moving the text and point up together as `C-l' might. `C-v' with a +negative argument shows you more lines at the top of the window. +`Meta-v' (`scroll-down') is like `C-v', but moves in the opposite +direction. + + To read the buffer a windowful at a time, use `C-v' with no +argument. `C-v' takes the last two lines at the bottom of the window +and puts them at the top, followed by nearly a whole windowful of lines +not previously visible. Point moves to the new top of the window if it +was in the text scrolled off the top. `M-v' with no argument moves +backward with similar overlap. The number of lines of overlap across a +`C-v' or `M-v' is controlled by the variable +`next-screen-context-lines'; by default, it is two. + + Another way to scroll is using `C-l' with a numeric argument. `C-l' +does not clear the frame when given an argument; it only scrolls the +selected window. With a positive argument N, `C-l' repositions text to +put point N lines down from the top. An argument of zero puts point on +the very top line. Point does not move with respect to the text; +rather, the text and point move rigidly on the frame. `C-l' with a +negative argument puts point that many lines from the bottom of the +window. For example, `C-u - 1 C-l' puts point on the bottom line, and +`C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as +argument, as in `C-u C-l', scrolls point to the center of the frame. + + Scrolling happens automatically if point has moved out of the visible +portion of the text when it is time to display. Usually scrolling is +done to put point vertically centered within the window. However, if +the variable `scroll-step' has a non-zero value, an attempt is made to +scroll the buffer by that many lines; if that is enough to bring point +back into visibility, that is what happens. + + Scrolling happens automatically if point has moved out of the visible +portion of the text when it is time to display. Usually scrolling is +done to put point vertically centered within the window. However, if +the variable `scroll-step' has a non-zero value, an attempt is made to +scroll the buffer by that many lines; if that is enough to bring point +back into visibility, that is what happens. + + If you set `scroll-step' to a small value because you want to use +arrow keys to scroll the screen without recentering, the redisplay +preemption will likely make XEmacs keep recentering the screen when +scrolling fast, regardless of `scroll-step'. To prevent this, set +`scroll-conservatively' to a small value, which will have the result of +overriding the redisplay preemption. + + File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display Horizontal Scrolling @@ -1117,33 +1208,3 @@ the region, not the entire buffer. that is a correctly spelled English word. It prints a message giving the answer in the echo area. - -File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top - -File Handling -************* - - The basic unit of stored data in Unix is the "file". To edit a file, -you must tell Emacs to examine the file and prepare a buffer containing -a copy of the file's text. This is called "visiting" the file. Editing -commands apply directly to text in the buffer; that is, to the copy -inside Emacs. Your changes appear in the file itself only when you -"save" the buffer back into the file. - - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, and operate on file directories. - -* Menu: - -* File Names:: How to type and edit file name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -* Auto Save:: Auto Save periodically protects against loss of data. -* Version Control:: Version control systems (RCS and SCCS). -* ListDir:: Listing the contents of a file directory. -* Comparing Files:: Finding where two files differ. -* Dired:: ``Editing'' a directory to delete, rename, etc. - the files in it. -* Misc File Ops:: Other things you can do on files. - diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index 8bda945..d6029e5 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -30,6 +30,36 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top + +File Handling +************* + + The basic unit of stored data in Unix is the "file". To edit a file, +you must tell Emacs to examine the file and prepare a buffer containing +a copy of the file's text. This is called "visiting" the file. Editing +commands apply directly to text in the buffer; that is, to the copy +inside Emacs. Your changes appear in the file itself only when you +"save" the buffer back into the file. + + In addition to visiting and saving files, Emacs can delete, copy, +rename, and append to files, and operate on file directories. + +* Menu: + +* File Names:: How to type and edit file name arguments. +* Visiting:: Visiting a file prepares Emacs to edit the file. +* Saving:: Saving makes your changes permanent. +* Reverting:: Reverting cancels all the changes not saved. +* Auto Save:: Auto Save periodically protects against loss of data. +* Version Control:: Version control systems (RCS and SCCS). +* ListDir:: Listing the contents of a file directory. +* Comparing Files:: Finding where two files differ. +* Dired:: ``Editing'' a directory to delete, rename, etc. + the files in it. +* Misc File Ops:: Other things you can do on files. + + File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files File Names @@ -987,89 +1017,3 @@ minibuffer). Log mode, which involves running two hooks: `text-mode-hook' and `vc-log-mode-hook'. - -File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control - -Change Logs and VC ------------------- - - If you use RCS for a program and also maintain a change log file for -it (*note Change Log::), you can generate change log entries -automatically from the version control log entries: - -`C-x v a' - Visit the current directory's change log file and create new - entries for versions checked in since the most recent entry in the - change log file (`vc-update-change-log'). - - This command works with RCS only; it does not work with SCCS. - - For example, suppose the first line of `ChangeLog' is dated 10 April -1992, and that the only check-in since then was by Nathaniel Bowditch -to `rcs2log' on 8 May 1992 with log text `Ignore log messages that -start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text -like this: - - Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org) - - * rcs2log: Ignore log messages that start with `#'. - -You can then edit the new change log entry further as you wish. - - Normally, the log entry for file `foo' is displayed as `* foo: TEXT -OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log -entry starts with `(FUNCTIONNAME): '. For example, if the log entry -for `vc.el' is `(vc-do-command): Check call-process status.', then the -text in `ChangeLog' looks like this: - - Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.el (vc-do-command): Check call-process status. - - When `C-x v a' adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent checkins have the following log -entries: - -For `vc.texinfo': - Fix expansion typos. -For `vc.el': - Don't call expand-file-name. -For `vc-hooks.el': - Don't call expand-file-name. - - They appear like this in `ChangeLog': - - Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.texinfo: Fix expansion typos. - - * vc.el, vc-hooks.el: Don't call expand-file-name. - - Normally, `C-x v a' separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form `{CLUMPNAME} '. The label itself is not -copied to `ChangeLog'. For example, suppose the log entries are: - -For `vc.texinfo': - {expand} Fix expansion typos. -For `vc.el': - {expand} Don't call expand-file-name. -For `vc-hooks.el': - {expand} Don't call expand-file-name. - -Then the text in `ChangeLog' looks like this: - - Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. - - A log entry whose text begins with `#' is not copied to `ChangeLog'. -For example, if you merely fix some misspellings in comments, you can -log the change with an entry beginning with `#' to avoid putting such -trivia into `ChangeLog'. - diff --git a/info/xemacs.info-8 b/info/xemacs.info-8 index 363f8d6..2f1618a 100644 --- a/info/xemacs.info-8 +++ b/info/xemacs.info-8 @@ -30,6 +30,92 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control + +Change Logs and VC +------------------ + + If you use RCS for a program and also maintain a change log file for +it (*note Change Log::), you can generate change log entries +automatically from the version control log entries: + +`C-x v a' + Visit the current directory's change log file and create new + entries for versions checked in since the most recent entry in the + change log file (`vc-update-change-log'). + + This command works with RCS only; it does not work with SCCS. + + For example, suppose the first line of `ChangeLog' is dated 10 April +1992, and that the only check-in since then was by Nathaniel Bowditch +to `rcs2log' on 8 May 1992 with log text `Ignore log messages that +start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text +like this: + + Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org) + + * rcs2log: Ignore log messages that start with `#'. + +You can then edit the new change log entry further as you wish. + + Normally, the log entry for file `foo' is displayed as `* foo: TEXT +OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log +entry starts with `(FUNCTIONNAME): '. For example, if the log entry +for `vc.el' is `(vc-do-command): Check call-process status.', then the +text in `ChangeLog' looks like this: + + Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org) + + * vc.el (vc-do-command): Check call-process status. + + When `C-x v a' adds several change log entries at once, it groups +related log entries together if they all are checked in by the same +author at nearly the same time. If the log entries for several such +files all have the same text, it coalesces them into a single entry. +For example, suppose the most recent checkins have the following log +entries: + +For `vc.texinfo': + Fix expansion typos. +For `vc.el': + Don't call expand-file-name. +For `vc-hooks.el': + Don't call expand-file-name. + + They appear like this in `ChangeLog': + + Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) + + * vc.texinfo: Fix expansion typos. + + * vc.el, vc-hooks.el: Don't call expand-file-name. + + Normally, `C-x v a' separates log entries by a blank line, but you +can mark several related log entries to be clumped together (without an +intervening blank line) by starting the text of each related log entry +with a label of the form `{CLUMPNAME} '. The label itself is not +copied to `ChangeLog'. For example, suppose the log entries are: + +For `vc.texinfo': + {expand} Fix expansion typos. +For `vc.el': + {expand} Don't call expand-file-name. +For `vc-hooks.el': + {expand} Don't call expand-file-name. + +Then the text in `ChangeLog' looks like this: + + Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) + + * vc.texinfo: Fix expansion typos. + * vc.el, vc-hooks.el: Don't call expand-file-name. + + A log entry whose text begins with `#' is not copied to `ChangeLog'. +For example, if you merely fix some misspellings in comments, you can +log the change with an entry beginning with `#' to avoid putting such +trivia into `ChangeLog'. + + File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control Examining And Comparing Old Versions @@ -1101,103 +1187,3 @@ currently selected window is not acceptable. Commands such as `switch-to-buffer-other-window' and `find-file-other-window' work using this function. - -File: xemacs.info, Node: Change Window, Prev: Pop Up Window, Up: Windows - -Deleting and Rearranging Windows -================================ - -`C-x 0' - Get rid of the selected window (`delete-window'). That is a zero. - If there is more than one Emacs frame, deleting the sole remaining - window on that frame deletes the frame as well. If the current - frame is the only frame, it is not deleted. - -`C-x 1' - Get rid of all windows except the selected one - (`delete-other-windows'). - -`C-x ^' - Make the selected window taller, at the expense of the other(s) - (`enlarge-window'). - -`C-x }' - Make the selected window wider (`enlarge-window-horizontally'). - - To delete a window, type `C-x 0' (`delete-window'). (That is a -zero.) The space occupied by the deleted window is distributed among -the other active windows (but not the minibuffer window, even if that -is active at the time). Once a window is deleted, its attributes are -forgotten; there is no automatic way to make another window of the same -shape or showing the same buffer. The buffer continues to exist, and -you can select it in any window with `C-x b'. - - `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it -deletes all the windows except the selected one (and the minibuffer). -The selected window expands to use the whole frame except for the echo -area. - - To readjust the division of space among existing windows, use `C-x -^' (`enlarge-window'). It makes the currently selected window longer -by one line or as many lines as a numeric argument specifies. With a -negative argument, it makes the selected window smaller. `C-x }' -(`enlarge-window-horizontally') makes the selected window wider by the -specified number of columns. The extra screen space given to a window -comes from one of its neighbors, if that is possible; otherwise, all -the competing windows are shrunk in the same proportion. If this makes -some windows too small, those windows are deleted and their space is -divided up. Minimum window size is specified by the variables -`window-min-height' and `window-min-width'. - - You can also resize windows within a frame by clicking the left mouse -button on a modeline, and dragging. - - Clicking the right button on a mode line pops up a menu of common -window manager operations. This menu contains the following options: - -Delete Window - Remove the window above this modeline from the frame. - -Delete Other Windows - Delete all windows on the frame except for the one above this - modeline. - -Split Window - Split the window above the mode line in half, creating another - window. - -Split Window Horizontally - Split the window above the mode line in half horizontally, so that - there will be two windows side-by-side. - -Balance Windows - Readjust the sizes of all windows on the frame until all windows - have roughly the same number of lines. - - -File: xemacs.info, Node: Mule, Next: Major Modes, Prev: Windows, Up: Top - -World Scripts Support -********************* - - If you compile XEmacs with mule option, it supports a wide variety of -world scripts, including Latin script, as well as Arabic script, -Simplified Chinese script (for mainland of China), Traditional Chinese -script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA -symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts -(Hangul and Hanja) and Cyrillic script (for Beylorussian, Bulgarian, -Russian, Serbian and Ukrainian). These features have been merged from -the modified version of Emacs known as MULE (for "MULti-lingual -Enhancement to GNU Emacs"). - -* Menu: - -* Mule Intro:: Basic concepts of Mule. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How XEmacs figures out which conversion to use. -* Specify Coding:: Various ways to choose which conversion to use. - diff --git a/info/xemacs.info-9 b/info/xemacs.info-9 index cbbf7d1..6f85972 100644 --- a/info/xemacs.info-9 +++ b/info/xemacs.info-9 @@ -30,6 +30,106 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Change Window, Prev: Pop Up Window, Up: Windows + +Deleting and Rearranging Windows +================================ + +`C-x 0' + Get rid of the selected window (`delete-window'). That is a zero. + If there is more than one Emacs frame, deleting the sole remaining + window on that frame deletes the frame as well. If the current + frame is the only frame, it is not deleted. + +`C-x 1' + Get rid of all windows except the selected one + (`delete-other-windows'). + +`C-x ^' + Make the selected window taller, at the expense of the other(s) + (`enlarge-window'). + +`C-x }' + Make the selected window wider (`enlarge-window-horizontally'). + + To delete a window, type `C-x 0' (`delete-window'). (That is a +zero.) The space occupied by the deleted window is distributed among +the other active windows (but not the minibuffer window, even if that +is active at the time). Once a window is deleted, its attributes are +forgotten; there is no automatic way to make another window of the same +shape or showing the same buffer. The buffer continues to exist, and +you can select it in any window with `C-x b'. + + `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it +deletes all the windows except the selected one (and the minibuffer). +The selected window expands to use the whole frame except for the echo +area. + + To readjust the division of space among existing windows, use `C-x +^' (`enlarge-window'). It makes the currently selected window longer +by one line or as many lines as a numeric argument specifies. With a +negative argument, it makes the selected window smaller. `C-x }' +(`enlarge-window-horizontally') makes the selected window wider by the +specified number of columns. The extra screen space given to a window +comes from one of its neighbors, if that is possible; otherwise, all +the competing windows are shrunk in the same proportion. If this makes +some windows too small, those windows are deleted and their space is +divided up. Minimum window size is specified by the variables +`window-min-height' and `window-min-width'. + + You can also resize windows within a frame by clicking the left mouse +button on a modeline, and dragging. + + Clicking the right button on a mode line pops up a menu of common +window manager operations. This menu contains the following options: + +Delete Window + Remove the window above this modeline from the frame. + +Delete Other Windows + Delete all windows on the frame except for the one above this + modeline. + +Split Window + Split the window above the mode line in half, creating another + window. + +Split Window Horizontally + Split the window above the mode line in half horizontally, so that + there will be two windows side-by-side. + +Balance Windows + Readjust the sizes of all windows on the frame until all windows + have roughly the same number of lines. + + +File: xemacs.info, Node: Mule, Next: Major Modes, Prev: Windows, Up: Top + +World Scripts Support +********************* + + If you compile XEmacs with mule option, it supports a wide variety of +world scripts, including Latin script, as well as Arabic script, +Simplified Chinese script (for mainland of China), Traditional Chinese +script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA +symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts +(Hangul and Hanja) and Cyrillic script (for Beylorussian, Bulgarian, +Russian, Serbian and Ukrainian). These features have been merged from +the modified version of Emacs known as MULE (for "MULti-lingual +Enhancement to GNU Emacs"). + +* Menu: + +* Mule Intro:: Basic concepts of Mule. +* Language Environments:: Setting things up for the language you use. +* Input Methods:: Entering text characters not on your keyboard. +* Select Input Method:: Specifying your choice of input methods. +* Coding Systems:: Character set conversion when you read and + write files, and so on. +* Recognize Coding:: How XEmacs figures out which conversion to use. +* Specify Coding:: Various ways to choose which conversion to use. + + File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule Introduction to world scripts @@ -1028,113 +1128,3 @@ insert automatically a matching `\end' (on a new line following the `\begin'). A blank line is inserted between the two, and point is left there. - -File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode - -TeX Printing Commands -..................... - - You can invoke TeX as an inferior of Emacs on either the entire -contents of the buffer or just a region at a time. Running TeX in this -way on just one chapter is a good way to see what your changes look -like without taking the time to format the entire file. - -`C-c C-r' - Invoke TeX on the current region, plus the buffer's header - (`tex-region'). - -`C-c C-b' - Invoke TeX on the entire current buffer (`tex-buffer'). - -`C-c C-l' - Recenter the window showing output from the inferior TeX so that - the last line can be seen (`tex-recenter-output-buffer'). - -`C-c C-k' - Kill the inferior TeX (`tex-kill-job'). - -`C-c C-p' - Print the output from the last `C-c C-r' or `C-c C-b' command - (`tex-print'). - -`C-c C-q' - Show the printer queue (`tex-show-print-queue'). - - You can pass the current buffer through an inferior TeX using `C-c -C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp'; -to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q' -(`tex-show-print-queue') to view the progress of your output towards -being printed. - - The console output from TeX, including any error messages, appears -in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch -to this buffer and feed it input (this works as in Shell mode; *note -Interactive Shell::). Without switching to this buffer, you can scroll -it so that its last line is visible by typing `C-c C-l'. - - Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see -that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also -kills any TeX process still running. - - You can pass an arbitrary region through an inferior TeX by typing -`C-c C-r' (`tex-region'). This is tricky, however, because most files -of TeX input contain commands at the beginning to set parameters and -define macros. Without them, no later part of the file will format -correctly. To solve this problem, `C-c C-r' allows you to designate a -part of the file as containing essential commands; it is included -before the specified region as part of the input to TeX. The -designated part of the file is called the "header". - - To indicate the bounds of the header in Plain TeX mode, insert two -special strings in the file: `%**start of header' before the header, -and `%**end of header' after it. Each string must appear entirely on -one line, but there may be other text on the line before or after. The -lines containing the two strings are included in the header. If -`%**start of header' does not appear within the first 100 lines of the -buffer, `C-c C-r' assumes there is no header. - - In LaTeX mode, the header begins with `\documentstyle' and ends with -`\begin{document}'. These are commands that LaTeX requires you to use, -so you don't need to do anything special to identify the header. - - When you enter either kind of TeX mode, Emacs calls with no -arguments the value of the variable `text-mode-hook', if that value -exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook' -and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same -conditions. - - -File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode - -Outline Mode ------------- - - Outline mode is a major mode similar to Text mode but intended for -editing outlines. It allows you to make parts of the text temporarily -invisible so that you can see just the overall structure of the -outline. Type `M-x outline-mode' to turn on Outline mode in the -current buffer. - - When you enter Outline mode, Emacs calls with no arguments the value -of the variable `text-mode-hook', if that value exists and is not -`nil'; then it does the same with the variable `outline-mode-hook'. - - When a line is invisible in outline mode, it does not appear on the -screen. The screen appears exactly as if the invisible line were -deleted, except that an ellipsis (three periods in a row) appears at -the end of the previous visible line (only one ellipsis no matter how -many invisible lines follow). - - All editing commands treat the text of the invisible line as part of -the previous visible line. For example, `C-n' moves onto the next -visible line. Killing an entire visible line, including its -terminating newline, really kills all the following invisible lines as -well; yanking everything back yanks the invisible lines and they remain -invisible. - -* Menu: - -* Format: Outline Format. What the text of an outline looks like. -* Motion: Outline Motion. Special commands for moving through outlines. -* Visibility: Outline Visibility. Commands to control what is visible. -