From d4ae418691fc454f0fb7a6b377dbb675fccbdb8f Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 15 May 2022 19:02:46 +0300 Subject: [PATCH] ; 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 d805d087447..bba1dc2eee9 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 715827e76fe..a3ec2100e9a 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 c9a9b868f9f..41c0a188163 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[] = { -- 2.39.2