X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-38;h=e8bb726323ba2e0dd7231f6cf07c1261ee422b3a;hb=2d7a965e4f6bc4e21323ecbc5e1f2e732b8132f8;hp=5dffcd3c025a475bc79c520ba74dc875df56bdbc;hpb=82da33b61c3e2dd2937db17b75b2838188793053;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-38 b/info/lispref.info-38 index 5dffcd3..e8bb726 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -1,5 +1,5 @@ -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 @@ -50,1139 +50,1148 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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 -======================= + +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.  -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. - -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. - -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. - -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. - -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. + +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. - -File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes - -Creating an Asynchronous Process -================================ - - After an "asynchronous process" is created, Emacs and the Lisp -program both continue running immediately. The process may thereafter -run in parallel with Emacs, and the two may communicate with each other -using the functions described in following sections. Here we describe -how to create an asynchronous process with `start-process'. - - - Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS - This function creates a new asynchronous subprocess and starts the - program PROGRAM running in it. It returns a process object that - stands for the new subprocess in Lisp. The argument NAME - specifies the name for the process object; if a process with this - name already exists, then NAME is modified (by adding `<1>', etc.) - to be unique. The buffer BUFFER-OR-NAME is the buffer to - associate with the process. - - The remaining arguments, ARGS, are strings that specify command - line arguments for the program. - - In the example below, the first process is started and runs - (rather, sleeps) for 100 seconds. Meanwhile, the second process - is started, and given the name `my-process<1>' for the sake of - uniqueness. It inserts the directory listing at the end of the - buffer `foo', before the first process finishes. Then it - finishes, and a message to that effect is inserted in the buffer. - Much later, the first process finishes, and another message is - inserted in the buffer for it. - - (start-process "my-process" "foo" "sleep" "100") - => # - - (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") - => #> - - ---------- Buffer: foo ---------- - total 2 - lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs - -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon - - Process my-process<1> finished - - Process my-process finished - ---------- Buffer: foo ---------- + - Function: 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.  -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 -================== + +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.  -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) - => (# #) + +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") - => # + 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. + +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. + +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-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. - -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. + +File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display + +Warnings +======== + + XEmacs contains a facility for unified display of various warnings. +Unlike errors, warnings are displayed in the situations when XEmacs +encounters a problem that is recoverable, but which should be fixed for +safe future operation. + + For example, warnings are printed by the startup code when it +encounters problems with X keysyms, when there is an error in `.emacs', +and in other problematic situations. Unlike messages, warnings are +displayed in a separate buffer, and include an explanatory message that +may span across several lines. Here is an example of how a warning is +displayed: + + (1) (initialization/error) An error has occurred while loading ~/.emacs: + + Symbol's value as variable is void: bogus-variable + + To ensure normal operation, you should investigate the cause of the error + in your initialization file and remove it. Use the `-debug-init' option + to XEmacs to view a complete error backtrace. + + Each warning has a "class" and a "priority level". The class is a +symbol describing what sort of warning this is, such as +`initialization', `resource' or `key-mapping'. + + The warning priority level specifies how important the warning is. +The recognized warning levels, in increased order of priority, are: +`debug', `info', `notice', `warning', `error', `critical', `alert' and +`emergency'. + + - Function: display-warning class message &optional level + This function displays a warning message MESSAGE (a string). + CLASS should be a warning class symbol, as described above, or a + list of such symbols. LEVEL describes the warning priority level. + If unspecified, it default to `warning'. + + (display-warning 'resource + "Bad resource specification encountered: + something like + + Emacs*foo: bar + + You should replace the * with a . in order to get proper behavior when + you use the specifier and/or `set-face-*' functions.") + + ---------- Warning buffer ---------- + (1) (resource/warning) Bad resource specification encountered: + something like + + Emacs*foo: bar + + You should replace the * with a . in order to get proper behavior when + you use the specifier and/or `set-face-*' functions. + ---------- Warning buffer ---------- + + - Function: lwarn class level message &rest args + This function displays a formatted labeled warning message. As + above, CLASS should be the warning class symbol, or a list of such + symbols, and LEVEL should specify the warning priority level + (`warning' by default). + + Unlike in `display-warning', MESSAGE may be a formatted message, + which will be, together with the rest of the arguments, passed to + `format'. + + (lwarn 'message-log 'warning + "Error caught in `remove-message-hook': %s" + (error-message-string e)) + + - Variable: log-warning-minimum-level + This variable specifies the minimum level of warnings that should + be generated. Warnings with level lower than defined by this + variable are completely ignored, as if they never happened. + + - Variable: display-warning-minimum-level + This variable specifies the minimum level of warnings that should + be displayed. Unlike `log-warning-minimum-level', setting this + function does not suppress warnings entirely--they are still + generated in the `*Warnings*' buffer, only they are not displayed + by default. + + - Variable: log-warning-suppressed-classes + This variable specifies a list of classes that should not be + logged or displayed. If any of the class symbols associated with + a warning is the same as any of the symbols listed here, the + warning will be completely ignored, as it they never happened. + + - Variable: display-warning-suppressed-classes + This variable specifies a list of classes that should not be + logged or displayed. If any of the class symbols associated with + a warning is the same as any of the symbols listed here, the + warning will not be displayed. The warning will still logged in + the *Warnings* buffer (unless also contained in + `log-warning-suppressed-classes'), but the buffer will not be + automatically popped up. + + +File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display + +Invisible Text +============== + + You can make characters "invisible", so that they do not appear on +the screen, with the `invisible' property. This can be either a text +property or a property of an overlay. + + In the simplest case, any non-`nil' `invisible' property makes a +character invisible. This is the default case--if you don't alter the +default value of `buffer-invisibility-spec', this is how the +`invisibility' property works. This feature is much like selective +display (*note Selective Display::), but more general and cleaner. + + More generally, you can use the variable `buffer-invisibility-spec' +to control which values of the `invisible' property make text +invisible. This permits you to classify the text into different subsets +in advance, by giving them different `invisible' values, and +subsequently make various subsets visible or invisible by changing the +value of `buffer-invisibility-spec'. + + Controlling visibility with `buffer-invisibility-spec' is especially +useful in a program to display the list of entries in a data base. It +permits the implementation of convenient filtering commands to view +just a part of the entries in the data base. Setting this variable is +very fast, much faster than scanning all the text in the buffer looking +for properties to change. + + - Variable: buffer-invisibility-spec + This variable specifies which kinds of `invisible' properties + actually make a character invisible. - 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") + +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. + +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::). - -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. - -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. + +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. - -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 ---------- + 20 + + # + + ---------- Buffer: foo ---------- - (process-buffer (get-process "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*") - => # + ---------- 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.  -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)))  -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 - -File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes - -Sentinels: Detecting Process Status Changes -=========================================== - - A "process sentinel" is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by XEmacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is also -called if the process exits. The sentinel receives two arguments: the -process for which the event occurred, and a string describing the type -of event. - - The string describing the event looks like one of the following: - - * `"finished\n"'. - - * `"exited abnormally with code EXITCODE\n"'. - - * `"NAME-OF-SIGNAL\n"'. - - * `"NAME-OF-SIGNAL (core dumped)\n"'. - - A sentinel runs only while XEmacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running them at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling `sit-for' or `sleep-for' (*note -Waiting::.), or `accept-process-output' (*note Accepting Output::.). -Emacs is also waiting when the command loop is reading input. - - Quitting is normally inhibited within a sentinel--otherwise, the -effect of typing `C-g' at command level or to quit a user command would -be unpredictable. If you want to permit quitting inside a sentinel, -bind `inhibit-quit' to `nil'. *Note Quitting::. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -`(buffer-name (process-buffer PROCESS))' returns `nil'. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -`debug-on-error' is non-`nil', the error-catching is turned off. This -makes it possible to use the Lisp debugger to debug the sentinel. -*Note Debugger::. - - In earlier Emacs versions, every sentinel that did regexp searching -or matching had to explicitly save and restore the match data. Now -Emacs does this automatically; sentinels never need to do it explicitly. -*Note Match Data::. - - - Function: set-process-sentinel PROCESS SENTINEL - This function associates SENTINEL with PROCESS. If SENTINEL is - `nil', then the process will have no sentinel. The default - behavior when there is no sentinel is to insert a message in the - process's buffer when the process status changes. - - (defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) - (set-process-sentinel (get-process "shell") 'msg-me) - => msg-me - - (kill-process (get-process "shell")) - -| Process: # had the event `killed' - => # - - - Function: process-sentinel PROCESS - This function returns the sentinel of PROCESS, or `nil' if it has - none. - - - Function: waiting-for-user-input-p - While a sentinel or filter function is running, this function - returns non-`nil' if XEmacs was waiting for keyboard input from - the user at the time the sentinel or filter function was called, - `nil' if it was not. +Usual Display Conventions +========================= - -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'. - -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. + +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.  -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 "^?"))