bug#63861: [PATCH] pp.el: New "pretty printing" code

[Stefan Monnier]

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: 63861@debbugs.gnu.org
>> Date: Fri, 16 Jun 2023 14:26:54 -0400
>> 
>> +(defun pp-28 (beg &optional end)        ;FIXME: Better name?
>> +  "Prettify the current region with printed representation of a Lisp object.
>> +Uses the pretty-printing algorithm that was standard in Emacs≤29.
>                                                            ^^^^^^^^
> Please avoid non-ASCII characters in doc strings: they could produce
> display problems on less-than-capable terminals.

OK

>> +@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.
>
> This text references arguments like @var{object} that are named
> differently in the @defun line.

Indeed.  Assuming you understood what I meant to say, do you have
a recommendation of how to write it?

Or maybe, I should leave `pp` alone and add a new `pp-region`
function instead instead of combining two different calling conventions
on a single function?  The reason I've done that is because it was
difficult to avoid doing it for the "backend functions" (those that can
be put on `pp-default-function`), but admittedly, that doesn't have to
carry over to `pp`.


        Stefan