-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
-
-Sorting Text
-============
-
- The sorting functions described in this section all rearrange text in
-a buffer. This is in contrast to the function `sort', which rearranges
-the order of the elements of a list (*note Rearrangement::). The
-values returned by these functions are not meaningful.
-
- - Function: sort-subr reverse nextrecfun endrecfun &optional
- startkeyfun endkeyfun
- This function is the general text-sorting routine that divides a
- buffer into records and sorts them. Most of the commands in this
- section use this function.
-
- To understand how `sort-subr' works, consider the whole accessible
- portion of the buffer as being divided into disjoint pieces called
- "sort records". The records may or may not be contiguous; they may
- not overlap. A portion of each sort record (perhaps all of it) is
- designated as the sort key. Sorting rearranges the records in
- order by their sort keys.
-
- Usually, the records are rearranged in order of ascending sort key.
- If the first argument to the `sort-subr' function, REVERSE, is
- non-`nil', the sort records are rearranged in order of descending
- sort key.
-
- The next four arguments to `sort-subr' are functions that are
- called to move point across a sort record. They are called many
- times from within `sort-subr'.
-
- 1. NEXTRECFUN is called with point at the end of a record. This
- function moves point to the start of the next record. The
- first record is assumed to start at the position of point
- when `sort-subr' is called. Therefore, you should usually
- move point to the beginning of the buffer before calling
- `sort-subr'.
-
- This function can indicate there are no more sort records by
- leaving point at the end of the buffer.
-
- 2. ENDRECFUN is called with point within a record. It moves
- point to the end of the record.
-
- 3. STARTKEYFUN is called to move point from the start of a
- record to the start of the sort key. This argument is
- optional; if it is omitted, the whole record is the sort key.
- If supplied, the function should either return a non-`nil'
- value to be used as the sort key, or return `nil' to indicate
- that the sort key is in the buffer starting at point. In the
- latter case, ENDKEYFUN is called to find the end of the sort
- key.
-
- 4. ENDKEYFUN is called to move point from the start of the sort
- key to the end of the sort key. This argument is optional.
- If STARTKEYFUN returns `nil' and this argument is omitted (or
- `nil'), then the sort key extends to the end of the record.
- There is no need for ENDKEYFUN if STARTKEYFUN returns a
- non-`nil' value.
-
- As an example of `sort-subr', here is the complete function
- definition for `sort-lines':
-
- ;; Note that the first two lines of doc string
- ;; are effectively one line when viewed by a user.
- (defun sort-lines (reverse beg end)
- "Sort lines in region alphabetically.
- Called from a program, there are three arguments:
- REVERSE (non-nil means reverse order),
- and BEG and END (the region to sort)."
- (interactive "P\nr")
- (save-restriction
- (narrow-to-region beg end)
- (goto-char (point-min))
- (sort-subr reverse
- 'forward-line
- 'end-of-line)))
-
- Here `forward-line' moves point to the start of the next record,
- and `end-of-line' moves point to the end of record. We do not pass
- the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
- is used as the sort key.
-
- The `sort-paragraphs' function is very much the same, except that
- its `sort-subr' call looks like this:
-
- (sort-subr reverse
- (function
- (lambda ()
- (skip-chars-forward "\n \t\f")))
- 'forward-paragraph)
-
- - Command: sort-regexp-fields reverse record-regexp key-regexp start
- end
- This command sorts the region between START and END alphabetically
- as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
- negative integer, then sorting is in reverse order.
-
- Alphabetical sorting means that two sort keys are compared by
- comparing the first characters of each, the second characters of
- each, and so on. If a mismatch is found, it means that the sort
- keys are unequal; the sort key whose character is less at the
- point of first mismatch is the lesser sort key. The individual
- characters are compared according to their numerical values.
- Since Emacs uses the ASCII character set, the ordering in that set
- determines alphabetical order.
-
- The value of the RECORD-REGEXP argument specifies how to divide
- the buffer into sort records. At the end of each record, a search
- is done for this regular expression, and the text that matches it
- is the next record. For example, the regular expression `^.+$',
- which matches lines with at least one character besides a newline,
- would make each such line into a sort record. *Note Regular
- Expressions::, for a description of the syntax and meaning of
- regular expressions.
-
- The value of the KEY-REGEXP argument specifies what part of each
- record is the sort key. The KEY-REGEXP could match the whole
- record, or only a part. In the latter case, the rest of the
- record has no effect on the sorted order of records, but it is
- carried along when the record moves to its new position.
-
- The KEY-REGEXP argument can refer to the text matched by a
- subexpression of RECORD-REGEXP, or it can be a regular expression
- on its own.
-
- If KEY-REGEXP is:
-
- `\DIGIT'
- then the text matched by the DIGITth `\(...\)' parenthesis
- grouping in RECORD-REGEXP is the sort key.
-
- `\&'
- then the whole record is the sort key.
-
- a regular expression
- then `sort-regexp-fields' searches for a match for the regular
- expression within the record. If such a match is found, it
- is the sort key. If there is no match for KEY-REGEXP within
- a record then that record is ignored, which means its
- position in the buffer is not changed. (The other records
- may move around it.)
-
- For example, if you plan to sort all the lines in the region by the
- first word on each line starting with the letter `f', you should
- set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'. The
- resulting expression looks like this:
-
- (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
- (region-beginning)
- (region-end))
-
- If you call `sort-regexp-fields' interactively, it prompts for
- RECORD-REGEXP and KEY-REGEXP in the minibuffer.
-
- - Command: sort-lines reverse start end
- This command alphabetically sorts lines in the region between
- START and END. If REVERSE is non-`nil', the sort is in reverse
- order.
-
- - Command: sort-paragraphs reverse start end
- This command alphabetically sorts paragraphs in the region between
- START and END. If REVERSE is non-`nil', the sort is in reverse
- order.
-
- - Command: sort-pages reverse start end
- This command alphabetically sorts pages in the region between
- START and END. If REVERSE is non-`nil', the sort is in reverse
- order.
-
- - Command: sort-fields field start end
- This command sorts lines in the region between START and END,
- comparing them alphabetically by the FIELDth field of each line.
- Fields are separated by whitespace and numbered starting from 1.
- If FIELD is negative, sorting is by the -FIELDth field from the
- end of the line. This command is useful for sorting tables.
-
- - Command: sort-numeric-fields field start end
- This command sorts lines in the region between START and END,
- comparing them numerically by the FIELDth field of each line. The
- specified field must contain a number in each line of the region.
- Fields are separated by whitespace and numbered starting from 1.
- If FIELD is negative, sorting is by the -FIELDth field from the
- end of the line. This command is useful for sorting tables.
-
- - Command: sort-columns reverse &optional beg end
- This command sorts the lines in the region between BEG and END,
- comparing them alphabetically by a certain range of columns. The
- column positions of BEG and END bound the range of columns to sort
- on.
-
- If REVERSE is non-`nil', the sort is in reverse order.
-
- One unusual thing about this command is that the entire line
- containing position BEG, and the entire line containing position
- END, are included in the region sorted.
-
- Note that `sort-columns' uses the `sort' utility program, and so
- cannot work properly on text containing tab characters. Use `M-x
- `untabify'' to convert tabs to spaces before sorting.
-
-\1f
-File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
-
-Counting Columns
-================
-
- The column functions convert between a character position (counting
-characters from the beginning of the buffer) and a column position
-(counting screen characters from the beginning of a line).
-
- A character counts according to the number of columns it occupies on
-the screen. This means control characters count as occupying 2 or 4
-columns, depending upon the value of `ctl-arrow', and tabs count as
-occupying a number of columns that depends on the value of `tab-width'
-and on the column where the tab begins. *Note Usual Display::.
-
- Column number computations ignore the width of the window and the
-amount of horizontal scrolling. Consequently, a column value can be
-arbitrarily high. The first (or leftmost) column is numbered 0.
-
- - Function: current-column
- This function returns the horizontal position of point, measured in
- columns, counting from 0 at the left margin. The column position
- is the sum of the widths of all the displayed representations of
- the characters between the start of the current line and point.
-
- For an example of using `current-column', see the description of
- `count-lines' in *Note Text Lines::.
-
- - Function: move-to-column column &optional force
- This function moves point to COLUMN in the current line. The
- calculation of COLUMN takes into account the widths of the
- displayed representations of the characters between the start of
- the line and point.
-
- If column COLUMN is beyond the end of the line, point moves to the
- end of the line. If COLUMN is negative, point moves to the
- beginning of the line.
-
- If it is impossible to move to column COLUMN because that is in
- the middle of a multicolumn character such as a tab, point moves
- to the end of that character. However, if FORCE is non-`nil', and
- COLUMN is in the middle of a tab, then `move-to-column' converts
- the tab into spaces so that it can move precisely to column
- COLUMN. Other multicolumn characters can cause anomalies despite
- FORCE, since there is no way to split them.
-
- The argument FORCE also has an effect if the line isn't long
- enough to reach column COLUMN; in that case, it says to add
- whitespace at the end of the line to reach that column.
-
- If COLUMN is not an integer, an error is signaled.
-
- The return value is the column number actually moved to.
-
-\1f
-File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
-
-Indentation
-===========
-
- The indentation functions are used to examine, move to, and change
-whitespace that is at the beginning of a line. Some of the functions
-can also change whitespace elsewhere on a line. Columns and indentation
-count from zero at the left margin.
-
-* Menu:
-
-* Primitive Indent:: Functions used to count and insert indentation.
-* Mode-Specific Indent:: Customize indentation for different modes.
-* Region Indent:: Indent all the lines in a region.
-* Relative Indent:: Indent the current line based on previous lines.
-* Indent Tabs:: Adjustable, typewriter-like tab stops.
-* Motion by Indent:: Move to first non-blank character.
-
-\1f
-File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
-
-Indentation Primitives
-----------------------
-
- This section describes the primitive functions used to count and
-insert indentation. The functions in the following sections use these
-primitives.
-
- - Function: current-indentation
- This function returns the indentation of the current line, which is
- the horizontal position of the first nonblank character. If the
- contents are entirely blank, then this is the horizontal position
- of the end of the line.
-
- - Command: indent-to column &optional minimum
- This function indents from point with tabs and spaces until COLUMN
- is reached. If MINIMUM is specified and non-`nil', then at least
- that many spaces are inserted even if this requires going beyond
- COLUMN. Otherwise the function does nothing if point is already
- beyond COLUMN. The value is the column at which the inserted
- indentation ends.
-
- - User Option: indent-tabs-mode
- If this variable is non-`nil', indentation functions can insert
- tabs as well as spaces. Otherwise, they insert only spaces.
- Setting this variable automatically makes it local to the current
- buffer.
-
-\1f
-File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
-
-Indentation Controlled by Major Mode
-------------------------------------
-
- An important function of each major mode is to customize the <TAB>
-key to indent properly for the language being edited. This section
-describes the mechanism of the <TAB> key and how to control it. The
-functions in this section return unpredictable values.
-
- - Variable: indent-line-function
- This variable's value is the function to be used by <TAB> (and
- various commands) to indent the current line. The command
- `indent-according-to-mode' does no more than call this function.
-
- In Lisp mode, the value is the symbol `lisp-indent-line'; in C
- mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
- Fundamental mode, Text mode, and many other modes with no standard
- for indentation, the value is `indent-to-left-margin' (which is the
- default value).
-
- - Command: indent-according-to-mode
- This command calls the function in `indent-line-function' to
- indent the current line in a way appropriate for the current major
- mode.
-
- - Command: indent-for-tab-command
- This command calls the function in `indent-line-function' to indent
- the current line; except that if that function is
- `indent-to-left-margin', it calls `insert-tab' instead. (That is
- a trivial command that inserts a tab character.)
-
- - Command: newline-and-indent
- This function inserts a newline, then indents the new line (the one
- following the newline just inserted) according to the major mode.
-
- It does indentation by calling the current `indent-line-function'.
- In programming language modes, this is the same thing <TAB> does,
- but in some text modes, where <TAB> inserts a tab,
- `newline-and-indent' indents to the column specified by
- `left-margin'.
-
- - Command: reindent-then-newline-and-indent
- This command reindents the current line, inserts a newline at
- point, and then reindents the new line (the one following the
- newline just inserted).
-
- This command does indentation on both lines according to the
- current major mode, by calling the current value of
- `indent-line-function'. In programming language modes, this is
- the same thing <TAB> does, but in some text modes, where <TAB>
- inserts a tab, `reindent-then-newline-and-indent' indents to the
- column specified by `left-margin'.
-
-\1f
-File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
-
-Indenting an Entire Region
---------------------------
-
- This section describes commands that indent all the lines in the
-region. They return unpredictable values.
-
- - Command: indent-region start end to-column
- This command indents each nonblank line starting between START
- (inclusive) and END (exclusive). If TO-COLUMN is `nil',
- `indent-region' indents each nonblank line by calling the current
- mode's indentation function, the value of `indent-line-function'.
-
- If TO-COLUMN is non-`nil', it should be an integer specifying the
- number of columns of indentation; then this function gives each
- line exactly that much indentation, by either adding or deleting
- whitespace.
-
- If there is a fill prefix, `indent-region' indents each line by
- making it start with the fill prefix.
-
- - Variable: indent-region-function
- The value of this variable is a function that can be used by
- `indent-region' as a short cut. You should design the function so
- that it will produce the same results as indenting the lines of the
- region one by one, but presumably faster.
+File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
+
+Inserting Text
+==============
+
+ "Insertion" means adding new text to a buffer. The inserted text
+goes at point--between the character before point and the character
+after point.
+
+ Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text (*note
+Markers::). When a marker points at the place of insertion, insertion
+normally doesn't relocate the marker, so that it points to the
+beginning of the inserted text; however, certain special functions such
+as `insert-before-markers' relocate such markers to point after the
+inserted text.
+
+ Some insertion functions leave point before the inserted text, while
+other functions leave it after. We call the former insertion "after
+point" and the latter insertion "before point".
+
+ If a string with non-`nil' extent data is inserted, the remembered
+extents will also be inserted. *Note Duplicable Extents::.
+
+ Insertion functions signal an error if the current buffer is
+read-only.
+
+ These functions copy text characters from strings and buffers along
+with their properties. The inserted characters have exactly the same
+properties as the characters they were copied from. By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+ - Function: insert &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. In other words, it
+ inserts the text before point. An error is signaled unless all
+ ARGS are either strings or characters. The value is `nil'.
+
+ - Function: insert-before-markers &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. An error is
+ signaled unless all ARGS are either strings or characters. The
+ value is `nil'.
- If the value is `nil', there is no short cut, and `indent-region'
- actually works line by line.
+ This function is unlike the other insertion functions in that it
+ relocates markers initially pointing at the insertion point, to
+ point after the inserted text.
- A short-cut function is useful in modes such as C mode and Lisp
- mode, where the `indent-line-function' must scan from the
- beginning of the function definition: applying it to each line
- would be quadratic in time. The short cut can update the scan
- information as it moves through the lines indenting them; this
- takes linear time. In a mode where indenting a line individually
- is fast, there is no need for a short cut.
+ - Function: insert-string string &optional buffer
+ This function inserts STRING into BUFFER before point. BUFFER
+ defaults to the current buffer if omitted. This function is
+ chiefly useful if you want to insert a string in a buffer other
+ than the current one (otherwise you could just use `insert').
- `indent-region' with a non-`nil' argument TO-COLUMN has a
- different meaning and does not use this variable.
+ - Function: insert-char character &optional count ignored buffer
+ This function inserts COUNT instances of CHARACTER into BUFFER
+ before point. COUNT must be a number, and CHARACTER must be a
+ character.
- - Command: indent-rigidly start end count
- This command indents all lines starting between START (inclusive)
- and END (exclusive) sideways by COUNT columns. This "preserves
- the shape" of the affected region, moving it as a rigid unit.
- Consequently, this command is useful not only for indenting
- regions of unindented text, but also for indenting regions of
- formatted code.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. (In FSF Emacs, the third argument is called INHERIT and
+ refers to text properties. In XEmacs, it is always ignored.)
- For example, if COUNT is 3, this command adds 3 columns of
- indentation to each of the lines beginning in the region specified.
+ This function always returns `nil'.
- In Mail mode, `C-c C-y' (`mail-yank-original') uses
- `indent-rigidly' to indent the text copied from the message being
- replied to.
+ - Function: insert-buffer-substring from-buffer-or-name &optional
+ start end
+ This function inserts a portion of buffer FROM-BUFFER-OR-NAME
+ (which must already exist) into the current buffer before point.
+ The text inserted is the region from START and END. (These
+ arguments default to the beginning and end of the accessible
+ portion of that buffer.) This function returns `nil'.
- - Function: indent-code-rigidly start end columns &optional
- nochange-regexp
- This is like `indent-rigidly', except that it doesn't alter lines
- that start within strings or comments.
+ In this example, the form is executed with buffer `bar' as the
+ current buffer. We assume that buffer `bar' is initially empty.
- In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
- the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
+ ---------- Buffer: foo ----------
+ We hold these truths to be self-evident, that all
+ ---------- Buffer: foo ----------
+
+ (insert-buffer-substring "foo" 1 20)
+ => nil
+
+ ---------- Buffer: bar ----------
+ We hold these truth-!-
+ ---------- Buffer: bar ----------
\1f
-File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
+File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
-Indentation Relative to Previous Lines
---------------------------------------
+User-Level Insertion Commands
+=============================
- This section describes two commands that indent the current line
-based on the contents of previous lines.
+ This section describes higher-level commands for inserting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
- - Command: indent-relative &optional unindented-ok
- This command inserts whitespace at point, extending to the same
- column as the next "indent point" of the previous nonblank line.
- An indent point is a non-whitespace character following
- whitespace. The next indent point is the first one at a column
- greater than the current column of point. For example, if point
- is underneath and to the left of the first non-blank character of
- a line of text, it moves to that column by inserting whitespace.
+ - Command: insert-buffer from-buffer-or-name
+ This command inserts the entire contents of FROM-BUFFER-OR-NAME
+ (which must exist) into the current buffer after point. It leaves
+ the mark after the inserted text. The value is `nil'.
- If the previous nonblank line has no next indent point (i.e., none
- at a great enough column position), `indent-relative' either does
- nothing (if UNINDENTED-OK is non-`nil') or calls
- `tab-to-tab-stop'. Thus, if point is underneath and to the right
- of the last column of a short line of text, this command ordinarily
- moves point to the next tab stop by inserting whitespace.
+ - Command: self-insert-command count
+ This command inserts the last character typed; it does so COUNT
+ times, before point, and returns `nil'. Most printing characters
+ are bound to this command. In routine use, `self-insert-command'
+ is the most frequently called function in XEmacs, but programs
+ rarely use it except to install it on a keymap.
- The return value of `indent-relative' is unpredictable.
+ In an interactive call, COUNT is the numeric prefix argument.
- In the following example, point is at the beginning of the second
- line:
+ This command calls `auto-fill-function' whenever that is non-`nil'
+ and the character inserted is a space or a newline (*note Auto
+ Filling::).
- This line is indented twelve spaces.
- -!-The quick brown fox jumped.
+ This command performs abbrev expansion if Abbrev mode is enabled
+ and the inserted character does not have word-constituent syntax.
+ (*Note Abbrevs::, and *Note Syntax Class Table::.)
- Evaluation of the expression `(indent-relative nil)' produces the
- following:
+ This is also responsible for calling `blink-paren-function' when
+ the inserted character has close parenthesis syntax (*note
+ Blinking::).
- This line is indented twelve spaces.
- -!-The quick brown fox jumped.
+ - Command: newline &optional count
+ This command inserts newlines into the current buffer before point.
+ If COUNT is supplied, that many newline characters are inserted.
- In this example, point is between the `m' and `p' of `jumped':
+ This function calls `auto-fill-function' if the current column
+ number is greater than the value of `fill-column' and COUNT is
+ `nil'. Typically what `auto-fill-function' does is insert a
+ newline; thus, the overall result in this case is to insert two
+ newlines at different places: one at point, and another earlier in
+ the line. `newline' does not auto-fill if COUNT is non-`nil'.
- This line is indented twelve spaces.
- The quick brown fox jum-!-ped.
+ This command indents to the left margin if that is not zero.
+ *Note Margins::.
- Evaluation of the expression `(indent-relative nil)' produces the
- following:
+ The value returned is `nil'. In an interactive call, COUNT is the
+ numeric prefix argument.
- This line is indented twelve spaces.
- The quick brown fox jum -!-ped.
+ - Command: split-line
+ This command splits the current line, moving the portion of the
+ line after point down vertically so that it is on the next line
+ directly below where it was before. Whitespace is inserted as
+ needed at the beginning of the lower line, using the `indent-to'
+ function. `split-line' returns the position of point.
- - Command: indent-relative-maybe
- This command indents the current line like the previous nonblank
- line. It calls `indent-relative' with `t' as the UNINDENTED-OK
- argument. The return value is unpredictable.
+ Programs hardly ever use this function.
- If the previous nonblank line has no indent points beyond the
- current column, this command does nothing.
+ - Variable: overwrite-mode
+ This variable controls whether overwrite mode is in effect: a
+ non-`nil' value enables the mode. It is automatically made
+ buffer-local when set in any fashion.
\1f
-File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
-
-Adjustable "Tab Stops"
-----------------------
-
- This section explains the mechanism for user-specified "tab stops"
-and the mechanisms that use and set them. The name "tab stops" is used
-because the feature is similar to that of the tab stops on a
-typewriter. The feature works by inserting an appropriate number of
-spaces and tab characters to reach the next tab stop column; it does not
-affect the display of tab characters in the buffer (*note Usual
-Display::). Note that the <TAB> character as input uses this tab stop
-feature only in a few major modes, such as Text mode.
-
- - Command: tab-to-tab-stop
- This command inserts spaces or tabs up to the next tab stop column
- defined by `tab-stop-list'. It searches the list for an element
- greater than the current column number, and uses that element as
- the column to indent to. It does nothing if no such element is
- found.
-
- - User Option: tab-stop-list
- This variable is the list of tab stop columns used by
- `tab-to-tab-stops'. The elements should be integers in increasing
- order. The tab stop columns need not be evenly spaced.
-
- Use `M-x edit-tab-stops' to edit the location of tab stops
- interactively.
+File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
+
+Deleting Text
+=============
+
+ Deletion means removing part of the text in a buffer, without saving
+it in the kill ring (*note The Kill Ring::). Deleted text can't be
+yanked, but can be reinserted using the undo mechanism (*note Undo::).
+Some deletion functions do save text in the kill ring in some special
+cases.
+
+ All of the deletion functions operate on the current buffer, and all
+return a value of `nil'.
+
+ - Command: erase-buffer &optional buffer
+ This function deletes the entire text of BUFFER, leaving it empty.
+ If the buffer is read-only, it signals a `buffer-read-only'
+ error. Otherwise, it deletes the text without asking for any
+ confirmation. It returns `nil'. BUFFER defaults to the current
+ buffer if omitted.
+
+ Normally, deleting a large amount of text from a buffer inhibits
+ further auto-saving of that buffer "because it has shrunk".
+ However, `erase-buffer' does not do this, the idea being that the
+ future text is not really related to the former text, and its size
+ should not be compared with that of the former text.
+
+ - Command: delete-region start end &optional buffer
+ This command deletes the text in BUFFER in the region defined by
+ START and END. The value is `nil'. If optional argument BUFFER
+ is `nil', the current buffer is assumed.
+
+ - Command: delete-char &optional count killp
+ This command deletes COUNT characters directly after point, or
+ before point if COUNT is negative. COUNT defaults to `1'. If
+ KILLP is non-`nil', then it saves the deleted characters in the
+ kill ring.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
+
+ - Command: delete-backward-char &optional count killp
+ This command deletes COUNT characters directly before point, or
+ after point if COUNT is negative. COUNT defaults to 1. If KILLP
+ is non-`nil', then it saves the deleted characters in the kill
+ ring.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
+
+ - Command: backward-delete-char-untabify count &optional killp
+ This command deletes COUNT characters backward, changing tabs into
+ spaces. When the next character to be deleted is a tab, it is
+ first replaced with the proper number of spaces to preserve
+ alignment and then one of those spaces is deleted instead of the
+ tab. If KILLP is non-`nil', then the command saves the deleted
+ characters in the kill ring.
+
+ Conversion of tabs to spaces happens only if COUNT is positive.
+ If it is negative, exactly -COUNT characters after point are
+ deleted.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
\1f
-File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
+File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
-Indentation-Based Motion Commands
----------------------------------
+User-Level Deletion Commands
+============================
- These commands, primarily for interactive use, act based on the
-indentation in the text.
+ This section describes higher-level commands for deleting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
- - Command: back-to-indentation
- This command moves point to the first non-whitespace character in
- the current line (which is the line in which point is located).
- It returns `nil'.
-
- - Command: backward-to-indentation arg
- This command moves point backward ARG lines and then to the first
- nonblank character on that line. It returns `nil'.
+ - Command: delete-horizontal-space
+ This function deletes all spaces and tabs around point. It returns
+ `nil'.
- - Command: forward-to-indentation arg
- This command moves point forward ARG lines and then to the first
- nonblank character on that line. It returns `nil'.
-
-\1f
-File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
+ In the following examples, we call `delete-horizontal-space' four
+ times, once on each line, with point between the second and third
+ characters on the line each time.
-Case Changes
-============
-
- The case change commands described here work on text in the current
-buffer. *Note Character Case::, for case conversion commands that work
-on strings and characters. *Note Case Tables::, for how to customize
-which characters are upper or lower case and how to convert them.
+ ---------- Buffer: foo ----------
+ I -!-thought
+ I -!- thought
+ We-!- thought
+ Yo-!-u thought
+ ---------- Buffer: foo ----------
+
+ (delete-horizontal-space) ; Four times.
+ => nil
+
+ ---------- Buffer: foo ----------
+ Ithought
+ Ithought
+ Wethought
+ You thought
+ ---------- Buffer: foo ----------
- - Command: capitalize-region start end
- This function capitalizes all words in the region defined by START
- and END. To capitalize means to convert each word's first
- character to upper case and convert the rest of each word to lower
- case. The function returns `nil'.
+ - Command: delete-indentation &optional join-following-p
+ This function joins the line point is on to the previous line,
+ deleting any whitespace at the join and in some cases replacing it
+ with one space. If JOIN-FOLLOWING-P is non-`nil',
+ `delete-indentation' joins this line to the following line
+ instead. The value is `nil'.
- If one end of the region is in the middle of a word, the part of
- the word within the region is treated as an entire word.
+ If there is a fill prefix, and the second of the lines being joined
+ starts with the prefix, then `delete-indentation' deletes the fill
+ prefix before joining the lines. *Note Margins::.
- When `capitalize-region' is called interactively, START and END
- are point and the mark, with the smallest first.
+ In the example below, point is located on the line starting
+ `events', and it makes no difference if there are trailing spaces
+ in the preceding line.
---------- Buffer: foo ----------
- This is the contents of the 5th foo.
+ When in the course of human
+ -!- events, it becomes necessary
---------- Buffer: foo ----------
- (capitalize-region 1 44)
- => nil
+ (delete-indentation)
+ => nil
---------- Buffer: foo ----------
- This Is The Contents Of The 5th Foo.
+ When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
- - Command: downcase-region start end
- This function converts all of the letters in the region defined by
- START and END to lower case. The function returns `nil'.
+ After the lines are joined, the function `fixup-whitespace' is
+ responsible for deciding whether to leave a space at the junction.
- When `downcase-region' is called interactively, START and END are
- point and the mark, with the smallest first.
+ - Command: fixup-whitespace
+ This function replaces all the white space surrounding point with
+ either one space or no space, according to the context. It
+ returns `nil'.
- - Command: upcase-region start end
- This function converts all of the letters in the region defined by
- START and END to upper case. The function returns `nil'.
+ At the beginning or end of a line, the appropriate amount of space
+ is none. Before a character with close parenthesis syntax, or
+ after a character with open parenthesis or expression-prefix
+ syntax, no space is also appropriate. Otherwise, one space is
+ appropriate. *Note Syntax Class Table::.
- When `upcase-region' is called interactively, START and END are
- point and the mark, with the smallest first.
+ In the example below, `fixup-whitespace' is called the first time
+ with point before the word `spaces' in the first line. For the
+ second invocation, point is directly after the `('.
- - Command: capitalize-word count
- This function capitalizes COUNT words after point, moving point
- over as it does. To capitalize means to convert each word's first
- character to upper case and convert the rest of each word to lower
- case. If COUNT is negative, the function capitalizes the -COUNT
- previous words but does not move point. The value is `nil'.
-
- If point is in the middle of a word, the part of the word before
- point is ignored when moving forward. The rest is treated as an
- entire word.
-
- When `capitalize-word' is called interactively, COUNT is set to
- the numeric prefix argument.
+ ---------- Buffer: foo ----------
+ This has too many -!-spaces
+ This has too many spaces at the start of (-!- this list)
+ ---------- Buffer: foo ----------
+
+ (fixup-whitespace)
+ => nil
+ (fixup-whitespace)
+ => nil
+
+ ---------- Buffer: foo ----------
+ This has too many spaces
+ This has too many spaces at the start of (this list)
+ ---------- Buffer: foo ----------
- - Command: downcase-word count
- This function converts the COUNT words after point to all lower
- case, moving point over as it does. If COUNT is negative, it
- converts the -COUNT previous words but does not move point. The
- value is `nil'.
+ - Command: just-one-space
+ This command replaces any spaces and tabs around point with a
+ single space. It returns `nil'.
- When `downcase-word' is called interactively, COUNT is set to the
- numeric prefix argument.
+ - Command: delete-blank-lines
+ This function deletes blank lines surrounding point. If point is
+ on a blank line with one or more blank lines before or after it,
+ then all but one of them are deleted. If point is on an isolated
+ blank line, then it is deleted. If point is on a nonblank line,
+ the command deletes all blank lines following it.
- - Command: upcase-word count
- This function converts the COUNT words after point to all upper
- case, moving point over as it does. If COUNT is negative, it
- converts the -COUNT previous words but does not move point. The
- value is `nil'.
+ A blank line is defined as a line containing only tabs and spaces.
- When `upcase-word' is called interactively, COUNT is set to the
- numeric prefix argument.
+ `delete-blank-lines' returns `nil'.
\1f
-File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
+File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
+
+The Kill Ring
+=============
+
+ "Kill" functions delete text like the deletion functions, but save
+it so that the user can reinsert it by "yanking". Most of these
+functions have `kill-' in their name. By contrast, the functions whose
+names start with `delete-' normally do not save text for yanking
+(though they can still be undone); these are "deletion" functions.
+
+ Most of the kill commands are primarily for interactive use, and are
+not described here. What we do describe are the functions provided for
+use in writing such commands. You can use these functions to write
+commands for killing text. When you need to delete text for internal
+purposes within a Lisp function, you should normally use deletion
+functions, so as not to disturb the kill ring contents. *Note
+Deletion::.
+
+ Killed text is saved for later yanking in the "kill ring". This is
+a list that holds a number of recent kills, not just the last text
+kill. We call this a "ring" because yanking treats it as having
+elements in a cyclic order. The list is kept in the variable
+`kill-ring', and can be operated on with the usual functions for lists;
+there are also specialized functions, described in this section, that
+treat it as a ring.
+
+ Some people think this use of the word "kill" is unfortunate, since
+it refers to operations that specifically _do not_ destroy the entities
+"killed". This is in sharp contrast to ordinary life, in which death
+is permanent and "killed" entities do not come back to life.
+Therefore, other metaphors have been proposed. For example, the term
+"cut ring" makes sense to people who, in pre-computer days, used
+scissors and paste to cut up and rearrange manuscripts. However, it
+would be difficult to change the terminology now.
-Text Properties
-===============
+* Menu:
- Text properties are an alternative interface to extents (*note
-Extents::), and are built on top of them. They are useful when you
-want to view textual properties as being attached to the characters
-themselves rather than to intervals of characters. The text property
-interface is compatible with FSF Emacs.
+* Kill Ring Concepts:: What text looks like in the kill ring.
+* Kill Functions:: Functions that kill text.
+* Yank Commands:: Commands that access the kill ring.
+* Low-Level Kill Ring:: Functions and variables for kill ring access.
+* Internals of Kill Ring:: Variables that hold kill-ring data.
- Each character position in a buffer or a string can have a "text
-property list", much like the property list of a symbol (*note Property
-Lists::). The properties belong to a particular character at a
-particular place, such as, the letter `T' at the beginning of this
-sentence or the first `o' in `foo'--if the same character occurs in two
-different places, the two occurrences generally have different
-properties.
+\1f
+File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
- Each property has a name and a value. Both of these can be any Lisp
-object, but the name is normally a symbol. The usual way to access the
-property list is to specify a name and ask what value corresponds to it.
+Kill Ring Concepts
+------------------
- Note that FSF Emacs also looks at the `category' property to find
-defaults for text properties. We consider this too bogus to implement.
+ The kill ring records killed text as strings in a list, most recent
+first. A short kill ring, for example, might look like this:
- Copying text between strings and buffers preserves the properties
-along with the characters; this includes such diverse functions as
-`substring', `insert', and `buffer-substring'.
+ ("some text" "a different piece of text" "even older text")
-* Menu:
+When the list reaches `kill-ring-max' entries in length, adding a new
+entry automatically deletes the last entry.
-* Examining Properties:: Looking at the properties of one character.
-* Changing Properties:: Setting the properties of a range of text.
-* Property Search:: Searching for where a property changes value.
-* Special Properties:: Particular properties with special meanings.
-* Saving Properties:: Saving text properties in files, and reading
- them back.
+ When kill commands are interwoven with other commands, each kill
+command makes a new entry in the kill ring. Multiple kill commands in
+succession build up a single entry in the kill ring, which would be
+yanked as a unit; the second and subsequent consecutive kill commands
+add text to the entry made by the first one.
-\1f
-File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
+ For yanking, one entry in the kill ring is designated the "front" of
+the ring. Some yank commands "rotate" the ring by designating a
+different element as the "front." But this virtual rotation doesn't
+change the list itself--the most recent entry always comes first in the
+list.
-Examining Text Properties
--------------------------
-
- The simplest way to examine text properties is to ask for the value
-of a particular property of a particular character. For that, use
-`get-text-property'. Use `text-properties-at' to get the entire
-property list of a character. *Note Property Search::, for functions
-to examine the properties of a number of characters at once.
+\1f
+File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
+
+Functions for Killing
+---------------------
+
+ `kill-region' is the usual subroutine for killing text. Any command
+that calls this function is a "kill command" (and should probably have
+`kill' in its name). `kill-region' puts the newly killed text in a new
+element at the beginning of the kill ring or adds it to the most recent
+element. It uses the `last-command' variable to determine whether the
+previous command was a kill command, and if so appends the killed text
+to the most recent entry.
+
+ - Command: kill-region start end &optional verbose
+ This function kills the text in the region defined by START and
+ END. The text is deleted but saved in the kill ring, along with
+ its text properties. The value is always `nil'.
+
+ In an interactive call, START and END are point and the mark.
+
+ If the buffer is read-only, `kill-region' modifies the kill ring
+ just the same, then signals an error without modifying the buffer.
+ This is convenient because it lets the user use all the kill
+ commands to copy text into the kill ring from a read-only buffer.
+
+ - Command: copy-region-as-kill start end
+ This command saves the region defined by START and END on the kill
+ ring (including text properties), but does not delete the text
+ from the buffer. It returns `nil'. It also indicates the extent
+ of the text copied by moving the cursor momentarily, or by
+ displaying a message in the echo area.
+
+ The command does not set `this-command' to `kill-region', so a
+ subsequent kill command does not append to the same kill ring
+ entry.
+
+ Don't call `copy-region-as-kill' in Lisp programs unless you aim to
+ support Emacs 18. For Emacs 19, it is better to use `kill-new' or
+ `kill-append' instead. *Note Low-Level Kill Ring::.
- These functions handle both strings and buffers. (Keep in mind that
-positions in a string start from 0, whereas positions in a buffer start
-from 1.)
+\1f
+File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
- - Function: get-text-property pos prop &optional object
- This function returns the value of the PROP property of the
- character after position POS in OBJECT (a buffer or string). The
- argument OBJECT is optional and defaults to the current buffer.
+Functions for Yanking
+---------------------
- - Function: get-char-property pos prop &optional object
- This function is like `get-text-property', except that it checks
- all extents, not just text-property extents.
+ "Yanking" means reinserting an entry of previously killed text from
+the kill ring. The text properties are copied too.
+ - Command: yank &optional arg
+ This command inserts before point the text in the first entry in
+ the kill ring. It positions the mark at the beginning of that
+ text, and point at the end.
- - Function: text-properties-at position &optional object
- This function returns the entire property list of the character at
- POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
- defaults to the current buffer.
+ If ARG is a list (which occurs interactively when the user types
+ `C-u' with no digits), then `yank' inserts the text as described
+ above, but puts point before the yanked text and puts the mark
+ after it.
- - Variable: default-text-properties
- This variable holds a property list giving default values for text
- properties. Whenever a character does not specify a value for a
- property, the value stored in this list is used instead. Here is
- an example:
+ If ARG is a number, then `yank' inserts the ARGth most recently
+ killed text--the ARGth element of the kill ring list.
- (setq default-text-properties '(foo 69))
- ;; Make sure character 1 has no properties of its own.
- (set-text-properties 1 2 nil)
- ;; What we get, when we ask, is the default value.
- (get-text-property 1 'foo)
- => 69
+ `yank' does not alter the contents of the kill ring or rotate it.
+ It returns `nil'.
-\1f
-File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
+ - Command: yank-pop arg
+ This command replaces the just-yanked entry from the kill ring
+ with a different entry from the kill ring.
-Changing Text Properties
-------------------------
+ This is allowed only immediately after a `yank' or another
+ `yank-pop'. At such a time, the region contains text that was just
+ inserted by yanking. `yank-pop' deletes that text and inserts in
+ its place a different piece of killed text. It does not add the
+ deleted text to the kill ring, since it is already in the kill
+ ring somewhere.
- The primitives for changing properties apply to a specified range of
-text. The function `set-text-properties' (see end of section) sets the
-entire property list of the text in that range; more often, it is
-useful to add, change, or delete just certain properties specified by
-name.
+ If ARG is `nil', then the replacement text is the previous element
+ of the kill ring. If ARG is numeric, the replacement is the ARGth
+ previous kill. If ARG is negative, a more recent kill is the
+ replacement.
- Since text properties are considered part of the buffer's contents,
-and can affect how the buffer looks on the screen, any change in the
-text properties is considered a buffer modification. Buffer text
-property changes are undoable (*note Undo::).
+ The sequence of kills in the kill ring wraps around, so that after
+ the oldest one comes the newest one, and before the newest one
+ goes the oldest.
- - Function: put-text-property start end prop value &optional object
- This function sets the PROP property to VALUE for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
+ The value is always `nil'.
- - Function: add-text-properties start end props &optional object
- This function modifies the text properties for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
+\1f
+File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
- The argument PROPS specifies which properties to change. It
- should have the form of a property list (*note Property Lists::):
- a list whose elements include the property names followed
- alternately by the corresponding values.
+Low-Level Kill Ring
+-------------------
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or its values
- agree with those in the text).
+ These functions and variables provide access to the kill ring at a
+lower level, but still convenient for use in Lisp programs. They take
+care of interaction with X Window selections. They do not exist in
+Emacs version 18.
- For example, here is how to set the `comment' and `face'
- properties of a range of text:
+ - Function: current-kill count &optional do-not-move
+ The function `current-kill' rotates the yanking pointer which
+ designates the "front" of the kill ring by COUNT places (from newer
+ kills to older ones), and returns the text at that place in the
+ ring.
- (add-text-properties START END
- '(comment t face highlight))
+ If the optional second argument DO-NOT-MOVE is non-`nil', then
+ `current-kill' doesn't alter the yanking pointer; it just returns
+ the COUNTth kill, counting from the current yanking pointer.
- - Function: remove-text-properties start end props &optional object
- This function deletes specified text properties from the text
- between START and END in the string or buffer OBJECT. If OBJECT
- is `nil', it defaults to the current buffer.
+ If COUNT is zero, indicating a request for the latest kill,
+ `current-kill' calls the value of `interprogram-paste-function'
+ (documented below) before consulting the kill ring.
- The argument PROPS specifies which properties to delete. It
- should have the form of a property list (*note Property Lists::):
- a list whose elements are property names alternating with
- corresponding values. But only the names matter--the values that
- accompany them are ignored. For example, here's how to remove the
- `face' property.
+ - Function: kill-new string &optional replace
+ This function makes the text STRING the latest entry in the kill
+ ring, and sets `kill-ring-yank-pointer' to point to it.
- (remove-text-properties START END '(face nil))
+ Normally, STRING is added to the front of the kill ring as a new
+ entry. However, if optional argument REPLACE is non-`nil', the
+ entry previously at the front of the kill ring is discarded, and
+ STRING replaces it.
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or if no
- character in the specified text had any of those properties).
+ This function runs the functions on `kill-hooks', and also invokes
+ the value of `interprogram-cut-function' (see below).
- - Function: set-text-properties start end props &optional object
- This function completely replaces the text property list for the
- text between START and END in the string or buffer OBJECT. If
- OBJECT is `nil', it defaults to the current buffer.
+ - Function: kill-append string before-p
+ This function appends the text STRING to the first entry in the
+ kill ring. Normally STRING goes at the end of the entry, but if
+ BEFORE-P is non-`nil', it goes at the beginning. This function
+ also invokes the value of `interprogram-cut-function' (see below).
- The argument PROPS is the new property list. It should be a list
- whose elements are property names alternating with corresponding
- values.
+ - Variable: interprogram-paste-function
+ This variable provides a way of transferring killed text from other
+ programs, when you are using a window system. Its value should be
+ `nil' or a function of no arguments.
- After `set-text-properties' returns, all the characters in the
- specified range have identical properties.
+ If the value is a function, `current-kill' calls it to get the
+ "most recent kill". If the function returns a non-`nil' value,
+ then that value is used as the "most recent kill". If it returns
+ `nil', then the first element of `kill-ring' is used.
- If PROPS is `nil', the effect is to get rid of all properties from
- the specified range of text. Here's an example:
+ The normal use of this hook is to get the X server's primary
+ selection as the most recent kill, even if the selection belongs
+ to another X client. *Note X Selections::.
- (set-text-properties START END nil)
+ - Variable: interprogram-cut-function
+ This variable provides a way of communicating killed text to other
+ programs, when you are using a window system. Its value should be
+ `nil' or a function of one argument.
- See also the function `buffer-substring-without-properties' (*note
-Buffer Contents::) which copies text from the buffer but does not copy
-its properties.
+ If the value is a function, `kill-new' and `kill-append' call it
+ with the new first element of the kill ring as an argument.
-\1f
-File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
-
-Property Search Functions
--------------------------
-
- In typical use of text properties, most of the time several or many
-consecutive characters have the same value for a property. Rather than
-writing your programs to examine characters one by one, it is much
-faster to process chunks of text that have the same property value.
-
- Here are functions you can use to do this. They use `eq' for
-comparing property values. In all cases, OBJECT defaults to the
-current buffer.
-
- For high performance, it's very important to use the LIMIT argument
-to these functions, especially the ones that search for a single
-property--otherwise, they may spend a long time scanning to the end of
-the buffer, if the property you are interested in does not change.
-
- Remember that a position is always between two characters; the
-position returned by these functions is between two characters with
-different properties.
-
- - Function: next-property-change pos &optional object limit
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in some text
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose properties are not identical to those of the character just
- after POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-property-change' returns LIMIT.
-
- The value is `nil' if the properties remain unchanged all the way
- to the end of OBJECT and LIMIT is `nil'. If the value is
- non-`nil', it is a position greater than or equal to POS. The
- value equals POS only when LIMIT equals POS.
-
- Here is an example of how to scan the buffer by chunks of text
- within which all properties are constant:
-
- (while (not (eobp))
- (let ((plist (text-properties-at (point)))
- (next-change
- (or (next-property-change (point) (current-buffer))
- (point-max))))
- Process text from point to NEXT-CHANGE...
- (goto-char next-change)))
-
- - Function: next-single-property-change pos prop &optional object limit
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in the PROP
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose PROP property differs from that of the character just after
- POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-single-property-change' returns LIMIT.
-
- The value is `nil' if the property remains unchanged all the way to
- the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
- it is a position greater than or equal to POS; it equals POS only
- if LIMIT equals POS.
-
- - Function: previous-property-change pos &optional object limit
- This is like `next-property-change', but scans back from POS
- instead of forward. If the value is non-`nil', it is a position
- less than or equal to POS; it equals POS only if LIMIT equals POS.
-
- - Function: previous-single-property-change pos prop &optional object
- limit
- This is like `next-single-property-change', but scans back from
- POS instead of forward. If the value is non-`nil', it is a
- position less than or equal to POS; it equals POS only if LIMIT
- equals POS.
-
- - Function: text-property-any start end prop value &optional object
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value is VALUE. More
- precisely, it returns the position of the first such character.
- Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
-
- - Function: text-property-not-all start end prop value &optional object
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value differs from VALUE.
- More precisely, it returns the position of the first such
- character. Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
+ The normal use of this hook is to set the X server's primary
+ selection to the newly killed text.
\1f
-File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
+File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
-Properties with Special Meanings
---------------------------------
+Internals of the Kill Ring
+--------------------------
- The predefined properties are the same as those for extents. *Note
-Extent Properties::.
+ 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: Saving Properties, Prev: Special Properties, Up: Text Properties
-
-Saving Text Properties in Files
--------------------------------
-
- You can save text properties in files, and restore text properties
-when inserting the files, using these two hooks:
-
- - Variable: write-region-annotate-functions
- This variable's value is a list of functions for `write-region' to
- run to encode text properties in some fashion as annotations to
- the text being written in the file. *Note Writing to Files::.
-
- Each function in the list is called with two arguments: the start
- and end of the region to be written. These functions should not
- alter the contents of the buffer. Instead, they should return
- lists indicating annotations to write in the file in addition to
- the text in the buffer.
-
- Each function should return a list of elements of the form
- `(POSITION . STRING)', where POSITION is an integer specifying the
- relative position in the text to be written, and STRING is the
- annotation to add there.
-
- Each list returned by one of these functions must be already
- sorted in increasing order by POSITION. If there is more than one
- function, `write-region' merges the lists destructively into one
- sorted list.
-
- When `write-region' actually writes the text from the buffer to the
- file, it intermixes the specified annotations at the corresponding
- positions. All this takes place without modifying the buffer.
-
- - Variable: after-insert-file-functions
- This variable holds a list of functions for `insert-file-contents'
- to call after inserting a file's contents. These functions should
- scan the inserted text for annotations, and convert them to the
- text properties they stand for.
-
- Each function receives one argument, the length of the inserted
- text; point indicates the start of that text. The function should
- scan that text for annotations, delete them, and create the text
- properties that the annotations specify. The function should
- return the updated length of the inserted text, as it stands after
- those changes. The value returned by one function becomes the
- argument to the next function.
-
- These functions should always return with point at the beginning of
- the inserted text.
-
- The intended use of `after-insert-file-functions' is for converting
- some sort of textual annotations into actual text properties. But
- other uses may be possible.
-
- We invite users to write Lisp programs to store and retrieve text
-properties in files, using these hooks, and thus to experiment with
-various data formats and find good ones. Eventually we hope users will
-produce good, general extensions we can install in Emacs.
-
- We suggest not trying to handle arbitrary Lisp objects as property
-names or property values--because a program that general is probably
-difficult to write, and slow. Instead, choose a set of possible data
-types that are reasonably flexible, and not too hard to encode.
-
- *Note Format Conversion::, for a related feature.
+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.
+
+`(START . END)'
+ This kind of element indicates how to delete text that was
+ inserted. Upon insertion, the text occupied the range START-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 START . END)'
+ This kind of element records a change in a text property. Here's
+ how you might undo the change:
+
+ (put-text-property START 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: Substitution, Next: Registers, Prev: Text Properties, Up: Text
+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.
+
+ - Command: buffer-disable-undo &optional buffer
+ - Command: 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.
-Substituting for a Character Code
-=================================
+\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.
- The following functions replace characters within a specified region
-based on their character codes.
+ - 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: subst-char-in-region start end old-char new-char &optional
- noundo
- This function replaces all occurrences of the character OLD-CHAR
- with the character NEW-CHAR in the region of the current buffer
- defined by START and END.
+ - Function: current-justification
+ This function returns the proper justification style to use for
+ filling the text around point.
- If NOUNDO is non-`nil', then `subst-char-in-region' does not
- record the change for undo and does not mark the buffer as
- modified. This feature is used for controlling selective display
- (*note Selective Display::).
+ - 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.
- `subst-char-in-region' does not move point and returns `nil'.
+ 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:
- ---------- Buffer: foo ----------
- This is the contents of the buffer before.
- ---------- Buffer: foo ----------
-
- (subst-char-in-region 1 20 ?i ?X)
- => nil
-
- ---------- Buffer: foo ----------
- ThXs Xs the contents of the buffer before.
- ---------- Buffer: foo ----------
+ (let ((fill-paragraph-function nil))
+ (fill-paragraph arg))
- - Function: translate-region start end table
- This function applies a translation table to the characters in the
- buffer between positions START and END. The translation table
- TABLE can be either a string, a vector, or a char-table.
+ - 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.
- If TABLE is a string, its Nth element is the mapping for the
- character with code N.
+\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'.
- If TABLE is a vector, its Nth element is the mapping for character
- with code N. Legal mappings are characters, strings, or `nil'
- (meaning don't replace.)
+ - 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.
- If TABLE is a char-table, its elements describe the mapping
- between characters and their replacements. The char-table should
- be of type `char' or `generic'.
+ - 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.
- When the TABLE is a string or vector and its length is less than
- the total number of characters (256 without Mule), any characters
- with codes larger than the length of TABLE are not altered by the
- translation.
+ If FORCE is non-`nil', that says to fix the line's indentation if
+ that doesn't match the left margin value.
- The return value of `translate-region' is the number of characters
- that were actually changed by the translation. This does not
- count characters that were mapped into themselves in the
- translation table.
+ - Function: delete-to-left-margin &optional 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.
- *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
- to be a string. This is still the case in FSF Emacs.
+ The arguments FROM and TO are optional; the default is the whole
+ buffer.
- The following example creates a char-table that is passed to
- `translate-region', which translates character `a' to `the letter
- a', removes character `b', and translates character `c' to newline.
+ - 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.
- ---------- Buffer: foo ----------
- Here is a sentence in the buffer.
- ---------- Buffer: foo ----------
-
- (let ((table (make-char-table 'generic)))
- (put-char-table ?a "the letter a" table)
- (put-char-table ?b "" table)
- (put-char-table ?c ?\n table)
- (translate-region (point-min) (point-max) table))
- => 3
-
- ---------- Buffer: foo ----------
- Here is the letter a senten
- e in the uffer.
- ---------- Buffer: foo ----------
+ - 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: Registers, Next: Transposition, Prev: Substitution, Up: Text
-
-Registers
-=========
-
- A register is a sort of variable used in XEmacs editing that can
-hold a marker, a string, a rectangle, a window configuration (of one
-frame), or a frame configuration (of all frames). Each register is
-named by a single character. All characters, including control and
-meta characters (but with the exception of `C-g'), can be used to name
-registers. Thus, there are 255 possible registers. A register is
-designated in Emacs Lisp by a character that is its name.
-
- The functions in this section return unpredictable values unless
-otherwise stated.
-
- - Variable: register-alist
- This variable is an alist of elements of the form `(NAME .
- CONTENTS)'. Normally, there is one element for each XEmacs
- register that has been used.
-
- The object NAME is a character (an integer) identifying the
- register. The object CONTENTS is a string, marker, or list
- representing the register contents. A string represents text
- stored in the register. A marker represents a position. A list
- represents a rectangle; its elements are strings, one per line of
- the rectangle.
-
- - Function: get-register reg
- This function returns the contents of the register REG, or `nil'
- if it has no contents.
-
- - Function: set-register reg value
- This function sets the contents of register REG to VALUE. A
- register can be set to any value, but the other register functions
- expect only certain data types. The return value is VALUE.
-
- - Command: view-register reg
- This command displays what is contained in register REG.
-
- - Command: insert-register reg &optional beforep
- This command inserts contents of register REG into the current
- buffer.
-
- Normally, this command puts point before the inserted text, and the
- mark after it. However, if the optional second argument BEFOREP
- is non-`nil', it puts the mark before and point after. You can
- pass a non-`nil' second argument BEFOREP to this function
- interactively by supplying any prefix argument.
+File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
- If the register contains a rectangle, then the rectangle is
- inserted with its upper left corner at point. This means that
- text is inserted in the current line and underneath it on
- successive lines.
-
- If the register contains something other than saved text (a
- string) or a rectangle (a list), currently useless things happen.
- This may be changed in the future.
+Auto Filling
+============
-\1f
-File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
+ 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::.
-Transposition of Text
-=====================
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. *Note Margins::.
- This subroutine is used by the transposition commands.
+ - 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.
- - Function: transpose-regions start1 end1 start2 end2 &optional
- leave-markers
- This function exchanges two nonoverlapping portions of the buffer.
- Arguments START1 and END1 specify the bounds of one portion and
- arguments START2 and END2 specify the bounds of the other portion.
+ 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.
- Normally, `transpose-regions' relocates markers with the transposed
- text; a marker previously positioned within one of the two
- transposed portions moves along with that portion, thus remaining
- between the same two characters in their new position. However,
- if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
- this--it leaves all markers unrelocated.
+ In older Emacs versions, this variable was named
+ `auto-fill-hook', but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `auto-fill-function' in version 19.
projects / chise / xemacs-chise.git / blobdiff