Mercurial > emacs
comparison lispref/text.texi @ 72381:4300054c252b
* text.texi (Near Point): Say "cursor" not "terminal cursor".
(Commands for Insertion): Removed split-line since it's not
relevant for Lisp programming.
(Yank Commands): Rewrite introduction.
(Undo): Clarify.
(Maintaining Undo): Clarify. Document undo-ask-before-discard.
(Filling): Remove redundant comment. Clarify return value of
current-justification.
(Margins): Minor clarifications.
(Adaptive Fill): Update default value of adaptive-fill-regexp.
(Sorting): Update definition of sort-lines.
(Columns): Clarify behavior of sort-columns.
(Indent Tabs): Link to Tab Stops in Emacs manual.
(Special Properties): Clarify.
(Clickable Text): Mention Buttons package.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Sun, 13 Aug 2006 03:12:43 +0000 |
parents | 6b63f7efd5b6 |
children | 77837c7f1fa0 7f3f771c85fa |
comparison
equal
deleted
inserted
replaced
72380:37cc9e9df5a4 | 72381:4300054c252b |
---|---|
101 @defun following-char | 101 @defun following-char |
102 This function returns the character following point in the current | 102 This function returns the character following point in the current |
103 buffer. This is similar to @code{(char-after (point))}. However, if | 103 buffer. This is similar to @code{(char-after (point))}. However, if |
104 point is at the end of the buffer, then @code{following-char} returns 0. | 104 point is at the end of the buffer, then @code{following-char} returns 0. |
105 | 105 |
106 Remember that point is always between characters, and the terminal | 106 Remember that point is always between characters, and the cursor |
107 cursor normally appears over the character following point. Therefore, | 107 normally appears over the character following point. Therefore, the |
108 the character returned by @code{following-char} is the character the | 108 character returned by @code{following-char} is the character the |
109 cursor is over. | 109 cursor is over. |
110 | 110 |
111 In this example, point is between the @samp{a} and the @samp{c}. | 111 In this example, point is between the @samp{a} and the @samp{c}. |
112 | 112 |
113 @example | 113 @example |
524 | 524 |
525 The value returned is @code{nil}. In an interactive call, @var{count} | 525 The value returned is @code{nil}. In an interactive call, @var{count} |
526 is the numeric prefix argument. | 526 is the numeric prefix argument. |
527 @end deffn | 527 @end deffn |
528 | 528 |
529 @deffn Command split-line | |
530 This command splits the current line, moving the portion of the line | |
531 after point down vertically so that it is on the next line directly | |
532 below where it was before. Whitespace is inserted as needed at the | |
533 beginning of the lower line, using the @code{indent-to} function. | |
534 @code{split-line} returns the position of point. | |
535 | |
536 Programs hardly ever use this function. | |
537 @end deffn | |
538 | |
539 @defvar overwrite-mode | 529 @defvar overwrite-mode |
540 This variable controls whether overwrite mode is in effect. The value | 530 This variable controls whether overwrite mode is in effect. The value |
541 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, | 531 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, |
542 or @code{nil}. @code{overwrite-mode-textual} specifies textual | 532 or @code{nil}. @code{overwrite-mode-textual} specifies textual |
543 overwrite mode (treats newlines and tabs specially), and | 533 overwrite mode (treats newlines and tabs specially), and |
976 | 966 |
977 @node Yank Commands | 967 @node Yank Commands |
978 @comment node-name, next, previous, up | 968 @comment node-name, next, previous, up |
979 @subsection Functions for Yanking | 969 @subsection Functions for Yanking |
980 | 970 |
981 @dfn{Yanking} means reinserting an entry of previously killed text | 971 This section describes higher-level commands for yanking, which are |
982 from the kill ring. The text properties are copied too. | 972 intended primarily for the user but useful also in Lisp programs. |
973 Both @code{yank} and @code{yank-pop} honor the | |
974 @code{yank-excluded-properties} variable and @code{yank-handler} text | |
975 property (@pxref{Yanking}). | |
983 | 976 |
984 @deffn Command yank &optional arg | 977 @deffn Command yank &optional arg |
985 @cindex inserting killed text | 978 @cindex inserting killed text |
986 This command inserts before point the text at the front of the | 979 This command inserts before point the text at the front of the |
987 kill ring. It positions the mark at the beginning of that text, and | 980 kill ring. It positions the mark at the beginning of that text, and |
1211 | 1204 |
1212 Most buffers have an @dfn{undo list}, which records all changes made | 1205 Most buffers have an @dfn{undo list}, which records all changes made |
1213 to the buffer's text so that they can be undone. (The buffers that | 1206 to the buffer's text so that they can be undone. (The buffers that |
1214 don't have one are usually special-purpose buffers for which Emacs | 1207 don't have one are usually special-purpose buffers for which Emacs |
1215 assumes that undoing is not useful. In particular, any buffer whose | 1208 assumes that undoing is not useful. In particular, any buffer whose |
1216 name begins with a space has its undo recording off by default, | 1209 name begins with a space has its undo recording off by default; |
1217 see @ref{Buffer Names}.) All the primitives that modify the | 1210 see @ref{Buffer Names}.) All the primitives that modify the |
1218 text in the buffer automatically add elements to the front of the undo | 1211 text in the buffer automatically add elements to the front of the undo |
1219 list, which is in the variable @code{buffer-undo-list}. | 1212 list, which is in the variable @code{buffer-undo-list}. |
1220 | 1213 |
1221 @defvar buffer-undo-list | 1214 @defvar buffer-undo-list |
1316 @end defvar | 1309 @end defvar |
1317 | 1310 |
1318 @defun primitive-undo count list | 1311 @defun primitive-undo count list |
1319 This is the basic function for undoing elements of an undo list. | 1312 This is the basic function for undoing elements of an undo list. |
1320 It undoes the first @var{count} elements of @var{list}, returning | 1313 It undoes the first @var{count} elements of @var{list}, returning |
1321 the rest of @var{list}. You could write this function in Lisp, | 1314 the rest of @var{list}. |
1322 but it is convenient to have it in C. | |
1323 | 1315 |
1324 @code{primitive-undo} adds elements to the buffer's undo list when it | 1316 @code{primitive-undo} adds elements to the buffer's undo list when it |
1325 changes the buffer. Undo commands avoid confusion by saving the undo | 1317 changes the buffer. Undo commands avoid confusion by saving the undo |
1326 list value at the beginning of a sequence of undo operations. Then the | 1318 list value at the beginning of a sequence of undo operations. Then the |
1327 undo operations use and update the saved value. The new elements added | 1319 undo operations use and update the saved value. The new elements added |
1370 them from using up all available memory space, garbage collection trims | 1362 them from using up all available memory space, garbage collection trims |
1371 them back to size limits you can set. (For this purpose, the ``size'' | 1363 them back to size limits you can set. (For this purpose, the ``size'' |
1372 of an undo list measures the cons cells that make up the list, plus the | 1364 of an undo list measures the cons cells that make up the list, plus the |
1373 strings of deleted text.) Three variables control the range of acceptable | 1365 strings of deleted text.) Three variables control the range of acceptable |
1374 sizes: @code{undo-limit}, @code{undo-strong-limit} and | 1366 sizes: @code{undo-limit}, @code{undo-strong-limit} and |
1375 @code{undo-outer-limit}. | 1367 @code{undo-outer-limit}. In these variables, size is counted as the |
1368 number of bytes occupied, which includes both saved text and other | |
1369 data. | |
1376 | 1370 |
1377 @defopt undo-limit | 1371 @defopt undo-limit |
1378 This is the soft limit for the acceptable size of an undo list. The | 1372 This is the soft limit for the acceptable size of an undo list. The |
1379 change group at which this size is exceeded is the last one kept. | 1373 change group at which this size is exceeded is the last one kept. |
1380 @end defopt | 1374 @end defopt |
1388 | 1382 |
1389 @defopt undo-outer-limit | 1383 @defopt undo-outer-limit |
1390 If at garbage collection time the undo info for the current command | 1384 If at garbage collection time the undo info for the current command |
1391 exceeds this limit, Emacs discards the info and displays a warning. | 1385 exceeds this limit, Emacs discards the info and displays a warning. |
1392 This is a last ditch limit to prevent memory overflow. | 1386 This is a last ditch limit to prevent memory overflow. |
1387 @end defopt | |
1388 | |
1389 @defopt undo-ask-before-discard | |
1390 If this variable is non-@code{nil}, when the undo info exceeds | |
1391 @code{undo-outer-limit}, Emacs asks in the echo area whether to | |
1392 discard the info. The default value is @code{nil}, which means to | |
1393 discard it automatically. | |
1394 | |
1395 This option is mainly intended for debugging. Garbage collection is | |
1396 inhibited while the question is asked, which means that Emacs might | |
1397 leak memory if the user waits too long before answering the question. | |
1393 @end defopt | 1398 @end defopt |
1394 | 1399 |
1395 @node Filling | 1400 @node Filling |
1396 @comment node-name, next, previous, up | 1401 @comment node-name, next, previous, up |
1397 @section Filling | 1402 @section Filling |
1479 This command considers a region of text as a single paragraph and fills | 1484 This command considers a region of text as a single paragraph and fills |
1480 it. If the region was made up of many paragraphs, the blank lines | 1485 it. If the region was made up of many paragraphs, the blank lines |
1481 between paragraphs are removed. This function justifies as well as | 1486 between paragraphs are removed. This function justifies as well as |
1482 filling when @var{justify} is non-@code{nil}. | 1487 filling when @var{justify} is non-@code{nil}. |
1483 | 1488 |
1484 In an interactive call, any prefix argument requests justification. | |
1485 | |
1486 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace | 1489 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace |
1487 other than line breaks untouched. If @var{squeeze-after} is | 1490 other than line breaks untouched. If @var{squeeze-after} is |
1488 non-@code{nil}, it specifies a position in the region, and means don't | 1491 non-@code{nil}, it specifies a position in the region, and means don't |
1489 canonicalize spaces before that position. | 1492 canonicalize spaces before that position. |
1490 | 1493 |
1520 @end defopt | 1523 @end defopt |
1521 | 1524 |
1522 @defun current-justification | 1525 @defun current-justification |
1523 This function returns the proper justification style to use for filling | 1526 This function returns the proper justification style to use for filling |
1524 the text around point. | 1527 the text around point. |
1528 | |
1529 This returns the value of the @code{justification} text property at | |
1530 point, or the variable @var{default-justification} if there is no such | |
1531 text property. However, it returns @code{nil} rather than @code{none} | |
1532 to mean ``don't justify''. | |
1525 @end defun | 1533 @end defun |
1526 | 1534 |
1527 @defopt sentence-end-double-space | 1535 @defopt sentence-end-double-space |
1528 @anchor{Definition of sentence-end-double-space} | 1536 @anchor{Definition of sentence-end-double-space} |
1529 If this variable is non-@code{nil}, a period followed by just one space | 1537 If this variable is non-@code{nil}, a period followed by just one space |
1567 | 1575 |
1568 @node Margins | 1576 @node Margins |
1569 @section Margins for Filling | 1577 @section Margins for Filling |
1570 | 1578 |
1571 @defopt fill-prefix | 1579 @defopt fill-prefix |
1572 This buffer-local variable specifies a string of text that appears at | 1580 This buffer-local variable, if non-@code{nil}, specifies a string of |
1573 the beginning | 1581 text that appears at the beginning of normal text lines and should be |
1574 of normal text lines and should be disregarded when filling them. Any | 1582 disregarded when filling them. Any line that fails to start with the |
1575 line that fails to start with the fill prefix is considered the start of | 1583 fill prefix is considered the start of a paragraph; so is any line |
1576 a paragraph; so is any line that starts with the fill prefix followed by | 1584 that starts with the fill prefix followed by additional whitespace. |
1577 additional whitespace. Lines that start with the fill prefix but no | 1585 Lines that start with the fill prefix but no additional whitespace are |
1578 additional whitespace are ordinary text lines that can be filled | 1586 ordinary text lines that can be filled together. The resulting filled |
1579 together. The resulting filled lines also start with the fill prefix. | 1587 lines also start with the fill prefix. |
1580 | 1588 |
1581 The fill prefix follows the left margin whitespace, if any. | 1589 The fill prefix follows the left margin whitespace, if any. |
1582 @end defopt | 1590 @end defopt |
1583 | 1591 |
1584 @defopt fill-column | 1592 @defopt fill-column |
1659 becomes buffer-local when set in any fashion. | 1667 becomes buffer-local when set in any fashion. |
1660 @end defvar | 1668 @end defvar |
1661 | 1669 |
1662 @defvar fill-nobreak-predicate | 1670 @defvar fill-nobreak-predicate |
1663 This variable gives major modes a way to specify not to break a line | 1671 This variable gives major modes a way to specify not to break a line |
1664 at certain places. Its value should be a list of functions, but a | 1672 at certain places. Its value should be a list of functions. Whenever |
1665 single function is also supported for compatibility. Whenever filling | 1673 filling considers breaking the line at a certain place in the buffer, |
1666 considers breaking the line at a certain place in the buffer, it calls | 1674 it calls each of these functions with no arguments and with point |
1667 each of these functions with no arguments and with point located at | 1675 located at that place. If any of the functions returns |
1668 that place. If any of the functions returns non-@code{nil}, then the | 1676 non-@code{nil}, then the line won't be broken there. |
1669 line won't be broken there. | |
1670 @end defvar | 1677 @end defvar |
1671 | 1678 |
1672 @node Adaptive Fill | 1679 @node Adaptive Fill |
1673 @section Adaptive Fill Mode | 1680 @section Adaptive Fill Mode |
1674 @cindex Adaptive Fill mode | 1681 @cindex Adaptive Fill mode |
1731 @defopt adaptive-fill-regexp | 1738 @defopt adaptive-fill-regexp |
1732 Adaptive Fill mode matches this regular expression against the text | 1739 Adaptive Fill mode matches this regular expression against the text |
1733 starting after the left margin whitespace (if any) on a line; the | 1740 starting after the left margin whitespace (if any) on a line; the |
1734 characters it matches are that line's candidate for the fill prefix. | 1741 characters it matches are that line's candidate for the fill prefix. |
1735 | 1742 |
1736 @w{@code{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the | 1743 @w{@code{"[ \t]*\\([-!|#%;>*·•‣⁃◦]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the |
1737 default value. This matches a number enclosed in parentheses or | 1744 default value. This matches a number enclosed in parentheses or |
1738 followed by a period, or certain punctuation characters, or any | 1745 followed by a period, or certain punctuation characters, or any |
1739 sequence of these intermingled with whitespace. In particular, it | 1746 sequence of these intermingled with whitespace. In particular, it |
1740 matches a sequence of whitespace, possibly empty. | 1747 matches a sequence of whitespace, possibly empty. |
1741 @end defopt | 1748 @end defopt |
1896 (interactive "P\nr") | 1903 (interactive "P\nr") |
1897 (save-excursion | 1904 (save-excursion |
1898 (save-restriction | 1905 (save-restriction |
1899 (narrow-to-region beg end) | 1906 (narrow-to-region beg end) |
1900 (goto-char (point-min)) | 1907 (goto-char (point-min)) |
1901 (sort-subr reverse 'forward-line 'end-of-line)))) | 1908 (let ((inhibit-field-text-motion t)) |
1909 (sort-subr reverse 'forward-line 'end-of-line))))) | |
1902 @end group | 1910 @end group |
1903 @end example | 1911 @end example |
1904 | 1912 |
1905 Here @code{forward-line} moves point to the start of the next record, | 1913 Here @code{forward-line} moves point to the start of the next record, |
1906 and @code{end-of-line} moves point to the end of record. We do not pass | 1914 and @code{end-of-line} moves point to the end of record. We do not pass |
2052 | 2060 |
2053 One unusual thing about this command is that the entire line | 2061 One unusual thing about this command is that the entire line |
2054 containing position @var{beg}, and the entire line containing position | 2062 containing position @var{beg}, and the entire line containing position |
2055 @var{end}, are included in the region sorted. | 2063 @var{end}, are included in the region sorted. |
2056 | 2064 |
2057 Note that @code{sort-columns} uses the @code{sort} utility program, | 2065 Note that @code{sort-columns} rejects text that contains tabs, because |
2058 and so cannot work properly on text containing tab characters. Use | 2066 tabs could be split across the specified columns. Use @kbd{M-x |
2059 @kbd{M-x untabify} to convert tabs to spaces before sorting. | 2067 untabify} to convert tabs to spaces before sorting. |
2068 | |
2069 When possible, this command actually works by calling the @code{sort} | |
2070 utility program. | |
2060 @end deffn | 2071 @end deffn |
2061 | 2072 |
2062 @node Columns | 2073 @node Columns |
2063 @comment node-name, next, previous, up | 2074 @comment node-name, next, previous, up |
2064 @section Counting Columns | 2075 @section Counting Columns |
2389 typewriter. The feature works by inserting an appropriate number of | 2400 typewriter. The feature works by inserting an appropriate number of |
2390 spaces and tab characters to reach the next tab stop column; it does not | 2401 spaces and tab characters to reach the next tab stop column; it does not |
2391 affect the display of tab characters in the buffer (@pxref{Usual | 2402 affect the display of tab characters in the buffer (@pxref{Usual |
2392 Display}). Note that the @key{TAB} character as input uses this tab | 2403 Display}). Note that the @key{TAB} character as input uses this tab |
2393 stop feature only in a few major modes, such as Text mode. | 2404 stop feature only in a few major modes, such as Text mode. |
2405 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}. | |
2394 | 2406 |
2395 @deffn Command tab-to-tab-stop | 2407 @deffn Command tab-to-tab-stop |
2396 This command inserts spaces or tabs before point, up to the next tab | 2408 This command inserts spaces or tabs before point, up to the next tab |
2397 stop column defined by @code{tab-stop-list}. It searches the list for | 2409 stop column defined by @code{tab-stop-list}. It searches the list for |
2398 an element greater than the current column number, and uses that element | 2410 an element greater than the current column number, and uses that element |
3077 | 3089 |
3078 @item keymap | 3090 @item keymap |
3079 @cindex keymap of character | 3091 @cindex keymap of character |
3080 @kindex keymap @r{(text property)} | 3092 @kindex keymap @r{(text property)} |
3081 The @code{keymap} property specifies an additional keymap for | 3093 The @code{keymap} property specifies an additional keymap for |
3082 commands. The property's value for the character before point applies | 3094 commands. When this keymap applies, it is used for key lookup before |
3083 if it is non-@code{nil} and rear-sticky, and the property's value for | 3095 the minor mode keymaps and before the buffer's local map. |
3084 the character after point applies if it is non-@code{nil} and | 3096 @xref{Active Keymaps}. If the property value is a symbol, the |
3097 symbol's function definition is used as the keymap. | |
3098 | |
3099 The property's value for the character before point applies if it is | |
3100 non-@code{nil} and rear-sticky, and the property's value for the | |
3101 character after point applies if it is non-@code{nil} and | |
3085 front-sticky. (For mouse clicks, the position of the click is used | 3102 front-sticky. (For mouse clicks, the position of the click is used |
3086 instead of the position of point.) If the property value is a symbol, | 3103 instead of the position of point.) |
3087 the symbol's function definition is used as the keymap. | |
3088 | |
3089 When this keymap applies, it is used for key lookup before the minor | |
3090 mode keymaps and before the buffer's local map. @xref{Active | |
3091 Keymaps}. | |
3092 | 3104 |
3093 @item local-map | 3105 @item local-map |
3094 @kindex local-map @r{(text property)} | 3106 @kindex local-map @r{(text property)} |
3095 This property works like @code{keymap} except that it specifies a | 3107 This property works like @code{keymap} except that it specifies a |
3096 keymap to use @emph{instead of} the buffer's local map. For most | 3108 keymap to use @emph{instead of} the buffer's local map. For most |
3097 purposes (perhaps all purposes), the @code{keymap} is superior. | 3109 purposes (perhaps all purposes), it is better to use the @code{keymap} |
3110 property. | |
3098 | 3111 |
3099 @item syntax-table | 3112 @item syntax-table |
3100 The @code{syntax-table} property overrides what the syntax table says | 3113 The @code{syntax-table} property overrides what the syntax table says |
3101 about this particular character. @xref{Syntax Properties}. | 3114 about this particular character. @xref{Syntax Properties}. |
3102 | 3115 |
3477 | 3490 |
3478 @node Clickable Text | 3491 @node Clickable Text |
3479 @subsection Defining Clickable Text | 3492 @subsection Defining Clickable Text |
3480 @cindex clickable text | 3493 @cindex clickable text |
3481 | 3494 |
3482 There are two parts of setting up @dfn{clickable text} in a buffer: | 3495 @dfn{Clickable text} is text that can be clicked, with either the |
3483 (1) to indicate clickability when the mouse moves over the text, and (2) | 3496 the mouse or via keyboard commands, to produce some result. Many |
3484 to make a mouse button do something when you click on that text. | 3497 major modes use clickable text to implement features such as |
3498 hyper-links. The @code{button} package provides an easy way to insert | |
3499 and manipulate clickable text. @xref{Buttons}. | |
3500 | |
3501 In this section, we will explain how to manually set up clickable | |
3502 text in a buffer using text properties. This involves two things: (1) | |
3503 indicating clickability when the mouse moves over the text, and (2) | |
3504 making @kbd{RET} or a mouse click on that text do something. | |
3485 | 3505 |
3486 Indicating clickability usually involves highlighting the text, and | 3506 Indicating clickability usually involves highlighting the text, and |
3487 often involves displaying helpful information about the action, such | 3507 often involves displaying helpful information about the action, such |
3488 as which mouse button to press, or a short summary of the action. | 3508 as which mouse button to press, or a short summary of the action. |
3489 This can be done with the @code{mouse-face} and @code{help-echo} | 3509 This can be done with the @code{mouse-face} and @code{help-echo} |