-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
+File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
+
+Annotation Basics
+=================
+
+ Marginal annotations are notes associated with a particular location
+in a buffer. They may be displayed in a margin created on the
+left-hand or right-hand side of the frame, in any whitespace at the
+beginning or end of a line, or inside of the text itself. Every
+annotation may have an associated action to be performed when the
+annotation is selected. The term "annotation" is used to refer to an
+individual note. The term "margin" is generically used to refer to the
+whitespace before the first character on a line or after the last
+character on a line.
+
+ Each annotation has the following characteristics:
+GLYPH
+ This is a glyph object and is used as the displayed representation
+ of the annotation.
+
+DOWN-GLYPH
+ If given, this glyph is used as the displayed representation of
+ the annotation when the mouse is pressed down over the annotation.
+
+FACE
+ The face with which to display the glyph.
+
+SIDE
+ Which side of the text (left or right) the annotation is displayed
+ at.
+
+ACTION
+ If non-`nil', this field must contain a function capable of being
+ the first argument to `funcall'. This function is normally
+ evaluated with a single argument, the value of the DATA field,
+ each time the annotation is selected. However, if the WITH-EVENT
+ parameter to `make-annotation' is non-`nil', the function is
+ called with two arguments. The first argument is the same as
+ before, and the second argument is the event (a button-up event,
+ usually) that activated the annotation.
+
+DATA
+ Not used internally. This field can contain any E-Lisp object.
+ It is passed as the first argument to ACTION described above.
+
+MENU
+ A menu displayed when the right mouse button is pressed over the
+ annotation.
+
+ The margin is divided into "outside" and "inside". The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in. The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+ There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+ The annotation is placed in the outside margin area. as close as
+ possible to the edge of the frame. If the outside margin is not
+ wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+ The annotation is placed in the inside margin area, as close as
+ possible to the edge of the frame. If the inside margin is not
+ wide enough for the annotation to fit, it will be displayed using
+ any available outside margin space if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`whitespace'
+ The annotation is placed in the inside margin area, as close as
+ possible to the first or last non-whitespace character on a line.
+ If the inside margin is not wide enough for the annotation to fit,
+ it will be displayed if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`text'
+ The annotation is placed at the position it is inserted. It will
+ create enough space for itself inside of the text area. It does
+ not take up a place in the logical buffer, only in the display of
+ the buffer.
+
+ The current layout policy is that all `whitespace' annotations are
+displayed first. Next, all `inside-margin' annotations are displayed
+using any remaining space. Finally as many `outside-margin'
+annotations are displayed as possible. The `text' annotations will
+always display as they create their own space to display in.
-Working With a Database
-=======================
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+
+Annotation Primitives
+=====================
- - 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: make-annotation glyph &optional position layout buffer
+ with-event d-glyph rightp
+ This function creates a marginal annotation at position POSITION in
+ BUFFER. The annotation is displayed using GLYPH, which should be
+ a glyph object or a string, and is positioned using layout policy
+ LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
+ `whitespace' is used. If BUFFER is `nil', the current buffer is
+ used.
- - 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.
+ If WITH-EVENT is non-`nil', then when an annotation is activated,
+ the triggering event is passed as the second arg to the annotation
+ function. If D-GLYPH is non-`nil' then it is used as the glyph
+ that will be displayed when button1 is down. If RIGHTP is
+ non-`nil' then the glyph will be displayed on the right side of
+ the buffer instead of the left.
- - 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.
+ The newly created annotation is returned.
- - Function: remove-database KEY DBASE
- This function removes KEY from DATABASE.
+ - Function: delete-annotation annotation
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
+
+ - Function: annotationp annotation
+ This function returns `t' if ANNOTATION is an annotation, `nil'
+ otherwise.
\1f
-File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
-Other Database Functions
-========================
+Annotation Properties
+=====================
- - Function: database-file-name OBJ
- This function returns the filename associated with the database
- OBJ.
+ - Function: annotation-glyph annotation
+ This function returns the glyph object used to display ANNOTATION.
- - Function: database-last-error &optional OBJ
- This function returns the last error associated with database OBJ.
+ - Function: set-annotation-glyph annotation glyph &optional layout side
+ This function sets the glyph of ANNOTATION to GLYPH, which should
+ be a glyph object. If LAYOUT is non-`nil', set the layout policy
+ of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
+ side of the buffer at which the annotation is displayed to the
+ given side. The new value of `annotation-glyph' is returned.
- - Function: database-subtype OBJ
- This function returns the subtype of database OBJ, if any.
+ - Function: annotation-down-glyph annotation
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation.
- - Function: database-type OBJ
- This function returns the type of database OBJ.
+ - Function: set-annotation-down-glyph annotation glyph
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation to GLYPH,
+ which should be a glyph object.
-\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.
+ - Function: annotation-face annotation
+ This function returns the face associated with ANNOTATION.
-* Menu:
+ - Function: set-annotation-face annotation face
+ This function sets the face associated with ANNOTATION to FACE.
-* 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.
+ - Function: annotation-layout annotation
+ This function returns the layout policy of ANNOTATION.
-\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.
+ - Function: set-annotation-layout annotation layout
+ This function sets the layout policy of ANNOTATION to LAYOUT.
-\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.
+ - Function: annotation-side annotation
+ This function returns the side of the buffer that ANNOTATION is
+ displayed on. Return value is a symbol, either `left' or `right'.
- `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 ----------
+ - Function: annotation-data annotation
+ This function returns the data associated with ANNOTATION.
- (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.
+ - Function: set-annotation-data annotation data
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
- ---------- Buffer: foo ----------
- input-!-
- ---------- Buffer: foo ----------
+ - Function: annotation-action annotation
+ This function returns the action associated with ANNOTATION.
- (call-process-region 1 6 "cat" nil t)
- => nil
-
- ---------- Buffer: foo ----------
- inputinput-!-
- ---------- Buffer: foo ----------
+ - Function: set-annotation-action annotation action
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
- The `shell-command-on-region' command uses `call-process-region'
- like this:
+ - Function: annotation-menu annotation
+ This function returns the menu associated with ANNOTATION.
- (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.
+ - Function: set-annotation-menu annotation menu
+ This function sets the menu associated with ANNOTATION to MENU.
+ This menu will be displayed when the right mouse button is pressed
+ over the annotation.
-\1f
-File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
+ - Function: annotation-visible annotation
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
-MS-DOS Subprocesses
-===================
+ - Function: annotation-width annotation
+ This function returns the width of ANNOTATION in pixels.
- 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).
+ - Function: hide-annotation annotation
+ This function removes ANNOTATION's glyph, making it invisible.
- 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.
+ - Function: reveal-annotation annotation
+ This function restores ANNOTATION's glyph, making it visible.
- - Variable: binary-process-input
- If this variable is `nil', convert newlines to CRLF sequences in
- the input to a synchronous subprocess.
+\1f
+File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
- - Variable: binary-process-output
- If this variable is `nil', convert CRLF sequences to newlines in
- the output from a synchronous subprocess.
+Locating Annotations
+====================
- *Note Files and MS-DOS::, for related information.
+ - Function: annotations-in-region start end buffer
+ This function returns a list of all annotations in BUFFER which
+ are between START and END inclusively.
-\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: annotations-at &optional position buffer
+ This function returns a list of all annotations at POSITION in
+ BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
+ the current buffer is used.
+
+ - Function: annotation-list &optional buffer
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
- - 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::.).
+ - Function: all-annotations
+ This function returns a list of all annotations in all buffers in
+ existence.
\1f
-File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
+File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
+
+Margin Primitives
+=================
+
+ The margin widths are controllable on a buffer-local, window-local,
+frame-local, device-local, or device-type-local basis through the use
+of specifiers. *Note Specifiers::.
+
+ - Specifier: left-margin-width
+ This is a specifier variable controlling the width of the left
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: right-margin-width
+ This is a specifier variable controlling the width of the right
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: use-left-overflow
+ If non-`nil', use the left outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Specifier: use-right-overflow
+ If non-`nil', use the right outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Function: window-left-margin-pixel-width &optional window
+ This function returns the width in pixels of the left outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ - Function: window-right-margin-pixel-width &optional window
+ This function returns the width in pixels of the right outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ The margin colors are controlled by the faces `left-margin' and
+`right-margin'. These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
-Deleting Processes
-==================
+\1f
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
- "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
+Annotation Hooks
+================
- - 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.
+ The following three hooks are provided for use with the marginal
+annotations:
- (process-kill-without-query (get-process "shell"))
- => t
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
+
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
\1f
-File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
-Process Information
-===================
+Emacs Display
+*************
- Several functions return information about processes.
-`list-processes' is provided for interactive use.
+ This chapter describes a number of other features related to the
+display that XEmacs presents to the user.
- - 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'.
+* Menu:
- - Function: process-list
- This function returns a list of all processes that have not been
- deleted.
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs shows the matching open parenthesis.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
- (process-list)
- => (#<process display-time> #<process shell>)
+\1f
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
- - 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.
+Refreshing the Screen
+=====================
- (get-process "shell")
- => #<process shell>
+ The function `redraw-frame' redisplays the entire contents of a
+given frame. *Note Frames::.
- - 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.
+ - Function: redraw-frame &optional frame no-preempt
+ This function clears and redisplays frame FRAME.
- (process-command (get-process "shell"))
- => ("/bin/csh" "-i")
+ FRAME defaults to the selected frame if omitted.
- - 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.
+ Normally, redisplay is preempted as normal if input arrives.
+ However, if optional second arg NO-PREEMPT is non-`nil', redisplay
+ will not stop for input and is guaranteed to proceed to completion.
- - Function: process-name PROCESS
- This function returns the name of PROCESS.
+ Even more powerful is `redraw-display':
- - 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).
+ - Command: redraw-display &optional device
+ This function redraws all frames on DEVICE marked as having their
+ image garbled. DEVICE defaults to the selected device. If DEVICE
+ is `t', all devices will have their frames checked.
- The possible values for an actual subprocess are:
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
- `run'
- for a process that is running.
+ Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display. If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption. *Note Suspending XEmacs::.
- `stop'
- for a process that is stopped but continuable.
+ - Variable: no-redraw-on-reenter
+ This variable controls whether XEmacs redraws the entire screen
+ after it has been suspended and resumed. Non-`nil' means yes,
+ `nil' means no.
- `exit'
- for a process that has exited.
+ The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch. Normally this occurs the next time that
+`next-event' or `sit-for' is called; however, a display update will not
+occur if there is input pending. *Note Command Loop::.
- `signal'
- for a process that has received a fatal signal.
+ - Function: force-cursor-redisplay &optional frame
+ This function causes an immediate update of the cursor on FRAME,
+ which defaults to the selected frame.
- `open'
- for a network connection that is open.
+\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::.
- `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.
+\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
+Lisp Reference Manual' specifies the rules for resolving conflicts
+between the echo area and the minibuffer for use of that screen space
+(*note The Minibuffer: (xemacs)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 ----------
- `nil'
- if PROCESS-NAME is not the name of an existing process.
+ 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:
- (process-status "shell")
- => run
+ * `message'--default label used by the `message' function;
- (process-status (get-buffer "*shell*"))
- => run
+ * `error'--default label used for reporting errors;
- x
- => #<process xx<1>>
- (process-status x)
- => exit
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
- 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'.
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
- In earlier Emacs versions (prior to version 19), the status of a
- network connection was `run' if open, and `exit' if closed.
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
- - 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'.
+ * `no-log'--messages that should never be logged
- - 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.
+ 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: 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::).
+ - Function: display-message label message &optional frame stdout-p
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
-\1f
-File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
+ 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.
-Sending Input to Processes
-==========================
+ (display-message 'command "Mark set")
- 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.
+ - 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.
- 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.
+ ;; 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.
- - 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.
+\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.
- The function returns `nil'.
+ `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.
- (process-send-string "shell<1>" "ls\n")
+\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 ----------
- ---------- Buffer: *shell* ----------
- ...
- introduction.texi syntax-tables.texi~
- introduction.texi~ text.texi
- introduction.txt text.texi~
- ...
- ---------- Buffer: *shell* ----------
+ - 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.
- - 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.)
+ (setq selective-display-ellipses t)
+ => t
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column ...
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
- 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.)
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
- - 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.
+\1f
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
- 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 Overlay Arrow
+=================
- The function returns PROCESS-NAME.
+ 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.
- (process-send-eof "shell")
- => "shell"
+ - 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::).
-\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.
+ - 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.
-\1f
-File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
+ 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.
-Receiving Output from Processes
-===============================
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
- 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.
+\1f
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
-* Menu:
+Temporary Displays
+==================
-* 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.
+ 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.
-\1f
-File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
+ - 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.
-Process Buffers
----------------
+ 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.
- A process can (and usually does) have an "associated buffer", which
-is an ordinary Emacs buffer that is used for two purposes: storing the
-output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into XEmacs Lisp.
+ `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::.
- Unless the process has a filter function (*note Filter Functions::.),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the `process-mark', which is then updated
-to point to the end of the text just inserted. Usually, but not
-always, the `process-mark' is at the end of the buffer.
+ The value of the last form in FORMS is returned.
- - Function: process-buffer PROCESS
- This function returns the associated buffer of the process PROCESS.
+ ---------- 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 ----------
- (process-buffer (get-process "shell"))
- => #<buffer *shell*>
+ - 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.
- - Function: process-mark PROCESS
- This function returns the process marker for PROCESS, which is the
- marker that says where to insert output from the process.
+ In Emacs versions 18 and earlier, this variable was called
+ `temp-buffer-show-hook'.
- If PROCESS does not have a buffer, `process-mark' returns a marker
- that points nowhere.
+ - 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.
- Insertion of process output in a buffer uses this marker to decide
- where to insert, and updates it to point after the inserted text.
- That is why successive batches of output are inserted
- consecutively.
+ 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.
- Filter functions normally should use this marker in the same
- fashion as is done by direct insertion of output in the buffer. A
- good example of a filter function that uses `process-mark' is
- found at the end of the following section.
+ The return value of `momentary-string-display' is not meaningful.
- When the user is expected to enter input in the process buffer for
- transmission to the process, the process marker is useful for
- distinguishing the new input from previous output.
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
- - Function: set-process-buffer PROCESS BUFFER
- This function sets the buffer associated with PROCESS to BUFFER.
- If BUFFER is `nil', the process becomes associated with no buffer.
+ 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.
- - Function: get-buffer-process BUFFER-OR-NAME
- This function returns the process associated with BUFFER-OR-NAME.
- If there are several processes associated with it, then one is
- chosen. (Presently, the one chosen is the one most recently
- created.) It is usually a bad idea to have more than one process
- associated with the same buffer.
+ In this example, point is initially located at the beginning of the
+ second line:
- (get-buffer-process "*shell*")
- => #<process shell>
+ ---------- 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 ----------
- Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::.).
+ 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: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-
-Process Filter Functions
-------------------------
-
- A process "filter function" is a function that receives the standard
-output from the associated process. If a process has a filter, then
-*all* output from that process is passed to the filter. The process
-buffer is used directly for output from the process only when there is
-no filter.
-
- A filter function must accept two arguments: the associated process
-and a string, which is the output. The function is then free to do
-whatever it chooses with the output.
-
- A filter function 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 filters at
-random places in the middle of other Lisp programs. You may explicitly
-cause Emacs to wait, so that filter functions 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 filter function--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 filter
-function, bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function 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 filter
-function. *Note Debugger::.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of XEmacs when there is no
-filter. Such filter functions need to use `set-buffer' in order to be
-sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must use `unwind-protect' to
-make sure to restore the previous current buffer. They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
-
- (defun ordinary-insertion-filter (proc string)
- (let ((old-buffer (current-buffer)))
- (unwind-protect
- (let (moving)
- (set-buffer (process-buffer proc))
- (setq moving (= (point) (process-mark proc)))
-
- (save-excursion
- ;; Insert the text, moving the process-marker.
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))
- (set-buffer old-buffer))))
-
-The reason to use an explicit `unwind-protect' rather than letting
-`save-excursion' restore the current buffer is so as to preserve the
-change in point made by `goto-char'.
-
- To make the filter force the process buffer to be visible whenever
-new text arrives, insert the following line just before the
-`unwind-protect':
-
- (display-buffer (process-buffer proc))
-
- To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable `moving' and call `goto-char'
-unconditionally.
-
- In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly. *Note Match Data::.
-
- A filter function 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'.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch
-of 200 characters one time, and five batches of 40 characters the next.
-
- - Function: set-process-filter PROCESS FILTER
- This function gives PROCESS the filter function FILTER. If FILTER
- is `nil', then the process will have no filter. If FILTER is `t',
- then no output from the process will be accepted until the filter
- is changed. (Output received during this time is not discarded,
- but is queued, and will be processed as soon as the filter is
- changed.)
-
- - Function: process-filter PROCESS
- This function returns the filter function of PROCESS, or `nil' if
- it has none. `t' means that output processing has been stopped.
-
- Here is an example of use of a filter function:
-
- (defun keep-output (process output)
- (setq kept (cons output kept)))
- => keep-output
-
- (setq kept nil)
- => nil
-
- (set-process-filter (get-process "shell") 'keep-output)
- => keep-output
-
- (process-send-string "shell" "ls ~/other\n")
- => nil
- kept
- => ("lewis@slug[8] % "
-
- "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
- address.txt backup.psf kolstad.psf
- backup.bib~ david.mss resume-Dec-86.mss~
- backup.err david.psf resume-Dec.psf
- backup.mss dland syllabus.mss
- "
- "#backups.mss# backup.mss~ kolstad.mss
- ")
+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.
+
+ - Command: 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: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-
-Accepting Output from Processes
--------------------------------
-
- Output from asynchronous subprocesses normally arrives only while
-XEmacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
- - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
- This function allows XEmacs to read pending output from processes.
- The output is inserted in the associated buffers or given to
- their filter functions. If PROCESS is non-`nil' then this
- function does not return until some output has been received from
- PROCESS.
-
- The arguments SECONDS and MILLISEC let you specify timeout
- periods. The former specifies a period measured in seconds and the
- latter specifies one measured in milliseconds. The two time
- periods thus specified are added together, and
- `accept-process-output' returns after that much time whether or
- not there has been any subprocess output. Note that SECONDS is
- allowed to be a floating-point number; thus, there is no need to
- ever use MILLISEC. (It is retained for compatibility purposes.)
-
- The function `accept-process-output' returns non-`nil' if it did
- get some output, or `nil' if the timeout expired before output
- arrived.
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
-\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.
+Usual Display Conventions
+=========================
-\1f
-File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+ 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:
-Process Window Size
-===================
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
- - 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.
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
-\1f
-File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+ * Character code 10 is a newline.
-Transaction Queues
-==================
+ * 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.
- 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.
+ * 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 `\'.)
- - 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.
+ 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.
- - 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.
+ 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.
- 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.
+ - 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'.
- 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.
+ - 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::.
- The return value of `tq-enqueue' itself is not meaningful.
+ - 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::.
- - Function: tq-close QUEUE
- Shut down transaction queue QUEUE, waiting for all pending
- transactions to complete, and then terminate the connection or
- child process.
+\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:
- Transaction queues are implemented by means of a filter function.
-*Note Filter Functions::.
+* 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: Network, Prev: Transaction Queues, Up: Processes
-
-Network Connections
-===================
-
- XEmacs Lisp programs can open TCP network connections to other
-processes on the same machine or other machines. A network connection
-is handled by Lisp much like a subprocess, and is represented by a
-process object. However, the process you are communicating with is not
-a child of the XEmacs process, so you can't kill it or send it signals.
-All you can do is send and receive data. `delete-process' closes the
-connection, but does not kill the process at the other end; that
-process must decide what to do about closure of the connection.
-
- You can distinguish process objects representing network connections
-from those representing subprocesses with the `process-status'
-function. It always returns either `open' or `closed' for a network
-connection, and it never returns either of those values for a real
-subprocess. *Note Process Information::.
-
- - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
- This function opens a TCP connection for a service to a host. It
- returns a process object to represent the connection.
-
- The NAME argument specifies the name for the process object. It
- is modified as necessary to make it unique.
-
- The BUFFER-OR-NAME argument is the buffer to associate with the
- connection. Output from the connection is inserted in the buffer,
- unless you specify a filter function to handle the output. If
- BUFFER-OR-NAME is `nil', it means that the connection is not
- associated with any buffer.
-
- The arguments HOST and SERVICE specify where to connect to; HOST
- is the host name or IP address (a string), and SERVICE is the name
- of a defined network service (a string) or a port number (an
- integer).
+File: lispref.info, Node: 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 "^?"))
projects / chise / xemacs-chise.git- / blobdiff