GNU bug report logs - #66267
Document cl-print.el in the CL manual.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66267 in the body.
You can then email your comments to 66267 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Document cl-print.el in the CL manual.
Date: Fri, 29 Sep 2023 16:40:24 +0000

Hello, Emacs.

cl-print.el isn't documented in the cl manual at all.  This needs doing.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #8 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 66267 <at> debbugs.gnu.org
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Fri, 29 Sep 2023 19:54:58 +0300

> Date: Fri, 29 Sep 2023 16:40:24 +0000
> From: Alan Mackenzie <acm <at> muc.de>
> 
> Hello, Emacs.
> 
> cl-print.el isn't documented in the cl manual at all.  This needs doing.

I think just a short description should be fine, given that it wasn't
documented at all.  AFAICT, it has just 2 methods.

Message #13 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66267 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Mon, 9 Oct 2023 17:41:04 +0000

Hello, Eli and Stefan.

On Fri, Sep 29, 2023 at 19:54:58 +0300, Eli Zaretskii wrote:
> > Date: Fri, 29 Sep 2023 16:40:24 +0000
> > From: Alan Mackenzie <acm <at> muc.de>
 
> > cl-print.el isn't documented in the cl manual at all.  This needs doing.

> I think just a short description should be fine, given that it wasn't
> documented at all.  AFAICT, it has just 2 methods.

Hah!  I found a bit more to document than that.  My first draught of a
new "Printing" chapter is below.  Review and criticism will be welcome.



diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 5de33350f4f..20227679c67 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -258,6 +258,159 @@ Naming Conventions
 @noindent
 [3] Only for one sequence argument or two list arguments.
 
