master d4ae418691: ; Improve documentation of the OVERRIDES argument to prin1

[Eli Zaretskii]

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

    ; Improve documentation of the OVERRIDES argument to prin1
    
    * src/print.c (Fprin1, syms_of_print):
    * etc/NEWS:
    * doc/lispref/streams.texi (Output Functions, Output Overrides):
    Fix typos and cross-references, and improve wording.
---
 doc/lispref/streams.texi | 49 ++++++++++++++++++++----------------------------
 etc/NEWS                 |  4 ++--
 src/print.c              | 13 +++++++------
 3 files changed, 29 insertions(+), 37 deletions(-)

diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index d805d08744..bba1dc2eee 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -653,7 +653,7 @@ This function outputs the printed representation of 
@var{object} to
 
 If @var{overrides} is non-@code{nil}, it should either be @code{t}
 (which tells @code{prin1} to use the defaults for all printer related
-variables), or a list of settings.  @xref{Output Overrides} for details.
+variables), or a list of settings.  @xref{Output Overrides}, for details.
 @end defun
 
 @defun princ object &optional stream
@@ -716,7 +716,7 @@ would have printed for the same argument.
 
 If @var{overrides} is non-@code{nil}, it should either be @code{t}
 (which tells @code{prin1} to use the defaults for all printer related
-variables), or a list of settings.  @xref{Output Overrides} for details.
+variables), or a list of settings.  @xref{Output Overrides}, for details.
 @end example
 
 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
@@ -983,20 +983,25 @@ having their own escape syntax such as newline.
 
 @node Output Overrides
 @section Overriding Output Variables
+@cindex overrides, in output functions
+@cindex output variables, overriding
 
-@xref{Output Functions} lists the numerous variables that controls how
-the Emacs Lisp printer outputs data.  These are generally available
-for users to change, but sometimes you want to output data in the
-default format.  For instance, if you're storing Emacs Lisp data in a
-file, you don't want that data to be shortened by a
-@code{print-length} setting.
+The previous section (@pxref{Output Functions}) lists the numerous
+variables that control how the Emacs Lisp printer formats data for
+outputs.  These are generally available for users to change, but
+sometimes you want to output data in the default format, or override
+the user settings in some other way.  For instance, if you're storing
+Emacs Lisp data in a file, you don't want that data to be shortened by
+a @code{print-length} setting.
 
 The @code{prin1} and @code{prin1-to-string} functions therefore have
-an optional @var{overrides} argument.  This variable can either be
-@code{t} (which means that all printing variables should be the
-default values), or a list of settings.  Each element in the list can
-either be @code{t} (which means ``reset to defaults'') or a pair where
-the @code{car} is a symbol, and the @code{cdr} is the value.
+an optional @var{overrides} argument.  This argument can either be
+@code{t} (which means that all printing variables should be reset to
+the default values), or a list of settings for some of the variables.
+Each element in the list can be either @code{t} (which means ``reset
+to defaults'', and will usually be the first element of the list), or
+a pair whose @code{car} is a symbol that stands for an output variable
+and whose @code{cdr} is the value for that variable.
 
 For instance, this prints using nothing but defaults:
 
@@ -1005,14 +1010,14 @@ For instance, this prints using nothing but defaults:
 @end lisp
 
 This prints @var{object} using the current printing settings, but
-overrides @code{print-length} to 5:
+overrides the value of @code{print-length} to be 5:
 
 @lisp
 (prin1 object nil '((length . 5)))
 @end lisp
 
 And finally, this prints @var{object} using only default settings, but
-overrides @code{print-length} to 5:
+with @code{print-length} bound to 5:
 
 @lisp
 (prin1 object nil '(t (length . 5)))
@@ -1024,46 +1029,32 @@ map to:
 @table @code
 @item length
 This overrides @code{print-length}.
-
 @item level
 This overrides @code{print-level}.
-
 @item circle
 This overrides @code{print-circle}.
-
 @item quoted
 This overrides @code{print-quoted}.
-
 @item escape-newlines
 This overrides @code{print-escape-newlines}.
-
 @item escape-control-characters
 This overrides @code{print-escape-control-characters}.
-
 @item escape-nonascii
 This overrides @code{print-escape-nonascii}.
-
 @item escape-multibyte
 This overrides @code{print-escape-multibyte}.
-
 @item charset-text-property
 This overrides @code{print-charset-text-property}.
-
 @item unreadeable-function
 This overrides @code{print-unreadable-function}.
-
 @item gensym
 This overrides @code{print-gensym}.
-
 @item continuous-numbering
 This overrides @code{print-continuous-numbering}.
-
 @item number-table
 This overrides @code{print-number-table}.
-
 @item float-format
 This overrides @code{float-output-format}.
-
 @item integers-as-characters
 This overrides @code{print-integers-as-characters}.
 @end table
diff --git a/etc/NEWS b/etc/NEWS
index 715827e76f..a3ec2100e9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1818,8 +1818,8 @@ functions.
 * Lisp Changes in Emacs 29.1
 
 +++
-** 'prin1' and 'prin1-to-string' now takes an OVERRIDES parameter.
-This parameter can be used to override printer settings.
+** 'prin1' and 'prin1-to-string' now take an optional OVERRIDES parameter.
+This parameter can be used to override values of print-related settings.
 
 +++
 ** New minor mode 'header-line-indent-mode'.
diff --git a/src/print.c b/src/print.c
index c9a9b868f9..41c0a18816 100644
--- a/src/print.c
+++ b/src/print.c
@@ -688,11 +688,11 @@ of these:
 If PRINTCHARFUN is omitted, the value of `standard-output' (which see)
 is used instead.
 
-OVERRIDES should be a list of settings.  An element in this list be
-the symbol t, which means "use all the defaults".  If not, an element
-should be a pair, where the `car' or the pair is the setting, and the
-`cdr' of the pair is the value of printer-related settings to use for
-this `prin1' call.
+Optional argument OVERRIDES should be a list of settings for print-related
+variables.  An element in this list can be the symbol t, which means "reset
+all the values to their defaults".  Otherwise, an element should be a pair,
+where the `car' or the pair is the setting symbol, and the `cdr' is the
+value of of the setting to use for this `prin1' call.
 
 For instance:
 
@@ -702,7 +702,7 @@ See the manual entry `(elisp)Output Overrides' for a list 
of possible
 values.
 
 As a special case, OVERRIDES can also simply be the symbol t, which
-means "use all the defaults".  */)
+means "use default values for all the print-related settings".  */)
   (Lisp_Object object, Lisp_Object printcharfun, Lisp_Object overrides)
 {
   specpdl_ref count = SPECPDL_INDEX ();
@@ -2645,6 +2645,7 @@ be printed.  */);
 
   DEFVAR_LISP ("print--variable-mapping", Vprint__variable_mapping,
               doc: /* Mapping for print variables in `prin1'.
+Internal use only.
 Do not modify this list.  */);
   Vprint__variable_mapping = Qnil;
   Lisp_Object total[] = {