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
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:
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
* 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.
\1f
-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
=============
toolbar to the same position, it will just not be visible.
\1f
-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.
+
+\1f
+File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
Toolbar Descriptor Format
=========================
* 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.
\1f
-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
============
gutter to the same position, it will just not be visible.
\1f
-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.
+
+\1f
+File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter
Gutter Descriptor Format
========================
File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
Buffer Tabs
-===========
+-----------
Not documented yet.
File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
Progress Bars
-=============
+-------------
Not documented yet.
For information about the OffiX project have a look at
http://leb.net/~offix/
-\1f
-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.
-
-\1f
-File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
-
-MSWindows OLE
--------------
-
- Only allows file drags and drops.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
-
-Drag Interface
-==============
-
- This describes the drag API (not implemented yet).
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
+
+MSWindows OLE
+-------------
+
+ Only allows file drags and drops.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
+
+Drag Interface
+==============
+
+ This describes the drag API (not implemented yet).
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
Major Modes
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::).
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
`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
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
so, which kind. Its value is `nil' for no version control, or a
string that appears in the mode line.
-\1f
-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'.
-
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
Hooks
The last thing `after-find-file' does is call all the functions in
`find-file-hooks'.
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
Reading from Files
completion-ignored-extensions
=> (".o" ".elc" "~" ".dvi")
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
Making Certain File Names "Magic"
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
The Current Buffer
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.
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
`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
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::).
+
\1f
File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: 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).
+
\1f
File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
which is 1 point smaller. Otherwise, it returns the next smaller
version of this font that is defined.
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+
+\1f
File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
Color Instances
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
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'.
\1f
File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
are passed to `make-image-instance'.
* Image Instances:: What an image specifier gets instanced as.
-\1f
-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 `<X11/cursorfont.h>'] 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).
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.)
-
-\1f
-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'.
-
-\1f
-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.)
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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 `<X11/cursorfont.h>'] 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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.)
+
+\1f
+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'.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
Annotation Basics
This function causes an immediate update of the cursor on the
selected frame. (This function does not exist in FSF Emacs.)
-\1f
-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::.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::.
-
-\1f
-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::.
-
-\1f
-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>
-
- ---------- Buffer: foo ----------
- 20
-
- #<buffer foo>
-
- ---------- 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.
-
-\1f
-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)))
-
-\1f
-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::.
-
-\1f
-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.
-
-\1f
-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 "^?"))
-
-\1f
-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::.
-
-\1f
-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::).
-
Foundation instead of in the original English.
\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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>
+
+ ---------- Buffer: foo ----------
+ 20
+
+ #<buffer foo>
+
+ ---------- 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.
+
+\1f
+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)))
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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 "^?"))
+
+\1f
+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::.
+
+\1f
+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::).
+
+\1f
File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
Beeping
FUNCTION may remhash or puthash the entry currently being
processed by FUNCTION.
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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")
- => #<process my-process>
-
- (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
- => #<process my-process<1>>
-
- ---------- 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::).
-
-\1f
-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
-
-\1f
-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)
- => (#<process display-time> #<process shell>)
-
- - 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")
- => #<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 xx<1>>
- (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::).
-
-\1f
-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"
-
-\1f
-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.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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")
+ => #<process my-process>
+
+ (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ => #<process my-process<1>>
+
+ ---------- 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::).
+
+\1f
+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
+
+\1f
+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)
+ => (#<process display-time> #<process shell>)
+
+ - 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")
+ => #<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 xx<1>>
+ (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::).
+
+\1f
+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"
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
Process Buffers
get some output, or `nil' if the timeout expired before output
arrived.
-\1f
-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: #<process shell> had the event `killed'
- => #<process shell>
-
- - 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.
-
-\1f
-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.
-
-\1f
-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::.
-
-\1f
-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).
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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: #<process shell> had the event `killed'
+ => #<process shell>
+
+ - 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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
Time of Day
into others.
* Recording Input:: Saving histories of recent or all input events.
-\1f
-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'.
-
-\1f
-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 `<ESC> 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" `<ESC> O P' to `[pf1]' in `function-key-map',
- when using a VT100.
-
- Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
- P'; later the function `read-key-sequence' translates this back
- into `C-c <PF1>', 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.
-
-\1f
-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::).
-
-\1f
-File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
-
-Terminal Output
-===============
-
- The terminal output functions send output to the terminal or keep
-track of output sent to the terminal. The function `device-baud-rate'
-tells you what XEmacs thinks is the output speed of the terminal.
-
- - Function: device-baud-rate &optional device
- This function's value is the output speed of the terminal
- associated with DEVICE, as far as XEmacs knows. DEVICE defaults
- to the selected device (usually the only device) if omitted.
- Changing this value does not change the speed of actual data
- transmission, but the value is used for calculations such as
- padding. This value has no effect for window-system devices.
- (This is different in FSF Emacs, where the baud rate also affects
- decisions about whether to scroll part of the screen or repaint,
- even when using a window system.)
-
- The value is measured in bits per second.
-
- XEmacs attempts to automatically initialize the baud rate by querying
-the terminal. If you are running across a network, however, and
-different parts of the network work are at different baud rates, the
-value returned by XEmacs may be different from the value used by your
-local terminal. Some network protocols communicate the local terminal
-speed to the remote machine, so that XEmacs and other programs can get
-the proper value, but others do not. If XEmacs has the wrong value, it
-makes decisions that are less than optimal. To fix the problem, use
-`set-device-baud-rate'.
-
- - Function: set-device-baud-rate &optional device
- This function sets the output speed of DEVICE. See
- `device-baud-rate'. DEVICE defaults to the selected device
- (usually the only device) if omitted.
-
- - Function: send-string-to-terminal char-or-string &optional stdout-p
- device
- This function sends CHAR-OR-STRING to the terminal without
- alteration. Control characters in CHAR-OR-STRING have
- terminal-dependent effects.
-
- If DEVICE is `nil', this function writes to XEmacs's stderr, or to
- stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
- tty or stream device, and the function writes to the device's
- normal or error output, according to STDOUT-P.
-
- One use of this function is to define function keys on terminals
- that have downloadable function key definitions. For example,
- this is how on certain terminals to define function key 4 to move
- forward four characters (by transmitting the characters `C-u C-f'
- to the computer):
-
- (send-string-to-terminal "\eF4\^U\^F")
- => nil
-
- - Command: open-termscript filename
- This function is used to open a "termscript file" that will record
- all the characters sent by XEmacs to the terminal. (If there are
- multiple tty or stream devices, all characters sent to all such
- devices are recorded.) The function returns `nil'. Termscript
- files are useful for investigating problems where XEmacs garbles
- the screen, problems that are due to incorrect Termcap entries or
- to undesirable settings of terminal options more often than to
- actual XEmacs bugs. Once you are certain which characters were
- actually output, you can determine reliably whether they
- correspond to the Termcap specifications in use.
-
- A `nil' value for FILENAME stops recording terminal output.
-
- See also `open-dribble-file' in *Note Terminal Input::.
-
- (open-termscript "../junk/termscript")
- => nil
-
-\1f
-File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
-
-Flow Control
-============
-
- This section attempts to answer the question "Why does XEmacs choose
-to use flow-control characters in its command character set?" For a
-second view on this issue, read the comments on flow control in the
-`emacs/INSTALL' file from the distribution; for help with Termcap
-entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
-
- At one time, most terminals did not need flow control, and none used
-`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
-`C-q' as command characters was uncontroversial. XEmacs, for economy
-of keystrokes and portability, used nearly all the ASCII control
-characters, with mnemonic meanings when possible; thus, `C-s' for
-search and `C-q' for quote.
-
- Later, some terminals were introduced which required these characters
-for flow control. They were not very good terminals for full-screen
-editing, so XEmacs maintainers did not pay attention. In later years,
-flow control with `C-s' and `C-q' became widespread among terminals,
-but by this time it was usually an option. And the majority of users,
-who can turn flow control off, were unwilling to switch to less
-mnemonic key bindings for the sake of flow control.
-
- So which usage is "right", XEmacs's or that of some terminal and
-concentrator manufacturers? This question has no simple answer.
-
- One reason why we are reluctant to cater to the problems caused by
-`C-s' and `C-q' is that they are gratuitous. There are other
-techniques (albeit less common in practice) for flow control that
-preserve transparency of the character stream. Note also that their use
-for flow control is not an official standard. Interestingly, on the
-model 33 teletype with a paper tape punch (which is very old), `C-s'
-and `C-q' were sent by the computer to turn the punch on and off!
-
- As X servers and other window systems replace character-only
-terminals, this problem is gradually being cured. For the mean time,
-XEmacs provides a convenient way of enabling flow control if you want
-it: call the function `enable-flow-control'.
-
- - Function: enable-flow-control
- This function enables use of `C-s' and `C-q' for output flow
- control, and provides the characters `C-\' and `C-^' as aliases
- for them using `keyboard-translate-table' (*note Translating
- Input::).
-
- You can use the function `enable-flow-control-on' in your `.emacs'
-file to enable flow control automatically on certain terminal types.
-
- - Function: enable-flow-control-on &rest termtypes
- This function enables flow control, and the aliases `C-\' and
- `C-^', if the terminal type is one of TERMTYPES. For example:
-
- (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
-
- Here is how `enable-flow-control' does its job:
-
- 1. It sets CBREAK mode for terminal input, and tells the operating
- system to handle flow control, with `(set-input-mode nil t)'.
-
- 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
- into `C-s' and `C-q'. Except at its very lowest level, XEmacs
- never knows that the characters typed were anything but `C-s' and
- `C-q', so you can in effect type them as `C-\' and `C-^' even when
- they are input for other commands. *Note Translating Input::.
-
- If the terminal is the source of the flow control characters, then
-once you enable kernel flow control handling, you probably can make do
-with less padding than normal for that terminal. You can reduce the
-amount of padding by customizing the Termcap entry. You can also
-reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
-a smaller speed when calculating the padding needed. *Note Terminal
-Output::.
-
-\1f
-File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
-
-Batch Mode
-==========
-
- The command line option `-batch' causes XEmacs to run
-noninteractively. In this mode, XEmacs does not read commands from the
-terminal, it does not alter the terminal modes, and it does not expect
-to be outputting to an erasable screen. The idea is that you specify
-Lisp programs to run; when they are finished, XEmacs should exit. The
-way to specify the programs to run is with `-l FILE', which loads the
-library named FILE, and `-f FUNCTION', which calls FUNCTION with no
-arguments.
-
- Any Lisp program output that would normally go to the echo area,
-either using `message' or using `prin1', etc., with `t' as the stream,
-goes instead to XEmacs's standard error descriptor when in batch mode.
-Thus, XEmacs behaves much like a noninteractive application program.
-(The echo area output that XEmacs itself normally generates, such as
-command echoing, is suppressed entirely.)
-
- - Function: noninteractive
- This function returns non-`nil' when XEmacs is running in batch
- mode.
-
- - Variable: noninteractive
- This variable is non-`nil' when XEmacs is running in batch mode.
- Setting this variable to `nil', however, will not change whether
- XEmacs is running in batch mode, and will not change the return
- value of the `noninteractive' function.
-
-\1f
-File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
-
-Functions Specific to the X Window System
-*****************************************
-
- XEmacs provides the concept of "devices", which generalizes
-connections to an X server, a TTY device, etc. Most information about
-an X server that XEmacs is connected to can be determined through
-general console and device functions. *Note Consoles and Devices::.
-However, there are some features of the X Window System that do not
-generalize well, and they are covered specially here.
-
-* Menu:
-
-* X Selections:: Transferring text to and from other X clients.
-* X Server:: Information about the X server connected to
- a particular device.
-* X Miscellaneous:: Other X-specific functions and variables.
-
-\1f
-File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
-
-X Selections
-============
-
- The X server records a set of "selections" which permit transfer of
-data between application programs. The various selections are
-distinguished by "selection types", represented in XEmacs by symbols.
-X clients including XEmacs can read or set the selection for any given
-type.
-
- - Function: x-own-selection data &optional type
- This function sets a "selection" in the X server. It takes two
- arguments: a value, DATA, and the selection type TYPE to assign it
- to. DATA may be a string, a cons of two markers, or an extent.
- In the latter cases, the selection is considered to be the text
- between the markers, or between the extent's endpoints.
-
- Each possible TYPE has its own selection value, which changes
- independently. The usual values of TYPE are `PRIMARY' and
- `SECONDARY'; these are symbols with upper-case names, in accord
- with X Windows conventions. The default is `PRIMARY'.
-
- (In FSF Emacs, this function is called `x-set-selection' and takes
- different arguments.)
-
- - Function: x-get-selection
- This function accesses selections set up by XEmacs or by other X
- clients. It returns the value of the current primary selection.
-
- - Function: x-disown-selection &optional secondary-p
- Assuming we own the selection, this function disowns it. If
- SECONDARY-P is non-`nil', the secondary selection instead of the
- primary selection is discarded.
-
- The X server also has a set of numbered "cut buffers" which can
-store text or other data being moved between applications. Cut buffers
-are considered obsolete, but XEmacs supports them for the sake of X
-clients that still use them.
-
- - Function: x-get-cutbuffer &optional n
- This function returns the contents of cut buffer number N. (This
- function is called `x-get-cut-buffer' in FSF Emacs.)
-
- - Function: x-store-cutbuffer string
- This function stores STRING into the first cut buffer (cut buffer
- 0), moving the other values down through the series of cut buffers,
- kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
- Emacs.)
-
-\1f
-File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
-
-X Server
-========
-
- This section describes how to access and change the overall status of
-the X server XEmacs is using.
-
-* Menu:
-
-* Resources:: Getting resource values from the server.
-* Server Data:: Getting info about the X server.
-* Grabs:: Restricting access to the server by other apps.
-
-\1f
-File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
-
-Resources
----------
-
- - Function: default-x-device
- This function return the default X device for resourcing. This is
- the first-created X device that still exists.
-
- - Function: x-get-resource name class type &optional locale device
- noerror
- This function retrieves a resource value from the X resource
- manager.
-
- * The first arg is the name of the resource to retrieve, such as
- `"font"'.
-
- * The second arg is the class of the resource to retrieve, like
- `"Font"'.
-
- * The third arg should be one of the symbols `string',
- `integer', `natnum', or `boolean', specifying the type of
- object that the database is searched for.
-
- * The fourth arg is the locale to search for the resources on,
- and can currently be a a buffer, a frame, a device, or the
- symbol `global'. If omitted, it defaults to `global'.
-
- * The fifth arg is the device to search for the resources on.
- (The resource database for a particular device is constructed
- by combining non-device- specific resources such any
- command-line resources specified and any app-defaults files
- found [or the fallback resources supplied by XEmacs, if no
- app-defaults file is found] with device-specific resources
- such as those supplied using `xrdb'.) If omitted, it defaults
- to the device of LOCALE, if a device can be derived (i.e. if
- LOCALE is a frame or device), and otherwise defaults to the
- value of `default-x-device'.
-
- * The sixth arg NOERROR, if non-`nil', means do not signal an
- error if a bogus resource specification was retrieved (e.g.
- if a non-integer was given when an integer was requested).
- In this case, a warning is issued instead.
-
- The resource names passed to this function are looked up relative
- to the locale.
-
- If you want to search for a subresource, you just need to specify
- the resource levels in NAME and CLASS. For example, NAME could be
- `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
-
- Specifically,
-
- 1. If LOCALE is a buffer, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
- "String");'
-
- 2. If LOCALE is a frame, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
- "String");'
-
- 3. If LOCALE is a device, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
- "String");'
-
- 4. If LOCALE is the symbol `global', a call
-
- `(x-get-resource "foreground" "Foreground" 'string 'global)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.foreground",
- "Emacs.Foreground",
- "String");'
-
- Note that for `global', no prefix is added other than that of the
- application itself; thus, you can use this locale to retrieve
- arbitrary application resources, if you really want to.
-
- The returned value of this function is `nil' if the queried
- resource is not found. If TYPE is `string', a string is returned,
- and if it is `integer', an integer is returned. If TYPE is
- `boolean', then the returned value is the list `(t)' for true,
- `(nil)' for false, and is `nil' to mean "unspecified".
-
- - Function: x-put-resource resource-line &optional device
- This function adds a resource to the resource database for DEVICE.
- RESOURCE-LINE specifies the resource to add and should be a
- standard resource specification.
-
- - Variable: x-emacs-application-class
- This variable holds The X application class of the XEmacs process.
- This controls, among other things, the name of the "app-defaults"
- file that XEmacs will use. For changes to this variable to take
- effect, they must be made before the connection to the X server is
- initialized, that is, this variable may only be changed before
- XEmacs is dumped, or by setting it in the file
- `lisp/term/x-win.el'.
-
- By default, this variable is nil at startup. When the connection
- to the X server is first initialized, the X resource database will
- be consulted and the value will be set according to whether any
- resources are found for the application class "XEmacs".
-
-\1f
-File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
-
-Data about the X Server
------------------------
-
- This section describes functions and a variable that you can use to
-get information about the capabilities and origin of the X server
-corresponding to a particular device. The device argument is generally
-optional and defaults to the selected device.
-
- - Function: x-server-version &optional device
- This function returns the list of version numbers of the X server
- DEVICE is on. The returned value is a list of three integers: the
- major and minor version numbers of the X protocol in use, and the
- vendor-specific release number.
-
- - Function: x-server-vendor &optional device
- This function returns the vendor supporting the X server DEVICE is
- on.
-
- - Function: x-display-visual-class &optional device
- This function returns the visual class of the display DEVICE is
- on. The value is one of the symbols `static-gray', `gray-scale',
- `static-color', `pseudo-color', `true-color', and `direct-color'.
- (Note that this is different from previous versions of XEmacs,
- which returned `StaticGray', `GrayScale', etc.)
-
-\1f
-File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
-
-Restricting Access to the Server by Other Apps
-----------------------------------------------
-
- - Function: x-grab-keyboard &optional device
- This function grabs the keyboard on the given device (defaulting
- to the selected one). So long as the keyboard is grabbed, all
- keyboard events will be delivered to XEmacs--it is not possible
- for other X clients to eavesdrop on them. Ungrab the keyboard
- with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
- if the grab was successful; `nil' otherwise.
-
- - Function: x-ungrab-keyboard &optional device
- This function releases a keyboard grab made with `x-grab-keyboard'.
-
- - Function: x-grab-pointer &optional device cursor ignore-keyboard
- This function grabs the pointer and restricts it to its current
- window. If optional DEVICE argument is `nil', the selected device
- will be used. If optional CURSOR argument is non-`nil', change
- the pointer shape to that until `x-ungrab-pointer' is called (it
- should be an object returned by the `make-cursor' function). If
- the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
- all keyboard events during the grab. Returns `t' if the grab is
- successful, `nil' otherwise.
-
- - Function: x-ungrab-pointer &optional device
- This function releases a pointer grab made with `x-grab-pointer'.
- If optional first arg DEVICE is `nil' the selected device is used.
- If it is `t' the pointer will be released on all X devices.
-
-\1f
-File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
-
-Miscellaneous X Functions and Variables
-=======================================
-
- - Variable: x-bitmap-file-path
- This variable holds a list of the directories in which X bitmap
- files may be found. If `nil', this is initialized from the
- `"*bitmapFilePath"' resource. This is used by the
- `make-image-instance' function (however, note that if the
- environment variable `XBMLANGPATH' is set, it is consulted first).
-
- - Variable: x-library-search-path
- This variable holds the search path used by `read-color' to find
- `rgb.txt'.
-
- - Function: x-valid-keysym-name-p keysym
- This function returns true if KEYSYM names a keysym that the X
- library knows about. Valid keysyms are listed in the files
- `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
- whatever the equivalents are on your system.
-
- - Function: x-window-id &optional frame
- This function returns the ID of the X11 window. This gives us a
- chance to manipulate the Emacs window from within a different
- program. Since the ID is an unsigned long, we return it as a
- string.
-
- - Variable: x-allow-sendevents
- If non-`nil', synthetic events are allowed. `nil' means they are
- ignored. Beware: allowing XEmacs to process SendEvents opens a
- big security hole.
-
- - Function: x-debug-mode arg &optional device
- With a true arg, make the connection to the X server synchronous.
- With false, make it asynchronous. Synchronous connections are
- much slower, but are useful for debugging. (If you get X errors,
- make the connection synchronous, and use a debugger to set a
- breakpoint on `x_error_handler'. Your backtrace of the C stack
- will now be useful. In asynchronous mode, the stack above
- `x_error_handler' isn't helpful because of buffering.) If DEVICE
- is not specified, the selected device is assumed.
-
- Calling this function is the same as calling the C function
- `XSynchronize', or starting the program with the `-sync' command
- line argument.
-
- - Variable: x-debug-events
- If non-zero, debug information about events that XEmacs sees is
- displayed. Information is displayed on stderr. Currently defined
- values are:
-
- * 1 == non-verbose output
-
- * 2 == verbose output
-
-\1f
-File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
-
-ToolTalk Support
-****************
-
-* Menu:
-
-* XEmacs ToolTalk API Summary::
-* Sending Messages::
-* Receiving Messages::
-
-\1f
-File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
-
-XEmacs ToolTalk API Summary
-===========================
-
- The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
-to the standard C ToolTalk API. Only the message and pattern parts of
-the API are supported at present; more of the API could be added if
-needed. The Lisp interface departs from the C API in a few ways:
-
- * ToolTalk is initialized automatically at XEmacs startup-time.
- Messages can only be sent other ToolTalk applications connected to
- the same X11 server that XEmacs is running on.
-
- * There are fewer entry points; polymorphic functions with keyword
- arguments are used instead.
-
- * The callback interface is simpler and marginally less functional.
- A single callback may be associated with a message or a pattern;
- the callback is specified with a Lisp symbol (the symbol should
- have a function binding).
-
- * The session attribute for messages and patterns is always
- initialized to the default session.
-
- * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
- can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
- simplifies building lists that represent messages and patterns.
-
-\1f
-File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
-
-Sending Messages
-================
-
-* Menu:
-
-* Example of Sending Messages::
-* Elisp Interface for Sending Messages::
-
-\1f
-File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
-
-Example of Sending Messages
----------------------------
-
- Here's a simple example that sends a query to another application
-and then displays its reply. Both the query and the reply are stored
-in the first argument of the message.
-
- (defun tooltalk-random-query-handler (msg)
- (let ((state (get-tooltalk-message-attribute msg 'state)))
- (cond
- ((eq state 'TT_HANDLED)
- (message (get-tooltalk-message-attribute msg arg_val 0)))
- ((memq state '(TT_FAILED TT_REJECTED))
- (message "Random query turns up nothing")))))
-
- (defvar random-query-message
- '( class TT_REQUEST
- scope TT_SESSION
- address TT_PROCEDURE
- op "random-query"
- args '((TT_INOUT "?" "string"))
- callback tooltalk-random-query-handler))
-
- (let ((m (make-tooltalk-message random-query-message)))
- (send-tooltalk-message m))
-
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
+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 `<ESC> 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" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', 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.
+
+\1f
+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::).
+
+\1f
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+
+Terminal Output
+===============
+
+ The terminal output functions send output to the terminal or keep
+track of output sent to the terminal. The function `device-baud-rate'
+tells you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional device
+ This function's value is the output speed of the terminal
+ associated with DEVICE, as far as XEmacs knows. DEVICE defaults
+ to the selected device (usually the only device) if omitted.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not. If XEmacs has the wrong value, it
+makes decisions that are less than optimal. To fix the problem, use
+`set-device-baud-rate'.
+
+ - Function: set-device-baud-rate &optional device
+ This function sets the output speed of DEVICE. See
+ `device-baud-rate'. DEVICE defaults to the selected device
+ (usually the only device) if omitted.
+
+ - Function: send-string-to-terminal char-or-string &optional stdout-p
+ device
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
+ => nil
+
+ - Command: open-termscript filename
+ This function is used to open a "termscript file" that will record
+ all the characters sent by XEmacs to the terminal. (If there are
+ multiple tty or stream devices, all characters sent to all such
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
+ => nil
+
+\1f
+File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
+
+Flow Control
+============
+
+ This section attempts to answer the question "Why does XEmacs choose
+to use flow-control characters in its command character set?" For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+ At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial. XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+ Later, some terminals were introduced which required these characters
+for flow control. They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention. In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option. And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+ So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers? This question has no simple answer.
+
+ One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous. There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream. Note also that their use
+for flow control is not an official standard. Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+XEmacs provides a convenient way of enabling flow control if you want
+it: call the function `enable-flow-control'.
+
+ - Function: enable-flow-control
+ This function enables use of `C-s' and `C-q' for output flow
+ control, and provides the characters `C-\' and `C-^' as aliases
+ for them using `keyboard-translate-table' (*note Translating
+ Input::).
+
+ You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest termtypes
+ This function enables flow control, and the aliases `C-\' and
+ `C-^', if the terminal type is one of TERMTYPES. For example:
+
+ (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+ Here is how `enable-flow-control' does its job:
+
+ 1. It sets CBREAK mode for terminal input, and tells the operating
+ system to handle flow control, with `(set-input-mode nil t)'.
+
+ 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+ into `C-s' and `C-q'. Except at its very lowest level, XEmacs
+ never knows that the characters typed were anything but `C-s' and
+ `C-q', so you can in effect type them as `C-\' and `C-^' even when
+ they are input for other commands. *Note Translating Input::.
+
+ If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal. You can reduce the
+amount of padding by customizing the Termcap entry. You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed. *Note Terminal
+Output::.
+
+\1f
+File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
+
+Batch Mode
+==========
+
+ The command line option `-batch' causes XEmacs to run
+noninteractively. In this mode, XEmacs does not read commands from the
+terminal, it does not alter the terminal modes, and it does not expect
+to be outputting to an erasable screen. The idea is that you specify
+Lisp programs to run; when they are finished, XEmacs should exit. The
+way to specify the programs to run is with `-l FILE', which loads the
+library named FILE, and `-f FUNCTION', which calls FUNCTION with no
+arguments.
+
+ Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+ This function returns non-`nil' when XEmacs is running in batch
+ mode.
+
+ - Variable: noninteractive
+ This variable is non-`nil' when XEmacs is running in batch mode.
+ Setting this variable to `nil', however, will not change whether
+ XEmacs is running in batch mode, and will not change the return
+ value of the `noninteractive' function.
+
+\1f
+File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
+
+Functions Specific to the X Window System
+*****************************************
+
+ XEmacs provides the concept of "devices", which generalizes
+connections to an X server, a TTY device, etc. Most information about
+an X server that XEmacs is connected to can be determined through
+general console and device functions. *Note Consoles and Devices::.
+However, there are some features of the X Window System that do not
+generalize well, and they are covered specially here.
+
+* Menu:
+
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* X Miscellaneous:: Other X-specific functions and variables.
+
+\1f
+File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
+
+X Selections
+============
+
+ The X server records a set of "selections" which permit transfer of
+data between application programs. The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection data &optional type
+ This function sets a "selection" in the X server. It takes two
+ arguments: a value, DATA, and the selection type TYPE to assign it
+ to. DATA may be a string, a cons of two markers, or an extent.
+ In the latter cases, the selection is considered to be the text
+ between the markers, or between the extent's endpoints.
+
+ Each possible TYPE has its own selection value, which changes
+ independently. The usual values of TYPE are `PRIMARY' and
+ `SECONDARY'; these are symbols with upper-case names, in accord
+ with X Windows conventions. The default is `PRIMARY'.
+
+ (In FSF Emacs, this function is called `x-set-selection' and takes
+ different arguments.)
+
+ - Function: x-get-selection
+ This function accesses selections set up by XEmacs or by other X
+ clients. It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional secondary-p
+ Assuming we own the selection, this function disowns it. If
+ SECONDARY-P is non-`nil', the secondary selection instead of the
+ primary selection is discarded.
+
+ The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications. Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional n
+ This function returns the contents of cut buffer number N. (This
+ function is called `x-get-cut-buffer' in FSF Emacs.)
+
+ - Function: x-store-cutbuffer string
+ This function stores STRING into the first cut buffer (cut buffer
+ 0), moving the other values down through the series of cut buffers,
+ kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
+ Emacs.)
+
+\1f
+File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
+
+X Server
+========
+
+ This section describes how to access and change the overall status of
+the X server XEmacs is using.
+
+* Menu:
+
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
+
+\1f
+File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
+
+Resources
+---------
+
+ - Function: default-x-device
+ This function return the default X device for resourcing. This is
+ the first-created X device that still exists.
+
+ - Function: x-get-resource name class type &optional locale device
+ noerror
+ This function retrieves a resource value from the X resource
+ manager.
+
+ * The first arg is the name of the resource to retrieve, such as
+ `"font"'.
+
+ * The second arg is the class of the resource to retrieve, like
+ `"Font"'.
+
+ * The third arg should be one of the symbols `string',
+ `integer', `natnum', or `boolean', specifying the type of
+ object that the database is searched for.
+
+ * The fourth arg is the locale to search for the resources on,
+ and can currently be a a buffer, a frame, a device, or the
+ symbol `global'. If omitted, it defaults to `global'.
+
+ * The fifth arg is the device to search for the resources on.
+ (The resource database for a particular device is constructed
+ by combining non-device- specific resources such any
+ command-line resources specified and any app-defaults files
+ found [or the fallback resources supplied by XEmacs, if no
+ app-defaults file is found] with device-specific resources
+ such as those supplied using `xrdb'.) If omitted, it defaults
+ to the device of LOCALE, if a device can be derived (i.e. if
+ LOCALE is a frame or device), and otherwise defaults to the
+ value of `default-x-device'.
+
+ * The sixth arg NOERROR, if non-`nil', means do not signal an
+ error if a bogus resource specification was retrieved (e.g.
+ if a non-integer was given when an integer was requested).
+ In this case, a warning is issued instead.
+
+ The resource names passed to this function are looked up relative
+ to the locale.
+
+ If you want to search for a subresource, you just need to specify
+ the resource levels in NAME and CLASS. For example, NAME could be
+ `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
+
+ Specifically,
+
+ 1. If LOCALE is a buffer, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+ "String");'
+
+ 2. If LOCALE is a frame, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+ "String");'
+
+ 3. If LOCALE is a device, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+ "String");'
+
+ 4. If LOCALE is the symbol `global', a call
+
+ `(x-get-resource "foreground" "Foreground" 'string 'global)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.foreground",
+ "Emacs.Foreground",
+ "String");'
+
+ Note that for `global', no prefix is added other than that of the
+ application itself; thus, you can use this locale to retrieve
+ arbitrary application resources, if you really want to.
+
+ The returned value of this function is `nil' if the queried
+ resource is not found. If TYPE is `string', a string is returned,
+ and if it is `integer', an integer is returned. If TYPE is
+ `boolean', then the returned value is the list `(t)' for true,
+ `(nil)' for false, and is `nil' to mean "unspecified".
+
+ - Function: x-put-resource resource-line &optional device
+ This function adds a resource to the resource database for DEVICE.
+ RESOURCE-LINE specifies the resource to add and should be a
+ standard resource specification.
+
+ - Variable: x-emacs-application-class
+ This variable holds The X application class of the XEmacs process.
+ This controls, among other things, the name of the "app-defaults"
+ file that XEmacs will use. For changes to this variable to take
+ effect, they must be made before the connection to the X server is
+ initialized, that is, this variable may only be changed before
+ XEmacs is dumped, or by setting it in the file
+ `lisp/term/x-win.el'.
+
+ By default, this variable is nil at startup. When the connection
+ to the X server is first initialized, the X resource database will
+ be consulted and the value will be set according to whether any
+ resources are found for the application class "XEmacs".
+
+\1f
+File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
+
+Data about the X Server
+-----------------------
+
+ This section describes functions and a variable that you can use to
+get information about the capabilities and origin of the X server
+corresponding to a particular device. The device argument is generally
+optional and defaults to the selected device.
+
+ - Function: x-server-version &optional device
+ This function returns the list of version numbers of the X server
+ DEVICE is on. The returned value is a list of three integers: the
+ major and minor version numbers of the X protocol in use, and the
+ vendor-specific release number.
+
+ - Function: x-server-vendor &optional device
+ This function returns the vendor supporting the X server DEVICE is
+ on.
+
+ - Function: x-display-visual-class &optional device
+ This function returns the visual class of the display DEVICE is
+ on. The value is one of the symbols `static-gray', `gray-scale',
+ `static-color', `pseudo-color', `true-color', and `direct-color'.
+ (Note that this is different from previous versions of XEmacs,
+ which returned `StaticGray', `GrayScale', etc.)
+
+\1f
+File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
+
+Restricting Access to the Server by Other Apps
+----------------------------------------------
+
+ - Function: x-grab-keyboard &optional device
+ This function grabs the keyboard on the given device (defaulting
+ to the selected one). So long as the keyboard is grabbed, all
+ keyboard events will be delivered to XEmacs--it is not possible
+ for other X clients to eavesdrop on them. Ungrab the keyboard
+ with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
+ if the grab was successful; `nil' otherwise.
+
+ - Function: x-ungrab-keyboard &optional device
+ This function releases a keyboard grab made with `x-grab-keyboard'.
+
+ - Function: x-grab-pointer &optional device cursor ignore-keyboard
+ This function grabs the pointer and restricts it to its current
+ window. If optional DEVICE argument is `nil', the selected device
+ will be used. If optional CURSOR argument is non-`nil', change
+ the pointer shape to that until `x-ungrab-pointer' is called (it
+ should be an object returned by the `make-cursor' function). If
+ the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
+ all keyboard events during the grab. Returns `t' if the grab is
+ successful, `nil' otherwise.
+
+ - Function: x-ungrab-pointer &optional device
+ This function releases a pointer grab made with `x-grab-pointer'.
+ If optional first arg DEVICE is `nil' the selected device is used.
+ If it is `t' the pointer will be released on all X devices.
+
+\1f
+File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
+
+Miscellaneous X Functions and Variables
+=======================================
+
+ - Variable: x-bitmap-file-path
+ This variable holds a list of the directories in which X bitmap
+ files may be found. If `nil', this is initialized from the
+ `"*bitmapFilePath"' resource. This is used by the
+ `make-image-instance' function (however, note that if the
+ environment variable `XBMLANGPATH' is set, it is consulted first).
+
+ - Variable: x-library-search-path
+ This variable holds the search path used by `read-color' to find
+ `rgb.txt'.
+
+ - Function: x-valid-keysym-name-p keysym
+ This function returns true if KEYSYM names a keysym that the X
+ library knows about. Valid keysyms are listed in the files
+ `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
+ whatever the equivalents are on your system.
+
+ - Function: x-window-id &optional frame
+ This function returns the ID of the X11 window. This gives us a
+ chance to manipulate the Emacs window from within a different
+ program. Since the ID is an unsigned long, we return it as a
+ string.
+
+ - Variable: x-allow-sendevents
+ If non-`nil', synthetic events are allowed. `nil' means they are
+ ignored. Beware: allowing XEmacs to process SendEvents opens a
+ big security hole.
+
+ - Function: x-debug-mode arg &optional device
+ With a true arg, make the connection to the X server synchronous.
+ With false, make it asynchronous. Synchronous connections are
+ much slower, but are useful for debugging. (If you get X errors,
+ make the connection synchronous, and use a debugger to set a
+ breakpoint on `x_error_handler'. Your backtrace of the C stack
+ will now be useful. In asynchronous mode, the stack above
+ `x_error_handler' isn't helpful because of buffering.) If DEVICE
+ is not specified, the selected device is assumed.
+
+ Calling this function is the same as calling the C function
+ `XSynchronize', or starting the program with the `-sync' command
+ line argument.
+
+ - Variable: x-debug-events
+ If non-zero, debug information about events that XEmacs sees is
+ displayed. Information is displayed on stderr. Currently defined
+ values are:
+
+ * 1 == non-verbose output
+
+ * 2 == verbose output
+
+\1f
+File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
+
+ToolTalk Support
+****************
+
+* Menu:
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
+
+\1f
+File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
+
+XEmacs ToolTalk API Summary
+===========================
+
+ The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
+to the standard C ToolTalk API. Only the message and pattern parts of
+the API are supported at present; more of the API could be added if
+needed. The Lisp interface departs from the C API in a few ways:
+
+ * ToolTalk is initialized automatically at XEmacs startup-time.
+ Messages can only be sent other ToolTalk applications connected to
+ the same X11 server that XEmacs is running on.
+
+ * There are fewer entry points; polymorphic functions with keyword
+ arguments are used instead.
+
+ * The callback interface is simpler and marginally less functional.
+ A single callback may be associated with a message or a pattern;
+ the callback is specified with a Lisp symbol (the symbol should
+ have a function binding).
+
+ * The session attribute for messages and patterns is always
+ initialized to the default session.
+
+ * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
+ can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
+ simplifies building lists that represent messages and patterns.
+
+\1f
+File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
+
+Sending Messages
+================
+
+* Menu:
+
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
+
+\1f
+File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
+
+Example of Sending Messages
+---------------------------
+
+ Here's a simple example that sends a query to another application
+and then displays its reply. Both the query and the reply are stored
+in the first argument of the message.
+
+ (defun tooltalk-random-query-handler (msg)
+ (let ((state (get-tooltalk-message-attribute msg 'state)))
+ (cond
+ ((eq state 'TT_HANDLED)
+ (message (get-tooltalk-message-attribute msg arg_val 0)))
+ ((memq state '(TT_FAILED TT_REJECTED))
+ (message "Random query turns up nothing")))))
+
+ (defvar random-query-message
+ '( class TT_REQUEST
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "random-query"
+ args '((TT_INOUT "?" "string"))
+ callback tooltalk-random-query-handler))
+
+ (let ((m (make-tooltalk-message random-query-message)))
+ (send-tooltalk-message m))
+
+\1f
File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
Elisp Interface for Sending Messages
* The Low-Level LDAP API:: Low-level LDAP lisp primitives
* LDAP Internationalization:: I18n variables and functions
-\1f
-File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
-
-LDAP Variables
---------------
-
- - Variable: ldap-default-host
- The default LDAP server hostname. A TCP port number can be
- appended to that name using a colon as a separator.
-
- - Variable: ldap-default-port
- Default TCP port for LDAP connections. Initialized from the LDAP
- library. Default value is 389.
-
- - Variable: ldap-default-base
- Default base for LDAP searches. This is a string using the syntax
- of RFC 1779. For instance, "o=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'.
-
-\1f
-File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
-
-The High-Level LDAP API
------------------------
-
- 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.
-
-\1f
-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::
-
-\1f
-File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
-
-The LDAP Lisp Object
-....................
-
- An internal built-in `ldap' lisp object represents a LDAP connection.
-
- - Function: ldapp object
- This function returns non-`nil' if OBJECT is a `ldap' object.
-
- - Function: ldap-host ldap
- Return the server host of the connection represented by LDAP
-
- - Function: ldap-live-p ldap
- Return non-`nil' if LDAP is an active LDAP connection
-
-\1f
-File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: 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
-
-\1f
-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
-
-\1f
-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::
-
-\1f
-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
-
-\1f
-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
-
-\1f
-File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
-
-Syntax of Search Filters
-========================
-
- LDAP search functions use RFC1558 syntax to describe the search
-filter. In that syntax simple filters have the form:
-
- (<attr> <filtertype> <value>)
-
- `<attr>' is an attribute name such as `cn' for Common Name, `o' for
-Organization, etc...
-
- `<value>' is the corresponding value. This is generally an exact
-string but may also contain `*' characters as wildcards
-
- `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
-equality, approximate equality, inferiority and superiority.
-
- Thus `(cn=John Smith)' matches all records having a canonical name
-equal to John Smith.
-
- A special case is the presence filter `(<attr>=*' which matches
-records containing a particular attribute. For instance `(mail=*)'
-matches all records containing a `mail' attribute.
-
- Simple filters can be connected together with the logical operators
-`&', `|' and `!' which stand for the usual and, or and not operators.
-
- `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
-matches records of class `Person' containing a `mail' attribute and
-corresponding to people whose last name is `Smith' or whose first name
-is `John'.
-
-\1f
-File: lispref.info, Node: 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::
-
-\1f
-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
-(<ftp://ftp.xemacs.org/>), 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.
-
-\1f
-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::
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
+
+LDAP Variables
+--------------
+
+ - Variable: ldap-default-host
+ The default LDAP server hostname. A TCP port number can be
+ appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+ Default TCP port for LDAP connections. Initialized from the LDAP
+ library. Default value is 389.
+
+ - Variable: ldap-default-base
+ Default base for LDAP searches. This is a string using the syntax
+ of RFC 1779. For instance, "o=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'.
+
+\1f
+File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
+
+The High-Level LDAP API
+-----------------------
+
+ 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.
+
+\1f
+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::
+
+\1f
+File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
+
+The LDAP Lisp Object
+....................
+
+ An internal built-in `ldap' lisp object represents a LDAP connection.
+
+ - Function: ldapp object
+ This function returns non-`nil' if OBJECT is a `ldap' object.
+
+ - Function: ldap-host ldap
+ Return the server host of the connection represented by LDAP
+
+ - Function: ldap-live-p ldap
+ Return non-`nil' if LDAP is an active LDAP connection
+
+\1f
+File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: 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
+
+\1f
+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
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+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
+
+\1f
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
+
+Syntax of Search Filters
+========================
+
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
+
+ (<attr> <filtertype> <value>)
+
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
+
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
+
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
+
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
+
+ A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute. For instance `(mail=*)'
+matches all records containing a `mail' attribute.
+
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
+
+ `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
+matches records of class `Person' containing a `mail' attribute and
+corresponding to people whose last name is `Smith' or whose first name
+is `John'.
+
+\1f
+File: lispref.info, Node: 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::
+
+\1f
+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
+(<ftp://ftp.xemacs.org/>), 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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
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
The data is returned as a list of lists, where each sublist
contains info regarding a single option.
-\1f
-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.
-
-\1f
-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
- => #<PGconn localhost:25432 steve/steve>
-
- 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
- => #<PGconn localhost:25432 steve/steve>
-
- 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
- => (#<PGresult PGRES_TUPLES_OK - SELECT>)
-
- 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
- => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
-
- 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;"))
- => #<PGresult PGRES_TUPLES_OK - SELECT>
- (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
- => #<PGresult PGRES_COMMAND_OK - COMMIT>
-
-\1f
-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.
-
-\1f
-File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
-
-I18N Levels 1 and 2
-===================
-
- XEmacs is now compliant with I18N levels 1 and 2. Specifically,
-this means that it is 8-bit clean and correctly handles time and date
-functions. XEmacs will correctly display the entire ISO-Latin 1
-character set.
-
- The compose key may now be used to create any character in the
-ISO-Latin 1 character set not directly available via the keyboard.. In
-order for the compose key to work it is necessary to load the file
-`x-compose.el'. At any time while composing a character, `C-h' will
-display all valid completions and the character which would be produced.
-
-\1f
-File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
-
-I18N Level 3
-============
-
-* Menu:
-
-* Level 3 Basics::
-* Level 3 Primitives::
-* Dynamic Messaging::
-* Domain Specification::
-* Documentation String Extraction::
-
-\1f
-File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
-
-Level 3 Basics
---------------
-
- XEmacs now provides alpha-level functionality for I18N Level 3.
-This means that everything necessary for full messaging is available,
-but not every file has been converted.
-
- The two message files which have been created are `src/emacs.po' and
-`lisp/packages/mh-e.po'. Both files need to be converted using
-`msgfmt', and the resulting `.mo' files placed in some locale's
-`LC_MESSAGES' directory. The test "translations" in these files are
-the original messages prefixed by `TRNSLT_'.
-
- The domain for a variable is stored on the variable's property list
-under the property name VARIABLE-DOMAIN. The function
-`documentation-property' uses this information when translating a
-variable's documentation.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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")
-
-\1f
-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.)
-
-\1f
-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::.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+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
+ => #<PGconn localhost:25432 steve/steve>
+
+ 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
+ => #<PGconn localhost:25432 steve/steve>
+
+ 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
+ => (#<PGresult PGRES_TUPLES_OK - SELECT>)
+
+ 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
+ => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
+
+ 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;"))
+ => #<PGresult PGRES_TUPLES_OK - SELECT>
+ (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
+ => #<PGresult PGRES_COMMAND_OK - COMMIT>
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+
+I18N Levels 1 and 2
+===================
+
+ XEmacs is now compliant with I18N levels 1 and 2. Specifically,
+this means that it is 8-bit clean and correctly handles time and date
+functions. XEmacs will correctly display the entire ISO-Latin 1
+character set.
+
+ The compose key may now be used to create any character in the
+ISO-Latin 1 character set not directly available via the keyboard.. In
+order for the compose key to work it is necessary to load the file
+`x-compose.el'. At any time while composing a character, `C-h' will
+display all valid completions and the character which would be produced.
+
+\1f
+File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+
+I18N Level 3
+============
+
+* Menu:
+
+* Level 3 Basics::
+* Level 3 Primitives::
+* Dynamic Messaging::
+* Domain Specification::
+* Documentation String Extraction::
+
+\1f
+File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
+
+Level 3 Basics
+--------------
+
+ XEmacs now provides alpha-level functionality for I18N Level 3.
+This means that everything necessary for full messaging is available,
+but not every file has been converted.
+
+ The two message files which have been created are `src/emacs.po' and
+`lisp/packages/mh-e.po'. Both files need to be converted using
+`msgfmt', and the resulting `.mo' files placed in some locale's
+`LC_MESSAGES' directory. The test "translations" in these files are
+the original messages prefixed by `TRNSLT_'.
+
+ The domain for a variable is stored on the variable's property list
+under the property name VARIABLE-DOMAIN. The function
+`documentation-property' uses this information when translating a
+variable's documentation.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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")
+
+\1f
+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.)
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE
Internationalization Terminology
encodings.
* Predefined Coding Systems:: Coding systems implemented by MULE.
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.)
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.)
+
+\1f
File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
Coding System Properties
successfully, and returns to caller (which may be a CCL program). It
does not alter the status of the registers.
-\1f
-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.
-
-\1f
-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.
-
-\1f
-File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
-
-CCL Examples
-------------
-
- This section is not yet written.
-
-\1f
-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.
-
-\1f
-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.
-
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+
+CCL Examples
+------------
+
+ This section is not yet written.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
Writing Clean Lisp Programs
You should not change this flag in a running XEmacs.
-\1f
-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'.
-
-\1f
-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::.
-
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
+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::.
+
+\1f
File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top
Buffer-Local Variables
* 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.
* 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.
* 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.
* 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.
* 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.
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
Format of Outlines
mark. The command `C-M-\' (`indent-region') applies <TAB> to every
line whose first character is between point and mark.
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
Customizing C Indentation
Move to beginning of current or previous statement (`fortran-
previous-statement').
-\1f
-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.
-
-\1f
-File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
-
-Fortran Indentation Commands
-............................
-
-`<TAB>'
- Indent the current line (`fortran-indent-line').
-
-`M-<LFD>'
- 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').
-
- <TAB> 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-<LFD>' 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.
-
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
+
+Fortran Indentation Commands
+............................
+
+`<TAB>'
+ Indent the current line (`fortran-indent-line').
+
+`M-<LFD>'
+ 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').
+
+ <TAB> 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-<LFD>' 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.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
Syntactic Conventions
necessary to build distribution tarballs (Unix Tar format files,
gzipped for space savings).
-\1f
-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 `<package-name>-<version>-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 <RET> 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.
-
-`<RET>'
-`<Mouse-2>'
- Toggle between selecting and unselecting a package for
- installation.
-
-`x'
- Install selected packages.
-
-`<SPC>'
- 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 <return>
-
- 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.
-
-
translation approved by the author instead of in the original English.
\1f
+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 `<package-name>-<version>-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 <RET> 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.
+
+`<RET>'
+`<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
+
+`x'
+ Install selected packages.
+
+`<SPC>'
+ 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 <return>
+
+ 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.
+
+
+\1f
File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
Source packages are available from the `packages/source-packages'
* Diary:: Displaying events from your diary.
* Calendar Customization:: Altering the behavior of the features above.
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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').
-
-\1f
-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'
-`<NEXT>'
- Scroll calendar three months forward
- (`scroll-calendar-left-three-months').
-
-`M-v'
-`<PRIOR>'
- 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 <NEXT> and <PRIOR> are equivalent to `C-v' and
-`M-v', just as they are in other modes.
-
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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'
+`<NEXT>'
+ Scroll calendar three months forward
+ (`scroll-calendar-left-three-months').
+
+`M-v'
+`<PRIOR>'
+ 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 <NEXT> and <PRIOR> are equivalent to `C-v' and
+`M-v', just as they are in other modes.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary
Miscellaneous Calendar Commands
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.
-\1f
-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.
-
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
Customizing the Holidays
For example, `C-c C-x o' invokes the global binding of `C-x o',
which is normally `other-window'.
-\1f
-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.
-
-\1f
-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::.
-
-\1f
-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'.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
Recursive Editing Levels
the keyboard macro, so that the macro is reassigned the same keys when
you load the file.
-\1f
-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 <SPC>, <DEL>, `C-d',
-`C-l', and `C-r'. Any other character terminates execution of the
-keyboard macro and is then read as a command. <SPC> means to continue.
-<DEL> 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 <SPC> 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::.
-
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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 <SPC>, <DEL>, `C-d',
+`C-l', and `C-r'. Any other character terminates execution of the
+keyboard macro and is then read as a command. <SPC> means to continue.
+<DEL> 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 <SPC> 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::.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
Keymaps
possible to set the iconic flag on particular frames (by name) by using
the `Emacs*FRAME-NAME.iconic' resource.
-\1f
-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'.
-
translation approved by the author instead of in the original English.
\1f
+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'.
+
+\1f
File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
Face Resources
* ? (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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* TAB (Shell mode): Shell Mode.
* u (Calendar mode) <1>: Diary Commands.
* u (Calendar mode): Holidays.
-* UP: Basic.
+* UP: Moving Point.
* x (Calendar mode): Holidays.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* holiday forms: Holiday Customizing.
* holidays: Holidays.
* horizontal scrolling: Horizontal Scrolling.
+* Icomplete mode: Completion Options.
* ignoriginal: Dissociated Press.
* indentation <1>: Comments.
* indentation <2>: Grinding.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
translation approved by the author instead of in the original English.
\1f
+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-<SPC>' (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-<SPC>' 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-<SPC>' 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.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top
Additional Mouse Operations
* Selective Display:: Hiding lines with lots of indentation.
* Display Vars:: Information on variables for customizing display.
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
Horizontal Scrolling
that is a correctly spelled English word. It prints a message giving
the answer in the echo area.
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
File Names
Log mode, which involves running two hooks: `text-mode-hook' and
`vc-log-mode-hook'.
-\1f
-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'.
-
translation approved by the author instead of in the original English.
\1f
+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'.
+
+\1f
File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
Examining And Comparing Old Versions
`switch-to-buffer-other-window' and `find-file-other-window' work using
this function.
-\1f
-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.
-
-\1f
-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.
-
translation approved by the author instead of in the original English.
\1f
+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.
+
+\1f
+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.
+
+\1f
File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
Introduction to world scripts
`\begin'). A blank line is inserted between the two, and point is left
there.
-\1f
-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.
-
-\1f
-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.
-
projects / chise / xemacs-chise.git- / commitdiff