Initial revision
[chise/xemacs-chise.git-] / info / lispref.info-29
1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
7 END-INFO-DIR-ENTRY
8
9    Edition History:
10
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
20
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.
24
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.
28
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.
33
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.
38
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.
45
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.
51
52 \1f
53 File: lispref.info,  Node: Commands for Insertion,  Next: Deletion,  Prev: Insertion,  Up: Text
54
55 User-Level Insertion Commands
56 =============================
57
58    This section describes higher-level commands for inserting text,
59 commands intended primarily for the user but useful also in Lisp
60 programs.
61
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'.
66
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.
73
74      In an interactive call, COUNT is the numeric prefix argument.
75
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
78      Filling::.).
79
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::.)
83
84      This is also responsible for calling `blink-paren-function' when
85      the inserted character has close parenthesis syntax (*note
86      Blinking::.).
87
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
91      are inserted.
92
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'.
100
101      This command indents to the left margin if that is not zero.
102      *Note Margins::.
103
104      The value returned is `nil'.  In an interactive call, COUNT is the
105      numeric prefix argument.
106
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.
113
114      Programs hardly ever use this function.
115
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.
120
121 \1f
122 File: lispref.info,  Node: Deletion,  Next: User-Level Deletion,  Prev: Commands for Insertion,  Up: Text
123
124 Deleting Text
125 =============
126
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
131 cases.
132
133    All of the deletion functions operate on the current buffer, and all
134 return a value of `nil'.
135
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
141      buffer if omitted.
142
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.
148
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.
153
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.
158
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.
164
165      The value returned is always `nil'.
166
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.
171
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.
177
178      The value returned is always `nil'.
179
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.
187
188      Conversion of tabs to spaces happens only if COUNT is positive.
189      If it is negative, exactly -COUNT characters after point are
190      deleted.
191
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.
197
198      The value returned is always `nil'.
199
200 \1f
201 File: lispref.info,  Node: User-Level Deletion,  Next: The Kill Ring,  Prev: Deletion,  Up: Text
202
203 User-Level Deletion Commands
204 ============================
205
206    This section describes higher-level commands for deleting text,
207 commands intended primarily for the user but useful also in Lisp
208 programs.
209
210  - Command: delete-horizontal-space
211      This function deletes all spaces and tabs around point.  It returns
212      `nil'.
213
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.
217
218           ---------- Buffer: foo ----------
219           I -!-thought
220           I -!-     thought
221           We-!- thought
222           Yo-!-u thought
223           ---------- Buffer: foo ----------
224           
225           (delete-horizontal-space)   ; Four times.
226                => nil
227           
228           ---------- Buffer: foo ----------
229           Ithought
230           Ithought
231           Wethought
232           You thought
233           ---------- Buffer: foo ----------
234
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'.
241
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::.
245
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.
249
250           ---------- Buffer: foo ----------
251           When in the course of human
252           -!-    events, it becomes necessary
253           ---------- Buffer: foo ----------
254           
255           (delete-indentation)
256                => nil
257           ---------- Buffer: foo ----------
258           When in the course of human-!- events, it becomes necessary
259           ---------- Buffer: foo ----------
260
261      After the lines are joined, the function `fixup-whitespace' is
262      responsible for deciding whether to leave a space at the junction.
263
264  - Function: fixup-whitespace
265      This function replaces all the white space surrounding point with
266      either one space or no space, according to the context.  It
267      returns `nil'.
268
269      At the beginning or end of a line, the appropriate amount of space
270      is none.  Before a character with close parenthesis syntax, or
271      after a character with open parenthesis or expression-prefix
272      syntax, no space is also appropriate.  Otherwise, one space is
273      appropriate.  *Note Syntax Class Table::.
274
275      In the example below, `fixup-whitespace' is called the first time
276      with point before the word `spaces' in the first line.  For the
277      second invocation, point is directly after the `('.
278
279           ---------- Buffer: foo ----------
280           This has too many     -!-spaces
281           This has too many spaces at the start of (-!-   this list)
282           ---------- Buffer: foo ----------
283
284           (fixup-whitespace)
285                => nil
286           (fixup-whitespace)
287                => nil
288
289           ---------- Buffer: foo ----------
290           This has too many spaces
291           This has too many spaces at the start of (this list)
292           ---------- Buffer: foo ----------
293
294  - Command: just-one-space
295      This command replaces any spaces and tabs around point with a
296      single space.  It returns `nil'.
297
298  - Command: delete-blank-lines
299      This function deletes blank lines surrounding point.  If point is
300      on a blank line with one or more blank lines before or after it,
301      then all but one of them are deleted.  If point is on an isolated
302      blank line, then it is deleted.  If point is on a nonblank line,
303      the command deletes all blank lines following it.
304
305      A blank line is defined as a line containing only tabs and spaces.
306
307      `delete-blank-lines' returns `nil'.
308
309 \1f
310 File: lispref.info,  Node: The Kill Ring,  Next: Undo,  Prev: User-Level Deletion,  Up: Text
311
312 The Kill Ring
313 =============
314
315    "Kill" functions delete text like the deletion functions, but save
316 it so that the user can reinsert it by "yanking".  Most of these
317 functions have `kill-' in their name.  By contrast, the functions whose
318 names start with `delete-' normally do not save text for yanking
319 (though they can still be undone); these are "deletion" functions.
320
321    Most of the kill commands are primarily for interactive use, and are
322 not described here.  What we do describe are the functions provided for
323 use in writing such commands.  You can use these functions to write
324 commands for killing text.  When you need to delete text for internal
325 purposes within a Lisp function, you should normally use deletion
326 functions, so as not to disturb the kill ring contents.  *Note
327 Deletion::.
328
329    Killed text is saved for later yanking in the "kill ring".  This is
330 a list that holds a number of recent kills, not just the last text
331 kill.  We call this a "ring" because yanking treats it as having
332 elements in a cyclic order.  The list is kept in the variable
333 `kill-ring', and can be operated on with the usual functions for lists;
334 there are also specialized functions, described in this section, that
335 treat it as a ring.
336
337    Some people think this use of the word "kill" is unfortunate, since
338 it refers to operations that specifically *do not* destroy the entities
339 "killed".  This is in sharp contrast to ordinary life, in which death
340 is permanent and "killed" entities do not come back to life.
341 Therefore, other metaphors have been proposed.  For example, the term
342 "cut ring" makes sense to people who, in pre-computer days, used
343 scissors and paste to cut up and rearrange manuscripts.  However, it
344 would be difficult to change the terminology now.
345
346 * Menu:
347
348 * Kill Ring Concepts::     What text looks like in the kill ring.
349 * Kill Functions::         Functions that kill text.
350 * Yank Commands::          Commands that access the kill ring.
351 * Low-Level Kill Ring::    Functions and variables for kill ring access.
352 * Internals of Kill Ring:: Variables that hold kill-ring data.
353
354 \1f
355 File: lispref.info,  Node: Kill Ring Concepts,  Next: Kill Functions,  Up: The Kill Ring
356
357 Kill Ring Concepts
358 ------------------
359
360    The kill ring records killed text as strings in a list, most recent
361 first.  A short kill ring, for example, might look like this:
362
363      ("some text" "a different piece of text" "even older text")
364
365 When the list reaches `kill-ring-max' entries in length, adding a new
366 entry automatically deletes the last entry.
367
368    When kill commands are interwoven with other commands, each kill
369 command makes a new entry in the kill ring.  Multiple kill commands in
370 succession build up a single entry in the kill ring, which would be
371 yanked as a unit; the second and subsequent consecutive kill commands
372 add text to the entry made by the first one.
373
374    For yanking, one entry in the kill ring is designated the "front" of
375 the ring.  Some yank commands "rotate" the ring by designating a
376 different element as the "front."  But this virtual rotation doesn't
377 change the list itself--the most recent entry always comes first in the
378 list.
379
380 \1f
381 File: lispref.info,  Node: Kill Functions,  Next: Yank Commands,  Prev: Kill Ring Concepts,  Up: The Kill Ring
382
383 Functions for Killing
384 ---------------------
385
386    `kill-region' is the usual subroutine for killing text.  Any command
387 that calls this function is a "kill command" (and should probably have
388 `kill' in its name).  `kill-region' puts the newly killed text in a new
389 element at the beginning of the kill ring or adds it to the most recent
390 element.  It uses the `last-command' variable to determine whether the
391 previous command was a kill command, and if so appends the killed text
392 to the most recent entry.
393
394  - Command: kill-region START END
395      This function kills the text in the region defined by START and
396      END.  The text is deleted but saved in the kill ring, along with
397      its text properties.  The value is always `nil'.
398
399      In an interactive call, START and END are point and the mark.
400
401      If the buffer is read-only, `kill-region' modifies the kill ring
402      just the same, then signals an error without modifying the buffer.
403      This is convenient because it lets the user use all the kill
404      commands to copy text into the kill ring from a read-only buffer.
405
406  - Command: copy-region-as-kill START END
407      This command saves the region defined by START and END on the kill
408      ring (including text properties), but does not delete the text
409      from the buffer.  It returns `nil'.  It also indicates the extent
410      of the text copied by moving the cursor momentarily, or by
411      displaying a message in the echo area.
412
413      The command does not set `this-command' to `kill-region', so a
414      subsequent kill command does not append to the same kill ring
415      entry.
416
417      Don't call `copy-region-as-kill' in Lisp programs unless you aim to
418      support Emacs 18.  For Emacs 19, it is better to use `kill-new' or
419      `kill-append' instead.  *Note Low-Level Kill Ring::.
420
421 \1f
422 File: lispref.info,  Node: Yank Commands,  Next: Low-Level Kill Ring,  Prev: Kill Functions,  Up: The Kill Ring
423
424 Functions for Yanking
425 ---------------------
426
427    "Yanking" means reinserting an entry of previously killed text from
428 the kill ring.  The text properties are copied too.
429
430  - Command: yank &optional ARG
431      This command inserts before point the text in the first entry in
432      the kill ring.  It positions the mark at the beginning of that
433      text, and point at the end.
434
435      If ARG is a list (which occurs interactively when the user types
436      `C-u' with no digits), then `yank' inserts the text as described
437      above, but puts point before the yanked text and puts the mark
438      after it.
439
440      If ARG is a number, then `yank' inserts the ARGth most recently
441      killed text--the ARGth element of the kill ring list.
442
443      `yank' does not alter the contents of the kill ring or rotate it.
444      It returns `nil'.
445
446  - Command: yank-pop ARG
447      This command replaces the just-yanked entry from the kill ring
448      with a different entry from the kill ring.
449
450      This is allowed only immediately after a `yank' or another
451      `yank-pop'.  At such a time, the region contains text that was just
452      inserted by yanking.  `yank-pop' deletes that text and inserts in
453      its place a different piece of killed text.  It does not add the
454      deleted text to the kill ring, since it is already in the kill
455      ring somewhere.
456
457      If ARG is `nil', then the replacement text is the previous element
458      of the kill ring.  If ARG is numeric, the replacement is the ARGth
459      previous kill.  If ARG is negative, a more recent kill is the
460      replacement.
461
462      The sequence of kills in the kill ring wraps around, so that after
463      the oldest one comes the newest one, and before the newest one
464      goes the oldest.
465
466      The value is always `nil'.
467
468 \1f
469 File: lispref.info,  Node: Low-Level Kill Ring,  Next: Internals of Kill Ring,  Prev: Yank Commands,  Up: The Kill Ring
470
471 Low-Level Kill Ring
472 -------------------
473
474    These functions and variables provide access to the kill ring at a
475 lower level, but still convenient for use in Lisp programs.  They take
476 care of interaction with X Window selections.  They do not exist in
477 Emacs version 18.
478
479  - Function: current-kill N &optional DO-NOT-MOVE
480      The function `current-kill' rotates the yanking pointer which
481      designates the "front" of the kill ring by N places (from newer
482      kills to older ones), and returns the text at that place in the
483      ring.
484
485      If the optional second argument DO-NOT-MOVE is non-`nil', then
486      `current-kill' doesn't alter the yanking pointer; it just returns
487      the Nth kill, counting from the current yanking pointer.
488
489      If N is zero, indicating a request for the latest kill,
490      `current-kill' calls the value of `interprogram-paste-function'
491      (documented below) before consulting the kill ring.
492
493  - Function: kill-new STRING
494      This function puts the text STRING into the kill ring as a new
495      entry at the front of the ring.  It discards the oldest entry if
496      appropriate.  It also invokes the value of
497      `interprogram-cut-function' (see below).
498
499  - Function: kill-append STRING BEFORE-P
500      This function appends the text STRING to the first entry in the
501      kill ring.  Normally STRING goes at the end of the entry, but if
502      BEFORE-P is non-`nil', it goes at the beginning.  This function
503      also invokes the value of `interprogram-cut-function' (see below).
504
505  - Variable: interprogram-paste-function
506      This variable provides a way of transferring killed text from other
507      programs, when you are using a window system.  Its value should be
508      `nil' or a function of no arguments.
509
510      If the value is a function, `current-kill' calls it to get the
511      "most recent kill".  If the function returns a non-`nil' value,
512      then that value is used as the "most recent kill".  If it returns
513      `nil', then the first element of `kill-ring' is used.
514
515      The normal use of this hook is to get the X server's primary
516      selection as the most recent kill, even if the selection belongs
517      to another X client.  *Note X Selections::.
518
519  - Variable: interprogram-cut-function
520      This variable provides a way of communicating killed text to other
521      programs, when you are using a window system.  Its value should be
522      `nil' or a function of one argument.
523
524      If the value is a function, `kill-new' and `kill-append' call it
525      with the new first element of the kill ring as an argument.
526
527      The normal use of this hook is to set the X server's primary
528      selection to the newly killed text.
529
530 \1f
531 File: lispref.info,  Node: Internals of Kill Ring,  Prev: Low-Level Kill Ring,  Up: The Kill Ring
532
533 Internals of the Kill Ring
534 --------------------------
535
536    The variable `kill-ring' holds the kill ring contents, in the form
537 of a list of strings.  The most recent kill is always at the front of
538 the list.
539
540    The `kill-ring-yank-pointer' variable points to a link in the kill
541 ring list, whose CAR is the text to yank next.  We say it identifies
542 the "front" of the ring.  Moving `kill-ring-yank-pointer' to a
543 different link is called "rotating the kill ring".  We call the kill
544 ring a "ring" because the functions that move the yank pointer wrap
545 around from the end of the list to the beginning, or vice-versa.
546 Rotation of the kill ring is virtual; it does not change the value of
547 `kill-ring'.
548
549    Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
550 whose values are normally lists.  The word "pointer" in the name of the
551 `kill-ring-yank-pointer' indicates that the variable's purpose is to
552 identify one element of the list for use by the next yank command.
553
554    The value of `kill-ring-yank-pointer' is always `eq' to one of the
555 links in the kill ring list.  The element it identifies is the CAR of
556 that link.  Kill commands, which change the kill ring, also set this
557 variable to the value of `kill-ring'.  The effect is to rotate the ring
558 so that the newly killed text is at the front.
559
560    Here is a diagram that shows the variable `kill-ring-yank-pointer'
561 pointing to the second entry in the kill ring `("some text" "a
562 different piece of text" "yet older text")'.
563
564      kill-ring       kill-ring-yank-pointer
565        |               |
566        |     ___ ___    --->  ___ ___      ___ ___
567         --> |___|___|------> |___|___|--> |___|___|--> nil
568               |                |            |
569               |                |            |
570               |                |             -->"yet older text"
571               |                |
572               |                 --> "a different piece of text"
573               |
574                --> "some text"
575
576 This state of affairs might occur after `C-y' (`yank') immediately
577 followed by `M-y' (`yank-pop').
578
579  - Variable: kill-ring
580      This variable holds the list of killed text sequences, most
581      recently killed first.
582
583  - Variable: kill-ring-yank-pointer
584      This variable's value indicates which element of the kill ring is
585      at the "front" of the ring for yanking.  More precisely, the value
586      is a tail of the value of `kill-ring', and its CAR is the kill
587      string that `C-y' should yank.
588
589  - User Option: kill-ring-max
590      The value of this variable is the maximum length to which the kill
591      ring can grow, before elements are thrown away at the end.  The
592      default value for `kill-ring-max' is 30.
593
594 \1f
595 File: lispref.info,  Node: Undo,  Next: Maintaining Undo,  Prev: The Kill Ring,  Up: Text
596
597 Undo
598 ====
599
600    Most buffers have an "undo list", which records all changes made to
601 the buffer's text so that they can be undone.  (The buffers that don't
602 have one are usually special-purpose buffers for which XEmacs assumes
603 that undoing is not useful.)  All the primitives that modify the text
604 in the buffer automatically add elements to the front of the undo list,
605 which is in the variable `buffer-undo-list'.
606
607  - Variable: buffer-undo-list
608      This variable's value is the undo list of the current buffer.  A
609      value of `t' disables the recording of undo information.
610
611    Here are the kinds of elements an undo list can have:
612
613 `INTEGER'
614      This kind of element records a previous value of point.  Ordinary
615      cursor motion does not get any sort of undo record, but deletion
616      commands use these entries to record where point was before the
617      command.
618
619 `(BEG . END)'
620      This kind of element indicates how to delete text that was
621      inserted.  Upon insertion, the text occupied the range BEG-END in
622      the buffer.
623
624 `(TEXT . POSITION)'
625      This kind of element indicates how to reinsert text that was
626      deleted.  The deleted text itself is the string TEXT.  The place to
627      reinsert it is `(abs POSITION)'.
628
629 `(t HIGH . LOW)'
630      This kind of element indicates that an unmodified buffer became
631      modified.  The elements HIGH and LOW are two integers, each
632      recording 16 bits of the visited file's modification time as of
633      when it was previously visited or saved.  `primitive-undo' uses
634      those values to determine whether to mark the buffer as unmodified
635      once again; it does so only if the file's modification time
636      matches those numbers.
637
638 `(nil PROPERTY VALUE BEG . END)'
639      This kind of element records a change in a text property.  Here's
640      how you might undo the change:
641
642           (put-text-property BEG END PROPERTY VALUE)
643
644 `POSITION'
645      This element indicates where point was at an earlier time.
646      Undoing this element sets point to POSITION.  Deletion normally
647      creates an element of this kind as well as a reinsertion element.
648
649 `nil'
650      This element is a boundary.  The elements between two boundaries
651      are called a "change group"; normally, each change group
652      corresponds to one keyboard command, and undo commands normally
653      undo an entire group as a unit.
654
655  - Function: undo-boundary
656      This function places a boundary element in the undo list.  The undo
657      command stops at such a boundary, and successive undo commands undo
658      to earlier and earlier boundaries.  This function returns `nil'.
659
660      The editor command loop automatically creates an undo boundary
661      before each key sequence is executed.  Thus, each undo normally
662      undoes the effects of one command.  Self-inserting input
663      characters are an exception.  The command loop makes a boundary
664      for the first such character; the next 19 consecutive
665      self-inserting input characters do not make boundaries, and then
666      the 20th does, and so on as long as self-inserting characters
667      continue.
668
669      All buffer modifications add a boundary whenever the previous
670      undoable change was made in some other buffer.  This way, a
671      command that modifies several buffers makes a boundary in each
672      buffer it changes.
673
674      Calling this function explicitly is useful for splitting the
675      effects of a command into more than one unit.  For example,
676      `query-replace' calls `undo-boundary' after each replacement, so
677      that the user can undo individual replacements one by one.
678
679  - Function: primitive-undo COUNT LIST
680      This is the basic function for undoing elements of an undo list.
681      It undoes the first COUNT elements of LIST, returning the rest of
682      LIST.  You could write this function in Lisp, but it is convenient
683      to have it in C.
684
685      `primitive-undo' adds elements to the buffer's undo list when it
686      changes the buffer.  Undo commands avoid confusion by saving the
687      undo list value at the beginning of a sequence of undo operations.
688      Then the undo operations use and update the saved value.  The new
689      elements added by undoing are not part of this saved value, so
690      they don't interfere with continuing to undo.
691
692 \1f
693 File: lispref.info,  Node: Maintaining Undo,  Next: Filling,  Prev: Undo,  Up: Text
694
695 Maintaining Undo Lists
696 ======================
697
698    This section describes how to enable and disable undo information for
699 a given buffer.  It also explains how the undo list is truncated
700 automatically so it doesn't get too big.
701
702    Recording of undo information in a newly created buffer is normally
703 enabled to start with; but if the buffer name starts with a space, the
704 undo recording is initially disabled.  You can explicitly enable or
705 disable undo recording with the following two functions, or by setting
706 `buffer-undo-list' yourself.
707
708  - Command: buffer-enable-undo &optional BUFFER-OR-NAME
709      This command enables recording undo information for buffer
710      BUFFER-OR-NAME, so that subsequent changes can be undone.  If no
711      argument is supplied, then the current buffer is used.  This
712      function does nothing if undo recording is already enabled in the
713      buffer.  It returns `nil'.
714
715      In an interactive call, BUFFER-OR-NAME is the current buffer.  You
716      cannot specify any other buffer.
717
718  - Function: buffer-disable-undo &optional BUFFER
719  - Function: buffer-flush-undo &optional BUFFER
720      This function discards the undo list of BUFFER, and disables
721      further recording of undo information.  As a result, it is no
722      longer possible to undo either previous changes or any subsequent
723      changes.  If the undo list of BUFFER is already disabled, this
724      function has no effect.
725
726      This function returns `nil'.  It cannot be called interactively.
727
728      The name `buffer-flush-undo' is not considered obsolete, but the
729      preferred name `buffer-disable-undo' is new as of Emacs versions
730      19.
731
732    As editing continues, undo lists get longer and longer.  To prevent
733 them from using up all available memory space, garbage collection trims
734 them back to size limits you can set.  (For this purpose, the "size" of
735 an undo list measures the cons cells that make up the list, plus the
736 strings of deleted text.)  Two variables control the range of acceptable
737 sizes: `undo-limit' and `undo-strong-limit'.
738
739  - Variable: undo-limit
740      This is the soft limit for the acceptable size of an undo list.
741      The change group at which this size is exceeded is the last one
742      kept.
743
744  - Variable: undo-strong-limit
745      This is the upper limit for the acceptable size of an undo list.
746      The change group at which this size is exceeded is discarded
747      itself (along with all older change groups).  There is one
748      exception: the very latest change group is never discarded no
749      matter how big it is.
750
751 \1f
752 File: lispref.info,  Node: Filling,  Next: Margins,  Prev: Maintaining Undo,  Up: Text
753
754 Filling
755 =======
756
757    "Filling" means adjusting the lengths of lines (by moving the line
758 breaks) so that they are nearly (but no greater than) a specified
759 maximum width.  Additionally, lines can be "justified", which means
760 inserting spaces to make the left and/or right margins line up
761 precisely.  The width is controlled by the variable `fill-column'.  For
762 ease of reading, lines should be no longer than 70 or so columns.
763
764    You can use Auto Fill mode (*note Auto Filling::.) to fill text
765 automatically as you insert it, but changes to existing text may leave
766 it improperly filled.  Then you must fill the text explicitly.
767
768    Most of the commands in this section return values that are not
769 meaningful.  All the functions that do filling take note of the current
770 left margin, current right margin, and current justification style
771 (*note Margins::.).  If the current justification style is `none', the
772 filling functions don't actually do anything.
773
774    Several of the filling functions have an argument JUSTIFY.  If it is
775 non-`nil', that requests some kind of justification.  It can be `left',
776 `right', `full', or `center', to request a specific style of
777 justification.  If it is `t', that means to use the current
778 justification style for this part of the text (see
779 `current-justification', below).
780
781    When you call the filling functions interactively, using a prefix
782 argument implies the value `full' for JUSTIFY.
783
784  - Command: fill-paragraph JUSTIFY
785      This command fills the paragraph at or after point.  If JUSTIFY is
786      non-`nil', each line is justified as well.  It uses the ordinary
787      paragraph motion commands to find paragraph boundaries.  *Note
788      Paragraphs: (xemacs)Paragraphs.
789
790  - Command: fill-region START END &optional JUSTIFY
791      This command fills each of the paragraphs in the region from START
792      to END.  It justifies as well if JUSTIFY is non-`nil'.
793
794      The variable `paragraph-separate' controls how to distinguish
795      paragraphs.  *Note Standard Regexps::.
796
797  - Command: fill-individual-paragraphs START END &optional JUSTIFY
798           MAIL-FLAG
799      This command fills each paragraph in the region according to its
800      individual fill prefix.  Thus, if the lines of a paragraph were
801      indented with spaces, the filled paragraph will remain indented in
802      the same fashion.
803
804      The first two arguments, START and END, are the beginning and end
805      of the region to be filled.  The third and fourth arguments,
806      JUSTIFY and MAIL-FLAG, are optional.  If JUSTIFY is non-`nil', the
807      paragraphs are justified as well as filled.  If MAIL-FLAG is
808      non-`nil', it means the function is operating on a mail message
809      and therefore should not fill the header lines.
810
811      Ordinarily, `fill-individual-paragraphs' regards each change in
812      indentation as starting a new paragraph.  If
813      `fill-individual-varying-indent' is non-`nil', then only separator
814      lines separate paragraphs.  That mode can handle indented
815      paragraphs with additional indentation on the first line.
816
817  - User Option: fill-individual-varying-indent
818      This variable alters the action of `fill-individual-paragraphs' as
819      described above.
820
821  - Command: fill-region-as-paragraph START END &optional JUSTIFY
822      This command considers a region of text as a paragraph and fills
823      it.  If the region was made up of many paragraphs, the blank lines
824      between paragraphs are removed.  This function justifies as well
825      as filling when JUSTIFY is non-`nil'.
826
827      In an interactive call, any prefix argument requests justification.
828
829      In Adaptive Fill mode, which is enabled by default,
830      `fill-region-as-paragraph' on an indented paragraph when there is
831      no fill prefix uses the indentation of the second line of the
832      paragraph as the fill prefix.
833
834  - Command: justify-current-line HOW EOP NOSQUEEZE
835      This command inserts spaces between the words of the current line
836      so that the line ends exactly at `fill-column'.  It returns `nil'.
837
838      The argument HOW, if non-`nil' specifies explicitly the style of
839      justification.  It can be `left', `right', `full', `center', or
840      `none'.  If it is `t', that means to do follow specified
841      justification style (see `current-justification', below).  `nil'
842      means to do full justification.
843
844      If EOP is non-`nil', that means do left-justification when
845      `current-justification' specifies full justification.  This is used
846      for the last line of a paragraph; even if the paragraph as a whole
847      is fully justified, the last line should not be.
848
849      If NOSQUEEZE is non-`nil', that means do not change interior
850      whitespace.
851
852  - User Option: default-justification
853      This variable's value specifies the style of justification to use
854      for text that doesn't specify a style with a text property.  The
855      possible values are `left', `right', `full', `center', or `none'.
856      The default value is `left'.
857
858  - Function: current-justification
859      This function returns the proper justification style to use for
860      filling the text around point.
861
862  - Variable: fill-paragraph-function
863      This variable provides a way for major modes to override the
864      filling of paragraphs.  If the value is non-`nil',
865      `fill-paragraph' calls this function to do the work.  If the
866      function returns a non-`nil' value, `fill-paragraph' assumes the
867      job is done, and immediately returns that value.
868
869      The usual use of this feature is to fill comments in programming
870      language modes.  If the function needs to fill a paragraph in the
871      usual way, it can do so as follows:
872
873           (let ((fill-paragraph-function nil))
874             (fill-paragraph arg))
875
876  - Variable: use-hard-newlines
877      If this variable is non-`nil', the filling functions do not delete
878      newlines that have the `hard' text property.  These "hard
879      newlines" act as paragraph separators.
880
881 \1f
882 File: lispref.info,  Node: Margins,  Next: Auto Filling,  Prev: Filling,  Up: Text
883
884 Margins for Filling
885 ===================
886
887  - User Option: fill-prefix
888      This variable specifies a string of text that appears at the
889      beginning of normal text lines and should be disregarded when
890      filling them.  Any line that fails to start with the fill prefix
891      is considered the start of a paragraph; so is any line that starts
892      with the fill prefix followed by additional whitespace.  Lines
893      that start with the fill prefix but no additional whitespace are
894      ordinary text lines that can be filled together.  The resulting
895      filled lines also start with the fill prefix.
896
897      The fill prefix follows the left margin whitespace, if any.
898
899  - User Option: fill-column
900      This buffer-local variable specifies the maximum width of filled
901      lines.  Its value should be an integer, which is a number of
902      columns.  All the filling, justification and centering commands
903      are affected by this variable, including Auto Fill mode (*note
904      Auto Filling::.).
905
906      As a practical matter, if you are writing text for other people to
907      read, you should set `fill-column' to no more than 70.  Otherwise
908      the line will be too long for people to read comfortably, and this
909      can make the text seem clumsy.
910
911  - Variable: default-fill-column
912      The value of this variable is the default value for `fill-column'
913      in buffers that do not override it.  This is the same as
914      `(default-value 'fill-column)'.
915
916      The default value for `default-fill-column' is 70.
917
918  - Command: set-left-margin FROM TO MARGIN
919      This sets the `left-margin' property on the text from FROM to TO
920      to the value MARGIN.  If Auto Fill mode is enabled, this command
921      also refills the region to fit the new margin.
922
923  - Command: set-right-margin FROM TO MARGIN
924      This sets the `right-margin' property on the text from FROM to TO
925      to the value MARGIN.  If Auto Fill mode is enabled, this command
926      also refills the region to fit the new margin.
927
928  - Function: current-left-margin
929      This function returns the proper left margin value to use for
930      filling the text around point.  The value is the sum of the
931      `left-margin' property of the character at the start of the
932      current line (or zero if none), and the value of the variable
933      `left-margin'.
934
935  - Function: current-fill-column
936      This function returns the proper fill column value to use for
937      filling the text around point.  The value is the value of the
938      `fill-column' variable, minus the value of the `right-margin'
939      property of the character after point.
940
941  - Command: move-to-left-margin &optional N FORCE
942      This function moves point to the left margin of the current line.
943      The column moved to is determined by calling the function
944      `current-left-margin'.  If the argument N is non-`nil',
945      `move-to-left-margin' moves forward N-1 lines first.
946
947      If FORCE is non-`nil', that says to fix the line's indentation if
948      that doesn't match the left margin value.
949
950  - Function: delete-to-left-margin FROM TO
951      This function removes left margin indentation from the text
952      between FROM and TO.  The amount of indentation to delete is
953      determined by calling `current-left-margin'.  In no case does this
954      function delete non-whitespace.
955
956  - Function: indent-to-left-margin
957      This is the default `indent-line-function', used in Fundamental
958      mode, Text mode, etc.  Its effect is to adjust the indentation at
959      the beginning of the current line to the value specified by the
960      variable `left-margin'.  This may involve either inserting or
961      deleting whitespace.
962
963  - Variable: left-margin
964      This variable specifies the base left margin column.  In
965      Fundamental mode, <LFD> indents to this column.  This variable
966      automatically becomes buffer-local when set in any fashion.
967
968 \1f
969 File: lispref.info,  Node: Auto Filling,  Next: Sorting,  Prev: Margins,  Up: Text
970
971 Auto Filling
972 ============
973
974    Auto Fill mode is a minor mode that fills lines automatically as text
975 is inserted.  This section describes the hook used by Auto Fill mode.
976 For a description of functions that you can call explicitly to fill and
977 justify existing text, see *Note Filling::.
978
979    Auto Fill mode also enables the functions that change the margins and
980 justification style to refill portions of the text.  *Note Margins::.
981
982  - Variable: auto-fill-function
983      The value of this variable should be a function (of no arguments)
984      to be called after self-inserting a space or a newline.  It may be
985      `nil', in which case nothing special is done in that case.
986
987      The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
988      mode is enabled.  That is a function whose sole purpose is to
989      implement the usual strategy for breaking a line.
990
991           In older Emacs versions, this variable was named
992           `auto-fill-hook', but since it is not called with the
993           standard convention for hooks, it was renamed to
994           `auto-fill-function' in version 19.
995