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.