+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.
+
+\1f