[Emacs-diffs] emacs-25 3f42061 2/2: Improve documentation of 'eval-buffer' and 'eval-region'

[Eli Zaretskii]

branch: emacs-25
commit 3f42061bb631361465a7693035f220760a74133b
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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".
---
 doc/lispref/eval.texi |    3 ++-
 src/lread.c           |   20 +++++++++++++-------
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 067dbd2..662737b 100644
--- 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 2239bfc..94f373c 100644
--- 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.