Improve documentation of 'eval-buffer' and 'eval-region'

* src/lread.c (Feval_buffer, Feval_region): Doc fixes.  (Bug#22023)

* doc/lispref/eval.texi (Eval): Mention narrowing to clarify
"accessible portion of buffer".

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 067dbd2d99f0fb9b60bead2b2ecccee67a4b4629..662737b754e89e0d6318090cc03ad0b364ec6bfb 100644 (file)
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -780,7 +780,8 @@ to specify this function, but it is more robust to use the
 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
 This is similar to @code{eval-region}, but the arguments provide
 different optional features.  @code{eval-buffer} operates on the
-entire accessible portion of buffer @var{buffer-or-name}.
+entire accessible portion of buffer @var{buffer-or-name}
+(@pxref{Narrowing,,, emacs, The GNU Emacs Manual}).
 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
 @code{nil} (or omitted), which means to use the current buffer.
 @var{stream} is used as in @code{eval-region}, unless @var{stream} is

diff --git a/src/lread.c b/src/lread.c
index 2239bfc452a3e272f6bdaa51beb9429fc93ecdc9..94f373c3539f55dc6c6687a22fa40c7e4a17a227 100644 (file)
--- a/src/lread.c
+++ b/src/lread.c
@@ -1941,17 +1941,22 @@ readevalloop (Lisp_Object readcharfun,
 }
 
 DEFUN ("eval-buffer", Feval_buffer, Seval_buffer, 0, 5, "",
-       doc: /* Execute the current buffer as Lisp code.
+       doc: /* Execute the accessible portion of current buffer as Lisp code.
+You can use \\[narrow-to-region] to limit the part of buffer to be evaluated.
 When called from a Lisp program (i.e., not interactively), this
 function accepts up to five optional arguments:
-BUFFER is the buffer to evaluate (nil means use current buffer).
-PRINTFLAG controls printing of output:
- A value of nil means discard it; anything else is stream for print.
+BUFFER is the buffer to evaluate (nil means use current buffer),
+ or a name of a buffer (a string).
+PRINTFLAG controls printing of output by any output functions in the
+ evaluated code, such as `print', `princ', and `prin1':
+  a value of nil means discard it; anything else is the stream to print to.
+  See Info node `(elisp)Output Streams' for details on streams.
 FILENAME specifies the file name to use for `load-history'.
 UNIBYTE, if non-nil, specifies `load-convert-to-unibyte' for this
  invocation.
-DO-ALLOW-PRINT, if non-nil, specifies that `print' and related
- functions should work normally even if PRINTFLAG is nil.
+DO-ALLOW-PRINT, if non-nil, specifies that output functions in the
+ evaluated code should work normally even if PRINTFLAG is nil, in
+ which case the output is displayed in the echo area.
 
 This function preserves the position of point.  */)
   (Lisp_Object buffer, Lisp_Object printflag, Lisp_Object filename, Lisp_Object unibyte, Lisp_Object do_allow_print)
@@ -1992,7 +1997,8 @@ When called from programs, expects two arguments,
 giving starting and ending indices in the current buffer
 of the text to be executed.
 Programs can pass third argument PRINTFLAG which controls output:
-A value of nil means discard it; anything else is stream for printing it.
+ a value of nil means discard it; anything else is stream for printing it.
+ See Info node `(elisp)Output Streams' for details on streams.
 Also the fourth argument READ-FUNCTION, if non-nil, is used
 instead of `read' to read each expression.  It gets one argument
 which is the input stream for reading characters.