+@node Printing
+@chapter Printing
+
+@noindent
+This chapter describes some enhancements to Emacs Lisp's
+@dfn{printing}, the action of representing Lisp objects in text form.
+The functions documented here are intended to produce output more for
+human readers than the standard printing functions such as
+@code{prin1} and @code{princ} (@pxref{Output Functions,,,elisp,GNU
+Emacs Lisp Reference Manual}).
+
+Several of these functions have a parameter @var{stream}; this
+specifies what to do with the characters printing produces.  For
+example, it might be a buffer, a marker, @code{nil} (meaning use
+standard output), or @code{t} (use the echo area).  @xref{Output
+Streams,,,elisp,GNU Emacs Lisp Reference Manual} for a full
+description.
+
+@defvar cl-print-readably
+When this variable is non-@code{nil}, @code{cl-prin1} and other
+functions described here try to produce output which can later be read
+by the Lisp reader (@pxref{Input Functions,,,elisp,GNU Emacs Lisp
+Reference Manual}).
+@end defvar
+
+@defvar cl-print-compiled
+This variable controls how to print byte-compiled functions.  Valid
+values are:
+@itemize @bullet
+@item
+@code{nil}, the default: Just an internal hex identifier is printed.
+@item
+The symbol @code{static}: The internal hex identifier together with
+the function's constant vector are printed.
+@item
+The symbol @code{disassemble}: The byte code gets disassembled.
+@item
+The symbol @code{raw}: The raw form of the function is printed by
+@code{prin1}.
+@end itemize
+Sometimes, a button is set on the output to allow you to disassemble
+the function.  See @code{cl-print-compile-button}.
+@end defvar
+
+@defvar cl-print-compile-button
+When this variable is non-@code{nil} and a byte-compiled function has
+been printed to a buffer, you can click with the mouse or type
+@key{RET} on that output to disassemble the code.  This doesn't apply
+when @code{cl-print-compiled} is set to @code{disassemble}.
+@end defvar
+
+@defvar cl-print-string-length
+The maximum length of a string to print before abbreviating it.  A
+value of @code{nil} means no limit.
+
+When the CL printing functions abbreviate a string, they print the
+first @code{cl-print-string-length} characters of the string, followed
+by @samp{...}.  When the printing is to a buffer, you can click with
+the mouse or type @key{RET} on this ellipsis to expand the string.
+
+This variable has effect only in the `cl-prin*' functions, not in
+primitives such as `prin1'.
+@end defvar
+
+@defun cl-prin1 object &option stream
+Print @var{object} on @var{stream} (see above) according to its type
+and the settings described above.  The variables @code{print-length}
+and @code{print-level} and the other standard Emacs settings also
+affect the printing (@pxref{Output Variables,,,elisp,GNU Emacs Lisp
+Reference Manual}).
+@end defun
+
+@defun cl-prin1-to-string object
+This function is like @code{cl-prin1}, except the output characters
+are returned as a string from this function rather than being passed
+to a stream.
+@end defun
+
+@defun cl-print-to-string-with-limit print-function value limit
+Return a string containing a printed representation of @var{value}.
+Attempt to get the length of the returned string under @var{limit}
+characters with successively more restrictive settings of
+@code{print-level}, @code{print-length}, and
+@code{cl-print-string-length}.  Use @var{print-function} to print,
+which should take the arguments @var{value} and @var{stream} and which
+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.
+@end defun
+
+@defun cl-print-object object stream
+Print OBJECT on STREAM (see above).  This function is actually a
+@code{cl-defgeneric} which is defined for several types of
+@var{object}
+@c (@pxref{cl-defgeneric})  This macro is currently not documented,
+@c but certainly ought to be.  ACM, 2023-10-08.
+.  Normally, you just call @code{cl-prin1} to print an @var{object}
+rather than calling this function directly.
+
+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
+@code{cl-print-object-contents} method for the same type.  For
+examples of these methods, see @file{emacs-lisp/cl-print.el} in the
+Emacs source directory.
+@end defun
+
+@defun cl-print-object-contents object start stream
+Replace an ellipsis in @var{stream} beginning at @var{start} with the
+text from the partially printed @var{object} it represents.  This
+function is also a @code{cl-defgeneric} defined for several types of
+@var{object}.  @var{stream} is a buffer containing the text with the
+ellipsis.  @var{start} specifies the starting position of the ellipsis
+in a manner dependent on the type; it will have been obtained from a
+text property on the ellipsis, having been put there by
+@code{cl-print-insert-ellipsis}.
+@end defun
+
+@defun cl-print-insert-ellipsis object start stream
+Print an ellipsis (@samp{...}) to @var{stream} (see above).  When
+@var{stream} is a buffer, the ellipsis will be given the
+@code{cl-print-ellipsis} text property.  The value of the text
+property will contain state (including @var{start}) in order to print
+the elided part of OBJECT later.  START should be nil if the whole
+OBJECT is being elided, otherwise it should be an index or other
+pointer into the internals of OBJECT which can be passed to
+`cl-print-object-contents' at a later time.
+@end defun
+
+@defvar cl-print-expand-ellipsis-function
+This variable holds a function which expands an ellipsis in the
+current buffer.  The function takes four arguments: @var{begin} and
+@var{end}, which are the bounds of the ellipsis; @var{value}, which is
+the value of the @code{cl-print-ellipsis} text property on the
+ellipsis (typically set earlier by @code{cl-prin1}); and
+@var{line-length}, the desired maximum length of the output.  Its
+return value is the buffer position after the expanded text.
+@end defvar
+
+@defun cl-print-expand-ellipsis &optional button
+This command expands the ellipsis at point.  Non-interactively, if
+@var{button} is supplied, it should be either a buffer position or a
+button made by @code{cl-print-insert-ellipsis}
+(@pxref{Buttons,,,elisp,GNU Emacs Lisp Reference Manual}), which
+indicates the position of the ellipsis.  The return value is the
+buffer position after the expanded text.
+@end defun
+
 @node Program Structure
 @chapter Program Structure
 

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #16 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 66267 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Tue, 10 Oct 2023 14:26:09 +0300

> Date: Mon, 9 Oct 2023 17:41:04 +0000
> Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 66267 <at> debbugs.gnu.org
> From: Alan Mackenzie <acm <at> muc.de>
> 
> +Several of these functions have a parameter @var{stream}; this
> +specifies what to do with the characters printing produces.  For
> +example, it might be a buffer, a marker, @code{nil} (meaning use
> +standard output), or @code{t} (use the echo area).  @xref{Output
> +Streams,,,elisp,GNU Emacs Lisp Reference Manual} for a full
> +description.                                    ^

Comma missing there.  Old Texinfo versions insist on that.

> +@defvar cl-print-compiled
> +This variable controls how to print byte-compiled functions.  Valid
> +values are:
> +@itemize @bullet
> +@item

This kind of stuff is better formatted with "@table @code", not with
@itemize.

> +@defvar cl-print-string-length
> +The maximum length of a string to print before abbreviating it.  A
> +value of @code{nil} means no limit.

And the default is...?

> +When the CL printing functions abbreviate a string, they print the
> +first @code{cl-print-string-length} characters of the string, followed
> +by @samp{...}.  When the printing is to a buffer, you can click with
      ^^^^^^^^^^
Why not @enddots{} ?

> +This variable has effect only in the `cl-prin*' functions, not in
> +primitives such as `prin1'.          ^^^^^^^^^^
                      ^^^^^^^
These should be quoted with @code, not with literals quotes.

> +@end defvar
> +
> +@defun cl-prin1 object &option stream
> +Print @var{object} on @var{stream} (see above) according to its type
> +and the settings described above.  The variables @code{print-length}
> +and @code{print-level} and the other standard Emacs settings also
> +affect the printing (@pxref{Output Variables,,,elisp,GNU Emacs Lisp
> +Reference Manual}).
> +@end defun
> +
> +@defun cl-prin1-to-string object
> +This function is like @code{cl-prin1}, except the output characters
> +are returned as a string from this function rather than being passed
> +to a stream.
> +@end defun
> +
> +@defun cl-print-to-string-with-limit print-function value limit
> +Return a string containing a printed representation of @var{value}.
> +Attempt to get the length of the returned string under @var{limit}
> +characters with successively more restrictive settings of
> +@code{print-level}, @code{print-length}, and
> +@code{cl-print-string-length}.  Use @var{print-function} to print,
> +which should take the arguments @var{value} and @var{stream} and which
                                                   ^^^^^^^^^^^^
What is STREAM?

> +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"

The description of this function follows our style for doc string, not
our style for manuals.  In a manual, we don't say "print", "use",
etc.; we say "the function prints", "it uses", etc. instead.

> +@defun cl-print-object object stream
> +Print OBJECT on STREAM (see above).  This function is actually a
         ^^^^^^^^^^^^^^^^
@var{object} and @var{stream}

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

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

> +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"

> +@defun cl-print-insert-ellipsis object start stream
> +Print an ellipsis (@samp{...}) to @var{stream} (see above).  When
                      ^^^^^^^^^^
@dots{} is better

> +@var{stream} is a buffer, the ellipsis will be given the
> +@code{cl-print-ellipsis} text property.  The value of the text
> +property will contain state (including @var{start}) in order to print
> +the elided part of OBJECT later.  START should be nil if the whole
> +OBJECT is being elided, otherwise it should be an index or other
> +pointer into the internals of OBJECT which can be passed to
> +`cl-print-object-contents' at a later time.

Use @var here for arguments, instead of capitalizing.

> +@defun cl-print-expand-ellipsis &optional button
> +This command expands the ellipsis at point.  Non-interactively, if

If it's a command, it should be documented with "@deffn Command"
instead of "@defun".

Thanks.

Message #19 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66267 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Tue, 10 Oct 2023 16:49:29 +0000

Hello, Eli,

Thanks for the review.

On Tue, Oct 10, 2023 at 14:26:09 +0300, Eli Zaretskii wrote:
> > Date: Mon, 9 Oct 2023 17:41:04 +0000
> > Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 66267 <at> debbugs.gnu.org
> > From: Alan Mackenzie <acm <at> muc.de>

> > +Several of these functions have a parameter @var{stream}; this
> > +specifies what to do with the characters printing produces.  For
> > +example, it might be a buffer, a marker, @code{nil} (meaning use
> > +standard output), or @code{t} (use the echo area).  @xref{Output
> > +Streams,,,elisp,GNU Emacs Lisp Reference Manual} for a full
> > +description.                                    ^

> Comma missing there.  Old Texinfo versions insist on that.

Fixed.

> > +@defvar cl-print-compiled
> > +This variable controls how to print byte-compiled functions.  Valid
> > +values are:
> > +@itemize @bullet
> > +@item

