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

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: 63861@debbugs.gnu.org
> Date: Sat, 17 Jun 2023 12:13:54 -0400
> 
> >> +@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?

Something like this:

  The function can be called to pretty-print either a region of text,
  presumably containing the printed representation of one or more
  objects, or to pretty-print an object.  In the first case, the
  function must be called with 2 arguments, @var{object-or-beg} and
  @var{stream-or-end}, which are integer buffer positions that define
  the region; in the second case, @var{object-or-beg} is the object to
  print and @var{stream-or-end} is the stream to which to print it,
  which defaults to @code{standard-output} if nil or omitted.

> 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?

That might be better, indeed, both for documentation and for usage.