From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 Sep 2023 16:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 66267@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.169600567726366 (code B ref -1); Fri, 29 Sep 2023 16:42:02 +0000 Received: (at submit) by debbugs.gnu.org; 29 Sep 2023 16:41:17 +0000 Received: from localhost ([127.0.0.1]:57055 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGYH-0006rC-5P for submit@debbugs.gnu.org; Fri, 29 Sep 2023 12:41:17 -0400 Received: from lists.gnu.org ([2001:470:142::17]:32822) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGYE-0006qs-5l for submit@debbugs.gnu.org; Fri, 29 Sep 2023 12:41:16 -0400 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 1qmGXm-0008TI-PT for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 12:40:46 -0400 Received: from mail.muc.de ([193.149.48.3]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qmGXh-0003Le-Ke for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 12:40:46 -0400 Received: (qmail 91704 invoked by uid 3782); 29 Sep 2023 18:40:29 +0200 Received: from acm.muc.de (p4fe15322.dip0.t-ipconnect.de [79.225.83.34]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 29 Sep 2023 18:40:28 +0200 Received: (qmail 18622 invoked by uid 1000); 29 Sep 2023 16:40:24 -0000 Date: Fri, 29 Sep 2023 16:40:24 +0000 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de Received-SPF: pass client-ip=193.149.48.3; envelope-from=acm@muc.de; helo=mail.muc.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_PASS=-0.001, T_SPF_HELO_TEMPERROR=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) Hello, Emacs. cl-print.el isn't documented in the cl manual at all. This needs doing. -- Alan Mackenzie (Nuremberg, Germany). From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 Sep 2023 16:56:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Alan Mackenzie Cc: 66267@debbugs.gnu.org Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.169600653928286 (code B ref 66267); Fri, 29 Sep 2023 16:56:01 +0000 Received: (at 66267) by debbugs.gnu.org; 29 Sep 2023 16:55:39 +0000 Received: from localhost ([127.0.0.1]:57085 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGmB-0007MA-B5 for submit@debbugs.gnu.org; Fri, 29 Sep 2023 12:55:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57548) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGm9-0007Lx-4W for 66267@debbugs.gnu.org; Fri, 29 Sep 2023 12:55:37 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qmGlo-0006jQ-VL; Fri, 29 Sep 2023 12:55:16 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=GSyVXCRV4NNJwsdHx4Tx4KWKNELk+7roBxiUB5cSIaM=; b=SnqYjBoeqQlr kaxbeJvhfwox5UBQp5yMAq+c2mY/Y/2RS7mvSyvke/xGz2QgyQ8xlw2FkvfuzmRq0TkkWRqPy9BFJ nzu4uL6WXp4wIAIpDudd41pJSRlbUSuQBqL3Sd92jEzH56RAoe/ECaVJjLb9et3SJffOP36QdBZC3 mMntrm4OGqSxlh5mvXnUoJ2EcdLqz1mYChUvNYO/wP6ndUXKxxZlK2Sn34vdvL4UMSky+ODeeuNS4 pThe9IAmOxTxkfo1iWO8T3xJuUNXOZU4TsJIRIta8ZUrtSCCP9fJsY4XElps4zbD4LXm1/SZKhDWd /vNWfxEk2maJ8qJtTIIS3g==; Date: Fri, 29 Sep 2023 19:54:58 +0300 Message-Id: <83fs2wyl5p.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Alan Mackenzie on Fri, 29 Sep 2023 16:40:24 +0000) References: X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Fri, 29 Sep 2023 16:40:24 +0000 > From: Alan Mackenzie > > 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. From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 30 19:05:07 2023 Received: (at control) by debbugs.gnu.org; 30 Sep 2023 23:05:07 +0000 Received: from localhost ([127.0.0.1]:59920 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmj1G-0005xN-Px for submit@debbugs.gnu.org; Sat, 30 Sep 2023 19:05:06 -0400 Received: from mail-lj1-x22c.google.com ([2a00:1450:4864:20::22c]:49301) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmj1D-0005wH-BY for control@debbugs.gnu.org; Sat, 30 Sep 2023 19:05:03 -0400 Received: by mail-lj1-x22c.google.com with SMTP id 38308e7fff4ca-2c00df105f8so244958711fa.2 for ; Sat, 30 Sep 2023 16:04:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696115082; x=1696719882; darn=debbugs.gnu.org; h=to:subject:message-id:date:mime-version:from:from:to:cc:subject :date:message-id:reply-to; bh=Bjh54M9Jia3ixMoKj6fqvkkjPKFpri570no6+HB4MdM=; b=imuGrlLTRskOVzDUjw4Qff68srDonFGA2UQuZuo7E75kQlOmyaYa6R5GF4H3HG0pHw iBZqV/iBnB5Hi/BzJYXNEOwfFCiDrAjLhMNIYQq9Ij0NDK7dhhdkno6YxlAz1VAF6eh3 0X9746aOsQhcbR91yHDMovvmSmB6tR7WXQPnMVaG9ZvYuQCUq1iaTPdPOHNz2NVI/vf3 EoCVYt1Bh5E80OZync70AKIEOwAQ2qnJKd6O0O3hwWPu/f31eCbdEeS4woSyk3ciuuaT UNTXY9296s5QhtsjubTNLIVjp1jjfa3NIDzrmhx2c60py5yiS8A31wzpP5pLYS9qq7AC f3Eg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696115082; x=1696719882; h=to:subject:message-id:date:mime-version:from:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=Bjh54M9Jia3ixMoKj6fqvkkjPKFpri570no6+HB4MdM=; b=ky5y68nuYBwGLzbzjeS2PbcU/1LRVBB+5pQwnKpTzIQlmi4uF9bxkewm8wM7GEVvjs bKjSKkfPOktCuFlmlZ74R4mSLA5ufpRuB+zAZf1igzSGgtkNkP8M14fwYZlohZtQjv4l cvhycrryxw/pvkJsqaxAfNAVqyiw6s7Bl6PLuDtVz0z/HdZHlhZ6067gKDn3ejYs1fPR YcdLXdrSoY9FRG3pEXv/JzwwdScp5zm2xOBpZoEQUEM+QbScC8hKtWdmoFXC677vX+ds FFL7nWhU6eMmrmUSpUz9m9htLjClo0rEnJF7bOzakKltL3QfJ2JqNLVAwPRvK9wr/rnW wgWw== X-Gm-Message-State: AOJu0YxIjytssmxolwrzpBSC3/MarMMc3ZrbHcNhpUb/qvt8Q34eNB+I toOX/keAf4VHTezIHQlwImQ8mL/VJzJ7loi3cEbgdC2D X-Google-Smtp-Source: AGHT+IH4eDdojqVmZz4cQhxYXo2dCfUZHCdWiXbfsJUXc5XfS4Z5ycEntBNqBQSojfuiYb6tqvPqQMJoBj9nOk1wYEg= X-Received: by 2002:a2e:7d0a:0:b0:2b6:a827:164f with SMTP id y10-20020a2e7d0a000000b002b6a827164fmr6558377ljc.10.1696115081633; Sat, 30 Sep 2023 16:04:41 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 30 Sep 2023 16:04:41 -0700 From: Stefan Kangas MIME-Version: 1.0 Date: Sat, 30 Sep 2023 16:04:41 -0700 Message-ID: Subject: control message for bug #66267 To: control@debbugs.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) severity 66267 wishlist quit From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 09 Oct 2023 17:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 66267@debbugs.gnu.org, Stefan Monnier Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.16968732981642 (code B ref 66267); Mon, 09 Oct 2023 17:42:02 +0000 Received: (at 66267) by debbugs.gnu.org; 9 Oct 2023 17:41:38 +0000 Received: from localhost ([127.0.0.1]:33086 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpuG9-0000QQ-IF for submit@debbugs.gnu.org; Mon, 09 Oct 2023 13:41:38 -0400 Received: from mail.muc.de ([193.149.48.3]:58343) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpuG4-0000Q5-4q for 66267@debbugs.gnu.org; Mon, 09 Oct 2023 13:41:36 -0400 Received: (qmail 97679 invoked by uid 3782); 9 Oct 2023 19:41:05 +0200 Received: from acm.muc.de (pd953a1c9.dip0.t-ipconnect.de [217.83.161.201]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 09 Oct 2023 19:41:04 +0200 Received: (qmail 12496 invoked by uid 1000); 9 Oct 2023 17:41:04 -0000 Date: Mon, 9 Oct 2023 17:41:04 +0000 Message-ID: References: <83fs2wyl5p.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83fs2wyl5p.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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 > > 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). From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 10 Oct 2023 11:27:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Alan Mackenzie Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.169693721811588 (code B ref 66267); Tue, 10 Oct 2023 11:27:02 +0000 Received: (at 66267) by debbugs.gnu.org; 10 Oct 2023 11:26:58 +0000 Received: from localhost ([127.0.0.1]:34119 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqAt7-00030q-OJ for submit@debbugs.gnu.org; Tue, 10 Oct 2023 07:26:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:56242) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqAt2-00030a-VA for 66267@debbugs.gnu.org; Tue, 10 Oct 2023 07:26:56 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qqAsa-0007wC-DM; Tue, 10 Oct 2023 07:26:24 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=WNs6EKG2+pw0Dwb7yCEnuAyKz6GyX1AXr7WYkP/hgvY=; b=dHDA0WmZXbgM ZEGf+itVw3FHbPdd/W6EP2KnHw1xBd7Cv4sJWrvcgXUP0OJBhGHmWSqGoryPsyJAT6HC89cLRGLzA LES2r0jTOe58TNFIaWOHeTAt1EJ2ZR8uyvEXGUWzGk6TEbyZqDuDpzveDumDIJYycy5DTDBhqcynB ZoaTi3xup2nyC2E3N0Tr8mhEZ3nQgj3oXKFZoNQg4JMqolfVTcofRMAez0eQuSDDc/g5UVnQxcoIn JN6Z7BJ4e84IpXMAljFCCMEGl078oS8XBqOEywko16VgYe7uBDI2MKQ0deQ/oxlhP04ICfnXtZMJT EyXiwZc/wLODZ4HJuBHiyA==; Date: Tue, 10 Oct 2023 14:26:09 +0300 Message-Id: <83v8bevhv2.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Alan Mackenzie on Mon, 9 Oct 2023 17:41:04 +0000) References: <83fs2wyl5p.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > 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. > +@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. From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. 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 X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.1696956606486 (code B ref 66267); Tue, 10 Oct 2023 16:51:01 +0000 Received: (at 66267) by debbugs.gnu.org; 10 Oct 2023 16:50:06 +0000 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 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 Received: (qmail 76638 invoked by uid 3782); 10 Oct 2023 18:49:31 +0200 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 Received: (qmail 6037 invoked by uid 1000); 10 Oct 2023 16:49:30 -0000 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 Content-Disposition: inline In-Reply-To: <83v8bevhv2.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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). From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 10 Oct 2023 18:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Alan Mackenzie Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.169696411317223 (code B ref 66267); Tue, 10 Oct 2023 18:56:02 +0000 Received: (at 66267) by debbugs.gnu.org; 10 Oct 2023 18:55:13 +0000 Received: from localhost ([127.0.0.1]:36894 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqHsq-0004Td-2R for submit@debbugs.gnu.org; Tue, 10 Oct 2023 14:55:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:32964) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqHsm-0004Sz-9M for 66267@debbugs.gnu.org; Tue, 10 Oct 2023 14:55:07 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qqHsG-0007gy-Sq; Tue, 10 Oct 2023 14:54:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=+8pbm+YjC2G/p25Yn9aUBrEGuKkT5DAU/g3k+ZvtM34=; b=V2jwow9UoEqk L1gpNLb7i3q5yYebrq6dRgo/IoN8EykGQIQ1ucrVHS9BxQeodMtHKZ3ICr/kLXmrlGtsq7K8hH2DH cfHA8DeNdAU++M0lZm07+QWYx4LC5VTK3kVtMThUk82CFrIwpk7NlNsM5gth7JRlB2CmczF9zJsb9 CDtIjrwWIcXyVAWxNAOGtGkRtD0jRbTBv8e7ICIguA2xmi3YWK4hQaoJMrpmsHAKIT+L5SjMeEygs YzldVv6S+jyYokYLUUKLTUOQ3XgQTdtOOzw7la6zyc2ymVZcqgKCpE3n1GfMC3kS4TyjbLR6dkGSx 3bJNbsWOccJStciKwuv63w==; Date: Tue, 10 Oct 2023 21:54:23 +0300 Message-Id: <83bkd6ux40.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Alan Mackenzie on Tue, 10 Oct 2023 16:49:29 +0000) References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Tue, 10 Oct 2023 16:49:29 +0000 > Cc: monnier@iro.umontreal.ca, 66267@debbugs.gnu.org > From: Alan Mackenzie > > > > +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. From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 10 Oct 2023 20:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.16969705699603 (code B ref 66267); Tue, 10 Oct 2023 20:43:01 +0000 Received: (at 66267) by debbugs.gnu.org; 10 Oct 2023 20:42:49 +0000 Received: from localhost ([127.0.0.1]:36993 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqJZ2-0002Up-Ii for submit@debbugs.gnu.org; Tue, 10 Oct 2023 16:42:48 -0400 Received: from mail.muc.de ([193.149.48.3]:50364) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqJYx-0002UL-Hd for 66267@debbugs.gnu.org; Tue, 10 Oct 2023 16:42:46 -0400 Received: (qmail 39239 invoked by uid 3782); 10 Oct 2023 22:42:15 +0200 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 22:42:14 +0200 Received: (qmail 14162 invoked by uid 1000); 10 Oct 2023 20:42:13 -0000 Date: Tue, 10 Oct 2023 20:42:13 +0000 Message-ID: References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> <83bkd6ux40.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83bkd6ux40.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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 > > > > +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). From unknown Sun Aug 17 01:01:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66267: Document cl-print.el in the CL manual. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 11 Oct 2023 12:04:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Alan Mackenzie Cc: 66267@debbugs.gnu.org, monnier@iro.umontreal.ca Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.169702582211166 (code B ref 66267); Wed, 11 Oct 2023 12:04:01 +0000 Received: (at 66267) by debbugs.gnu.org; 11 Oct 2023 12:03:42 +0000 Received: from localhost ([127.0.0.1]:37699 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqXwE-0002u2-8v for submit@debbugs.gnu.org; Wed, 11 Oct 2023 08:03:42 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54930) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqXwC-0002tp-C2 for 66267@debbugs.gnu.org; Wed, 11 Oct 2023 08:03:41 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qqXvk-0001yS-3o; Wed, 11 Oct 2023 08:03:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=vA5k9YvOuASa/5i0k8Nl9ONQefklWl5Yh9hqipAz64s=; b=sZvVNc+c+8kO IuvWsCdrTBj0OE+YPuxWI6zFrDdlHMUjTDuSrNX7Y2L0oM/9ocUo/S2/avGoytPFztAAuGYDOJIsE s8OydJwQyCKbyAqspn6BOsT1JJw0d54oIe1q0p/LwMFvUA6+nEbmkl80rMQYbrUVVScfNJPCSAUw8 tG4AzjlH0tlx+ihWOGSgD4Qwm1U0USvaymQJibCiYo3YPkYYqR6kt7l2pkgzGUajUlBmnmYWWyEhb Tfi8gMNApE4dlaSyma715nbtbRvgAPdcBg/gUqaNhpV6U0JkCOEQDC2G14asSAr9TVIYFW0H0hdc1 A7t0Nu2Mc1EyhN8SUqXQ7Q==; Date: Wed, 11 Oct 2023 15:02:57 +0300 Message-Id: <835y3dv026.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Alan Mackenzie on Tue, 10 Oct 2023 20:42:13 +0000) References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> <83bkd6ux40.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Tue, 10 Oct 2023 20:42:13 +0000 > Cc: monnier@iro.umontreal.ca, 66267@debbugs.gnu.org > From: Alan Mackenzie > > > > > > +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. From unknown Sun Aug 17 01:01:18 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Alan Mackenzie Subject: bug#66267: closed (Re: bug#66267: Document cl-print.el in the CL manual.) Message-ID: References: X-Gnu-PR-Message: they-closed 66267 X-Gnu-PR-Package: emacs Reply-To: 66267@debbugs.gnu.org Date: Wed, 11 Oct 2023 15:16:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1697037362-7754-1" This is a multi-part message in MIME format... ------------=_1697037362-7754-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #66267: Document cl-print.el in the CL manual. which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 66267@debbugs.gnu.org. --=20 66267: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D66267 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1697037362-7754-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 66267-done) by debbugs.gnu.org; 11 Oct 2023 15:15:40 +0000 Received: from localhost ([127.0.0.1]:39857 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqaw0-0001yi-0u for submit@debbugs.gnu.org; Wed, 11 Oct 2023 11:15:40 -0400 Received: from mail.muc.de ([193.149.48.3]:27850) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qqavv-0001w5-O8 for 66267-done@debbugs.gnu.org; Wed, 11 Oct 2023 11:15:38 -0400 Received: (qmail 99209 invoked by uid 3782); 11 Oct 2023 17:15:07 +0200 Received: from acm.muc.de (pd953a848.dip0.t-ipconnect.de [217.83.168.72]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Wed, 11 Oct 2023 17:15:06 +0200 Received: (qmail 29779 invoked by uid 1000); 11 Oct 2023 15:15:05 -0000 Date: Wed, 11 Oct 2023 15:15:05 +0000 To: Eli Zaretskii Subject: Re: bug#66267: Document cl-print.el in the CL manual. Message-ID: References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> <83bkd6ux40.fsf@gnu.org> <835y3dv026.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <835y3dv026.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 66267-done Cc: 66267-done@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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 [ .... ] > > > ??? 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). ------------=_1697037362-7754-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 29 Sep 2023 16:41:17 +0000 Received: from localhost ([127.0.0.1]:57055 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGYH-0006rC-5P for submit@debbugs.gnu.org; Fri, 29 Sep 2023 12:41:17 -0400 Received: from lists.gnu.org ([2001:470:142::17]:32822) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmGYE-0006qs-5l for submit@debbugs.gnu.org; Fri, 29 Sep 2023 12:41:16 -0400 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 1qmGXm-0008TI-PT for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 12:40:46 -0400 Received: from mail.muc.de ([193.149.48.3]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qmGXh-0003Le-Ke for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 12:40:46 -0400 Received: (qmail 91704 invoked by uid 3782); 29 Sep 2023 18:40:29 +0200 Received: from acm.muc.de (p4fe15322.dip0.t-ipconnect.de [79.225.83.34]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 29 Sep 2023 18:40:28 +0200 Received: (qmail 18622 invoked by uid 1000); 29 Sep 2023 16:40:24 -0000 Date: Fri, 29 Sep 2023 16:40:24 +0000 To: bug-gnu-emacs@gnu.org Subject: Document cl-print.el in the CL manual. Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline X-Submission-Agent: TMDA/1.3.x (Ph3nix) From: Alan Mackenzie X-Primary-Address: acm@muc.de Received-SPF: pass client-ip=193.149.48.3; envelope-from=acm@muc.de; helo=mail.muc.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_PASS=-0.001, T_SPF_HELO_TEMPERROR=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) Hello, Emacs. cl-print.el isn't documented in the cl manual at all. This needs doing. -- Alan Mackenzie (Nuremberg, Germany). ------------=_1697037362-7754-1--