> This kind of stuff is better formatted with "@table @code", not with
> @itemize.

Fixed

> > +@defvar cl-print-string-length
> > +The maximum length of a string to print before abbreviating it.  A
> > +value of @code{nil} means no limit.

> And the default is...?

The default is nil.  Fixed.

> > +When the CL printing functions abbreviate a string, they print the
> > +first @code{cl-print-string-length} characters of the string, followed
> > +by @samp{...}.  When the printing is to a buffer, you can click with
>       ^^^^^^^^^^
> Why not @enddots{} ?

Because I imagined that @dots{} and @enddots{} would generate unicode
ellipsis characters.  Actually, they don't.  cl-print.el doesn't use a
unicode ellipsis either, so we're OK.

But I put in ``@dots{}'' and ``@enddots{}'' to put quote marks around
them, which I think are appropriate.

> > +This variable has effect only in the `cl-prin*' functions, not in
> > +primitives such as `prin1'.          ^^^^^^^^^^
>                       ^^^^^^^
> These should be quoted with @code, not with literals quotes.

Whoops!  Fixed.

> > +@end defvar
> > +
> > +@defun cl-prin1 object &option stream
> > +Print @var{object} on @var{stream} (see above) according to its type
> > +and the settings described above.  The variables @code{print-length}
> > +and @code{print-level} and the other standard Emacs settings also
> > +affect the printing (@pxref{Output Variables,,,elisp,GNU Emacs Lisp
> > +Reference Manual}).
> > +@end defun
> > +
> > +@defun cl-prin1-to-string object
> > +This function is like @code{cl-prin1}, except the output characters
> > +are returned as a string from this function rather than being passed
> > +to a stream.
> > +@end defun
> > +
> > +@defun cl-print-to-string-with-limit print-function value limit
> > +Return a string containing a printed representation of @var{value}.
> > +Attempt to get the length of the returned string under @var{limit}
> > +characters with successively more restrictive settings of
> > +@code{print-level}, @code{print-length}, and
> > +@code{cl-print-string-length}.  Use @var{print-function} to print,
> > +which should take the arguments @var{value} and @var{stream} and which
>                                                    ^^^^^^^^^^^^
> What is STREAM?

Good point.  It's _a_ stream variable, but not one of the function's
parameters.  I've replaced it by "a stream (see above)".

> > +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".

> The description of this function follows our style for doc string, not
> our style for manuals.  In a manual, we don't say "print", "use",
> etc.; we say "the function prints", "it uses", etc. instead.

This observation applied to several functions in my patch.  I've fixed
all of them.

> > +@defun cl-print-object object stream
> > +Print OBJECT on STREAM (see above).  This function is actually a
>          ^^^^^^^^^^^^^^^^
> @var{object} and @var{stream}

Whoops![2].  Fixed.

> > +@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.  This is going to be my next bug report,
though I'm not sure I'm the right person to document these macros.

> > +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.

> > +@defun cl-print-insert-ellipsis object start stream
> > +Print an ellipsis (@samp{...}) to @var{stream} (see above).  When
>                       ^^^^^^^^^^
> @dots{} is better

Fixed, see above.

