master 71b433f035: Fix documentation of 'unprintable' stuff

[Eli Zaretskii]

branch: master
commit 71b433f0358807dca722c5b0b178d108b9d13436
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix documentation of 'unprintable' stuff
    
    * src/print.c (syms_of_print) <print-unreadable-function>:
    * doc/lispref/streams.texi (Input Functions, Output Variables):
    Improve the documentation of 'print-unreadable-function' and
    'readablep'.  Add indexing and cross-references.
---
 doc/lispref/streams.texi | 14 ++++++++------
 src/print.c              | 10 +++++-----
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index b93a7610fa..784adb9bd5 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -359,10 +359,12 @@ non-@code{nil} value and does nothing except flushing 
pending output.
 @end defun
 
 @defun readablep object
-This predicate says whether @var{object} can be written out and then
-read back by the Emacs Lisp reader.  If it can't, this function
-returns @code{nil}, and if it can, a printed representation (via
-@code{prin1}) of @var{object} is returned.
+@cindex readable syntax
+This predicate says whether @var{object} has @dfn{readable syntax},
+i.e., it can be written out and then read back by the Emacs Lisp
+reader.  If it can't, this function returns @code{nil}; if it can,
+this function returns a printed representation (via @code{prin1},
+@pxref{Output Functions}) of @var{object}.
 @end defun
 
 @node Output Streams
@@ -889,8 +891,8 @@ instance:
 @end example
 
 If this variable is non-@code{nil}, it should be a function that will
-be called to handle printing of these objects.  The first argument is
-the object, and the second argument is the @var{noescape} flag used by
+be called to handle printing of these objects.  The function will be
+called with two arguments: the object and the @var{noescape} flag used by
 the printing functions (@pxref{Output Functions}).
 
 The function should return either @code{nil} (print nothing), or a
diff --git a/src/print.c b/src/print.c
index 4d9feb55ac..e9a83d6d5d 100644
--- a/src/print.c
+++ b/src/print.c
@@ -2498,15 +2498,15 @@ priorities.  Values other than nil or t are also 
treated as
   staticpro (&print_prune_charset_plist);
 
   DEFVAR_LISP ("print-unreadable-function", Vprint_unreadable_function,
-              doc: /* Function called when printing unreadable objects.
+              doc: /* If non-nil, a function to call when printing unreadable 
objects.
 By default, Emacs printing functions (like `prin1') print unreadable
-objects like \"#<...>\", where \"...\" describes the object (for
+objects as \"#<...>\", where \"...\" describes the object (for
 instance, \"#<marker in no buffer>\").  If this variable is non-nil,
 it should be a function which will be called to print the object instead.
 
-It will be called with two arguments: The object to be printed, and
-noescape (see `prin1-to-string').  If this function returns nil, the
-object will be printed as normal.  If it returns a string, that string
+The function will be called with two arguments: the object to be printed, and
+the NOESCAPE flag (see `prin1-to-string').  If this function returns nil, the
+object will be printed as usual.  If it returns a string, that string
 will then be printed.  If the function returns anything else, the
 object will not be printed.  */);
   Vprint_unreadable_function = Qnil;