From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#66267: Document cl-print.el in the CL manual. Date: Tue, 10 Oct 2023 16:49:29 +0000 Message-ID: References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17153"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Oct 10 18:51:01 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qqFwj-0004Dc-Ck for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 10 Oct 2023 18:51:01 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qqFwR-0003LM-6n; Tue, 10 Oct 2023 12:50:43 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qqFwP-0003KV-4Y for bug-gnu-emacs@gnu.org; Tue, 10 Oct 2023 12:50:41 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qqFwO-0005HG-Sf for bug-gnu-emacs@gnu.org; Tue, 10 Oct 2023 12:50:40 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qqFwj-00009K-PP for bug-gnu-emacs@gnu.org; Tue, 10 Oct 2023 12:51:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 10 Oct 2023 16:51:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs Original-Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.1696956606486 (code B ref 66267); Tue, 10 Oct 2023 16:51:01 +0000 Original-Received: (at 66267) by debbugs.gnu.org; 10 Oct 2023 16:50:06 +0000 Original-Received: from localhost ([127.0.0.1]:36828 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqFvo-00007j-L0 for submit@debbugs.gnu.org; Tue, 10 Oct 2023 12:50:06 -0400 Original-Received: from mail.muc.de ([193.149.48.3]:43661) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqFvi-000071-R0 for 66267@debbugs.gnu.org; Tue, 10 Oct 2023 12:50:02 -0400 Original-Received: (qmail 76638 invoked by uid 3782); 10 Oct 2023 18:49:31 +0200 Original-Received: from acm.muc.de (pd953a92c.dip0.t-ipconnect.de [217.83.169.44]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 10 Oct 2023 18:49:30 +0200 Original-Received: (qmail 6037 invoked by uid 1000); 10 Oct 2023 16:49:30 -0000 Content-Disposition: inline In-Reply-To: <83v8bevhv2.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:272226 Archived-At: 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 , 66267@debbugs.gnu.org > > From: Alan Mackenzie > > +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).