> > +@var{stream} is a buffer, the ellipsis will be given the
> > +@code{cl-print-ellipsis} text property.  The value of the text
> > +property will contain state (including @var{start}) in order to print
> > +the elided part of OBJECT later.  START should be nil if the whole
> > +OBJECT is being elided, otherwise it should be an index or other
> > +pointer into the internals of OBJECT which can be passed to
> > +`cl-print-object-contents' at a later time.

> Use @var here for arguments, instead of capitalizing.

Whoops![3].  Fixed.

> > +@defun cl-print-expand-ellipsis &optional button
> > +This command expands the ellipsis at point.  Non-interactively, if

> If it's a command, it should be documented with "@deffn Command"
> instead of "@defun".

Thanks, I didn't know that.  Fixed.

I think the patch is ready to be committed now (to the release branch?),
but in case you want to give it another quick going over, here's the
current state:



diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 5de33350f4f..a61f55d7dcd 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -258,6 +258,157 @@ Naming Conventions
 @noindent
 [3] Only for one sequence argument or two list arguments.
 
+@node Printing
+@chapter Printing
+
+@noindent
+This chapter describes some enhancements to Emacs Lisp's
+@dfn{printing}, the action of representing Lisp objects in text form.
+The functions documented here are intended to produce output more for
+human readers than the standard printing functions such as
+@code{prin1} and @code{princ} (@pxref{Output Functions,,,elisp,GNU
+Emacs Lisp Reference Manual}).
+
+Several of these functions have a parameter @var{stream}; this
+specifies what to do with the characters printing produces.  For
+example, it might be a buffer, a marker, @code{nil} (meaning use
+standard output), or @code{t} (use the echo area).  @xref{Output
+Streams,,,elisp,GNU Emacs Lisp Reference Manual}, for a full
+description.
+
+@defvar cl-print-readably
+When this variable is non-@code{nil}, @code{cl-prin1} and other
+functions described here try to produce output which can later be read
+by the Lisp reader (@pxref{Input Functions,,,elisp,GNU Emacs Lisp
+Reference Manual}).
+@end defvar
+
+@defvar cl-print-compiled
+This variable controls how to print byte-compiled functions.  Valid
+values are:
+@table @code
+@item nil
+The default: Just an internal hex identifier is printed.
+@item static
+The internal hex identifier together with the function's constant
+vector are printed.
+@item disassemble
+The byte code gets disassembled.
+@item raw
+The raw form of the function is printed by @code{prin1}.
+@end table
+Sometimes, a button is set on the output to allow you to disassemble
+the function.  See @code{cl-print-compile-button}.
+@end defvar
+
+@defvar cl-print-compile-button
+When this variable is non-@code{nil} and a byte-compiled function has
+been printed to a buffer, you can click with the mouse or type
+@key{RET} on that output to disassemble the code.  This doesn't apply
+when @code{cl-print-compiled} is set to @code{disassemble}.
+@end defvar
+
+@defvar cl-print-string-length
+The maximum length of a string to print before abbreviating it.  A
+value of @code{nil}, the default, means no limit.
+
+When the CL printing functions abbreviate a string, they print the
+first @code{cl-print-string-length} characters of the string, followed
+by ``@enddots{}''.  When the printing is to a buffer, you can click
+with the mouse or type @key{RET} on this ellipsis to expand the
+string.
+
+This variable has effect only in the @code{cl-prin*} functions, not in
+primitives such as @code{prin1}.
+@end defvar
+
+@defun cl-prin1 object &option stream
+@code{cl-print1} prints @var{object} on @var{stream} (see above)
+according to its type and the settings described above.  The variables
+@code{print-length} and @code{print-level} and the other standard
+Emacs settings also affect the printing (@pxref{Output
+Variables,,,elisp,GNU Emacs Lisp Reference Manual}).
+@end defun
+
+@defun cl-prin1-to-string object
+This function is like @code{cl-prin1}, except the output characters
+are returned as a string from this function rather than being passed
+to a stream.
+@end defun
+
+@defun cl-print-to-string-with-limit print-function value limit
+This function returns a string containing a printed representation of
+@var{value}.  It attempts to get the length of the returned string
+under @var{limit} characters with successively more restrictive
+settings of @code{print-level}, @code{print-length}, and
+@code{cl-print-string-length}.  It uses @var{print-function} to print,
+a function which should take the arguments @var{value} and a stream
+(see above), and which 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}; 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.
+@end defun
+
+@defun cl-print-object object stream
+This function prints @var{object} on @var{stream} (see above).  It is
+actually a @code{cl-defgeneric} which is defined for several types of
+@var{object}.  Normally, you just call @code{cl-prin1} to print an
+@var{object} rather than calling this function directly.
+
+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
+@code{cl-print-object-contents} method for the same type.  For
+examples of these methods, see @file{emacs-lisp/cl-print.el} in the
+Emacs source directory.
+@end defun
+
+@defun cl-print-object-contents object start stream
+This function replaces an ellipsis in @var{stream} beginning at
+@var{start} with the text from the partially printed @var{object} it
+represents.  It is also a @code{cl-defgeneric} defined for several
+types of @var{object}.  @var{stream} is a buffer containing the text
+with the ellipsis.  @var{start} specifies the starting position of the
+ellipsis in a manner dependent on the type; it will have been obtained
+from a text property on the ellipsis, having been put there by
+@code{cl-print-insert-ellipsis}.
+@end defun
+
+@defun cl-print-insert-ellipsis object start stream
+This function prints an ellipsis (``@dots{}'') to @var{stream} (see
+above).  When @var{stream} is a buffer, the ellipsis will be given the
+@code{cl-print-ellipsis} text property.  The value of the text
+property will contain state (including @var{start}) in order to print
+the elided part of @var{object} later.  @var{start} should be nil if
+the whole @var{object} is being elided, otherwise it should be an
+index or other pointer into the internals of @var{object} which can be
+passed to `cl-print-object-contents' at a later time.
+@end defun
+
+@defvar cl-print-expand-ellipsis-function
+This variable holds a function which expands an ellipsis in the
+current buffer.  The function takes four arguments: @var{begin} and
+@var{end}, which are the bounds of the ellipsis; @var{value}, which is
+the value of the @code{cl-print-ellipsis} text property on the
+ellipsis (typically set earlier by @code{cl-prin1}); and
+@var{line-length}, the desired maximum length of the output.  Its
+return value is the buffer position after the expanded text.
+@end defvar
+
+@deffn Command cl-print-expand-ellipsis &optional button
+This command expands the ellipsis at point.  Non-interactively, if
+@var{button} is supplied, it should be either a buffer position or a
+button made by @code{cl-print-insert-ellipsis}
+(@pxref{Buttons,,,elisp,GNU Emacs Lisp Reference Manual}), which
+indicates the position of the ellipsis.  The return value is the
+buffer position after the expanded text.
+@end deffn
+
 @node Program Structure
 @chapter Program Structure
 

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #22 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 66267 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Tue, 10 Oct 2023 21:54:23 +0300

