From 67cd45a2b4cdee89f80460052032ac70c18e9e52 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 7 Mar 2012 13:36:33 +0800 Subject: [PATCH] Minor updates to Markers and Text chapters of Lisp manual. * doc/lispref/markers.texi (The Mark): Fix typo. (The Region): Copyedits. * doc/lispref/text.texi (Buffer Contents): Don't duplicate explanation of region arguments from Text node. Put doc of obsolete var buffer-substring-filters back, since it is referred to. (Low-Level Kill Ring): Yank now uses clipboard instead of primary selection by default. --- doc/lispref/ChangeLog | 11 ++++++ doc/lispref/markers.texi | 27 +++++++-------- doc/lispref/text.texi | 75 +++++++++++++++++----------------------- 3 files changed, 56 insertions(+), 57 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 59d900ff82c..999714eaf73 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2012-03-07 Chong Yidong + + * text.texi (Buffer Contents): Don't duplicate explanation of + region arguments from Text node. Put doc of obsolete var + buffer-substring-filters back, since it is referred to. + (Low-Level Kill Ring): Yank now uses clipboard instead of primary + selection by default. + + * markers.texi (The Mark): Fix typo. + (The Region): Copyedits. + 2012-03-07 Glenn Morris * markers.texi (Overview of Markers): Copyedits. diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 2bcbf153d8b..653418e8345 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -422,11 +422,11 @@ can request deactivation of the mark upon return to the editor command loop by setting the variable @code{deactivate-mark} to a non-@code{nil} value. - If Transient Mode is enabled, certain editing commands that normally -apply to text near point, apply instead to the region when the mark is -active. This is the main motivation for using Transient Mark mode. -(Another is that this enables highlighting of the region when the mark -is active. @xref{Display}.) + If Transient Mark mode is enabled, certain editing commands that +normally apply to text near point, apply instead to the region when +the mark is active. This is the main motivation for using Transient +Mark mode. (Another is that this enables highlighting of the region +when the mark is active. @xref{Display}.) In addition to the mark, each buffer has a @dfn{mark ring} which is a list of markers containing previous values of the mark. When editing @@ -662,16 +662,15 @@ integer). This is the position of either point or the mark, whichever is larger. @end defun - Few programs need to use the @code{region-beginning} and -@code{region-end} functions. A command designed to operate on a region -should normally use @code{interactive} with the @samp{r} specification -to find the beginning and end of the region. This lets other Lisp -programs specify the bounds explicitly as arguments. (@xref{Interactive -Codes}.) + Instead of using @code{region-beginning} and @code{region-end}, a +command designed to operate on a region should normally use +@code{interactive} with the @samp{r} specification to find the +beginning and end of the region. This lets other Lisp programs +specify the bounds explicitly as arguments. @xref{Interactive Codes}. @defun use-region-p This function returns @code{t} if Transient Mark mode is enabled, the -mark is active, and there's a valid region in the buffer. Commands -that operate on the region (instead of on text near point) when -there's an active mark should use this to test whether to do that. +mark is active, and there is a valid region in the buffer. This +function is intended to be used by commands that operate on the +region, instead of on text near point, when the mark is active. @end defun diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 416bfef4a60..88cb6a157f8 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -169,13 +169,9 @@ convert any portion of the text in the buffer into a string. @defun buffer-substring start end This function returns a string containing a copy of the text of the region defined by positions @var{start} and @var{end} in the current -buffer. If the arguments are not positions in the accessible portion of -the buffer, @code{buffer-substring} signals an @code{args-out-of-range} -error. - -It is not necessary for @var{start} to be less than @var{end}; the -arguments can be given in either order. But most often the smaller -argument is written first. +buffer. If the arguments are not positions in the accessible portion +of the buffer, @code{buffer-substring} signals an +@code{args-out-of-range} error. Here's an example which assumes Font-Lock mode is not enabled: @@ -218,14 +214,20 @@ This is like @code{buffer-substring}, except that it does not copy text properties, just the characters themselves. @xref{Text Properties}. @end defun +@defun buffer-string +This function returns the contents of the entire accessible portion of +the current buffer as a string. It is equivalent to +@w{@code{(buffer-substring (point-min) (point-max))}}. +@end defun + @defun filter-buffer-substring start end &optional delete This function passes the buffer text between @var{start} and @var{end} through the filter functions specified by the wrapper hook -@code{filter-buffer-substring-functions}, and returns the final -result of applying all filters. The obsolete variable -@code{buffer-substring-filters} is also consulted. If both of these -variables are @code{nil}, the value is the unaltered text from the -buffer, as @code{buffer-substring} would return. +@code{filter-buffer-substring-functions}, and returns the result. The +obsolete variable @code{buffer-substring-filters} is also consulted. +If both of these variables are @code{nil}, the value is the unaltered +text from the buffer, i.e.@: what @code{buffer-substring} would +return. If @var{delete} is non-@code{nil}, this function deletes the text between @var{start} and @var{end} after copying it, like @@ -260,30 +262,20 @@ this, and so on. The actual return value is the result of all the hook functions acting in sequence. @end defvar -@defun buffer-string -This function returns the contents of the entire accessible portion of -the current buffer as a string. It is equivalent to - -@example -(buffer-substring (point-min) (point-max)) -@end example - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- - -(buffer-string) - @result{} "This is the contents of buffer foo\n" -@end group -@end example -@end defun +@defvar buffer-substring-filters +This variable is obsoleted by +@code{filter-buffer-substring-functions}, but is still supported for +backward compatibility. Its value should should be a list of +functions which accept a single string argument and return another +string. @code{filter-buffer-substring} passes the buffer substring to +the first function in this list, and the return value of each function +is passed to the next function. The return value of the last function +is passed to @code{filter-buffer-substring-functions}. +@end defvar @defun current-word &optional strict really-word -This function returns the symbol (or word) at or near point, as a string. -The return value includes no text properties. +This function returns the symbol (or word) at or near point, as a +string. The return value includes no text properties. If the optional argument @var{really-word} is non-@code{nil}, it finds a word; otherwise, it finds a symbol (which includes both word @@ -1112,13 +1104,11 @@ case, the first string is used as the ``most recent kill'', and all the other strings are pushed onto the kill ring, for easy access by @code{yank-pop}. -The normal use of this function is to get the window system's primary -selection as the most recent kill, even if the selection belongs to +The normal use of this function is to get the window system's +clipboard as the most recent kill, even if the selection belongs to another application. @xref{Window System Selections}. However, if -the selection was provided by the current Emacs session, this function -should return @code{nil}. (If it is hard to tell whether Emacs or -some other program provided the selection, it should be good enough to -use @code{string=} to compare it with the last text Emacs provided.) +the clipboard contents come from the current Emacs session, this +function should return @code{nil}. @end defvar @defvar interprogram-cut-function @@ -1129,9 +1119,8 @@ programs, when you are using a window system. Its value should be If the value is a function, @code{kill-new} and @code{kill-append} call it with the new first element of the kill ring as the argument. -The normal use of this function is to set the window system's primary -selection from the newly killed text. -@xref{Window System Selections}. +The normal use of this function is to put newly killed text in the +window system's clipboard. @xref{Window System Selections}. @end defvar @node Internals of Kill Ring