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