bug#66267: Document cl-print.el in the CL manual.

[Alan Mackenzie]

Hello, Eli.

On Tue, Oct 10, 2023 at 21:54:23 +0300, Eli Zaretskii wrote:
> > Date: Tue, 10 Oct 2023 16:49:29 +0000
> > Cc: monnier@iro.umontreal.ca, 66267@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > > +should respect @code{print-length}, @code{print-level}, and
> > > > +@code{cl-print-string-length}.  @var{limit} may be @code{nil} or zero
> > > > +in which case @var{print-function} will be called with these settings
> > > > +bound to @code{nil}, and it can also be @code{t} in which case
> > > > +@var{print-function} will be called with their current values.
> > > > +
> > > > +Use this function with @code{cl-prin1} to print an object,
> > > > +abbreviating it with ellipses to fit within a size limit.
> > >                         ^^^^^^^^
> > > "ellipsis"

> > No.  "EllipsEs" is the plural of "ellipsIs".

> ??? You say "abbreviating it with ellipses".  "It" is singular, so it
> gets abbreviated with only one ellipsis, not with several ones.

Not necessarily.  Something like a cons structure or vector printed by
cl-prin1 can have several, or even many ellipses in it.  Last week I got
a line from an ERT backtrace containing 42 ellipses - which incidentally
made it nearly useless for debugging.

New cl-print-object methods are likely to be for complex structures
rather than one-dimensional atoms, hence are likely to abbreviate several
substructures rather than just the top-level one.

Would, perhaps, the following be better: "Use this function with
@code{cl-prin1} to print an object, abbreviating it with ZERO OR MORE
ellipses to fit within a size limit."?

> > > > +@code{cl-defgeneric} which is defined for several types of

> > > Please add here a cross-reference to where cl-defgeneric is described.

> > There is no documentation for cl-defgeneric and cl-defmethod except,
> > perhaps, in their doc strings.

> Of course, there is: see "(elisp) Generic Functions".

Sorry about that.  I didn't think of looking anywhere but the CL manual
for cl- functions.

I'll add that/those cross-reference(s).

> > > > +You can write @code{cl-print-object} @code{cl-defmethod}s for other
> > > > +types of @var{object}, thus extending @code{cl-prin1}.  If you write
> > > > +such a method which uses ellipses, you should also write a
> > >                             ^^^^^^^^
> > > "ellipsis"

> > See above.

> See above.

No, here the plural is definitely required, because any particular
cl-print-object method will print (i.e. "use") many ellipses, not all
identical, in the course of its working life.

By the way, I forgot one detail about the patch.  I've written it on the
assumption that bug #66392 "Add raw printing for byte compiled functions
to cl-prin1, etc." gets OK'd.  Stefan M. has already explicitly expressed
no objection to it.  If that bug isn't OK, it's a simple matter to amend
the cl.texi patch.  Would you take a quick peep at it, please?  Thanks!

-- 
Alan Mackenzie (Nuremberg, Germany).