From f55500ef4033c5919783f391c079b9e5ec61fc0c Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Fri, 16 Jun 2023 13:35:36 -0400 Subject: [PATCH 5/5] lispref/streams.texi: Document new PP functionality * doc/lispref/streams.texi (Output Functions): Document new `pp` calling convention. (Output Variables): Document `pp-default-function`. --- doc/lispref/streams.texi | 24 ++++++++++++++++++++---- etc/NEWS | 10 ++++++++++ 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 89046a68249..2eb71b83f9c 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -755,10 +755,17 @@ Output Functions @end defmac @cindex pretty-printer -@defun pp object &optional stream -This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a prettier way. That is, it'll -indent and fill the object to make it more readable for humans. +@defun pp object-or-beg &optional stream-or-end +This function indents and fills the printed representation of an +object (typically representing ELisp code) to make it more readable +for humans. + +It accepts two calling conventions: if called with two integers +@var{beg} and @var{end}, it indents and fills the corresponding +region, presumably containing the printed representation of one or +more objects, otherwise it takes a @var{object} and an optional +@var{stream}, and prints @var{object} like @code{prin1}, but does it +in a prettier way. @end defun If you need to use binary I/O in batch mode, e.g., use the functions @@ -981,6 +988,15 @@ Output Variables having their own escape syntax such as newline. @end defvar +@defopt pp-default-function +This user variable specifies the function used by @code{pp} to prettify +its output. By default it uses @code{pp-fill} which attempts to +strike a good balance between speed and generating natural looking output +that fits within @code{fill-column}. The previous default was +@code{pp-28}, which tends to be faster but generate output that looks +less natural and is less compact. +@end defopt + @node Output Overrides @section Overriding Output Variables @cindex overrides, in output functions diff --git a/etc/NEWS b/etc/NEWS index 61e6e161665..7aa387b3a5c 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -396,6 +396,16 @@ name as a string. The new function 'dictionary-completing-read-dictionary' can be used to prompt with completion based on dictionaries that the server supports. +** Pp +*** New 'pp-default-function' custom variable replaces 'pp-use-max-width'. + +*** New default pretty printing function, which tries to obey 'fill-column'. + +*** 'pp' can be applied to a region rather than an object. +As a consequence, 'pp-buffer' is now declared obsolete. + +*** 'pp-to-string' takes an additional 'pp-function' argument. +This arg specifies the prettifying algorithm to use. * New Modes and Packages in Emacs 30.1 -- 2.39.2