> Date: Tue, 10 Oct 2023 16:49:29 +0000
> Cc: monnier <at> iro.umontreal.ca, 66267 <at> debbugs.gnu.org
> From: Alan Mackenzie <acm <at> 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.

> > > +@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".

> > > +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.

Message #25 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66267 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Tue, 10 Oct 2023 20:42:13 +0000

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 <at> iro.umontreal.ca, 66267 <at> debbugs.gnu.org
> > From: Alan Mackenzie <acm <at> 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).

Message #28 received at 66267 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 66267 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Wed, 11 Oct 2023 15:02:57 +0300

> Date: Tue, 10 Oct 2023 20:42:13 +0000
> Cc: monnier <at> iro.umontreal.ca, 66267 <at> debbugs.gnu.org
> From: Alan Mackenzie <acm <at> 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.

Then something like this is in order, I think:

  Use this function with @code{cl-prin1} to print an object, possibly
  abbreviating it with one or more ellipses to fit within the size
  limit.

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

I have no objections to it.

Message #33 received at 66267-done <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66267-done <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66267: Document cl-print.el in the CL manual.
Date: Wed, 11 Oct 2023 15:15:05 +0000

Hello, Eli.

On Wed, Oct 11, 2023 at 15:02:57 +0300, Eli Zaretskii wrote:
> > Date: Tue, 10 Oct 2023 20:42:13 +0000
> > Cc: monnier <at> iro.umontreal.ca, 66267 <at> debbugs.gnu.org
> > From: Alan Mackenzie <acm <at> muc.de>

[ .... ]

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

> Then something like this is in order, I think:

>   Use this function with @code{cl-prin1} to print an object, possibly
>   abbreviating it with one or more ellipses to fit within the size
>   limit.

I've put that text into cl.texi, thanks.  I've tidied up a few
trivialities, inserted that cross-reference we talked about, and
committed the change to master.

I'm closing the bug with this post.

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

> I have no objections to it.

Thanks.  I've committed that change and closed that bug, too.

-- 
Alan Mackenzie (Nuremberg, Germany).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.