; 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.
This commit is contained in:
Eli Zaretskii
parent
4aa8115855
commit
d4ae418691
3 changed files with 29 additions and 37 deletions
|
|
@ -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
|
||||
|
|
|
|||
4
etc/NEWS
4
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'.
|
||||
|
|
|
|||
13
src/print.c
13
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[] = {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue