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

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

[Alan Mackenzie]

Hello, Emacs.

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

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Eli Zaretskii]

> Date: Fri, 29 Sep 2023 16:40:24 +0000
> From: Alan Mackenzie <acm@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.

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

[Alan Mackenzie]

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@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).

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

[Eli Zaretskii]

> Date: Mon, 9 Oct 2023 17:41:04 +0000
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, 66267@debbugs.gnu.org
> From: Alan Mackenzie <acm@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.

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

[Alan Mackenzie]

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

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

[Eli Zaretskii]

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

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

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

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

[Eli Zaretskii]

> Date: Tue, 10 Oct 2023 20:42:13 +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.

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.

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

[Alan Mackenzie]

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