+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
-
-User-Level Insertion Commands
-=============================
-
- This section describes higher-level commands for inserting text,
-commands intended primarily for the user but useful also in Lisp
-programs.
-
- - Command: insert-buffer FROM-BUFFER-OR-NAME
- This command inserts the entire contents of FROM-BUFFER-OR-NAME
- (which must exist) into the current buffer after point. It leaves
- the mark after the inserted text. The value is `nil'.
-
- - Command: self-insert-command COUNT
- This command inserts the last character typed; it does so COUNT
- times, before point, and returns `nil'. Most printing characters
- are bound to this command. In routine use, `self-insert-command'
- is the most frequently called function in XEmacs, but programs
- rarely use it except to install it on a keymap.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- This command calls `auto-fill-function' whenever that is non-`nil'
- and the character inserted is a space or a newline (*note Auto
- Filling::.).
-
- This command performs abbrev expansion if Abbrev mode is enabled
- and the inserted character does not have word-constituent syntax.
- (*Note Abbrevs::, and *Note Syntax Class Table::.)
-
- This is also responsible for calling `blink-paren-function' when
- the inserted character has close parenthesis syntax (*note
- Blinking::.).
-
- - Command: newline &optional NUMBER-OF-NEWLINES
- This command inserts newlines into the current buffer before point.
- If NUMBER-OF-NEWLINES is supplied, that many newline characters
- are inserted.
-
- This function calls `auto-fill-function' if the current column
- number is greater than the value of `fill-column' and
- NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function'
- does is insert a newline; thus, the overall result in this case is
- to insert two newlines at different places: one at point, and
- another earlier in the line. `newline' does not auto-fill if
- NUMBER-OF-NEWLINES is non-`nil'.
-
- This command indents to the left margin if that is not zero.
- *Note Margins::.
-
- The value returned is `nil'. In an interactive call, COUNT is the
- numeric prefix argument.
-
- - Command: split-line
- This command splits the current line, moving the portion of the
- line after point down vertically so that it is on the next line
- directly below where it was before. Whitespace is inserted as
- needed at the beginning of the lower line, using the `indent-to'
- function. `split-line' returns the position of point.
-
- Programs hardly ever use this function.
-
- - Variable: overwrite-mode
- This variable controls whether overwrite mode is in effect: a
- non-`nil' value enables the mode. It is automatically made
- buffer-local when set in any fashion.
-
-\1f
-File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
-
-Deleting Text
-=============
-
- Deletion means removing part of the text in a buffer, without saving
-it in the kill ring (*note The Kill Ring::.). Deleted text can't be
-yanked, but can be reinserted using the undo mechanism (*note Undo::.).
-Some deletion functions do save text in the kill ring in some special
-cases.
-
- All of the deletion functions operate on the current buffer, and all
-return a value of `nil'.
-
- - Function: erase-buffer &optional BUFFER
- This function deletes the entire text of BUFFER, leaving it empty.
- If the buffer is read-only, it signals a `buffer-read-only'
- error. Otherwise, it deletes the text without asking for any
- confirmation. It returns `nil'. BUFFER defaults to the current
- buffer if omitted.
-
- Normally, deleting a large amount of text from a buffer inhibits
- further auto-saving of that buffer "because it has shrunk".
- However, `erase-buffer' does not do this, the idea being that the
- future text is not really related to the former text, and its size
- should not be compared with that of the former text.
-
- - Command: delete-region START END &optional BUFFER
- This command deletes the text in BUFFER in the region defined by
- START and END. The value is `nil'. If optional argument BUFFER
- is `nil', the current buffer is assumed.
-
- - Command: delete-char COUNT &optional KILLP
- This command deletes COUNT characters directly after point, or
- before point if COUNT is negative. If KILLP is non-`nil', then it
- saves the deleted characters in the kill ring.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
- - Command: delete-backward-char COUNT &optional KILLP
- This command deletes COUNT characters directly before point, or
- after point if COUNT is negative. If KILLP is non-`nil', then it
- saves the deleted characters in the kill ring.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
- - Command: backward-delete-char-untabify COUNT &optional KILLP
- This command deletes COUNT characters backward, changing tabs into
- spaces. When the next character to be deleted is a tab, it is
- first replaced with the proper number of spaces to preserve
- alignment and then one of those spaces is deleted instead of the
- tab. If KILLP is non-`nil', then the command saves the deleted
- characters in the kill ring.
-
- Conversion of tabs to spaces happens only if COUNT is positive.
- If it is negative, exactly -COUNT characters after point are
- deleted.
-
- In an interactive call, COUNT is the numeric prefix argument, and
- KILLP is the unprocessed prefix argument. Therefore, if a prefix
- argument is supplied, the text is saved in the kill ring. If no
- prefix argument is supplied, then one character is deleted, but
- not saved in the kill ring.
-
- The value returned is always `nil'.
-
-\1f
-File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
-
-User-Level Deletion Commands
-============================
-
- This section describes higher-level commands for deleting text,
-commands intended primarily for the user but useful also in Lisp
-programs.
-
- - Command: delete-horizontal-space
- This function deletes all spaces and tabs around point. It returns
- `nil'.
-
- In the following examples, we call `delete-horizontal-space' four
- times, once on each line, with point between the second and third
- characters on the line each time.
-
- ---------- Buffer: foo ----------
- I -!-thought
- I -!- thought
- We-!- thought
- Yo-!-u thought
- ---------- Buffer: foo ----------
-
- (delete-horizontal-space) ; Four times.
- => nil
-
- ---------- Buffer: foo ----------
- Ithought
- Ithought
- Wethought
- You thought
- ---------- Buffer: foo ----------
-
- - Command: delete-indentation &optional JOIN-FOLLOWING-P
- This function joins the line point is on to the previous line,
- deleting any whitespace at the join and in some cases replacing it
- with one space. If JOIN-FOLLOWING-P is non-`nil',
- `delete-indentation' joins this line to the following line
- instead. The value is `nil'.
-
- If there is a fill prefix, and the second of the lines being joined
- starts with the prefix, then `delete-indentation' deletes the fill
- prefix before joining the lines. *Note Margins::.
-
- In the example below, point is located on the line starting
- `events', and it makes no difference if there are trailing spaces
- in the preceding line.
-
- ---------- Buffer: foo ----------
- When in the course of human
- -!- events, it becomes necessary
- ---------- Buffer: foo ----------
-
- (delete-indentation)
- => nil
- ---------- Buffer: foo ----------
- When in the course of human-!- events, it becomes necessary
- ---------- Buffer: foo ----------
-
- After the lines are joined, the function `fixup-whitespace' is
- responsible for deciding whether to leave a space at the junction.
-
- - Function: fixup-whitespace
- This function replaces all the white space surrounding point with
- either one space or no space, according to the context. It
- returns `nil'.
-
- At the beginning or end of a line, the appropriate amount of space
- is none. Before a character with close parenthesis syntax, or
- after a character with open parenthesis or expression-prefix
- syntax, no space is also appropriate. Otherwise, one space is
- appropriate. *Note Syntax Class Table::.
-
- In the example below, `fixup-whitespace' is called the first time
- with point before the word `spaces' in the first line. For the
- second invocation, point is directly after the `('.
-
- ---------- Buffer: foo ----------
- This has too many -!-spaces
- This has too many spaces at the start of (-!- this list)
- ---------- Buffer: foo ----------
-
- (fixup-whitespace)
- => nil
- (fixup-whitespace)
- => nil
-
- ---------- Buffer: foo ----------
- This has too many spaces
- This has too many spaces at the start of (this list)
- ---------- Buffer: foo ----------
-
- - Command: just-one-space
- This command replaces any spaces and tabs around point with a
- single space. It returns `nil'.
-
- - Command: delete-blank-lines
- This function deletes blank lines surrounding point. If point is
- on a blank line with one or more blank lines before or after it,
- then all but one of them are deleted. If point is on an isolated
- blank line, then it is deleted. If point is on a nonblank line,
- the command deletes all blank lines following it.
-
- A blank line is defined as a line containing only tabs and spaces.
-
- `delete-blank-lines' returns `nil'.
-
-\1f
-File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
-
-The Kill Ring
-=============
-
- "Kill" functions delete text like the deletion functions, but save
-it so that the user can reinsert it by "yanking". Most of these
-functions have `kill-' in their name. By contrast, the functions whose
-names start with `delete-' normally do not save text for yanking
-(though they can still be undone); these are "deletion" functions.
-
- Most of the kill commands are primarily for interactive use, and are
-not described here. What we do describe are the functions provided for
-use in writing such commands. You can use these functions to write
-commands for killing text. When you need to delete text for internal
-purposes within a Lisp function, you should normally use deletion
-functions, so as not to disturb the kill ring contents. *Note
-Deletion::.
-
- Killed text is saved for later yanking in the "kill ring". This is
-a list that holds a number of recent kills, not just the last text
-kill. We call this a "ring" because yanking treats it as having
-elements in a cyclic order. The list is kept in the variable
-`kill-ring', and can be operated on with the usual functions for lists;
-there are also specialized functions, described in this section, that
-treat it as a ring.
-
- Some people think this use of the word "kill" is unfortunate, since
-it refers to operations that specifically *do not* destroy the entities
-"killed". This is in sharp contrast to ordinary life, in which death
-is permanent and "killed" entities do not come back to life.
-Therefore, other metaphors have been proposed. For example, the term
-"cut ring" makes sense to people who, in pre-computer days, used
-scissors and paste to cut up and rearrange manuscripts. However, it
-would be difficult to change the terminology now.
-
-* Menu:
-
-* Kill Ring Concepts:: What text looks like in the kill ring.
-* Kill Functions:: Functions that kill text.
-* Yank Commands:: Commands that access the kill ring.
-* Low-Level Kill Ring:: Functions and variables for kill ring access.
-* Internals of Kill Ring:: Variables that hold kill-ring data.
-
-\1f
-File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
-
-Kill Ring Concepts
-------------------
-
- The kill ring records killed text as strings in a list, most recent
-first. A short kill ring, for example, might look like this:
-
- ("some text" "a different piece of text" "even older text")
-
-When the list reaches `kill-ring-max' entries in length, adding a new
-entry automatically deletes the last entry.
-
- When kill commands are interwoven with other commands, each kill
-command makes a new entry in the kill ring. Multiple kill commands in
-succession build up a single entry in the kill ring, which would be
-yanked as a unit; the second and subsequent consecutive kill commands
-add text to the entry made by the first one.
-
- For yanking, one entry in the kill ring is designated the "front" of
-the ring. Some yank commands "rotate" the ring by designating a
-different element as the "front." But this virtual rotation doesn't
-change the list itself--the most recent entry always comes first in the
-list.
-
-\1f
-File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
-
-Functions for Killing
----------------------
-
- `kill-region' is the usual subroutine for killing text. Any command
-that calls this function is a "kill command" (and should probably have
-`kill' in its name). `kill-region' puts the newly killed text in a new
-element at the beginning of the kill ring or adds it to the most recent
-element. It uses the `last-command' variable to determine whether the
-previous command was a kill command, and if so appends the killed text
-to the most recent entry.
-
- - Command: kill-region START END
- This function kills the text in the region defined by START and
- END. The text is deleted but saved in the kill ring, along with
- its text properties. The value is always `nil'.
-
- In an interactive call, START and END are point and the mark.
-
- If the buffer is read-only, `kill-region' modifies the kill ring
- just the same, then signals an error without modifying the buffer.
- This is convenient because it lets the user use all the kill
- commands to copy text into the kill ring from a read-only buffer.
-
- - Command: copy-region-as-kill START END
- This command saves the region defined by START and END on the kill
- ring (including text properties), but does not delete the text
- from the buffer. It returns `nil'. It also indicates the extent
- of the text copied by moving the cursor momentarily, or by
- displaying a message in the echo area.
-
- The command does not set `this-command' to `kill-region', so a
- subsequent kill command does not append to the same kill ring
- entry.
-
- Don't call `copy-region-as-kill' in Lisp programs unless you aim to
- support Emacs 18. For Emacs 19, it is better to use `kill-new' or
- `kill-append' instead. *Note Low-Level Kill Ring::.
-
-\1f
-File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
-
-Functions for Yanking
----------------------
-
- "Yanking" means reinserting an entry of previously killed text from
-the kill ring. The text properties are copied too.
-
- - Command: yank &optional ARG
- This command inserts before point the text in the first entry in
- the kill ring. It positions the mark at the beginning of that
- text, and point at the end.
-
- If ARG is a list (which occurs interactively when the user types
- `C-u' with no digits), then `yank' inserts the text as described
- above, but puts point before the yanked text and puts the mark
- after it.
-
- If ARG is a number, then `yank' inserts the ARGth most recently
- killed text--the ARGth element of the kill ring list.
-
- `yank' does not alter the contents of the kill ring or rotate it.
- It returns `nil'.
-
- - Command: yank-pop ARG
- This command replaces the just-yanked entry from the kill ring
- with a different entry from the kill ring.
-
- This is allowed only immediately after a `yank' or another
- `yank-pop'. At such a time, the region contains text that was just
- inserted by yanking. `yank-pop' deletes that text and inserts in
- its place a different piece of killed text. It does not add the
- deleted text to the kill ring, since it is already in the kill
- ring somewhere.
-
- If ARG is `nil', then the replacement text is the previous element
- of the kill ring. If ARG is numeric, the replacement is the ARGth
- previous kill. If ARG is negative, a more recent kill is the
- replacement.
-
- The sequence of kills in the kill ring wraps around, so that after
- the oldest one comes the newest one, and before the newest one
- goes the oldest.
-
- The value is always `nil'.
-
-\1f
-File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
-
-Low-Level Kill Ring
--------------------
-
- These functions and variables provide access to the kill ring at a
-lower level, but still convenient for use in Lisp programs. They take
-care of interaction with X Window selections. They do not exist in
-Emacs version 18.
-
- - Function: current-kill N &optional DO-NOT-MOVE
- The function `current-kill' rotates the yanking pointer which
- designates the "front" of the kill ring by N places (from newer
- kills to older ones), and returns the text at that place in the
- ring.
-
- If the optional second argument DO-NOT-MOVE is non-`nil', then
- `current-kill' doesn't alter the yanking pointer; it just returns
- the Nth kill, counting from the current yanking pointer.
-
- If N is zero, indicating a request for the latest kill,
- `current-kill' calls the value of `interprogram-paste-function'
- (documented below) before consulting the kill ring.
-
- - Function: kill-new STRING
- This function puts the text STRING into the kill ring as a new
- entry at the front of the ring. It discards the oldest entry if
- appropriate. It also invokes the value of
- `interprogram-cut-function' (see below).
-
- - Function: kill-append STRING BEFORE-P
- This function appends the text STRING to the first entry in the
- kill ring. Normally STRING goes at the end of the entry, but if
- BEFORE-P is non-`nil', it goes at the beginning. This function
- also invokes the value of `interprogram-cut-function' (see below).
-
- - Variable: interprogram-paste-function
- This variable provides a way of transferring killed text from other
- programs, when you are using a window system. Its value should be
- `nil' or a function of no arguments.
-
- If the value is a function, `current-kill' calls it to get the
- "most recent kill". If the function returns a non-`nil' value,
- then that value is used as the "most recent kill". If it returns
- `nil', then the first element of `kill-ring' is used.
-
- The normal use of this hook is to get the X server's primary
- selection as the most recent kill, even if the selection belongs
- to another X client. *Note X Selections::.
-
- - Variable: interprogram-cut-function
- This variable provides a way of communicating killed text to other
- programs, when you are using a window system. Its value should be
- `nil' or a function of one argument.
-
- If the value is a function, `kill-new' and `kill-append' call it
- with the new first element of the kill ring as an argument.
-
- The normal use of this hook is to set the X server's primary
- selection to the newly killed text.
-
-\1f
-File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
-
-Internals of the Kill Ring
---------------------------
-
- The variable `kill-ring' holds the kill ring contents, in the form
-of a list of strings. The most recent kill is always at the front of
-the list.
-
- The `kill-ring-yank-pointer' variable points to a link in the kill
-ring list, whose CAR is the text to yank next. We say it identifies
-the "front" of the ring. Moving `kill-ring-yank-pointer' to a
-different link is called "rotating the kill ring". We call the kill
-ring a "ring" because the functions that move the yank pointer wrap
-around from the end of the list to the beginning, or vice-versa.
-Rotation of the kill ring is virtual; it does not change the value of
-`kill-ring'.
-
- Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
-whose values are normally lists. The word "pointer" in the name of the
-`kill-ring-yank-pointer' indicates that the variable's purpose is to
-identify one element of the list for use by the next yank command.
-
- The value of `kill-ring-yank-pointer' is always `eq' to one of the
-links in the kill ring list. The element it identifies is the CAR of
-that link. Kill commands, which change the kill ring, also set this
-variable to the value of `kill-ring'. The effect is to rotate the ring
-so that the newly killed text is at the front.
-
- Here is a diagram that shows the variable `kill-ring-yank-pointer'
-pointing to the second entry in the kill ring `("some text" "a
-different piece of text" "yet older text")'.
-
- kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | | -->"yet older text"
- | |
- | --> "a different piece of text"
- |
- --> "some text"
-
-This state of affairs might occur after `C-y' (`yank') immediately
-followed by `M-y' (`yank-pop').
-
- - Variable: kill-ring
- This variable holds the list of killed text sequences, most
- recently killed first.
-
- - Variable: kill-ring-yank-pointer
- This variable's value indicates which element of the kill ring is
- at the "front" of the ring for yanking. More precisely, the value
- is a tail of the value of `kill-ring', and its CAR is the kill
- string that `C-y' should yank.
-
- - User Option: kill-ring-max
- The value of this variable is the maximum length to which the kill
- ring can grow, before elements are thrown away at the end. The
- default value for `kill-ring-max' is 30.
-
-\1f
-File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
-
-Undo
-====
-
- Most buffers have an "undo list", which records all changes made to
-the buffer's text so that they can be undone. (The buffers that don't
-have one are usually special-purpose buffers for which XEmacs assumes
-that undoing is not useful.) All the primitives that modify the text
-in the buffer automatically add elements to the front of the undo list,
-which is in the variable `buffer-undo-list'.
-
- - Variable: buffer-undo-list
- This variable's value is the undo list of the current buffer. A
- value of `t' disables the recording of undo information.
-
- Here are the kinds of elements an undo list can have:
-
-`INTEGER'
- This kind of element records a previous value of point. Ordinary
- cursor motion does not get any sort of undo record, but deletion
- commands use these entries to record where point was before the
- command.
-
-`(BEG . END)'
- This kind of element indicates how to delete text that was
- inserted. Upon insertion, the text occupied the range BEG-END in
- the buffer.
-
-`(TEXT . POSITION)'
- This kind of element indicates how to reinsert text that was
- deleted. The deleted text itself is the string TEXT. The place to
- reinsert it is `(abs POSITION)'.
-
-`(t HIGH . LOW)'
- This kind of element indicates that an unmodified buffer became
- modified. The elements HIGH and LOW are two integers, each
- recording 16 bits of the visited file's modification time as of
- when it was previously visited or saved. `primitive-undo' uses
- those values to determine whether to mark the buffer as unmodified
- once again; it does so only if the file's modification time
- matches those numbers.
-
-`(nil PROPERTY VALUE BEG . END)'
- This kind of element records a change in a text property. Here's
- how you might undo the change:
-
- (put-text-property BEG END PROPERTY VALUE)
-
-`POSITION'
- This element indicates where point was at an earlier time.
- Undoing this element sets point to POSITION. Deletion normally
- creates an element of this kind as well as a reinsertion element.
-
-`nil'
- This element is a boundary. The elements between two boundaries
- are called a "change group"; normally, each change group
- corresponds to one keyboard command, and undo commands normally
- undo an entire group as a unit.
-
- - Function: undo-boundary
- This function places a boundary element in the undo list. The undo
- command stops at such a boundary, and successive undo commands undo
- to earlier and earlier boundaries. This function returns `nil'.
-
- The editor command loop automatically creates an undo boundary
- before each key sequence is executed. Thus, each undo normally
- undoes the effects of one command. Self-inserting input
- characters are an exception. The command loop makes a boundary
- for the first such character; the next 19 consecutive
- self-inserting input characters do not make boundaries, and then
- the 20th does, and so on as long as self-inserting characters
- continue.
-
- All buffer modifications add a boundary whenever the previous
- undoable change was made in some other buffer. This way, a
- command that modifies several buffers makes a boundary in each
- buffer it changes.
-
- Calling this function explicitly is useful for splitting the
- effects of a command into more than one unit. For example,
- `query-replace' calls `undo-boundary' after each replacement, so
- that the user can undo individual replacements one by one.
-
- - Function: primitive-undo COUNT LIST
- This is the basic function for undoing elements of an undo list.
- It undoes the first COUNT elements of LIST, returning the rest of
- LIST. You could write this function in Lisp, but it is convenient
- to have it in C.
-
- `primitive-undo' adds elements to the buffer's undo list when it
- changes the buffer. Undo commands avoid confusion by saving the
- undo list value at the beginning of a sequence of undo operations.
- Then the undo operations use and update the saved value. The new
- elements added by undoing are not part of this saved value, so
- they don't interfere with continuing to undo.
-
-\1f
-File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
-
-Maintaining Undo Lists
-======================
-
- This section describes how to enable and disable undo information for
-a given buffer. It also explains how the undo list is truncated
-automatically so it doesn't get too big.
-
- Recording of undo information in a newly created buffer is normally
-enabled to start with; but if the buffer name starts with a space, the
-undo recording is initially disabled. You can explicitly enable or
-disable undo recording with the following two functions, or by setting
-`buffer-undo-list' yourself.
-
- - Command: buffer-enable-undo &optional BUFFER-OR-NAME
- This command enables recording undo information for buffer
- BUFFER-OR-NAME, so that subsequent changes can be undone. If no
- argument is supplied, then the current buffer is used. This
- function does nothing if undo recording is already enabled in the
- buffer. It returns `nil'.
-
- In an interactive call, BUFFER-OR-NAME is the current buffer. You
- cannot specify any other buffer.
-
- - Function: buffer-disable-undo &optional BUFFER
- - Function: buffer-flush-undo &optional BUFFER
- This function discards the undo list of BUFFER, and disables
- further recording of undo information. As a result, it is no
- longer possible to undo either previous changes or any subsequent
- changes. If the undo list of BUFFER is already disabled, this
- function has no effect.
-
- This function returns `nil'. It cannot be called interactively.
-
- The name `buffer-flush-undo' is not considered obsolete, but the
- preferred name `buffer-disable-undo' is new as of Emacs versions
- 19.
-
- As editing continues, undo lists get longer and longer. To prevent
-them from using up all available memory space, garbage collection trims
-them back to size limits you can set. (For this purpose, the "size" of
-an undo list measures the cons cells that make up the list, plus the
-strings of deleted text.) Two variables control the range of acceptable
-sizes: `undo-limit' and `undo-strong-limit'.
-
- - Variable: undo-limit
- This is the soft limit for the acceptable size of an undo list.
- The change group at which this size is exceeded is the last one
- kept.
-
- - Variable: undo-strong-limit
- This is the upper limit for the acceptable size of an undo list.
- The change group at which this size is exceeded is discarded
- itself (along with all older change groups). There is one
- exception: the very latest change group is never discarded no
- matter how big it is.
-
-\1f
-File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
-
-Filling
-=======
-
- "Filling" means adjusting the lengths of lines (by moving the line
-breaks) so that they are nearly (but no greater than) a specified
-maximum width. Additionally, lines can be "justified", which means
-inserting spaces to make the left and/or right margins line up
-precisely. The width is controlled by the variable `fill-column'. For
-ease of reading, lines should be no longer than 70 or so columns.
-
- You can use Auto Fill mode (*note Auto Filling::.) to fill text
-automatically as you insert it, but changes to existing text may leave
-it improperly filled. Then you must fill the text explicitly.
-
- Most of the commands in this section return values that are not
-meaningful. All the functions that do filling take note of the current
-left margin, current right margin, and current justification style
-(*note Margins::.). If the current justification style is `none', the
-filling functions don't actually do anything.
-
- Several of the filling functions have an argument JUSTIFY. If it is
-non-`nil', that requests some kind of justification. It can be `left',
-`right', `full', or `center', to request a specific style of
-justification. If it is `t', that means to use the current
-justification style for this part of the text (see
-`current-justification', below).
-
- When you call the filling functions interactively, using a prefix
-argument implies the value `full' for JUSTIFY.
-
- - Command: fill-paragraph JUSTIFY
- This command fills the paragraph at or after point. If JUSTIFY is
- non-`nil', each line is justified as well. It uses the ordinary
- paragraph motion commands to find paragraph boundaries. *Note
- Paragraphs: (xemacs)Paragraphs.
-
- - Command: fill-region START END &optional JUSTIFY
- This command fills each of the paragraphs in the region from START
- to END. It justifies as well if JUSTIFY is non-`nil'.
-
- The variable `paragraph-separate' controls how to distinguish
- paragraphs. *Note Standard Regexps::.
-
- - Command: fill-individual-paragraphs START END &optional JUSTIFY
- MAIL-FLAG
- This command fills each paragraph in the region according to its
- individual fill prefix. Thus, if the lines of a paragraph were
- indented with spaces, the filled paragraph will remain indented in
- the same fashion.
-
- The first two arguments, START and END, are the beginning and end
- of the region to be filled. The third and fourth arguments,
- JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
- paragraphs are justified as well as filled. If MAIL-FLAG is
- non-`nil', it means the function is operating on a mail message
- and therefore should not fill the header lines.
-
- Ordinarily, `fill-individual-paragraphs' regards each change in
- indentation as starting a new paragraph. If
- `fill-individual-varying-indent' is non-`nil', then only separator
- lines separate paragraphs. That mode can handle indented
- paragraphs with additional indentation on the first line.
-
- - User Option: fill-individual-varying-indent
- This variable alters the action of `fill-individual-paragraphs' as
- described above.
-
- - Command: fill-region-as-paragraph START END &optional JUSTIFY
- This command considers a region of text as a paragraph and fills
- it. If the region was made up of many paragraphs, the blank lines
- between paragraphs are removed. This function justifies as well
- as filling when JUSTIFY is non-`nil'.
-
- In an interactive call, any prefix argument requests justification.
-
- In Adaptive Fill mode, which is enabled by default,
- `fill-region-as-paragraph' on an indented paragraph when there is
- no fill prefix uses the indentation of the second line of the
- paragraph as the fill prefix.
-
- - Command: justify-current-line HOW EOP NOSQUEEZE
- This command inserts spaces between the words of the current line
- so that the line ends exactly at `fill-column'. It returns `nil'.
-
- The argument HOW, if non-`nil' specifies explicitly the style of
- justification. It can be `left', `right', `full', `center', or
- `none'. If it is `t', that means to do follow specified
- justification style (see `current-justification', below). `nil'
- means to do full justification.
-
- If EOP is non-`nil', that means do left-justification when
- `current-justification' specifies full justification. This is used
- for the last line of a paragraph; even if the paragraph as a whole
- is fully justified, the last line should not be.
-
- If NOSQUEEZE is non-`nil', that means do not change interior
- whitespace.
-
- - User Option: default-justification
- This variable's value specifies the style of justification to use
- for text that doesn't specify a style with a text property. The
- possible values are `left', `right', `full', `center', or `none'.
- The default value is `left'.
-
- - Function: current-justification
- This function returns the proper justification style to use for
- filling the text around point.
-
- - Variable: fill-paragraph-function
- This variable provides a way for major modes to override the
- filling of paragraphs. If the value is non-`nil',
- `fill-paragraph' calls this function to do the work. If the
- function returns a non-`nil' value, `fill-paragraph' assumes the
- job is done, and immediately returns that value.
-
- The usual use of this feature is to fill comments in programming
- language modes. If the function needs to fill a paragraph in the
- usual way, it can do so as follows:
-
- (let ((fill-paragraph-function nil))
- (fill-paragraph arg))
-
- - Variable: use-hard-newlines
- If this variable is non-`nil', the filling functions do not delete
- newlines that have the `hard' text property. These "hard
- newlines" act as paragraph separators.
-
-\1f
-File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
-
-Margins for Filling
-===================
-
- - User Option: fill-prefix
- This variable specifies a string of text that appears at the
- beginning of normal text lines and should be disregarded when
- filling them. Any line that fails to start with the fill prefix
- is considered the start of a paragraph; so is any line that starts
- with the fill prefix followed by additional whitespace. Lines
- that start with the fill prefix but no additional whitespace are
- ordinary text lines that can be filled together. The resulting
- filled lines also start with the fill prefix.
-
- The fill prefix follows the left margin whitespace, if any.
-
- - User Option: fill-column
- This buffer-local variable specifies the maximum width of filled
- lines. Its value should be an integer, which is a number of
- columns. All the filling, justification and centering commands
- are affected by this variable, including Auto Fill mode (*note
- Auto Filling::.).
-
- As a practical matter, if you are writing text for other people to
- read, you should set `fill-column' to no more than 70. Otherwise
- the line will be too long for people to read comfortably, and this
- can make the text seem clumsy.
-
- - Variable: default-fill-column
- The value of this variable is the default value for `fill-column'
- in buffers that do not override it. This is the same as
- `(default-value 'fill-column)'.
-
- The default value for `default-fill-column' is 70.
-
- - Command: set-left-margin FROM TO MARGIN
- This sets the `left-margin' property on the text from FROM to TO
- to the value MARGIN. If Auto Fill mode is enabled, this command
- also refills the region to fit the new margin.
-
- - Command: set-right-margin FROM TO MARGIN
- This sets the `right-margin' property on the text from FROM to TO
- to the value MARGIN. If Auto Fill mode is enabled, this command
- also refills the region to fit the new margin.
-
- - Function: current-left-margin
- This function returns the proper left margin value to use for
- filling the text around point. The value is the sum of the
- `left-margin' property of the character at the start of the
- current line (or zero if none), and the value of the variable
- `left-margin'.
-
- - Function: current-fill-column
- This function returns the proper fill column value to use for
- filling the text around point. The value is the value of the
- `fill-column' variable, minus the value of the `right-margin'
- property of the character after point.
-
- - Command: move-to-left-margin &optional N FORCE
- This function moves point to the left margin of the current line.
- The column moved to is determined by calling the function
- `current-left-margin'. If the argument N is non-`nil',
- `move-to-left-margin' moves forward N-1 lines first.
-
- If FORCE is non-`nil', that says to fix the line's indentation if
- that doesn't match the left margin value.
-
- - Function: delete-to-left-margin FROM TO
- This function removes left margin indentation from the text
- between FROM and TO. The amount of indentation to delete is
- determined by calling `current-left-margin'. In no case does this
- function delete non-whitespace.
-
- - Function: indent-to-left-margin
- This is the default `indent-line-function', used in Fundamental
- mode, Text mode, etc. Its effect is to adjust the indentation at
- the beginning of the current line to the value specified by the
- variable `left-margin'. This may involve either inserting or
- deleting whitespace.
-
- - Variable: left-margin
- This variable specifies the base left margin column. In
- Fundamental mode, <LFD> indents to this column. This variable
- automatically becomes buffer-local when set in any fashion.
-
-\1f
-File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
-
-Auto Filling
-============
-
- Auto Fill mode is a minor mode that fills lines automatically as text
-is inserted. This section describes the hook used by Auto Fill mode.
-For a description of functions that you can call explicitly to fill and
-justify existing text, see *Note Filling::.
-
- Auto Fill mode also enables the functions that change the margins and
-justification style to refill portions of the text. *Note Margins::.
-
- - Variable: auto-fill-function
- The value of this variable should be a function (of no arguments)
- to be called after self-inserting a space or a newline. It may be
- `nil', in which case nothing special is done in that case.
-
- The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
- mode is enabled. That is a function whose sole purpose is to
- implement the usual strategy for breaking a line.
-
- In older Emacs versions, this variable was named
- `auto-fill-hook', but since it is not called with the
- standard convention for hooks, it was renamed to
- `auto-fill-function' in version 19.
-
projects / chise / xemacs-chise.git- / blobdiff