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