From 71b433f0358807dca722c5b0b178d108b9d13436 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 22 Jan 2022 16:49:06 +0200 Subject: [PATCH] Fix documentation of 'unprintable' stuff * src/print.c (syms_of_print) : * 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 b93a7610fa0..784adb9bd51 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 4d9feb55ac2..e9a83d6d5dc 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, \"#\"). 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; -- 2.39.5