1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
55 User-Level Insertion Commands
56 =============================
58 This section describes higher-level commands for inserting text,
59 commands intended primarily for the user but useful also in Lisp
62 - Command: insert-buffer from-buffer-or-name
63 This command inserts the entire contents of FROM-BUFFER-OR-NAME
64 (which must exist) into the current buffer after point. It leaves
65 the mark after the inserted text. The value is `nil'.
67 - Command: self-insert-command count
68 This command inserts the last character typed; it does so COUNT
69 times, before point, and returns `nil'. Most printing characters
70 are bound to this command. In routine use, `self-insert-command'
71 is the most frequently called function in XEmacs, but programs
72 rarely use it except to install it on a keymap.
74 In an interactive call, COUNT is the numeric prefix argument.
76 This command calls `auto-fill-function' whenever that is non-`nil'
77 and the character inserted is a space or a newline (*note Auto
80 This command performs abbrev expansion if Abbrev mode is enabled
81 and the inserted character does not have word-constituent syntax.
82 (*Note Abbrevs::, and *Note Syntax Class Table::.)
84 This is also responsible for calling `blink-paren-function' when
85 the inserted character has close parenthesis syntax (*note
88 - Command: newline &optional number-of-newlines
89 This command inserts newlines into the current buffer before point.
90 If NUMBER-OF-NEWLINES is supplied, that many newline characters
93 This function calls `auto-fill-function' if the current column
94 number is greater than the value of `fill-column' and
95 NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function'
96 does is insert a newline; thus, the overall result in this case is
97 to insert two newlines at different places: one at point, and
98 another earlier in the line. `newline' does not auto-fill if
99 NUMBER-OF-NEWLINES is non-`nil'.
101 This command indents to the left margin if that is not zero.
104 The value returned is `nil'. In an interactive call, COUNT is the
105 numeric prefix argument.
107 - Command: split-line
108 This command splits the current line, moving the portion of the
109 line after point down vertically so that it is on the next line
110 directly below where it was before. Whitespace is inserted as
111 needed at the beginning of the lower line, using the `indent-to'
112 function. `split-line' returns the position of point.
114 Programs hardly ever use this function.
116 - Variable: overwrite-mode
117 This variable controls whether overwrite mode is in effect: a
118 non-`nil' value enables the mode. It is automatically made
119 buffer-local when set in any fashion.
122 File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
127 Deletion means removing part of the text in a buffer, without saving
128 it in the kill ring (*note The Kill Ring::). Deleted text can't be
129 yanked, but can be reinserted using the undo mechanism (*note Undo::).
130 Some deletion functions do save text in the kill ring in some special
133 All of the deletion functions operate on the current buffer, and all
134 return a value of `nil'.
136 - Function: erase-buffer &optional buffer
137 This function deletes the entire text of BUFFER, leaving it empty.
138 If the buffer is read-only, it signals a `buffer-read-only'
139 error. Otherwise, it deletes the text without asking for any
140 confirmation. It returns `nil'. BUFFER defaults to the current
143 Normally, deleting a large amount of text from a buffer inhibits
144 further auto-saving of that buffer "because it has shrunk".
145 However, `erase-buffer' does not do this, the idea being that the
146 future text is not really related to the former text, and its size
147 should not be compared with that of the former text.
149 - Command: delete-region start end &optional buffer
150 This command deletes the text in BUFFER in the region defined by
151 START and END. The value is `nil'. If optional argument BUFFER
152 is `nil', the current buffer is assumed.
154 - Command: delete-char count &optional killp
155 This command deletes COUNT characters directly after point, or
156 before point if COUNT is negative. If KILLP is non-`nil', then it
157 saves the deleted characters in the kill ring.
159 In an interactive call, COUNT is the numeric prefix argument, and
160 KILLP is the unprocessed prefix argument. Therefore, if a prefix
161 argument is supplied, the text is saved in the kill ring. If no
162 prefix argument is supplied, then one character is deleted, but
163 not saved in the kill ring.
165 The value returned is always `nil'.
167 - Command: delete-backward-char count &optional killp
168 This command deletes COUNT characters directly before point, or
169 after point if COUNT is negative. If KILLP is non-`nil', then it
170 saves the deleted characters in the kill ring.
172 In an interactive call, COUNT is the numeric prefix argument, and
173 KILLP is the unprocessed prefix argument. Therefore, if a prefix
174 argument is supplied, the text is saved in the kill ring. If no
175 prefix argument is supplied, then one character is deleted, but
176 not saved in the kill ring.
178 The value returned is always `nil'.
180 - Command: backward-delete-char-untabify count &optional killp
181 This command deletes COUNT characters backward, changing tabs into
182 spaces. When the next character to be deleted is a tab, it is
183 first replaced with the proper number of spaces to preserve
184 alignment and then one of those spaces is deleted instead of the
185 tab. If KILLP is non-`nil', then the command saves the deleted
186 characters in the kill ring.
188 Conversion of tabs to spaces happens only if COUNT is positive.
189 If it is negative, exactly -COUNT characters after point are
192 In an interactive call, COUNT is the numeric prefix argument, and
193 KILLP is the unprocessed prefix argument. Therefore, if a prefix
194 argument is supplied, the text is saved in the kill ring. If no
195 prefix argument is supplied, then one character is deleted, but
196 not saved in the kill ring.
198 The value returned is always `nil'.
201 File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
203 User-Level Deletion Commands
204 ============================
206 This section describes higher-level commands for deleting text,
207 commands intended primarily for the user but useful also in Lisp
210 - Command: delete-horizontal-space
211 This function deletes all spaces and tabs around point. It returns
214 In the following examples, we call `delete-horizontal-space' four
215 times, once on each line, with point between the second and third
216 characters on the line each time.
218 ---------- Buffer: foo ----------
223 ---------- Buffer: foo ----------
225 (delete-horizontal-space) ; Four times.
228 ---------- Buffer: foo ----------
233 ---------- Buffer: foo ----------
235 - Command: delete-indentation &optional join-following-p
236 This function joins the line point is on to the previous line,
237 deleting any whitespace at the join and in some cases replacing it
238 with one space. If JOIN-FOLLOWING-P is non-`nil',
239 `delete-indentation' joins this line to the following line
240 instead. The value is `nil'.
242 If there is a fill prefix, and the second of the lines being joined
243 starts with the prefix, then `delete-indentation' deletes the fill
244 prefix before joining the lines. *Note Margins::.
246 In the example below, point is located on the line starting
247 `events', and it makes no difference if there are trailing spaces
248 in the preceding line.
250 ---------- Buffer: foo ----------
251 When in the course of human
252 -!- events, it becomes necessary
253 ---------- Buffer: foo ----------
258 ---------- Buffer: foo ----------
259 When in the course of human-!- events, it becomes necessary
260 ---------- Buffer: foo ----------
262 After the lines are joined, the function `fixup-whitespace' is
263 responsible for deciding whether to leave a space at the junction.
265 - Function: fixup-whitespace
266 This function replaces all the white space surrounding point with
267 either one space or no space, according to the context. It
270 At the beginning or end of a line, the appropriate amount of space
271 is none. Before a character with close parenthesis syntax, or
272 after a character with open parenthesis or expression-prefix
273 syntax, no space is also appropriate. Otherwise, one space is
274 appropriate. *Note Syntax Class Table::.
276 In the example below, `fixup-whitespace' is called the first time
277 with point before the word `spaces' in the first line. For the
278 second invocation, point is directly after the `('.
280 ---------- Buffer: foo ----------
281 This has too many -!-spaces
282 This has too many spaces at the start of (-!- this list)
283 ---------- Buffer: foo ----------
290 ---------- Buffer: foo ----------
291 This has too many spaces
292 This has too many spaces at the start of (this list)
293 ---------- Buffer: foo ----------
295 - Command: just-one-space
296 This command replaces any spaces and tabs around point with a
297 single space. It returns `nil'.
299 - Command: delete-blank-lines
300 This function deletes blank lines surrounding point. If point is
301 on a blank line with one or more blank lines before or after it,
302 then all but one of them are deleted. If point is on an isolated
303 blank line, then it is deleted. If point is on a nonblank line,
304 the command deletes all blank lines following it.
306 A blank line is defined as a line containing only tabs and spaces.
308 `delete-blank-lines' returns `nil'.
311 File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
316 "Kill" functions delete text like the deletion functions, but save
317 it so that the user can reinsert it by "yanking". Most of these
318 functions have `kill-' in their name. By contrast, the functions whose
319 names start with `delete-' normally do not save text for yanking
320 (though they can still be undone); these are "deletion" functions.
322 Most of the kill commands are primarily for interactive use, and are
323 not described here. What we do describe are the functions provided for
324 use in writing such commands. You can use these functions to write
325 commands for killing text. When you need to delete text for internal
326 purposes within a Lisp function, you should normally use deletion
327 functions, so as not to disturb the kill ring contents. *Note
330 Killed text is saved for later yanking in the "kill ring". This is
331 a list that holds a number of recent kills, not just the last text
332 kill. We call this a "ring" because yanking treats it as having
333 elements in a cyclic order. The list is kept in the variable
334 `kill-ring', and can be operated on with the usual functions for lists;
335 there are also specialized functions, described in this section, that
338 Some people think this use of the word "kill" is unfortunate, since
339 it refers to operations that specifically _do not_ destroy the entities
340 "killed". This is in sharp contrast to ordinary life, in which death
341 is permanent and "killed" entities do not come back to life.
342 Therefore, other metaphors have been proposed. For example, the term
343 "cut ring" makes sense to people who, in pre-computer days, used
344 scissors and paste to cut up and rearrange manuscripts. However, it
345 would be difficult to change the terminology now.
349 * Kill Ring Concepts:: What text looks like in the kill ring.
350 * Kill Functions:: Functions that kill text.
351 * Yank Commands:: Commands that access the kill ring.
352 * Low-Level Kill Ring:: Functions and variables for kill ring access.
353 * Internals of Kill Ring:: Variables that hold kill-ring data.
356 File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
361 The kill ring records killed text as strings in a list, most recent
362 first. A short kill ring, for example, might look like this:
364 ("some text" "a different piece of text" "even older text")
366 When the list reaches `kill-ring-max' entries in length, adding a new
367 entry automatically deletes the last entry.
369 When kill commands are interwoven with other commands, each kill
370 command makes a new entry in the kill ring. Multiple kill commands in
371 succession build up a single entry in the kill ring, which would be
372 yanked as a unit; the second and subsequent consecutive kill commands
373 add text to the entry made by the first one.
375 For yanking, one entry in the kill ring is designated the "front" of
376 the ring. Some yank commands "rotate" the ring by designating a
377 different element as the "front." But this virtual rotation doesn't
378 change the list itself--the most recent entry always comes first in the
382 File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
384 Functions for Killing
385 ---------------------
387 `kill-region' is the usual subroutine for killing text. Any command
388 that calls this function is a "kill command" (and should probably have
389 `kill' in its name). `kill-region' puts the newly killed text in a new
390 element at the beginning of the kill ring or adds it to the most recent
391 element. It uses the `last-command' variable to determine whether the
392 previous command was a kill command, and if so appends the killed text
393 to the most recent entry.
395 - Command: kill-region start end
396 This function kills the text in the region defined by START and
397 END. The text is deleted but saved in the kill ring, along with
398 its text properties. The value is always `nil'.
400 In an interactive call, START and END are point and the mark.
402 If the buffer is read-only, `kill-region' modifies the kill ring
403 just the same, then signals an error without modifying the buffer.
404 This is convenient because it lets the user use all the kill
405 commands to copy text into the kill ring from a read-only buffer.
407 - Command: copy-region-as-kill start end
408 This command saves the region defined by START and END on the kill
409 ring (including text properties), but does not delete the text
410 from the buffer. It returns `nil'. It also indicates the extent
411 of the text copied by moving the cursor momentarily, or by
412 displaying a message in the echo area.
414 The command does not set `this-command' to `kill-region', so a
415 subsequent kill command does not append to the same kill ring
418 Don't call `copy-region-as-kill' in Lisp programs unless you aim to
419 support Emacs 18. For Emacs 19, it is better to use `kill-new' or
420 `kill-append' instead. *Note Low-Level Kill Ring::.
423 File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
425 Functions for Yanking
426 ---------------------
428 "Yanking" means reinserting an entry of previously killed text from
429 the kill ring. The text properties are copied too.
431 - Command: yank &optional arg
432 This command inserts before point the text in the first entry in
433 the kill ring. It positions the mark at the beginning of that
434 text, and point at the end.
436 If ARG is a list (which occurs interactively when the user types
437 `C-u' with no digits), then `yank' inserts the text as described
438 above, but puts point before the yanked text and puts the mark
441 If ARG is a number, then `yank' inserts the ARGth most recently
442 killed text--the ARGth element of the kill ring list.
444 `yank' does not alter the contents of the kill ring or rotate it.
447 - Command: yank-pop arg
448 This command replaces the just-yanked entry from the kill ring
449 with a different entry from the kill ring.
451 This is allowed only immediately after a `yank' or another
452 `yank-pop'. At such a time, the region contains text that was just
453 inserted by yanking. `yank-pop' deletes that text and inserts in
454 its place a different piece of killed text. It does not add the
455 deleted text to the kill ring, since it is already in the kill
458 If ARG is `nil', then the replacement text is the previous element
459 of the kill ring. If ARG is numeric, the replacement is the ARGth
460 previous kill. If ARG is negative, a more recent kill is the
463 The sequence of kills in the kill ring wraps around, so that after
464 the oldest one comes the newest one, and before the newest one
467 The value is always `nil'.
470 File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
475 These functions and variables provide access to the kill ring at a
476 lower level, but still convenient for use in Lisp programs. They take
477 care of interaction with X Window selections. They do not exist in
480 - Function: current-kill n &optional do-not-move
481 The function `current-kill' rotates the yanking pointer which
482 designates the "front" of the kill ring by N places (from newer
483 kills to older ones), and returns the text at that place in the
486 If the optional second argument DO-NOT-MOVE is non-`nil', then
487 `current-kill' doesn't alter the yanking pointer; it just returns
488 the Nth kill, counting from the current yanking pointer.
490 If N is zero, indicating a request for the latest kill,
491 `current-kill' calls the value of `interprogram-paste-function'
492 (documented below) before consulting the kill ring.
494 - Function: kill-new string
495 This function puts the text STRING into the kill ring as a new
496 entry at the front of the ring. It discards the oldest entry if
497 appropriate. It also invokes the value of
498 `interprogram-cut-function' (see below).
500 - Function: kill-append string before-p
501 This function appends the text STRING to the first entry in the
502 kill ring. Normally STRING goes at the end of the entry, but if
503 BEFORE-P is non-`nil', it goes at the beginning. This function
504 also invokes the value of `interprogram-cut-function' (see below).
506 - Variable: interprogram-paste-function
507 This variable provides a way of transferring killed text from other
508 programs, when you are using a window system. Its value should be
509 `nil' or a function of no arguments.
511 If the value is a function, `current-kill' calls it to get the
512 "most recent kill". If the function returns a non-`nil' value,
513 then that value is used as the "most recent kill". If it returns
514 `nil', then the first element of `kill-ring' is used.
516 The normal use of this hook is to get the X server's primary
517 selection as the most recent kill, even if the selection belongs
518 to another X client. *Note X Selections::.
520 - Variable: interprogram-cut-function
521 This variable provides a way of communicating killed text to other
522 programs, when you are using a window system. Its value should be
523 `nil' or a function of one argument.
525 If the value is a function, `kill-new' and `kill-append' call it
526 with the new first element of the kill ring as an argument.
528 The normal use of this hook is to set the X server's primary
529 selection to the newly killed text.
532 File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
534 Internals of the Kill Ring
535 --------------------------
537 The variable `kill-ring' holds the kill ring contents, in the form
538 of a list of strings. The most recent kill is always at the front of
541 The `kill-ring-yank-pointer' variable points to a link in the kill
542 ring list, whose CAR is the text to yank next. We say it identifies
543 the "front" of the ring. Moving `kill-ring-yank-pointer' to a
544 different link is called "rotating the kill ring". We call the kill
545 ring a "ring" because the functions that move the yank pointer wrap
546 around from the end of the list to the beginning, or vice-versa.
547 Rotation of the kill ring is virtual; it does not change the value of
550 Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
551 whose values are normally lists. The word "pointer" in the name of the
552 `kill-ring-yank-pointer' indicates that the variable's purpose is to
553 identify one element of the list for use by the next yank command.
555 The value of `kill-ring-yank-pointer' is always `eq' to one of the
556 links in the kill ring list. The element it identifies is the CAR of
557 that link. Kill commands, which change the kill ring, also set this
558 variable to the value of `kill-ring'. The effect is to rotate the ring
559 so that the newly killed text is at the front.
561 Here is a diagram that shows the variable `kill-ring-yank-pointer'
562 pointing to the second entry in the kill ring `("some text" "a
563 different piece of text" "yet older text")'.
565 kill-ring kill-ring-yank-pointer
567 | ___ ___ ---> ___ ___ ___ ___
568 --> |___|___|------> |___|___|--> |___|___|--> nil
571 | | -->"yet older text"
573 | --> "a different piece of text"
577 This state of affairs might occur after `C-y' (`yank') immediately
578 followed by `M-y' (`yank-pop').
580 - Variable: kill-ring
581 This variable holds the list of killed text sequences, most
582 recently killed first.
584 - Variable: kill-ring-yank-pointer
585 This variable's value indicates which element of the kill ring is
586 at the "front" of the ring for yanking. More precisely, the value
587 is a tail of the value of `kill-ring', and its CAR is the kill
588 string that `C-y' should yank.
590 - User Option: kill-ring-max
591 The value of this variable is the maximum length to which the kill
592 ring can grow, before elements are thrown away at the end. The
593 default value for `kill-ring-max' is 30.
596 File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
601 Most buffers have an "undo list", which records all changes made to
602 the buffer's text so that they can be undone. (The buffers that don't
603 have one are usually special-purpose buffers for which XEmacs assumes
604 that undoing is not useful.) All the primitives that modify the text
605 in the buffer automatically add elements to the front of the undo list,
606 which is in the variable `buffer-undo-list'.
608 - Variable: buffer-undo-list
609 This variable's value is the undo list of the current buffer. A
610 value of `t' disables the recording of undo information.
612 Here are the kinds of elements an undo list can have:
615 This kind of element records a previous value of point. Ordinary
616 cursor motion does not get any sort of undo record, but deletion
617 commands use these entries to record where point was before the
621 This kind of element indicates how to delete text that was
622 inserted. Upon insertion, the text occupied the range BEG-END in
626 This kind of element indicates how to reinsert text that was
627 deleted. The deleted text itself is the string TEXT. The place to
628 reinsert it is `(abs POSITION)'.
631 This kind of element indicates that an unmodified buffer became
632 modified. The elements HIGH and LOW are two integers, each
633 recording 16 bits of the visited file's modification time as of
634 when it was previously visited or saved. `primitive-undo' uses
635 those values to determine whether to mark the buffer as unmodified
636 once again; it does so only if the file's modification time
637 matches those numbers.
639 `(nil PROPERTY VALUE BEG . END)'
640 This kind of element records a change in a text property. Here's
641 how you might undo the change:
643 (put-text-property BEG END PROPERTY VALUE)
646 This element indicates where point was at an earlier time.
647 Undoing this element sets point to POSITION. Deletion normally
648 creates an element of this kind as well as a reinsertion element.
651 This element is a boundary. The elements between two boundaries
652 are called a "change group"; normally, each change group
653 corresponds to one keyboard command, and undo commands normally
654 undo an entire group as a unit.
656 - Function: undo-boundary
657 This function places a boundary element in the undo list. The undo
658 command stops at such a boundary, and successive undo commands undo
659 to earlier and earlier boundaries. This function returns `nil'.
661 The editor command loop automatically creates an undo boundary
662 before each key sequence is executed. Thus, each undo normally
663 undoes the effects of one command. Self-inserting input
664 characters are an exception. The command loop makes a boundary
665 for the first such character; the next 19 consecutive
666 self-inserting input characters do not make boundaries, and then
667 the 20th does, and so on as long as self-inserting characters
670 All buffer modifications add a boundary whenever the previous
671 undoable change was made in some other buffer. This way, a
672 command that modifies several buffers makes a boundary in each
675 Calling this function explicitly is useful for splitting the
676 effects of a command into more than one unit. For example,
677 `query-replace' calls `undo-boundary' after each replacement, so
678 that the user can undo individual replacements one by one.
680 - Function: primitive-undo count list
681 This is the basic function for undoing elements of an undo list.
682 It undoes the first COUNT elements of LIST, returning the rest of
683 LIST. You could write this function in Lisp, but it is convenient
686 `primitive-undo' adds elements to the buffer's undo list when it
687 changes the buffer. Undo commands avoid confusion by saving the
688 undo list value at the beginning of a sequence of undo operations.
689 Then the undo operations use and update the saved value. The new
690 elements added by undoing are not part of this saved value, so
691 they don't interfere with continuing to undo.
694 File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
696 Maintaining Undo Lists
697 ======================
699 This section describes how to enable and disable undo information for
700 a given buffer. It also explains how the undo list is truncated
701 automatically so it doesn't get too big.
703 Recording of undo information in a newly created buffer is normally
704 enabled to start with; but if the buffer name starts with a space, the
705 undo recording is initially disabled. You can explicitly enable or
706 disable undo recording with the following two functions, or by setting
707 `buffer-undo-list' yourself.
709 - Command: buffer-enable-undo &optional buffer-or-name
710 This command enables recording undo information for buffer
711 BUFFER-OR-NAME, so that subsequent changes can be undone. If no
712 argument is supplied, then the current buffer is used. This
713 function does nothing if undo recording is already enabled in the
714 buffer. It returns `nil'.
716 In an interactive call, BUFFER-OR-NAME is the current buffer. You
717 cannot specify any other buffer.
719 - Function: buffer-disable-undo &optional buffer
720 - Function: buffer-flush-undo &optional buffer
721 This function discards the undo list of BUFFER, and disables
722 further recording of undo information. As a result, it is no
723 longer possible to undo either previous changes or any subsequent
724 changes. If the undo list of BUFFER is already disabled, this
725 function has no effect.
727 This function returns `nil'. It cannot be called interactively.
729 The name `buffer-flush-undo' is not considered obsolete, but the
730 preferred name `buffer-disable-undo' is new as of Emacs versions
733 As editing continues, undo lists get longer and longer. To prevent
734 them from using up all available memory space, garbage collection trims
735 them back to size limits you can set. (For this purpose, the "size" of
736 an undo list measures the cons cells that make up the list, plus the
737 strings of deleted text.) Two variables control the range of acceptable
738 sizes: `undo-limit' and `undo-strong-limit'.
740 - Variable: undo-limit
741 This is the soft limit for the acceptable size of an undo list.
742 The change group at which this size is exceeded is the last one
745 - Variable: undo-strong-limit
746 This is the upper limit for the acceptable size of an undo list.
747 The change group at which this size is exceeded is discarded
748 itself (along with all older change groups). There is one
749 exception: the very latest change group is never discarded no
750 matter how big it is.
753 File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
758 "Filling" means adjusting the lengths of lines (by moving the line
759 breaks) so that they are nearly (but no greater than) a specified
760 maximum width. Additionally, lines can be "justified", which means
761 inserting spaces to make the left and/or right margins line up
762 precisely. The width is controlled by the variable `fill-column'. For
763 ease of reading, lines should be no longer than 70 or so columns.
765 You can use Auto Fill mode (*note Auto Filling::) to fill text
766 automatically as you insert it, but changes to existing text may leave
767 it improperly filled. Then you must fill the text explicitly.
769 Most of the commands in this section return values that are not
770 meaningful. All the functions that do filling take note of the current
771 left margin, current right margin, and current justification style
772 (*note Margins::). If the current justification style is `none', the
773 filling functions don't actually do anything.
775 Several of the filling functions have an argument JUSTIFY. If it is
776 non-`nil', that requests some kind of justification. It can be `left',
777 `right', `full', or `center', to request a specific style of
778 justification. If it is `t', that means to use the current
779 justification style for this part of the text (see
780 `current-justification', below).
782 When you call the filling functions interactively, using a prefix
783 argument implies the value `full' for JUSTIFY.
785 - Command: fill-paragraph justify
786 This command fills the paragraph at or after point. If JUSTIFY is
787 non-`nil', each line is justified as well. It uses the ordinary
788 paragraph motion commands to find paragraph boundaries. *Note
789 Paragraphs: (xemacs)Paragraphs.
791 - Command: fill-region start end &optional justify
792 This command fills each of the paragraphs in the region from START
793 to END. It justifies as well if JUSTIFY is non-`nil'.
795 The variable `paragraph-separate' controls how to distinguish
796 paragraphs. *Note Standard Regexps::.
798 - Command: fill-individual-paragraphs start end &optional justify
800 This command fills each paragraph in the region according to its
801 individual fill prefix. Thus, if the lines of a paragraph were
802 indented with spaces, the filled paragraph will remain indented in
805 The first two arguments, START and END, are the beginning and end
806 of the region to be filled. The third and fourth arguments,
807 JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
808 paragraphs are justified as well as filled. If MAIL-FLAG is
809 non-`nil', it means the function is operating on a mail message
810 and therefore should not fill the header lines.
812 Ordinarily, `fill-individual-paragraphs' regards each change in
813 indentation as starting a new paragraph. If
814 `fill-individual-varying-indent' is non-`nil', then only separator
815 lines separate paragraphs. That mode can handle indented
816 paragraphs with additional indentation on the first line.
818 - User Option: fill-individual-varying-indent
819 This variable alters the action of `fill-individual-paragraphs' as
822 - Command: fill-region-as-paragraph start end &optional justify
823 This command considers a region of text as a paragraph and fills
824 it. If the region was made up of many paragraphs, the blank lines
825 between paragraphs are removed. This function justifies as well
826 as filling when JUSTIFY is non-`nil'.
828 In an interactive call, any prefix argument requests justification.
830 In Adaptive Fill mode, which is enabled by default,
831 `fill-region-as-paragraph' on an indented paragraph when there is
832 no fill prefix uses the indentation of the second line of the
833 paragraph as the fill prefix.
835 - Command: justify-current-line how eop nosqueeze
836 This command inserts spaces between the words of the current line
837 so that the line ends exactly at `fill-column'. It returns `nil'.
839 The argument HOW, if non-`nil' specifies explicitly the style of
840 justification. It can be `left', `right', `full', `center', or
841 `none'. If it is `t', that means to do follow specified
842 justification style (see `current-justification', below). `nil'
843 means to do full justification.
845 If EOP is non-`nil', that means do left-justification when
846 `current-justification' specifies full justification. This is used
847 for the last line of a paragraph; even if the paragraph as a whole
848 is fully justified, the last line should not be.
850 If NOSQUEEZE is non-`nil', that means do not change interior
853 - User Option: default-justification
854 This variable's value specifies the style of justification to use
855 for text that doesn't specify a style with a text property. The
856 possible values are `left', `right', `full', `center', or `none'.
857 The default value is `left'.
859 - Function: current-justification
860 This function returns the proper justification style to use for
861 filling the text around point.
863 - Variable: fill-paragraph-function
864 This variable provides a way for major modes to override the
865 filling of paragraphs. If the value is non-`nil',
866 `fill-paragraph' calls this function to do the work. If the
867 function returns a non-`nil' value, `fill-paragraph' assumes the
868 job is done, and immediately returns that value.
870 The usual use of this feature is to fill comments in programming
871 language modes. If the function needs to fill a paragraph in the
872 usual way, it can do so as follows:
874 (let ((fill-paragraph-function nil))
875 (fill-paragraph arg))
877 - Variable: use-hard-newlines
878 If this variable is non-`nil', the filling functions do not delete
879 newlines that have the `hard' text property. These "hard
880 newlines" act as paragraph separators.
883 File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
888 - User Option: fill-prefix
889 This variable specifies a string of text that appears at the
890 beginning of normal text lines and should be disregarded when
891 filling them. Any line that fails to start with the fill prefix
892 is considered the start of a paragraph; so is any line that starts
893 with the fill prefix followed by additional whitespace. Lines
894 that start with the fill prefix but no additional whitespace are
895 ordinary text lines that can be filled together. The resulting
896 filled lines also start with the fill prefix.
898 The fill prefix follows the left margin whitespace, if any.
900 - User Option: fill-column
901 This buffer-local variable specifies the maximum width of filled
902 lines. Its value should be an integer, which is a number of
903 columns. All the filling, justification and centering commands
904 are affected by this variable, including Auto Fill mode (*note
907 As a practical matter, if you are writing text for other people to
908 read, you should set `fill-column' to no more than 70. Otherwise
909 the line will be too long for people to read comfortably, and this
910 can make the text seem clumsy.
912 - Variable: default-fill-column
913 The value of this variable is the default value for `fill-column'
914 in buffers that do not override it. This is the same as
915 `(default-value 'fill-column)'.
917 The default value for `default-fill-column' is 70.
919 - Command: set-left-margin from to margin
920 This sets the `left-margin' property on the text from FROM to TO
921 to the value MARGIN. If Auto Fill mode is enabled, this command
922 also refills the region to fit the new margin.
924 - Command: set-right-margin from to margin
925 This sets the `right-margin' property on the text from FROM to TO
926 to the value MARGIN. If Auto Fill mode is enabled, this command
927 also refills the region to fit the new margin.
929 - Function: current-left-margin
930 This function returns the proper left margin value to use for
931 filling the text around point. The value is the sum of the
932 `left-margin' property of the character at the start of the
933 current line (or zero if none), and the value of the variable
936 - Function: current-fill-column
937 This function returns the proper fill column value to use for
938 filling the text around point. The value is the value of the
939 `fill-column' variable, minus the value of the `right-margin'
940 property of the character after point.
942 - Command: move-to-left-margin &optional n force
943 This function moves point to the left margin of the current line.
944 The column moved to is determined by calling the function
945 `current-left-margin'. If the argument N is non-`nil',
946 `move-to-left-margin' moves forward N-1 lines first.
948 If FORCE is non-`nil', that says to fix the line's indentation if
949 that doesn't match the left margin value.
951 - Function: delete-to-left-margin from to
952 This function removes left margin indentation from the text
953 between FROM and TO. The amount of indentation to delete is
954 determined by calling `current-left-margin'. In no case does this
955 function delete non-whitespace.
957 - Function: indent-to-left-margin
958 This is the default `indent-line-function', used in Fundamental
959 mode, Text mode, etc. Its effect is to adjust the indentation at
960 the beginning of the current line to the value specified by the
961 variable `left-margin'. This may involve either inserting or
964 - Variable: left-margin
965 This variable specifies the base left margin column. In
966 Fundamental mode, <LFD> indents to this column. This variable
967 automatically becomes buffer-local when set in any fashion.
970 File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
975 Auto Fill mode is a minor mode that fills lines automatically as text
976 is inserted. This section describes the hook used by Auto Fill mode.
977 For a description of functions that you can call explicitly to fill and
978 justify existing text, see *Note Filling::.
980 Auto Fill mode also enables the functions that change the margins and
981 justification style to refill portions of the text. *Note Margins::.
983 - Variable: auto-fill-function
984 The value of this variable should be a function (of no arguments)
985 to be called after self-inserting a space or a newline. It may be
986 `nil', in which case nothing special is done in that case.
988 The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
989 mode is enabled. That is a function whose sole purpose is to
990 implement the usual strategy for breaking a line.
992 In older Emacs versions, this variable was named
993 `auto-fill-hook', but since it is not called with the
994 standard convention for hooks, it was renamed to
995 `auto-fill-function' in version 19.
projects / chise / xemacs-chise.git- / blob