From unknown Fri Aug 15 14:45:39 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#66267 <66267@debbugs.gnu.org> To: bug#66267 <66267@debbugs.gnu.org> Subject: Status: Document cl-print.el in the CL manual. Reply-To: bug#66267 <66267@debbugs.gnu.org> Date: Fri, 15 Aug 2025 21:45:39 +0000 retitle 66267 Document cl-print.el in the CL manual. reassign 66267 emacs submitter 66267 Alan Mackenzie severity 66267 wishlist thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 29 12:41:17 2023 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). From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 29 12:55:39 2023 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 To: Alan Mackenzie In-Reply-To: (message from Alan Mackenzie on Fri, 29 Sep 2023 16:40:24 +0000) Subject: Re: bug#66267: Document cl-print.el in the CL manual. References: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66267 Cc: 66267@debbugs.gnu.org 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 debbugs-submit-bounces@debbugs.gnu.org Mon Oct 09 13:41:38 2023 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 To: Eli Zaretskii Subject: Re: bug#66267: Document cl-print.el in the CL manual. 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-Debbugs-Envelope-To: 66267 Cc: 66267@debbugs.gnu.org, Stefan Monnier 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 debbugs-submit-bounces@debbugs.gnu.org Tue Oct 10 07:26:58 2023 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 To: Alan Mackenzie In-Reply-To: (message from Alan Mackenzie on Mon, 9 Oct 2023 17:41:04 +0000) Subject: Re: bug#66267: Document cl-print.el in the CL manual. References: <83fs2wyl5p.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66267 Cc: 66267@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: -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 debbugs-submit-bounces@debbugs.gnu.org Tue Oct 10 12:50:06 2023 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 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> 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-Debbugs-Envelope-To: 66267 Cc: 66267@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, 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 debbugs-submit-bounces@debbugs.gnu.org Tue Oct 10 14:55:13 2023 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 To: Alan Mackenzie In-Reply-To: (message from Alan Mackenzie on Tue, 10 Oct 2023 16:49:29 +0000) Subject: Re: bug#66267: Document cl-print.el in the CL manual. References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66267 Cc: 66267@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: -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 debbugs-submit-bounces@debbugs.gnu.org Tue Oct 10 16:42:49 2023 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 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> 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-Debbugs-Envelope-To: 66267 Cc: 66267@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 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 debbugs-submit-bounces@debbugs.gnu.org Wed Oct 11 08:03:42 2023 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 To: Alan Mackenzie In-Reply-To: (message from Alan Mackenzie on Tue, 10 Oct 2023 20:42:13 +0000) Subject: Re: bug#66267: Document cl-print.el in the CL manual. References: <83fs2wyl5p.fsf@gnu.org> <83v8bevhv2.fsf@gnu.org> <83bkd6ux40.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 66267 Cc: 66267@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: -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 debbugs-submit-bounces@debbugs.gnu.org Wed Oct 11 11:15:40 2023 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). From unknown Fri Aug 15 14:45:39 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Thu, 09 Nov 2023 12:24:11 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator