From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 28 Feb 2023 22:37:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 61877@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.167762378324645 (code B ref -1); Tue, 28 Feb 2023 22:37:01 +0000 Received: (at submit) by debbugs.gnu.org; 28 Feb 2023 22:36:23 +0000 Received: from localhost ([127.0.0.1]:52148 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pX8a6-0006PP-Cu for submit@debbugs.gnu.org; Tue, 28 Feb 2023 17:36:22 -0500 Received: from lists.gnu.org ([209.51.188.17]:60192) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pX8a4-0006PG-Ll for submit@debbugs.gnu.org; Tue, 28 Feb 2023 17:36:21 -0500 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 1pX8a3-0008Cp-S7 for bug-gnu-emacs@gnu.org; Tue, 28 Feb 2023 17:36:20 -0500 Received: from sonic304-23.consmr.mail.ir2.yahoo.com ([77.238.179.148]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pX8a1-00042z-BI for bug-gnu-emacs@gnu.org; Tue, 28 Feb 2023 17:36:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1677623773; bh=GiWK+KAmdUS4pKHIyBO9MYVmZRjSAoyObd3RWrTcf7A=; h=From:To:Subject:Date:References:From:Subject:Reply-To; b=WHeq8CVhbl0SMTJu0s8Sn1FGJNuYl0W7ZlzoZG7edHZj0VaE5XZf5RRhXOR2ktcWMOnDTc41djiTkIfd5jxBzaucxszDhqFq+9cbJTM/pYB+dMZvjOGigIQcpqxEVVV8sZKmrKPGV1DQ/aUhvSCRkU3Xvj5EEbSafuPbP3pYalqS4eKMRSJaGk9oGzrtp2vvTamoFPCB7vP2YW7ipdi3Ffq+ENaBw4V6sobDDrayTRSdyfEGs8j87kEulSLsNyOH/k6bFKu4ruNic7tVSGoZNOab0PoccpjYAskOCQzIXi8IiQpSjHSAj7863afkuc719OGRZTu0YvT156Qli3n26A== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1677623773; bh=JHQzPnDg2WbMRT03mWZFtqoUgSdMi/ly8M8HRQ1Itgs=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=OsT89z4oWdwf1R2T+5zfdBWPB8mHmGzZ2/0WfVlDFznt7b15PxMuxP31pHKkwlwxIGg2YybvrUA6GJWW1QJUxLZ5LrNrR7yXc5OGUb6R9a4V1kAXKhD+ql6L+t0MBvUcRYuwoc9m8z4c3FsxGYES5ghjSpRcmBopyrpmtxYzrL8PvWekFHsoTzu5S2cBnrdJuUCGpd71DTLH2iZ+het86kwClobSLDE5WbXg2hjAW9jDxsdn6GT0VrJEb6kfyE169sqibu3NP4UxSmHDb9gmnlpHzBS01VCe9A11tGCGceIeMC69oCHoafiQ9zdw9YZombuyj3eVT4Tjsv3KAKhnhA== X-YMail-OSG: eUVJp4IVM1kl3PLWsjYlKVRkdxFYBKe4yaWZhYgqneyGj6H2ifykaNczuo1OHvp uoOZCIzyGAblr5bXswUe0uyiiiBG.HXxyXjIMQUb6W2degU20o6.xhjGflsOsM_3EvMznmnS9S_3 np4yn0pS6dTSQGe2C_99iVDT7yHhgFtgPXKViW6j.4fUfl9HRnqhSRGj9Ab_6S79_zxNyxP6WSNg 6I__Es1baly07V6U9O4XxwKYBjUm.WQjxE0AHc8lQ_Z0EmEIEUA3SKR1yaTi5rX8qX4_RsP9Vi_6 9.7TsP8p_mlRDT4d0LKHQjb2FfyAOWwNw7HyOCZESoeviBD6F1if21HjZaHHLSdIoGxH1HhKewvS V7LIRAMNETHDpommvb5KsHktw8w._fJrhcw31IWk0qS.X_3vUc09A5J1dq6k3XgKnw1..lBNztwZ WyWNAKWsfCY3.RvdVSppu2hJbgUTSKdgXI5c1kuZCTzUTi3VPxHxh6Xhdwgt9LtVkQ_9.UkiuAtp J_EtaPzhaovg.XhHmYn1beiqf5OtEva6389ROxiivE30CYEI4foSNgAimyzz1YY.3KVTzis7JYhJ QDmauSNxylTEYxexqGkstiXdvAVRxJqW6Au2YIQ61r1wg.GgZbmeGTsRNxCr9SsAWgDSDwdZPgrJ Ru8QLUYphWhvxzIY2fgrRm99AIlfm_382nse7vkMZwJSmnt47LnA3VTAv_1kQ7wsacsPevVp3f2P S.j0JCIOOes05wm504bPz6KNc5R.3WEe1itRU3MVga_5_9HEvorgoydQXXbl.yeZXTv2yzyU71ts cB4SqMnXI9Xyu8Ga2uLgmBd7RSTr2qYq.3r7b8e.x_Cujltye_wBjbuTs2zH48.7Kfw0ZbixGWlJ q8rLvLlQMKYevM3IT559k4etAiRjf3RefUnUnZK8fKtWGLmwjYvKpRH.JCGaW49TFbuuf9.4YC9i 2_iKkaqxaIQmvwNLTxqYboKRXEjw3GUNB80xDr2zINgwj7lo_14zANrNIqTLqYAXJ83E8mHMrYUH CJg3MdThP9frrTf46LDpbxnKR2XQLroHzS81jVrVrRLTo8Z73ZSuaPZBgFeKONmIOU1TizXW3QKx 66DcADc2tPLXGrlsRNLEgwcMklZRx.W3PFmYKQyVr0DKzcAsw2im41EGvUtB.t6NZUmfdrrGAoRM yQP5EnNqGS9HKuPF5EY_UYIec_Zd9PnjBeJUhgdq8abEIMpNvB0dkVLZvDOKikfqDj8bjeQiTfPb M50bGelmRtCJmza3UxGC8mIZ9bb37ZjR6dzwiPBHHxA1fHflIP7AcItp1nenou1pK5Lb6gM61U8h 6hntMRc2Yb5kTKLMn7YAjV_eIw5x3BrzFu71VBWY7Bk5qMS3CumaZj3D_.nmK5Lt7k1fGGgDqL3T vBp0Sezf9Hwyjc.PdEmbfYZtdRnbiMFnu3DLCTYGjU6lsuHK5QQJNCTP9XTlnpDs5JliuwkBgmrp x_TLu2VDF9JBa6U7LU1wgtUz2XROSk9bQcDokVor7V8IZ3vBzmw7pheQWq8IJBOXbI7FDbSUBfk9 b1SME5A_.F2aXT2km3z.N21noOY0QmucxoPZjy.6fJSEN8mo3vJRNFCRHdvMIABCI4BSkNZjY4VF tMerrNVF3K4xn_wGw_ytIOsRZaIs5vMfZE5tkAoILJKvYTOTNUJ6wO6okYJe.N0RWJWZ0det19Id siqPQ1rqLZNEH3uBiZmtziPulQbR.uBY0tleZ3dafcs0JH7h7VpTxhLK9RRMfx3PIbLfKrznWMnB sI4tfy9RlyFyc9O.GRgb.dco9ILAGHvLZsYX1smgmvXb5Ggqp2eg13Um35_V7sf1DV_1_GTyb44K Iw8o_0BOL6SY8jz0mh_KyzqT0RZpua5azdslkSUCPAIo3AnXeIjdm_USvGj0kMzAqJ5CkyXmP4Ja vk9MiFsRU250Ytkw7mqSQkuY87K.o.MK4Y0cJPRdelTITTSSIC26dWvD_EwW.dks32sDpdGhFwao W8fG4EKywtBzo.H2RIQGDvaL75k29Uq48hbg2WJaQLV226nKSjS8kklamssPHGNefxv.q47OKp7P JW_aJjj150w3afRFyT4X8bXFqdPwRjHgICU.qLMUc2HrrYiSJpxGFisP5R5iKF3JZCOSvDPPJApl At_B1pEdbKy6ZqeSlQyuYRP1AJF0Se_9niYFHBxj_omKHg4Uu9nl7R11Cl8.ZW.kDG1FH7PpahkE pfs71Qtlcuw2uAc9BoWMjNn8XLd_Q X-Sonic-MF: Received: from sonic.gate.mail.ne1.yahoo.com by sonic304.consmr.mail.ir2.yahoo.com with HTTP; Tue, 28 Feb 2023 22:36:13 +0000 Received: by hermes--production-ir2-65c64dfd66-8r58z (Yahoo Inc. Hermes SMTP Server) with ESMTPA ID 70ddf924b09e7907d71425080886081a; Tue, 28 Feb 2023 22:36:10 +0000 (UTC) From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Date: Tue, 28 Feb 2023 23:36:09 +0100 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" References: X-Mailer: WebService/1.1.21221 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 7435 Received-SPF: pass client-ip=77.238.179.148; envelope-from=mardani29@yahoo.es; helo=sonic304-23.consmr.mail.ir2.yahoo.com 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.4 (-) 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: -2.4 (--) --=-=-= Content-Type: text/plain Shortdoc contains a lot of useful examples about how to use common ELisp functions. This patch explores a new Emacs feature where those examples are identified and extracted so they can be displayed, perhaps, in *Help* buffers (via an additional help-fns-describe-function-functions hook). After you install the attached patch, take a look at the *Help* buffer produced by C-h f assq RET, or C-h f match-string RET, etc. What do you think of having this new Lisp feature in Emacs 30? I can send later another patch with tests, relevant NEWS entries and documentation changes. Thanks. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-Extract-Lisp-function-examples-from-shortdoc-informa.patch Content-Transfer-Encoding: quoted-printable >From da859693ba9fafd0ba43107bc99dba5464ac3ab6 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Daniel=3D20Mart=3DC3=3DADn?=3D Date: Tue, 28 Feb 2023 23:15:40 +0100 Subject: [PATCH] Extract Lisp function examples from shortdoc information * lisp/emacs-lisp/shortdoc.el (shortdoc--display-function): Add a new shortdoc-example text property so that ELisp examples can be searched for later. (shortdoc--insert-group-in-buffer): New function extracted from the buffer insertion code in shortdoc-display-group. (shortdoc-display-group): Implement in terms of shortdoc--insert-group-in-buffer. * lisp/help-fns.el (help-fns--shortdoc-example): Add a new help-fns-describe-function-functions hook that displays example code for functions documented in shortdoc groups. --- lisp/emacs-lisp/shortdoc.el | 80 ++++++++++++++++++++----------------- lisp/help-fns.el | 28 +++++++++++++ 2 files changed, 72 insertions(+), 36 deletions(-) diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index c49960c2ee6..4e19cd04c9e 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1443,45 +1443,51 @@ shortdoc-display-group (setq group (intern group))) (unless (assq group shortdoc--groups) (error "No such documentation group %s" group)) - (funcall (if same-window - #'pop-to-buffer-same-window - #'pop-to-buffer) - (format "*Shortdoc %s*" group)) - (let ((inhibit-read-only t) - (prev nil)) - (erase-buffer) - (shortdoc-mode) - (button-mode) - (mapc - (lambda (data) - (cond - ((stringp data) - (setq prev nil) - (unless (bobp) - (insert "\n")) - (insert (propertize - (substitute-command-keys data) - 'face 'shortdoc-heading - 'shortdoc-section t - 'outline-level 1)) - (insert (propertize - "\n\n" - 'face 'shortdoc-heading - 'shortdoc-section t))) - ;; There may be functions not yet defined in the data. - ((fboundp (car data)) - (when prev - (insert (make-separator-line) - ;; This helps with hidden outlines (bug#53981) - (propertize "\n" 'face '(:height 0)))) - (setq prev t) - (shortdoc--display-function data)))) - (cdr (assq group shortdoc--groups)))) + (let ((buf (get-buffer-create (format "*Shortdoc %s*" group)))) + (shortdoc--insert-group-in-buffer group buf) + (funcall (if same-window + #'pop-to-buffer-same-window + #'pop-to-buffer) + buf)) (goto-char (point-min)) (when function (text-property-search-forward 'shortdoc-function function t) (beginning-of-line))) =20 +(defun shortdoc--insert-group-in-buffer (group &optional buf) + "Insert a short documentation summary for functions in GROUP in buffer B= UF." + (with-current-buffer (or buf (current-buffer)) + (let ((inhibit-read-only t) + (prev nil)) + (erase-buffer) + (shortdoc-mode) + (button-mode) + (mapc + (lambda (data) + (cond + ((stringp data) + (setq prev nil) + (unless (bobp) + (insert "\n")) + (insert (propertize + (substitute-command-keys data) + 'face 'shortdoc-heading + 'shortdoc-section t + 'outline-level 1)) + (insert (propertize + "\n\n" + 'face 'shortdoc-heading + 'shortdoc-section t))) + ;; There may be functions not yet defined in the data. + ((fboundp (car data)) + (when prev + (insert (make-separator-line) + ;; This helps with hidden outlines (bug#53981) + (propertize "\n" 'face '(:height 0)))) + (setq prev t) + (shortdoc--display-function data)))) + (cdr (assq group shortdoc--groups)))))) + ;;;###autoload (defalias 'shortdoc #'shortdoc-display-group) =20 @@ -1521,7 +1527,8 @@ shortdoc--display-function "=3D>")) (single-arrow (if (char-displayable-p ?=E2=86=92) "=E2=86=92" - "->"))) + "->")) + (start-example (point))) (cl-loop for (type value) on data by #'cddr do (cl-case type @@ -1572,7 +1579,8 @@ shortdoc--display-function (:eg-result-string (insert " e.g. " double-arrow " ") (princ value (current-buffer)) - (insert "\n"))))) + (insert "\n")))) + (add-text-properties start-example (point) `(shortdoc-example ,funct= ion))) ;; Insert the arglist after doing the evals, in case that's pulled ;; in the function definition. (save-excursion diff --git a/lisp/help-fns.el b/lisp/help-fns.el index 50e60b68e17..843de957a5f 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -954,6 +954,34 @@ help-fns--mention-shortdoc-groups (fill-region-as-paragraph (point-min) (point-max)) (goto-char (point-max)))))) =20 +(add-hook 'help-fns-describe-function-functions + #'help-fns--shortdoc-example) +(defun help-fns--shortdoc-example (object) + (require 'shortdoc) + (when-let ((groups (and (symbolp object) + (shortdoc-function-groups object))) + (times 0)) + (mapc + (lambda (group) + (let ((buf (current-buffer))) + (with-temp-buffer + (shortdoc--insert-group-in-buffer group) + (goto-char (point-min)) + (setq match (text-property-search-forward + 'shortdoc-example object t)) + (let ((temp-buffer (current-buffer))) + (with-current-buffer buf + (when (zerop times) + (if (eq (length groups) 1) + (insert " Example:\n\n") + (insert " Examples:\n\n"))) + (setq times (1+ times)) + (insert-buffer-substring temp-buffer + (prop-match-beginning match) + (prop-match-end match)) + (insert "\n")))))) + groups))) + (defun help-fns-short-filename (filename) (let* ((abbrev (abbreviate-file-name filename)) (short abbrev)) --=20 2.34.1 --=-=-=-- From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 02 Mar 2023 21:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167779314010434 (code B ref 61877); Thu, 02 Mar 2023 21:39:02 +0000 Received: (at 61877) by debbugs.gnu.org; 2 Mar 2023 21:39:00 +0000 Received: from localhost ([127.0.0.1]:58540 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pXqdf-0002iC-Au for submit@debbugs.gnu.org; Thu, 02 Mar 2023 16:39:00 -0500 Received: from sonic302-21.consmr.mail.ir2.yahoo.com ([87.248.110.84]:35360) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pXqda-0002hw-PB for 61877@debbugs.gnu.org; Thu, 02 Mar 2023 16:38:57 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1677793127; bh=UmLo5ys8EMoGUGjeY8ikPs00YAN7nh4wqc3EkjzVbEg=; h=From:To:Subject:References:Date:In-Reply-To:From:Subject:Reply-To; b=rziKMYABt1Ndts5rbirHQlq9ACHkA8BkJV7+OorLiDBKqJhsDJGMZ5wMVlyEfvJavcpYKJa62xdI8nqGb/LdnoEQdX6lEZffEmHF04yKY8EzQDJTZzaUCgbMSVi5AHW8wkEBN+fOUekO9Y6zwp/450/uun+ucndmxSqzhcHImjW0/LoKgJPA58cXPlsHa773MEz8cEPVZMWTgMGZN9ch0EDcN8sYa2xERnezQ27/agoy8ZlDWSL7wl2IEsK66W2JQqEO72qzddmnXHkuHDNaFHociUolm0J99HI+q9HkzSZhnBn+mGkzpoekGltQ+vsQ8D6VHnOAJJRp8ChCz5n3MA== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1677793127; bh=eH+Dd3fzHVv1LKGCpOcEME1qSIEYt4Rylu7iyBh0eEi=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=RR9PkHFZTWiE2jjmuQk+coN9JVMBrULo5Dh8DwL2W/mLJjthGNjfF2y4li4Iw6TwKKFeZmBe0Y56KOe2D7eWTZsCXCt3xxNQ4AVE7wJ8B3XMHh1ubQC7voseqK3SzmLq5h977ZkOeXjtT5JZDV6K27lb3KwCT7a377kWKZb35vwlz3RaJiZD0DCcp+TsbBTTUW3RG/fvSntj08H1muS29zF+yrfDbsyRQVmtg9G88Hs8OAHzxIdrF18F26w1FswL7q62Qwz20a5t8nIwtrA81IzTueYkfEF/C74/2SnXjrQCkr5zAD1IPMQarqvKZ3CZNZK/4yNN2vm95xeH/MmOfw== X-YMail-OSG: HwyVrWIVM1kJVr0j2KgqMdtaUKNhMOFXHTnlZp9fpx.2DI4nrcw40CDGfCzWqpV xNgBLWhWYZ1wESHF1YKKs1lkSuCWIAtuZrmge_iM_J8eIPMAIP1U2rhS2FUBsl4KDpCMQje11Wi. gRq5YZeDhFXx0Ea8uwD1jIWtAW9PNmQ56CZF1P5xgzmsOvxyYkBg.WoU5iujLXWs5GoovtUcJlm4 6qdhoiGa6MlFjtTvg5Bph1KDA13rLlGWofgkM3FpQGDGGZB2TiuC2Uc0OslHpXWelbk7m0uf2GxY t_dQuv.cYfbkzDZIcLRkibxs_e8jeIZ1PJXmHTFqADSF.hIwIXUU9f_OEOO1qTUP8kduNPqMKseQ SEXpoggOyqS1qDNoBF7OiLHrjntumgNoYWAd2fudcpBiZH6HDQy95YIA3LyYpWpIKxA58yqecgnz HNesFagG59mY92BDHFvJsZBMbQa8Lt3uMqxRfou52bA7yzI99rNElFdmmGKkNMWCktz4AOWC8yvA O1.NknTbT6oKoPTcFRuxJm2yir3J8qvXokWJCM_m3BvaktBCHnIVNeIxjcQluKCCdJKVi9Ume5ZV qkNRPUHrmCNqqARh7ZcMB7zBbkSPypuOF8JaaFUVeEHgYRCV7Zbx_KxxUMdLCC_9bgXx..rbaWop y58A4qztIBgdkTtGSOIOcUW04gCyNQs_BbG7Lfpasuxzc8NzqgdWf8wf.bvjhQiS5M0yDjfpgySI nNBnDbbxGBomJWv.IygBaGd4EUprLGzAf3.ABZhtaV.8xuqnx3QSZ0pi7vV.SGUNQKyFz_CR6KMj qHq0COHGcZnLub4_c_ObAeheyqDmUF3.vh35yPh5clPut15LA_rbwqdDqRRe2Q6hfjN5xksZ1OG7 CgaSQEIRkxQ9_g_q.3eTmCud_JbPmy1ThqdlHg0uMjA8NjxIlgjjaorFHmVikKGuR14_tc6KD6i4 AaYzONQzRtDsbUa1GGMh2QzQAomVB_MhsaqxOBoGUwbxX6ZRbqyA3h15WZBp201qpofnfx86oHVq bRwZRIwjiRWK._W1a9cWcZhpkGqirpot4yMk7TRrE854vg7ofMTFbPQ_1HHDPxyHyUZPB0JCPAUZ ISCC4N0w9RhJvCN.qTsEDDFQrdvROxCEP809MMlTMdMiS7bNP_tVeIGP4JULyT4iLHILte1HUBMZ Rz35PDt89YcDBTzpFAWpXtaizfZU9P6cMxfCO5viqV7lZy3dVwMv.AQyRZS5IX.aundp0g0peajs BIGZNcMdHGrX_s4qX9dz0x7ZuJK8_qevOOBMNbpaiOj0ooGDq2YSDcWb3GWEtLUtE84Oqn7UxXwX UBI3U8izrpRcmB3SWMQVIP1Sw0Iddg9OfeRw3dY5LwaBWaz6yj.99MsbPZkXCLq1qNn.5vOqrBgS BIZFAjr9fOkGMQaZ.lWHX4Xa6htaDCsZuKbcvscBWgKR8cAT8KDKJzsUIhvkT.Q6mvnM6TrcoEd. 6E8418wcBBKhllBqDkE5yhW1lAEdNBcyS387vwMHGFD4rMupZ3SG4abqsEkuYgQ.PxeoRtEr.ntT 6LusyCjWssoH1oCBjLwOqyG_X.c5m1V39U7ondP0moHKNW9wcvMT8dTZOOowTFFhfYxmpLduSc2W Hw617DHEHn8CniswZNl6Dp.XL74UfQ0lVVnwOYpHr39YprxVr_YfytixNZ2qDutNgLhfb1WGxlmA uZXDGSAfi8V8GtRxFcTHqkJkrKKtGelOn19JWcxB8LQ_Mr97QcExt9.ovkPEb8K78h5s65odETng xUWMUKDAAENORJsaw_O5H4RxtRfEHQaO252RuAch7EHgg02kJMErHzWJfbdtBIPY01OAvRxnSG9R ggaLNAkJIvnN5nUhoTDxaKqqZru48ZUwr96qt9HQuOry_y8IYTiW_8UwA198acp0xEzZqHw4._QK WTYHiRbQeb176vqdapRjUH64jV8lKqFw_SkAL6K4eewyNPHLV2a12PHD_GvH9KMFaoi.x2QzNXty PwIeIG7Aby44r7_P9R__XuQ8_.3KhBymsgezNQ8_K3QF5wmJpcm8cn1SxvxAsxz6AnfAPDH3rs.t _kdtMybKym2nVSUt8BgT1ZHvjEKxCZ.btPjQ8_KXr3uqDYpZFvL4ruT6I24wE_OvFJciuS1lZfbz 0toHn4.WtUxYA3ZPALODikvVu3lY.1iaIdhrHltLKWYWY_9MyBLA5JeUPiLoMuuxjR3REvLlLnVO MOFNBV0iOajQWCix1vVCFzgo- X-Sonic-MF: Received: from sonic.gate.mail.ne1.yahoo.com by sonic302.consmr.mail.ir2.yahoo.com with HTTP; Thu, 2 Mar 2023 21:38:47 +0000 Received: by hermes--production-ir2-5b7d458747-lqssg (Yahoo Inc. Hermes SMTP Server) with ESMTPA ID 3eba8d8da71d9380e95649f6cf492e5c; Thu, 02 Mar 2023 21:38:43 +0000 (UTC) From: Daniel =?UTF-8?Q?Mart=C3=ADn?= References: Date: Thu, 02 Mar 2023 22:38:42 +0100 In-Reply-To: ("Daniel =?UTF-8?Q?Mart=C3=ADn?="'s message of "Tue, 28 Feb 2023 23:36:09 +0100") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (darwin) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Mailer: WebService/1.1.21221 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 11730 X-Spam-Score: 0.2 (/) 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.8 (/) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Daniel Mart=C3=ADn writes: > Shortdoc contains a lot of useful examples about how to use common ELisp > functions. This patch explores a new Emacs feature where those examples > are identified and extracted so they can be displayed, perhaps, in > *Help* buffers (via an additional help-fns-describe-function-functions > hook). > > After you install the attached patch, take a look at the *Help* buffer > produced by C-h f assq RET, or C-h f match-string RET, etc. > > What do you think of having this new Lisp feature in Emacs 30? I can > send later another patch with tests, relevant NEWS entries and > documentation changes. > > Thanks. I attach a second version of the patch. I've confined the implementation to shortdoc.el, added a test, and documented the new functions. The NEWS entry explains how users could show this information in their *Help* buffers, if they want. Thanks. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-Add-functions-to-query-Emacs-Lisp-examples-registere.patch Content-Transfer-Encoding: quoted-printable >From 709f3605c84e6a0948c30753011e366f5caaace9 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Daniel=3D20Mart=3DC3=3DADn?=3D Date: Tue, 28 Feb 2023 23:15:40 +0100 Subject: [PATCH] Add functions to query Emacs Lisp examples registered in shortdoc * lisp/emacs-lisp/shortdoc.el (shortdoc--display-function): Add a new shortdoc-example text property so that ELisp examples can be searched for later. (shortdoc--insert-group-in-buffer): New function extracted from the buffer insertion code in shortdoc-display-group. (shortdoc-display-group): Implement in terms of shortdoc--insert-group-in-buffer. (shortdoc-function-examples): New function that returns an alist of Emacs Lisp examples from shortdoc. (shortdoc-help-fns-examples-function): New function to insert Emacs Lisp function examples in *Help* buffers, if added to help-fns-describe-function-functions. * test/lisp/emacs-lisp/shortdoc-tests.el (shortdoc-function-examples-test): Test it. * doc/lispref/help.texi (Documentation Groups): Document it. * etc/NEWS: Advertise it. (Bug#61877) --- doc/lispref/help.texi | 20 ++++ etc/NEWS | 18 ++++ lisp/emacs-lisp/shortdoc.el | 122 +++++++++++++++++-------- test/lisp/emacs-lisp/shortdoc-tests.el | 10 ++ 4 files changed, 134 insertions(+), 36 deletions(-) diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 59b6b6dab1d..b4c3b0eed5f 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -989,3 +989,23 @@ Documentation Groups If @var{group} doesn't exist, it will be created. If @var{section} doesn't exist, it will be added to the end of the function group. @end defun + +You can also query the examples of use of functions defined in +shortdoc groups. + +@defun shortdoc-function-examples function +This function returns all shortdoc examples for @var{function}. The +result is an alist with items of the form + +@example +(@var{group} . @var{examples}) +@end example + +@noindent +where @var{group} is a documentation group where @var{function} +appears in and @var{examples} is a string with the examples of use of +@var{function} defined in @var{group}. + +@code{shortdoc-function-examples} returns @code{nil} if @var{function} +is not a function or if it doesn=E2=80=99t contain shortdoc information. +@end defun diff --git a/etc/NEWS b/etc/NEWS index 31fb22fc1e2..a0934b7d7d0 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -201,6 +201,24 @@ This command adds a docstring comment to the current d= efun. If a comment already exists, point is only moved to the comment. It is bound to 'C-c C-d' in 'go-ts-mode'. =20 +** Shortdoc + ++++ +*** New function 'shortdoc-function-examples'. +This function queries the registered documentation groups and returns +examples of use of a given Emacs Lisp function. + ++++ +*** New function 'shortdoc-help-fns-examples-function'. +This function queries the registered documentation groups and inserts +examples of use of a given Emacs Lisp function into the current +buffer. If you want to insert Emacs Lisp function examples into +regular *Help* buffers when you use 'describe-function', add the +following to you init file: + +(add-hook 'help-fns-describe-function-functions + #'shortdoc-help-fns-examples-function) + * New Modes and Packages in Emacs 30.1 =20 diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index c49960c2ee6..cf66a43fc35 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1443,45 +1443,51 @@ shortdoc-display-group (setq group (intern group))) (unless (assq group shortdoc--groups) (error "No such documentation group %s" group)) - (funcall (if same-window - #'pop-to-buffer-same-window - #'pop-to-buffer) - (format "*Shortdoc %s*" group)) - (let ((inhibit-read-only t) - (prev nil)) - (erase-buffer) - (shortdoc-mode) - (button-mode) - (mapc - (lambda (data) - (cond - ((stringp data) - (setq prev nil) - (unless (bobp) - (insert "\n")) - (insert (propertize - (substitute-command-keys data) - 'face 'shortdoc-heading - 'shortdoc-section t - 'outline-level 1)) - (insert (propertize - "\n\n" - 'face 'shortdoc-heading - 'shortdoc-section t))) - ;; There may be functions not yet defined in the data. - ((fboundp (car data)) - (when prev - (insert (make-separator-line) - ;; This helps with hidden outlines (bug#53981) - (propertize "\n" 'face '(:height 0)))) - (setq prev t) - (shortdoc--display-function data)))) - (cdr (assq group shortdoc--groups)))) + (let ((buf (get-buffer-create (format "*Shortdoc %s*" group)))) + (shortdoc--insert-group-in-buffer group buf) + (funcall (if same-window + #'pop-to-buffer-same-window + #'pop-to-buffer) + buf)) (goto-char (point-min)) (when function (text-property-search-forward 'shortdoc-function function t) (beginning-of-line))) =20 +(defun shortdoc--insert-group-in-buffer (group &optional buf) + "Insert a short documentation summary for functions in GROUP in buffer B= UF." + (with-current-buffer (or buf (current-buffer)) + (let ((inhibit-read-only t) + (prev nil)) + (erase-buffer) + (shortdoc-mode) + (button-mode) + (mapc + (lambda (data) + (cond + ((stringp data) + (setq prev nil) + (unless (bobp) + (insert "\n")) + (insert (propertize + (substitute-command-keys data) + 'face 'shortdoc-heading + 'shortdoc-section t + 'outline-level 1)) + (insert (propertize + "\n\n" + 'face 'shortdoc-heading + 'shortdoc-section t))) + ;; There may be functions not yet defined in the data. + ((fboundp (car data)) + (when prev + (insert (make-separator-line) + ;; This helps with hidden outlines (bug#53981) + (propertize "\n" 'face '(:height 0)))) + (setq prev t) + (shortdoc--display-function data)))) + (cdr (assq group shortdoc--groups)))))) + ;;;###autoload (defalias 'shortdoc #'shortdoc-display-group) =20 @@ -1521,7 +1527,8 @@ shortdoc--display-function "=3D>")) (single-arrow (if (char-displayable-p ?=E2=86=92) "=E2=86=92" - "->"))) + "->")) + (start-example (point))) (cl-loop for (type value) on data by #'cddr do (cl-case type @@ -1572,7 +1579,8 @@ shortdoc--display-function (:eg-result-string (insert " e.g. " double-arrow " ") (princ value (current-buffer)) - (insert "\n"))))) + (insert "\n")))) + (add-text-properties start-example (point) `(shortdoc-example ,funct= ion))) ;; Insert the arglist after doing the evals, in case that's pulled ;; in the function definition. (save-excursion @@ -1582,6 +1590,48 @@ shortdoc--display-function (insert " " (symbol-name param))) (add-face-text-property arglist-start (point) 'shortdoc-section t)))) =20 +(defun shortdoc-function-examples (function) + "Return all shortdoc examples for FUNCTION. +The result is an alist with items of the form (GROUP . EXAMPLES), +where GROUP is a shortdoc group where FUNCTION appears in and +EXAMPLES is a string with the usage examples of FUNCTION defined +in GROUP. Return nil if FUNCTION is not a function or if it +doesn't contain shortdoc information." + (let ((groups (and (symbolp function) + (shortdoc-function-groups function))) + (examples nil)) + (mapc + (lambda (group) + (with-temp-buffer + (shortdoc--insert-group-in-buffer group) + (goto-char (point-min)) + (setq match (text-property-search-forward + 'shortdoc-example function t)) + (push `(,group . ,(string-trim + (buffer-substring-no-properties + (prop-match-beginning match) + (prop-match-end match)))) + examples))) + groups) + examples)) + +(defun shortdoc-help-fns-examples-function (function) + "Insert Emacs Lisp examples for FUNCTION into the current buffer. +You can add this function to the +`help-fns-describe-function-functions' list to show function +example documentation in *Help* buffers." + (let ((examples (shortdoc-function-examples function)) + (times 0)) + (dolist (example examples) + (when (zerop times) + (if (eq (length examples) 1) + (insert " Example:\n\n") + (insert " Examples:\n\n"))) + (setq times (1+ times)) + (insert " ") + (insert (cdr example)) + (insert "\n\n")))) + (defun shortdoc-function-groups (function) "Return all shortdoc groups FUNCTION appears in." (cl-loop for group in shortdoc--groups diff --git a/test/lisp/emacs-lisp/shortdoc-tests.el b/test/lisp/emacs-lisp/= shortdoc-tests.el index 516d095767f..a65a4a5ddc3 100644 --- a/test/lisp/emacs-lisp/shortdoc-tests.el +++ b/test/lisp/emacs-lisp/shortdoc-tests.el @@ -65,6 +65,16 @@ shortdoc-all-groups-work (when buf (kill-buffer buf)))))) =20 +(ert-deftest shortdoc-function-examples-test () + "Test the extraction of usage examples of some Elisp functions." + (should (equal '((list . "(delete 2 (list 1 2 3 4))\n =3D> (1 3 4)\n = (delete \"a\" (list \"a\" \"b\" \"c\" \"d\"))\n =3D> (\"b\" \"c\" \"d\"= )")) + (shortdoc-function-examples 'delete))) + (should (equal '((alist . "(assq 'foo '((foo . bar) (zot . baz)))\n = =3D> (foo . bar)") + (list . "(assq 'b '((a . 1) (b . 2)))\n =3D> (b . 2)")) + (shortdoc-function-examples 'assq))) + (should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n = =3D> 0")) + (shortdoc-function-examples 'string-match-p)))) + (provide 'shortdoc-tests) =20 ;;; shortdoc-tests.el ends here --=20 2.34.1 --=-=-=-- From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 11 Mar 2023 08:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Daniel =?UTF-8?Q?Mart=C3=ADn?= Cc: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167852389823832 (code B ref 61877); Sat, 11 Mar 2023 08:39:02 +0000 Received: (at 61877) by debbugs.gnu.org; 11 Mar 2023 08:38:18 +0000 Received: from localhost ([127.0.0.1]:56502 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pauk5-0006CJ-IM for submit@debbugs.gnu.org; Sat, 11 Mar 2023 03:38:17 -0500 Received: from eggs.gnu.org ([209.51.188.92]:36090) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pauk3-0006C5-Np for 61877@debbugs.gnu.org; Sat, 11 Mar 2023 03:38:16 -0500 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 1paujy-0003jI-F3; Sat, 11 Mar 2023 03:38:10 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=DWAkF02KswT+5uO1WMCqe95ptq3DUd96Lt1YXVdlPeI=; b=JDJL6M07HaJ3q/YtPFJK vPGfRdpvIwZ97CcY3cMST1Ppq3BuaFYYYNnNKrGCfhTITML4Y54Ue1DUaPeG+U7cx5qCoH/rP9xbr 2YH7X8WUX/jU9sm8k647EBjUhwdG57RolHBXba45cPL0RYBc268/vrz8gZ2p3F9U/sTJBc6jcDOcj Nk18YB9IjJ6vojpb/jz2nNclHWeiET/hPYbv5LYoxdcght5h0q4qvjZgcjh9N2AnkVC82Rksq+I5y q8jqLwj9PVuKrMG//X2ApHG48wd7ULld7tBgPwJr2/fixPPMriu8eIqeb9ts3hzFpbqKzuUUy1nzR EDeNzm/DDJy8Ig==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1paujx-0002fD-MF; Sat, 11 Mar 2023 03:38:10 -0500 Date: Sat, 11 Mar 2023 10:37:54 +0200 Message-Id: <837cvny97h.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (bug-gnu-emacs@gnu.org) References: MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit 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: Thu, 02 Mar 2023 22:38:42 +0100 > From: Daniel Martín via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > Daniel Martín writes: > > > Shortdoc contains a lot of useful examples about how to use common ELisp > > functions. This patch explores a new Emacs feature where those examples > > are identified and extracted so they can be displayed, perhaps, in > > *Help* buffers (via an additional help-fns-describe-function-functions > > hook). > > > > After you install the attached patch, take a look at the *Help* buffer > > produced by C-h f assq RET, or C-h f match-string RET, etc. > > > > What do you think of having this new Lisp feature in Emacs 30? I can > > send later another patch with tests, relevant NEWS entries and > > documentation changes. > > > > Thanks. > > I attach a second version of the patch. I've confined the > implementation to shortdoc.el, added a test, and documented the new > functions. Thanks. This no longer applies to the current master, so please resubmit, and I will install. > The NEWS entry explains how users could show this information in their > *Help* buffers, if they want. Maybe this part should be also in the user manual? From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 11 Mar 2023 14:29:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167854488815133 (code B ref 61877); Sat, 11 Mar 2023 14:29:02 +0000 Received: (at 61877) by debbugs.gnu.org; 11 Mar 2023 14:28:08 +0000 Received: from localhost ([127.0.0.1]:56955 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pb0Cd-0003w0-CB for submit@debbugs.gnu.org; Sat, 11 Mar 2023 09:28:08 -0500 Received: from sonic313-20.consmr.mail.ir2.yahoo.com ([77.238.179.187]:34597) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pb0Cb-0003vY-23 for 61877@debbugs.gnu.org; Sat, 11 Mar 2023 09:28:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1678544877; bh=wjykakxQZjxJ3qMYw3JXs66xcfm3zKv3D6DZ3zeU5W4=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From:Subject:Reply-To; b=YFjJSrICVU9p3HURzcRi+hOsJ2QPlyDQLXl5WuTGljJIkXASYmb80hMyKF0vZTnhDVXQo0oUP/rR/7RzgIUqw8wSv813HU2iOF/6qbqkRLhRcizISksm7zMLp9iY3Les3IrrJKomaEqeYFRVHxePlOD2eZFMt7uZwELSvEXGO+YakpsSS0tiH2RpunucBuBqvpRAondb0wk/oPcAbqhKL6W5oaGqDaVpU9jbuCL7FOdEJtEMR2Y50YTsZ3sB0hdEK3pGUfLRtJ4gSJNNcW+sPy92Nrx5M+n3J+JfY9nSZfTdxHYBjxpncJQdWi4u5t8lX7+0BAMhF7xS4Eg5kY5LKg== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1678544877; bh=KUtasTjnKKZjzS5q3alqWolfxpDZI62BxMEsusPklVa=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=URtNYtohC8bnbRHYGAA6auDcHx9ZNrC1sua3Qo38tVah6f4E/IIWHB924hpeBtWJYQndSUU3GJMRnyitdRvKnyAABWo9D1h1amOUDvVszv/cSi7NUoU45NUZo3enFNPE4eXCWpyE97IT689uYV/XxHQh+/04DKgVeVhiC57QRgxNUYizFWKgJ1Q/2lpKBAg9k3M71Ze2uMWDIKseTjDUC7rqui0cnFVSKvCD1NVylfOqhSF5vc491DSKU/8UzYqpwlWQZwkXWpCmN1oxu/mKajW3TcS/vYvrgkNcsqcsKYhLGLiWW4U6pHeAl9yIjHkm8/K8hqTzB0XxLPtZeUt9nQ== X-YMail-OSG: k4t2ytEVM1ltVKS1o_ZKgMiXvOFFA4EHw76pFe4c9.99Bg7DONTZ2ibDSnXERt8 OEZ_76s3t6JcLxlm6HPtSZEtCgd4jK68xHa0onq3MP2Khe9IJbH.pgtfx5o92yfTz2GG5XUHujwv Xura1Vec62FQP102jRv3L.urr2R0_ntQ4iIhqDI.6eOMw0_I9jZJBbsNzY44zEYfoMCh.4vowSsC kvaycNUGduBfTp6uJU1o1y1WlfTJCF_9I0pxnDKRKV00DYjkOWqDncr.nCuI8a4HEpu47_u1tovK 0NWnbHyqA0HmPltY5B2PlqBdMW6wPwnZywfg1DmHEF.nBRRAap1y52YyY1iBqDD9xMaJyQdN.erh rIQO4YXTAr91ZGwpdLAuYw7g6ypMsBVa5gykPEkKp8VRZRRXAmB0FQLisg_DPvmsofbLaEfYos00 GD9Uj71UQKkWpUB8lLTvQWAUy7D1l5pSWNIIaw2EIVzO18Bkb2Rt3.0PZVntOah0hoX_Bz5AbkCq MmGZTOp8d_ixDoofUJV0fTBqqveirOvhaOLEHjPwvzeCyD5vkjKPegDAgy01d9ML1MW8Hq6pUDn. TpAIJVZEQSe3ad3Nqq4VWBjzTmedp0Y1oAn0DNYMiTmMwlBB9TVhZmzrvzgGTEmRS9Lg5kcYp3T9 g2jG40vIcYYCNUxWDz0ufqOjPbwYdVqaGjIW4iLsadLcXGGWT.mbu66OrIFGgmLCcQl6eCeY9E3u KO27DaY_bYPCAIKGOz3jLFqVe4MS_QpLkQgi9iRk4W8IRS6ebizyvWTkqkmVfomBdHN4OSd_HVbX vUt7MPHXta3ka_TCjQMNT11e5.yXwhpCynVUEY2m5kMp_wbz3xI4eP2yawjSoP8g8yd2xUGSHwLl qIN6Bgi.K.K806_1HhGFuSLvKGU3xJlr5Wvc8phH2QUNXFlZivK7.JIRGrvfyPtXAzZx8EAEUuqC DV4dZ0EmwD0H5Fh_cciy2f9DcU_k1aRx_WnQotuVup1VBB8txWHLIOTXP.OBbpB4rW9NzbD6qmVp LxsbC.FzLbxBbfD1pBqNs0D3ja0UbmQLNsY_gJftLuuBbxbwGWkVlbZzJEyjbQ.tKqUmtoVkzT8O UJAgBorICermAJ.0nYLxHdalPXFitBX90YbF6cuZC_M0haMlTVON8_A0OrBmzfkiyXmYP57rwiu. 24eYmTxTdZUUP4qxTqeATjo2BpxtcPMmb5mc42eNf7mUdGNqr.UBddN5JL1OPW1MDHodqWxRzeEq 3qpfa5E69viIiNhU70SM0uv48YfM.Alj.qGiP7Ije.MUlLxvOm0T.8jPQREbwWUwZLCPM0yHMO5S H4oirJvIUBf6kgOXfzpEwfXlYkQfVuN787zUy83VgcVdRPc8ch_DtJn4g5CojOh43D3c.CoNuun3 De0BXEKG_d0K00cbTOUCcatZJxkarNZO.BA7Rj2qPHA5nmtERkV5Xm6OquU_t4reNkIA7QVVZw_9 S7SHVIfo0mbBnVKi6PK8iNNbOmd1Z5spQaqXlb.jnrmbstC6oSCop9G3ec2qYD5q7hzCA2PM48H6 pngifVvULj6FSrZ3H7pYd1unntBx2YgKUlOks5sYo_GdqhXWBhFUrsPm7rvXLgcJRTlkqBGnSXDi XlV5oe3gqTeHyjvxRXQsjG5VtEkVW.7s_VXmuDMJTKs_P_ImKGdfO_Tw5JR9mrnFYOaZ8dlU0ZxL yHHShnY_jcqzo5ZhAIO1fgbWR0GXMUQIlSWswpaPvQLKfe_g3D1uBpdDuTFo7xqIexcVBMQHC5k1 .5Oz6nKinx2Kc8fEYXUb1Y.HSp1fVSYvNtAYUYcsxqBduTsXvQsWoHVYWKuYYuPXBeev4OCmPb5Z qYDbA4h5gJNSUjz.3xjrFXs9_zTIQc1gM0ci3bDFHx0U9695T6rXAzjVabIlVDiS4yt47pbOWeMw MrfMHD_LrYQdOtlXmT9TFTkxBpgWZv4WIJDobmeVPAhVg4vV0IyZv8pF1Dd4Hs8xKNrRxaMZnR0y 3YntXFuXRxPDfA09ilwwJStOYiXzENDsawwWyq6h4KDJRhZb2xpQt7wKVKwEFlhnqbgY.2aJZ8fZ 4R6s8GxRMOy6n2qgBBLQrhCG5nws1ginYufq_y9nk.M8KdrnaZ1NyblVQmz1QcpEaauxGIacZQg_ riGg5JQ7FHAAJpdp_wcoq8X6.GG7bHBUdoFraFndFTBc7PlurOb5x0QeDF8p.lsKCbhbCU3FPNPf k07_YP_Wp1bXJRclNVNUyH8rJc.EC6qF7085hyFtkq6q0eA-- X-Sonic-MF: Received: from sonic.gate.mail.ne1.yahoo.com by sonic313.consmr.mail.ir2.yahoo.com with HTTP; Sat, 11 Mar 2023 14:27:57 +0000 Received: by hermes--production-ir2-5b7d458747-s752v (Yahoo Inc. Hermes SMTP Server) with ESMTPA ID e52dbf05e3c667106cb5f0364a786c42; Sat, 11 Mar 2023 14:27:56 +0000 (UTC) From: Daniel =?UTF-8?Q?Mart=C3=ADn?= References: <837cvny97h.fsf@gnu.org> Date: Sat, 11 Mar 2023 15:27:54 +0100 In-Reply-To: <837cvny97h.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 11 Mar 2023 10:37:54 +0200") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (darwin) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Mailer: WebService/1.1.21284 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 12522 X-Spam-Score: 0.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: -0.7 (/) --=-=-= Content-Type: text/plain Eli Zaretskii writes: > > Thanks. This no longer applies to the current master, so please > resubmit, and I will install. > Thanks, I've rebased the patch. >> The NEWS entry explains how users could show this information in their >> *Help* buffers, if they want. > > Maybe this part should be also in the user manual? I've added some information to the user manual. I see we don't document help-fns-describe-function-functions in the user manual at all, should we do it? Customizing what is displayed in describe-function buffers may be something that users want to do. But perhaps we need to make the hook part of the Customize interface first, I don't know. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-Add-functions-to-query-Emacs-Lisp-examples-registere.patch Content-Transfer-Encoding: quoted-printable >From e1cfca117c7c757fd87bdd76eb612ada682d0f00 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Daniel=3D20Mart=3DC3=3DADn?=3D Date: Tue, 28 Feb 2023 23:15:40 +0100 Subject: [PATCH] Add functions to query Emacs Lisp examples registered in shortdoc * lisp/emacs-lisp/shortdoc.el (shortdoc--display-function): Add a new shortdoc-example text property so that ELisp examples can be searched for later. (shortdoc--insert-group-in-buffer): New function extracted from the buffer insertion code in shortdoc-display-group. (shortdoc-display-group): Implement in terms of shortdoc--insert-group-in-buffer. (shortdoc-function-examples): New function that returns an alist of Emacs Lisp examples from shortdoc. (shortdoc-help-fns-examples-function): New function to insert Emacs Lisp function examples in *Help* buffers, if added to help-fns-describe-function-functions. * test/lisp/emacs-lisp/shortdoc-tests.el (shortdoc-function-examples-test): Test it. * doc/emacs/help.texi (Name Help): Document in the user manual. * doc/lispref/help.texi (Documentation Groups): Document it. * etc/NEWS: Advertise it. (Bug#61877) --- doc/emacs/help.texi | 9 ++ doc/lispref/help.texi | 26 ++++++ etc/NEWS | 18 ++++ lisp/emacs-lisp/shortdoc.el | 122 +++++++++++++++++-------- test/lisp/emacs-lisp/shortdoc-tests.el | 10 ++ 5 files changed, 149 insertions(+), 36 deletions(-) diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 2513e6be271..10c007eb635 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -316,6 +316,15 @@ Name Help by using the @kbd{M-x shortdoc} command. This will prompt you for an area of interest, e.g., @code{string}, and pop you to a buffer where many of the functions relevant for handling strings are listed. +Here's an example you can include in your initialization file +(@pxref{Init File}) that uses @code{shortdoc} to insert Emacs Lisp +function examples into regular @file{*Help*} buffers when you use +@kbd{C-h f}: + +@example +(add-hook 'help-fns-describe-function-functions + #'shortdoc-help-fns-examples-function) +@end example =20 @kindex C-h v @findex describe-variable diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 59b6b6dab1d..3175f66122e 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -989,3 +989,29 @@ Documentation Groups If @var{group} doesn't exist, it will be created. If @var{section} doesn't exist, it will be added to the end of the function group. @end defun + +You can also query the examples of use of functions defined in +shortdoc groups. + +@defun shortdoc-function-examples function +This function returns all shortdoc examples for @var{function}. The +result is an alist with items of the form + +@example +(@var{group} . @var{examples}) +@end example + +@noindent +where @var{group} is a documentation group where @var{function} +appears in and @var{examples} is a string with the examples of use of +@var{function} defined in @var{group}. + +@code{shortdoc-function-examples} returns @code{nil} if @var{function} +is not a function or if it doesn=E2=80=99t contain shortdoc information. +@end defun + +@defun shortdoc-help-fns-examples-function function +This function queries the registered documentation groups and inserts +examples of use of a given Emacs Lisp function into the current +buffer. +@end defun diff --git a/etc/NEWS b/etc/NEWS index 13d073c7fb8..5f51b801774 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -220,6 +220,24 @@ asynchronously (which is the default behavior). *** New face 'doc-view-svg-face'. This replaces 'doc-view-svg-foreground' and 'doc-view-svg-background'. =20 +** Shortdoc + ++++ +*** New function 'shortdoc-function-examples'. +This function queries the registered documentation groups and returns +examples of use of a given Emacs Lisp function. + ++++ +*** New function 'shortdoc-help-fns-examples-function'. +This function queries the registered documentation groups and inserts +examples of use of a given Emacs Lisp function into the current +buffer. If you want to insert Emacs Lisp function examples into +regular *Help* buffers when you use 'describe-function', add the +following to you init file: + + (add-hook 'help-fns-describe-function-functions + #'shortdoc-help-fns-examples-function) + * New Modes and Packages in Emacs 30.1 =20 diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index c49960c2ee6..cf66a43fc35 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1443,45 +1443,51 @@ shortdoc-display-group (setq group (intern group))) (unless (assq group shortdoc--groups) (error "No such documentation group %s" group)) - (funcall (if same-window - #'pop-to-buffer-same-window - #'pop-to-buffer) - (format "*Shortdoc %s*" group)) - (let ((inhibit-read-only t) - (prev nil)) - (erase-buffer) - (shortdoc-mode) - (button-mode) - (mapc - (lambda (data) - (cond - ((stringp data) - (setq prev nil) - (unless (bobp) - (insert "\n")) - (insert (propertize - (substitute-command-keys data) - 'face 'shortdoc-heading - 'shortdoc-section t - 'outline-level 1)) - (insert (propertize - "\n\n" - 'face 'shortdoc-heading - 'shortdoc-section t))) - ;; There may be functions not yet defined in the data. - ((fboundp (car data)) - (when prev - (insert (make-separator-line) - ;; This helps with hidden outlines (bug#53981) - (propertize "\n" 'face '(:height 0)))) - (setq prev t) - (shortdoc--display-function data)))) - (cdr (assq group shortdoc--groups)))) + (let ((buf (get-buffer-create (format "*Shortdoc %s*" group)))) + (shortdoc--insert-group-in-buffer group buf) + (funcall (if same-window + #'pop-to-buffer-same-window + #'pop-to-buffer) + buf)) (goto-char (point-min)) (when function (text-property-search-forward 'shortdoc-function function t) (beginning-of-line))) =20 +(defun shortdoc--insert-group-in-buffer (group &optional buf) + "Insert a short documentation summary for functions in GROUP in buffer B= UF." + (with-current-buffer (or buf (current-buffer)) + (let ((inhibit-read-only t) + (prev nil)) + (erase-buffer) + (shortdoc-mode) + (button-mode) + (mapc + (lambda (data) + (cond + ((stringp data) + (setq prev nil) + (unless (bobp) + (insert "\n")) + (insert (propertize + (substitute-command-keys data) + 'face 'shortdoc-heading + 'shortdoc-section t + 'outline-level 1)) + (insert (propertize + "\n\n" + 'face 'shortdoc-heading + 'shortdoc-section t))) + ;; There may be functions not yet defined in the data. + ((fboundp (car data)) + (when prev + (insert (make-separator-line) + ;; This helps with hidden outlines (bug#53981) + (propertize "\n" 'face '(:height 0)))) + (setq prev t) + (shortdoc--display-function data)))) + (cdr (assq group shortdoc--groups)))))) + ;;;###autoload (defalias 'shortdoc #'shortdoc-display-group) =20 @@ -1521,7 +1527,8 @@ shortdoc--display-function "=3D>")) (single-arrow (if (char-displayable-p ?=E2=86=92) "=E2=86=92" - "->"))) + "->")) + (start-example (point))) (cl-loop for (type value) on data by #'cddr do (cl-case type @@ -1572,7 +1579,8 @@ shortdoc--display-function (:eg-result-string (insert " e.g. " double-arrow " ") (princ value (current-buffer)) - (insert "\n"))))) + (insert "\n")))) + (add-text-properties start-example (point) `(shortdoc-example ,funct= ion))) ;; Insert the arglist after doing the evals, in case that's pulled ;; in the function definition. (save-excursion @@ -1582,6 +1590,48 @@ shortdoc--display-function (insert " " (symbol-name param))) (add-face-text-property arglist-start (point) 'shortdoc-section t)))) =20 +(defun shortdoc-function-examples (function) + "Return all shortdoc examples for FUNCTION. +The result is an alist with items of the form (GROUP . EXAMPLES), +where GROUP is a shortdoc group where FUNCTION appears in and +EXAMPLES is a string with the usage examples of FUNCTION defined +in GROUP. Return nil if FUNCTION is not a function or if it +doesn't contain shortdoc information." + (let ((groups (and (symbolp function) + (shortdoc-function-groups function))) + (examples nil)) + (mapc + (lambda (group) + (with-temp-buffer + (shortdoc--insert-group-in-buffer group) + (goto-char (point-min)) + (setq match (text-property-search-forward + 'shortdoc-example function t)) + (push `(,group . ,(string-trim + (buffer-substring-no-properties + (prop-match-beginning match) + (prop-match-end match)))) + examples))) + groups) + examples)) + +(defun shortdoc-help-fns-examples-function (function) + "Insert Emacs Lisp examples for FUNCTION into the current buffer. +You can add this function to the +`help-fns-describe-function-functions' list to show function +example documentation in *Help* buffers." + (let ((examples (shortdoc-function-examples function)) + (times 0)) + (dolist (example examples) + (when (zerop times) + (if (eq (length examples) 1) + (insert " Example:\n\n") + (insert " Examples:\n\n"))) + (setq times (1+ times)) + (insert " ") + (insert (cdr example)) + (insert "\n\n")))) + (defun shortdoc-function-groups (function) "Return all shortdoc groups FUNCTION appears in." (cl-loop for group in shortdoc--groups diff --git a/test/lisp/emacs-lisp/shortdoc-tests.el b/test/lisp/emacs-lisp/= shortdoc-tests.el index 516d095767f..a65a4a5ddc3 100644 --- a/test/lisp/emacs-lisp/shortdoc-tests.el +++ b/test/lisp/emacs-lisp/shortdoc-tests.el @@ -65,6 +65,16 @@ shortdoc-all-groups-work (when buf (kill-buffer buf)))))) =20 +(ert-deftest shortdoc-function-examples-test () + "Test the extraction of usage examples of some Elisp functions." + (should (equal '((list . "(delete 2 (list 1 2 3 4))\n =3D> (1 3 4)\n = (delete \"a\" (list \"a\" \"b\" \"c\" \"d\"))\n =3D> (\"b\" \"c\" \"d\"= )")) + (shortdoc-function-examples 'delete))) + (should (equal '((alist . "(assq 'foo '((foo . bar) (zot . baz)))\n = =3D> (foo . bar)") + (list . "(assq 'b '((a . 1) (b . 2)))\n =3D> (b . 2)")) + (shortdoc-function-examples 'assq))) + (should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n = =3D> 0")) + (shortdoc-function-examples 'string-match-p)))) + (provide 'shortdoc-tests) =20 ;;; shortdoc-tests.el ends here --=20 2.34.1 --=-=-=-- From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 12 Mar 2023 08:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Daniel =?UTF-8?Q?Mart=C3=ADn?= Cc: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167860984012002 (code B ref 61877); Sun, 12 Mar 2023 08:31:02 +0000 Received: (at 61877) by debbugs.gnu.org; 12 Mar 2023 08:30:40 +0000 Received: from localhost ([127.0.0.1]:59094 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbH6G-00037W-Bj for submit@debbugs.gnu.org; Sun, 12 Mar 2023 04:30:40 -0400 Received: from eggs.gnu.org ([209.51.188.92]:33846) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbH6E-00037H-2r for 61877@debbugs.gnu.org; Sun, 12 Mar 2023 04:30:38 -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 1pbH68-0005fj-LQ; Sun, 12 Mar 2023 04:30:32 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=/6jcYRZw1kju0MAe0C2Z3+PRsmPmtqcAqXOOnYH93B0=; b=hsZI/yuMF8/GzjQPc1OK t9aFQVB9IVMp3OtRbNyvwcARv5C0Uba4W5568shsptcscfquLg+Lph0GHTGZroqUNl97cqSzhbHZB tBi3F9MPqmYYW+9/fGMKt00G9961/zsSBNf8XckrT4jV645LJlktHN/61KqCO2nXiFQ45kJUOi1fZ dPk7wLnTpn4Cv27+8rd2N6UABDiIyEBW8mwE5HasuqiDzb2ECi6upoHywKwXN5Vzj8/hOXeJg27DY fpmWJ5IE6LDHK86SGKp6UO8GF2Zni/kKF8Nkc5zUJE5x2MgidfN7PDj98bh80Nf8Oz/3U2M8LleSZ VBW2wb1P8SnNiA==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pbH63-0004kN-AL; Sun, 12 Mar 2023 04:30:32 -0400 Date: Sun, 12 Mar 2023 10:30:14 +0200 Message-Id: <83ilf6v0bt.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Daniel =?UTF-8?Q?Mart=C3=ADn?= on Sat, 11 Mar 2023 15:27:54 +0100) References: <837cvny97h.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit 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 (---) > From: Daniel Martín > Cc: 61877@debbugs.gnu.org > Date: Sat, 11 Mar 2023 15:27:54 +0100 > > Eli Zaretskii writes: > > > > > Thanks. This no longer applies to the current master, so please > > resubmit, and I will install. > > > > Thanks, I've rebased the patch. > > >> The NEWS entry explains how users could show this information in their > >> *Help* buffers, if they want. > > > > Maybe this part should be also in the user manual? > > I've added some information to the user manual. I see we don't document > help-fns-describe-function-functions in the user manual at all, should > we do it? Customizing what is displayed in describe-function buffers > may be something that users want to do. But perhaps we need to make the > hook part of the Customize interface first, I don't know. I added an index entry for help-fns-describe-function-functions in the ELisp manual; I think this is enough for now. Now installed on master. Btw, something seems amiss: "C-h f" for string-fill, which has 2 examples in shortdoc, still says "Example:", not "Examples:", as I'd expect. Can you take a look? From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 12 Mar 2023 12:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167862576219726 (code B ref 61877); Sun, 12 Mar 2023 12:57:02 +0000 Received: (at 61877) by debbugs.gnu.org; 12 Mar 2023 12:56:02 +0000 Received: from localhost ([127.0.0.1]:59389 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbLF3-00057z-Jw for submit@debbugs.gnu.org; Sun, 12 Mar 2023 08:56:02 -0400 Received: from sonic313-20.consmr.mail.ir2.yahoo.com ([77.238.179.187]:38284) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbLF0-00057l-Ux for 61877@debbugs.gnu.org; Sun, 12 Mar 2023 08:55:59 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1678625752; bh=rBWp1dJIZJtuC93bOdzefVpWQi0WPj4KoY945JPxBRc=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From:Subject:Reply-To; b=VKyz3iH95khFLsMHdhfQ0NRDradPWcyTGvOKEC0tR4XXDzqnjPYMxs42ToEMSOdVu4n/glJ0GhhLs4iWj75iZ7pQWMmN58axM5JJtUEfcwjlJ6u+JWztpQB1qni+7IS83AVbccbEBYye4o6lvSZvQ1WpLyYzwD75OAMQWqKCAOFZQ3Nh5lIPihBWLSmKIb/0ebYesjRbcTGPA+iYHZH/Z0hnTRuhPmf12LcEGZC+36XMB3tP/lioWGvQZ3VI2GSF1470mI6ksNWAZzGojss1Kdp8Rcw5pd/PcD5JTzBAID+t7b9ymPdPEqZEcpKDeGe8fjwVBveYdXIjJyG8pWKVOg== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1678625752; bh=4hDy4XesPzmozqtU+UdFdpvoaSxSIx3cc3FekOIllg6=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=RMlK3kH6GgTr452B/RBw9OSTeJBuRclksI/7b3Ut7FFD5CRbsqXH6JnMEY62KX3lfGi2DbaG3CAtjnFg7h2mPf0/GPwKPZ2dJxBFZ8bOYLg/8Lzc0uN8OvoWJc4BMKoy05Yj1u2IyendR06BDiB4R2ZWTTGtd3hJbRHzW8CTq+/1nYn+mqMNM/VW/spVbpUZ0E2EGwE1HbzlDmDq1IzYMcE8S+nyZ4OzKuXR+wmL1fsI69euREsdQykSHvbrSWMhisXTET7JMEgBL0N7uBbcoMwQjCqXlYBU+k3YWtiNvbJydgZMHau88QdPrdu9aCKm/y1Jt3TB6uK3ikZQYkyP3A== X-YMail-OSG: lCSYrecVM1m_BPC3CvUoYzN0UJNLgtqDRaR4JWzGu3GLaaKaQUvR.u9e8UBsLFc nxNlZzPff2epMZFwu9bkrK4EgtpUhfx8XjPL_AgEVAiZKlTe5pjVrcbcIVucui54FaIDgGdpu9jZ Jm_tE2dJBgMdud7luQgWQDj3s7wJDB8veB848S4HKjanokR2gN2QEszbwVtL3LdJFUpUIyIAqu0p 6QgOlvWi9Ylt_jzmLyPt4kF468zRUxkpahkgrXB77BWM7ihxqCdLotXh5Xo6qqB..mDNmUiIPrsy 1KEHnQfl4ahUZZpbYDEheDnnih4HqO7ovXccwn_RBY.iUq_oIG4gdUsvEJHJD36C.TaJQaNj1TVV nPKkDsMnavSaBgvEaSYgFpYRMVATdpH9Q9Dj8DSoCTZk2bbvtAUkoxIKc76sxbUOQX4IP.PI3wjD JuwEsWaJ0TFCPyNiB0QeVgGuRCkP3etkqoHsEgIGGo2p4gi4eoel4YLpfOqQiWuObG_xA_lHQPRQ dcLUsJnbrwsv_1VCZ5MY0WRTCQxZH1rpiQFgUM9ShO_8EfcAHrR7jliqYravoymKKO.xiLvzOhvq oGJ9F9p6SlqMwH6_RPAc2YuxRkvr3Rdt3kV8gQ3K2o85dJofA8cNW6QszGtCRMAbZm7LzC4Rpi8o elHfwaBihPUf38cQ3UIKMJSQaw8i8_wPyvHGzcyTBfW.SDGXUvMIlNwJa_qINP8FtROVqO0pkKX3 RegoSsJaqo0lPlAjkzcDcDxgWVYLN22AaD04f3fuqU50IMlD23tKlEqv152hGNICZSxpQs4N4bv0 I4cllJ6LsVh_53QQO554ZG_61RePNcCg_gtLgSAKN8nWdeKm5LVX0N5fGYVd2PV2Mniy0bhQ5HFW evWPhQYeJv16i9eh3FYl9_LTWC6Mu_gw0eQDoe43zZIxqEa2EeV4OVYiA0SjtN_t1KTtORoXOC6l 7C4MZUuEIPJSGskYtD2jvEYABCA605pT1eZaf0DF4kx.AC4pbV5ETYdNp05woutdwx.mr1.BTQC. 0F36gUe4Hy8m4Gj5kDkNwx5Yake9cSCQWloDJ2NdX2hXYtpF1XyglnxmVpaiIDEVRDUKYPZz0Twe H8cOnQr4AmMd_yPvOcIDbAvBLVFRKjrJ_r3QV6RuXioLXntB2XKyNlpFhuk.7LdQR6P5c1Fq_rgW sZ57o4K5jqNPTk8aQ8FvSbbYC9sNckTTtKOipXSk45YaxtMVZ9PmI6nmNlw95q6NRvZI1m7BUUQv i8yrbQvGY10H3S6f4DUdgtrvUHfp1Ep8M3ghNG1CIWxR5zubSfBbhVw1CdMAZCNUXFzw4MFNTs0S cGSUvpxh7imBP2vT6Jm33bft58K1LKYeWsbbg.GwG8EOePef96qWo775vzRXkNngig0onGBczOgA MpXcIITFIK7BuFW_KiH77jbe8J6CKGuNE6_Fu6AkV_ZBf4jWCjhq2ZhADAds2N9IxibUNEkmb9Gl npKyr8V9J_mDoSqfI_Cp.VMh6s73vDER5SRWVWPs0BhhN_qje.SXLWfUDoDSSiz9VExGmAJyBupV NyGYxLLxyis1ijz3KQDMWVbUu0G9L1TEkBOfOksyYF8qF4C2J0r4DrnP2_LNphsv3MPF4rOTFPcq ._jbWsfVK8PbaYLZ.qn9UvXTu_gSyv7UP4rtgddSOOOt6MVxTPauVlka0zOXiGulFInfqRONtYSA 5Jejsq0OLpVNld1qiYTkG9On7g8zE5uDHVveX2J2jypdVn0qVldDJv8ZLHr1x.XejC8sQjMYsMFh c1Ud.Vp5.fwnBsPSnChkZwgOawB0.OJDkIYfnjt__6CbVht4njHTlIT5bnvrVRxgFehQUq6w0bdi SoN8QD2FuJOxEe._0UZ6Ho9zM3ApJF5rhS4mi3CGO9lcEDNqAylJg266SDRZiaupiyn1uLLi44MR jtZFGi7p4_R3zg18sUVb6u6XPneNFptapBcdUOXX0u0cBKtHWNJ_IAes_p0XYxqTGYu34KaT1a9U Ha_9H4OviwEtoyNYM9kyFagPadSdIqddsBbVmnlpNcAY2JfpabUwfkDLdoKOjNTH7t8VMbc1IeA6 HRDk2oq.dPprQEJCJoUQVcUujO_ahwQn7kvPfNwhbKdq696JB9nm0ReARqxlEBYvSCtDBMn6qutk I0HPVUr_FQjK9kdm5qwumZei_48giN4xhcOKj44FJNZqk7Xb4NF0PVUPLklb9RYs_6FzYD5lvCgq o5o4gwM8mk7l7CVEG6cGBuxdtXsKlQCvafIx7ApDIJNaWm2U- X-Sonic-MF: Received: from sonic.gate.mail.ne1.yahoo.com by sonic313.consmr.mail.ir2.yahoo.com with HTTP; Sun, 12 Mar 2023 12:55:52 +0000 Received: by hermes--production-ir2-5b7d458747-pvwxd (Yahoo Inc. Hermes SMTP Server) with ESMTPA ID e2d21915ac154ded0699a3d89776323f; Sun, 12 Mar 2023 12:55:50 +0000 (UTC) From: Daniel =?UTF-8?Q?Mart=C3=ADn?= References: <837cvny97h.fsf@gnu.org> <83ilf6v0bt.fsf@gnu.org> Date: Sun, 12 Mar 2023 13:55:49 +0100 In-Reply-To: <83ilf6v0bt.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 12 Mar 2023 10:30:14 +0200") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (darwin) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Mailer: WebService/1.1.21284 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 5431 X-Spam-Score: 0.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: -0.7 (/) --=-=-= Content-Type: text/plain Eli Zaretskii writes: > Btw, something seems amiss: "C-h f" for string-fill, which has 2 > examples in shortdoc, still says "Example:", not "Examples:", as I'd > expect. Can you take a look? That is because some functions have more than one example per group (for example, string-lessp is documented in the "comparison" and "string" groups), but the "s" is added when a function is documented in _more than one group_. I think a more accurate logic to add the "s" is to count the number of "arrow characters" that separate the form from the example. Could you give a try to the attached patch, and install it for me if all works correctly? Thanks. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-Fix-pluralization-in-shortdoc-help-fns-examples-func.patch Content-Transfer-Encoding: quoted-printable >From c3ca21707f38f1bc82939fc05e381dfc1131026d Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Daniel=3D20Mart=3DC3=3DADn?=3D Date: Sun, 12 Mar 2023 13:38:34 +0100 Subject: [PATCH] Fix pluralization in shortdoc-help-fns-examples-function * lisp/emacs-lisp/shortdoc.el (shortdoc-help-fns-examples-function): Implement a better logic to pluralize "Example", by counting the number of arrow characters in the example string. (Bug#61877) * test/lisp/emacs-lisp/shortdoc-tests.el (shortdoc-help-fns-examples-function-test): Add a test. --- lisp/emacs-lisp/shortdoc.el | 35 ++++++++++++++++++++++---- test/lisp/emacs-lisp/shortdoc-tests.el | 15 +++++++++++ 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index 6e3ebc7c6a2..9a6f5dd12ce 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1621,13 +1621,38 @@ shortdoc-help-fns-examples-function You can add this function to the `help-fns-describe-function-functions' hook to show examples of using FUNCTION in *Help* buffers produced by \\[describe-function]." - (let ((examples (shortdoc-function-examples function)) - (times 0)) + (let* ((examples (shortdoc-function-examples function)) + (num-examples (length examples)) + (times 0)) (dolist (example examples) (when (zerop times) - (if (eq (length examples) 1) - (insert "\n Example:\n\n") - (insert "\n Examples:\n\n"))) + (if (> num-examples 1) + (insert "\n Examples:\n\n") + ;; Some functions have more than one example per group. + ;; Count the number of arrows to know if we need to + ;; pluralize "Example". + (let* ((text (cdr example)) + (count 0) + (pos 0) + (end (length text)) + (double-arrow (if (char-displayable-p ?=E2=87=92) + " =E2=87=92" + " =3D>")) + (double-arrow-example (if (char-displayable-p ?=E2=87=92) + " e.g. =E2=87=92" + " e.g. =3D>")) + (single-arrow (if (char-displayable-p ?=E2=86=92) + " =E2=86=92" + " ->"))) + (while (and (< pos end) + (or (string-match double-arrow text pos) + (string-match double-arrow-example text pos) + (string-match single-arrow text pos))) + (setq count (1+ count) + pos (match-end 0))) + (if (> count 1) + (insert "\n Examples:\n\n") + (insert "\n Example:\n\n"))))) (setq times (1+ times)) (insert " ") (insert (cdr example)) diff --git a/test/lisp/emacs-lisp/shortdoc-tests.el b/test/lisp/emacs-lisp/= shortdoc-tests.el index a65a4a5ddc3..d2dfbc66864 100644 --- a/test/lisp/emacs-lisp/shortdoc-tests.el +++ b/test/lisp/emacs-lisp/shortdoc-tests.el @@ -75,6 +75,21 @@ shortdoc-function-examples-test (should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n = =3D> 0")) (shortdoc-function-examples 'string-match-p)))) =20 +(ert-deftest shortdoc-help-fns-examples-function-test () + "Test that `shortdoc-help-fns-examples-function' correctly prints ELisp = function examples." + (with-temp-buffer + (shortdoc-help-fns-examples-function 'string-fill) + (should (equal "\n Examples:\n\n (string-fill \"Three short words\" = 12)\n =3D> \"Three short\\nwords\"\n (string-fill \"Long-word\" 3)\n = =3D> \"Long-word\"\n\n" + (buffer-substring-no-properties (point-min) (point-max)= ))) + (erase-buffer) + (shortdoc-help-fns-examples-function 'assq) + (should (equal "\n Examples:\n\n (assq 'foo '((foo . bar) (zot . baz= )))\n =3D> (foo . bar)\n\n (assq 'b '((a . 1) (b . 2)))\n =3D> (b . = 2)\n\n" + (buffer-substring-no-properties (point-min) (point-max)= ))) + (erase-buffer) + (shortdoc-help-fns-examples-function 'string-trim) + (should (equal "\n Example:\n\n (string-trim \" foo \")\n =3D> \"= foo\"\n\n" + (buffer-substring-no-properties (point-min) (point-max)= ))))) + (provide 'shortdoc-tests) =20 ;;; shortdoc-tests.el ends here --=20 2.34.1 --=-=-=-- From unknown Sat Aug 09 21:22:16 2025 X-Loop: help-debbugs@gnu.org Subject: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 12 Mar 2023 13:26:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61877 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Daniel =?UTF-8?Q?Mart=C3=ADn?= Cc: 61877@debbugs.gnu.org Received: via spool by 61877-submit@debbugs.gnu.org id=B61877.167862754822552 (code B ref 61877); Sun, 12 Mar 2023 13:26:02 +0000 Received: (at 61877) by debbugs.gnu.org; 12 Mar 2023 13:25:48 +0000 Received: from localhost ([127.0.0.1]:59411 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbLhr-0005rg-Vr for submit@debbugs.gnu.org; Sun, 12 Mar 2023 09:25:48 -0400 Received: from eggs.gnu.org ([209.51.188.92]:50834) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pbLhp-0005rN-I3 for 61877@debbugs.gnu.org; Sun, 12 Mar 2023 09:25:46 -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 1pbLhk-0007cj-19; Sun, 12 Mar 2023 09:25:40 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=+Z5Wot4ooRcaj9RpkQ7BKt7pnXw9CMpG3ffOFUAhp+o=; b=gY/CU4Qqt4iM+3G+CrRF zZg63l0Ve1d7ZZbBj+GLCQ1xesUgbAy8CDLp4iwkWr1zyphi6JeVXY2+NGimMzRhq6WEz7nL7jafj xVNd3qX+pvY5QHlPYPIXx0d886lNs3PV3xbfsUB+hKfQgoBxMIq6Fqv/vDv7rdRraGRm7/uQK2jpE hHW12x6IndZiWU37OiQ8OkReI8qTwwz38+pGDxsMW56vdCdczlUJsSo5hnktD1oI4JPq4FjAjRt3I Ysi3McPjnYUM2hTwSNMN1XFMiniVeagwXgGsIvHMuzNHZtR7ujQ0mc2cvo0UbN6fmlacrQsjwh8G4 6iaOR9zKHjzZ/w==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pbLhj-0004e3-9t; Sun, 12 Mar 2023 09:25:39 -0400 Date: Sun, 12 Mar 2023 15:25:26 +0200 Message-Id: <834jqqumnt.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Daniel =?UTF-8?Q?Mart=C3=ADn?= on Sun, 12 Mar 2023 13:55:49 +0100) References: <837cvny97h.fsf@gnu.org> <83ilf6v0bt.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit 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 (---) > From: Daniel Martín > Cc: 61877@debbugs.gnu.org > Date: Sun, 12 Mar 2023 13:55:49 +0100 > > > Btw, something seems amiss: "C-h f" for string-fill, which has 2 > > examples in shortdoc, still says "Example:", not "Examples:", as I'd > > expect. Can you take a look? > > That is because some functions have more than one example per group (for > example, string-lessp is documented in the "comparison" and "string" > groups), but the "s" is added when a function is documented in _more > than one group_. > > I think a more accurate logic to add the "s" is to count the number of > "arrow characters" that separate the form from the example. > > Could you give a try to the attached patch, and install it for me if all > works correctly? Thanks. It works here; I installed it. Thanks. From unknown Sat Aug 09 21:22:16 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: Daniel =?UTF-8?Q?Mart=C3=ADn?= Subject: bug#61877: closed (Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information) Message-ID: References: X-Gnu-PR-Message: they-closed 61877 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: patch Reply-To: 61877@debbugs.gnu.org Date: Wed, 06 Sep 2023 00:04:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1693958642-32737-1" This is a multi-part message in MIME format... ------------=_1693958642-32737-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #61877: [PATCH] Extract Lisp function examples from shortdoc information 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 61877@debbugs.gnu.org. --=20 61877: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D61877 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1693958642-32737-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 61877-done) by debbugs.gnu.org; 6 Sep 2023 00:03:49 +0000 Received: from localhost ([127.0.0.1]:59955 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qdg1N-0008Vc-Bb for submit@debbugs.gnu.org; Tue, 05 Sep 2023 20:03:49 -0400 Received: from mail-lf1-x12c.google.com ([2a00:1450:4864:20::12c]:56466) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qdg1L-0008VL-5U for 61877-done@debbugs.gnu.org; Tue, 05 Sep 2023 20:03:47 -0400 Received: by mail-lf1-x12c.google.com with SMTP id 2adb3069b0e04-500a8b2b73eso4869197e87.0 for <61877-done@debbugs.gnu.org>; Tue, 05 Sep 2023 17:03:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1693958620; x=1694563420; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=L65p/GSaPYL8+IUDjULcq4qVZFYV6rErIMs6+HsYU7s=; b=mXX1qmHyceQUwbKkFU4OqePbZzMYHt8mROwtxmthqr2+rJtFcUpQx1tUdKPE6UICLX O4gFRolfXbyc7RA6tpNYYn89tJwRLOjuijtolFxPmAUGVgS11KUN508YDNfuLU/Ve2K5 iA1girrE9YgaEo8nvdb7vZZkvkWZ60NSVfHs25ItK7JivkN0YJXggelFHNIcVGMwdxr6 7xVzoJZUOYXLHTSM/tmKjs5+1UEQ81DNWCxzUa9Np5dBMHE15fzCq9rXqSKQR3rB1MWI iZPpajzA7MnQWNw3LrG0RDb4aG+6qBrC7wB1YaDcbV0SVl1rPSoYrn3mE0hLZBZR/FZd yr3g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693958620; x=1694563420; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=L65p/GSaPYL8+IUDjULcq4qVZFYV6rErIMs6+HsYU7s=; b=dwGaHDaNenBbIxqDQASKMN6VusIBU8VFiQRQOPkPE+uYdS349Q3ObD4+oV9huXy0F9 GfponjnRB3PgqyhFxLx+TSGxVpkcsDhF/g2m0KwvhzVwC+Zb57TrVLCnf4hcSmPemhnu dPgiVd4QCBJD/DEudmOQb8fBBO8gf8ZouGykYKz7IrZupfErowthlqxnlXNILYMeiyPK grWdCgRyVFpZ6fgNyjkFjbPogifVHEs9I2iLElTS85JUnFzU1gBfbXbMKSvdqjUs8bfp eO+iHIbfCdGRpJSw/p8et7XPDwZD4P4j5C8Mvxlh3i5li5Tp2HYyO9/zgDy5eIO3jzWi ei8A== X-Gm-Message-State: AOJu0YwWy0EaR2GVrSF1Cv0ddtmpUzwlBPppr80XYERLEIIjY5/6A/ly 2o8vL6mUthp6DNtkN0YbtamAu4s9dRgFkqpAQ0itf9h0/Lg= X-Google-Smtp-Source: AGHT+IFwgag/POqnTkOKlVgKvlWAyl/r20AmZQN6mwaJ1o3PJ8WcV1rIUXASmRQ4C35BYYg6VL97kuhmwlYImHxTu/U= X-Received: by 2002:a05:6512:2820:b0:4ff:9efd:8a9e with SMTP id cf32-20020a056512282000b004ff9efd8a9emr1137422lfb.7.1693958620297; Tue, 05 Sep 2023 17:03:40 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Tue, 5 Sep 2023 17:03:39 -0700 From: Stefan Kangas In-Reply-To: <834jqqumnt.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 12 Mar 2023 15:25:26 +0200") References: <837cvny97h.fsf@gnu.org> <83ilf6v0bt.fsf@gnu.org> <834jqqumnt.fsf@gnu.org> MIME-Version: 1.0 Date: Tue, 5 Sep 2023 17:03:39 -0700 Message-ID: Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information To: Eli Zaretskii Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 61877-done Cc: 61877-done@debbugs.gnu.org, =?UTF-8?Q?Daniel_Mart=C3=ADn?= 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 (-) Eli Zaretskii writes: >> Could you give a try to the attached patch, and install it for me if all >> works correctly? Thanks. > > It works here; I installed it. I'm therefore closing this bug report. ------------=_1693958642-32737-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 28 Feb 2023 22:36:23 +0000 Received: from localhost ([127.0.0.1]:52148 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pX8a6-0006PP-Cu for submit@debbugs.gnu.org; Tue, 28 Feb 2023 17:36:22 -0500 Received: from lists.gnu.org ([209.51.188.17]:60192) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pX8a4-0006PG-Ll for submit@debbugs.gnu.org; Tue, 28 Feb 2023 17:36:21 -0500 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 1pX8a3-0008Cp-S7 for bug-gnu-emacs@gnu.org; Tue, 28 Feb 2023 17:36:20 -0500 Received: from sonic304-23.consmr.mail.ir2.yahoo.com ([77.238.179.148]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pX8a1-00042z-BI for bug-gnu-emacs@gnu.org; Tue, 28 Feb 2023 17:36:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1677623773; bh=GiWK+KAmdUS4pKHIyBO9MYVmZRjSAoyObd3RWrTcf7A=; h=From:To:Subject:Date:References:From:Subject:Reply-To; b=WHeq8CVhbl0SMTJu0s8Sn1FGJNuYl0W7ZlzoZG7edHZj0VaE5XZf5RRhXOR2ktcWMOnDTc41djiTkIfd5jxBzaucxszDhqFq+9cbJTM/pYB+dMZvjOGigIQcpqxEVVV8sZKmrKPGV1DQ/aUhvSCRkU3Xvj5EEbSafuPbP3pYalqS4eKMRSJaGk9oGzrtp2vvTamoFPCB7vP2YW7ipdi3Ffq+ENaBw4V6sobDDrayTRSdyfEGs8j87kEulSLsNyOH/k6bFKu4ruNic7tVSGoZNOab0PoccpjYAskOCQzIXi8IiQpSjHSAj7863afkuc719OGRZTu0YvT156Qli3n26A== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1677623773; bh=JHQzPnDg2WbMRT03mWZFtqoUgSdMi/ly8M8HRQ1Itgs=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=OsT89z4oWdwf1R2T+5zfdBWPB8mHmGzZ2/0WfVlDFznt7b15PxMuxP31pHKkwlwxIGg2YybvrUA6GJWW1QJUxLZ5LrNrR7yXc5OGUb6R9a4V1kAXKhD+ql6L+t0MBvUcRYuwoc9m8z4c3FsxGYES5ghjSpRcmBopyrpmtxYzrL8PvWekFHsoTzu5S2cBnrdJuUCGpd71DTLH2iZ+het86kwClobSLDE5WbXg2hjAW9jDxsdn6GT0VrJEb6kfyE169sqibu3NP4UxSmHDb9gmnlpHzBS01VCe9A11tGCGceIeMC69oCHoafiQ9zdw9YZombuyj3eVT4Tjsv3KAKhnhA== X-YMail-OSG: eUVJp4IVM1kl3PLWsjYlKVRkdxFYBKe4yaWZhYgqneyGj6H2ifykaNczuo1OHvp uoOZCIzyGAblr5bXswUe0uyiiiBG.HXxyXjIMQUb6W2degU20o6.xhjGflsOsM_3EvMznmnS9S_3 np4yn0pS6dTSQGe2C_99iVDT7yHhgFtgPXKViW6j.4fUfl9HRnqhSRGj9Ab_6S79_zxNyxP6WSNg 6I__Es1baly07V6U9O4XxwKYBjUm.WQjxE0AHc8lQ_Z0EmEIEUA3SKR1yaTi5rX8qX4_RsP9Vi_6 9.7TsP8p_mlRDT4d0LKHQjb2FfyAOWwNw7HyOCZESoeviBD6F1if21HjZaHHLSdIoGxH1HhKewvS V7LIRAMNETHDpommvb5KsHktw8w._fJrhcw31IWk0qS.X_3vUc09A5J1dq6k3XgKnw1..lBNztwZ WyWNAKWsfCY3.RvdVSppu2hJbgUTSKdgXI5c1kuZCTzUTi3VPxHxh6Xhdwgt9LtVkQ_9.UkiuAtp J_EtaPzhaovg.XhHmYn1beiqf5OtEva6389ROxiivE30CYEI4foSNgAimyzz1YY.3KVTzis7JYhJ QDmauSNxylTEYxexqGkstiXdvAVRxJqW6Au2YIQ61r1wg.GgZbmeGTsRNxCr9SsAWgDSDwdZPgrJ Ru8QLUYphWhvxzIY2fgrRm99AIlfm_382nse7vkMZwJSmnt47LnA3VTAv_1kQ7wsacsPevVp3f2P S.j0JCIOOes05wm504bPz6KNc5R.3WEe1itRU3MVga_5_9HEvorgoydQXXbl.yeZXTv2yzyU71ts cB4SqMnXI9Xyu8Ga2uLgmBd7RSTr2qYq.3r7b8e.x_Cujltye_wBjbuTs2zH48.7Kfw0ZbixGWlJ q8rLvLlQMKYevM3IT559k4etAiRjf3RefUnUnZK8fKtWGLmwjYvKpRH.JCGaW49TFbuuf9.4YC9i 2_iKkaqxaIQmvwNLTxqYboKRXEjw3GUNB80xDr2zINgwj7lo_14zANrNIqTLqYAXJ83E8mHMrYUH CJg3MdThP9frrTf46LDpbxnKR2XQLroHzS81jVrVrRLTo8Z73ZSuaPZBgFeKONmIOU1TizXW3QKx 66DcADc2tPLXGrlsRNLEgwcMklZRx.W3PFmYKQyVr0DKzcAsw2im41EGvUtB.t6NZUmfdrrGAoRM yQP5EnNqGS9HKuPF5EY_UYIec_Zd9PnjBeJUhgdq8abEIMpNvB0dkVLZvDOKikfqDj8bjeQiTfPb M50bGelmRtCJmza3UxGC8mIZ9bb37ZjR6dzwiPBHHxA1fHflIP7AcItp1nenou1pK5Lb6gM61U8h 6hntMRc2Yb5kTKLMn7YAjV_eIw5x3BrzFu71VBWY7Bk5qMS3CumaZj3D_.nmK5Lt7k1fGGgDqL3T vBp0Sezf9Hwyjc.PdEmbfYZtdRnbiMFnu3DLCTYGjU6lsuHK5QQJNCTP9XTlnpDs5JliuwkBgmrp x_TLu2VDF9JBa6U7LU1wgtUz2XROSk9bQcDokVor7V8IZ3vBzmw7pheQWq8IJBOXbI7FDbSUBfk9 b1SME5A_.F2aXT2km3z.N21noOY0QmucxoPZjy.6fJSEN8mo3vJRNFCRHdvMIABCI4BSkNZjY4VF tMerrNVF3K4xn_wGw_ytIOsRZaIs5vMfZE5tkAoILJKvYTOTNUJ6wO6okYJe.N0RWJWZ0det19Id siqPQ1rqLZNEH3uBiZmtziPulQbR.uBY0tleZ3dafcs0JH7h7VpTxhLK9RRMfx3PIbLfKrznWMnB sI4tfy9RlyFyc9O.GRgb.dco9ILAGHvLZsYX1smgmvXb5Ggqp2eg13Um35_V7sf1DV_1_GTyb44K Iw8o_0BOL6SY8jz0mh_KyzqT0RZpua5azdslkSUCPAIo3AnXeIjdm_USvGj0kMzAqJ5CkyXmP4Ja vk9MiFsRU250Ytkw7mqSQkuY87K.o.MK4Y0cJPRdelTITTSSIC26dWvD_EwW.dks32sDpdGhFwao W8fG4EKywtBzo.H2RIQGDvaL75k29Uq48hbg2WJaQLV226nKSjS8kklamssPHGNefxv.q47OKp7P JW_aJjj150w3afRFyT4X8bXFqdPwRjHgICU.qLMUc2HrrYiSJpxGFisP5R5iKF3JZCOSvDPPJApl At_B1pEdbKy6ZqeSlQyuYRP1AJF0Se_9niYFHBxj_omKHg4Uu9nl7R11Cl8.ZW.kDG1FH7PpahkE pfs71Qtlcuw2uAc9BoWMjNn8XLd_Q X-Sonic-MF: Received: from sonic.gate.mail.ne1.yahoo.com by sonic304.consmr.mail.ir2.yahoo.com with HTTP; Tue, 28 Feb 2023 22:36:13 +0000 Received: by hermes--production-ir2-65c64dfd66-8r58z (Yahoo Inc. Hermes SMTP Server) with ESMTPA ID 70ddf924b09e7907d71425080886081a; Tue, 28 Feb 2023 22:36:10 +0000 (UTC) From: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: bug-gnu-emacs@gnu.org Subject: [PATCH] Extract Lisp function examples from shortdoc information Date: Tue, 28 Feb 2023 23:36:09 +0100 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" References: X-Mailer: WebService/1.1.21221 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 7435 Received-SPF: pass client-ip=77.238.179.148; envelope-from=mardani29@yahoo.es; helo=sonic304-23.consmr.mail.ir2.yahoo.com 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.4 (-) 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: -2.4 (--) --=-=-= Content-Type: text/plain Shortdoc contains a lot of useful examples about how to use common ELisp functions. This patch explores a new Emacs feature where those examples are identified and extracted so they can be displayed, perhaps, in *Help* buffers (via an additional help-fns-describe-function-functions hook). After you install the attached patch, take a look at the *Help* buffer produced by C-h f assq RET, or C-h f match-string RET, etc. What do you think of having this new Lisp feature in Emacs 30? I can send later another patch with tests, relevant NEWS entries and documentation changes. Thanks. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-Extract-Lisp-function-examples-from-shortdoc-informa.patch Content-Transfer-Encoding: quoted-printable >From da859693ba9fafd0ba43107bc99dba5464ac3ab6 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Daniel=3D20Mart=3DC3=3DADn?=3D Date: Tue, 28 Feb 2023 23:15:40 +0100 Subject: [PATCH] Extract Lisp function examples from shortdoc information * lisp/emacs-lisp/shortdoc.el (shortdoc--display-function): Add a new shortdoc-example text property so that ELisp examples can be searched for later. (shortdoc--insert-group-in-buffer): New function extracted from the buffer insertion code in shortdoc-display-group. (shortdoc-display-group): Implement in terms of shortdoc--insert-group-in-buffer. * lisp/help-fns.el (help-fns--shortdoc-example): Add a new help-fns-describe-function-functions hook that displays example code for functions documented in shortdoc groups. --- lisp/emacs-lisp/shortdoc.el | 80 ++++++++++++++++++++----------------- lisp/help-fns.el | 28 +++++++++++++ 2 files changed, 72 insertions(+), 36 deletions(-) diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index c49960c2ee6..4e19cd04c9e 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1443,45 +1443,51 @@ shortdoc-display-group (setq group (intern group))) (unless (assq group shortdoc--groups) (error "No such documentation group %s" group)) - (funcall (if same-window - #'pop-to-buffer-same-window - #'pop-to-buffer) - (format "*Shortdoc %s*" group)) - (let ((inhibit-read-only t) - (prev nil)) - (erase-buffer) - (shortdoc-mode) - (button-mode) - (mapc - (lambda (data) - (cond - ((stringp data) - (setq prev nil) - (unless (bobp) - (insert "\n")) - (insert (propertize - (substitute-command-keys data) - 'face 'shortdoc-heading - 'shortdoc-section t - 'outline-level 1)) - (insert (propertize - "\n\n" - 'face 'shortdoc-heading - 'shortdoc-section t))) - ;; There may be functions not yet defined in the data. - ((fboundp (car data)) - (when prev - (insert (make-separator-line) - ;; This helps with hidden outlines (bug#53981) - (propertize "\n" 'face '(:height 0)))) - (setq prev t) - (shortdoc--display-function data)))) - (cdr (assq group shortdoc--groups)))) + (let ((buf (get-buffer-create (format "*Shortdoc %s*" group)))) + (shortdoc--insert-group-in-buffer group buf) + (funcall (if same-window + #'pop-to-buffer-same-window + #'pop-to-buffer) + buf)) (goto-char (point-min)) (when function (text-property-search-forward 'shortdoc-function function t) (beginning-of-line))) =20 +(defun shortdoc--insert-group-in-buffer (group &optional buf) + "Insert a short documentation summary for functions in GROUP in buffer B= UF." + (with-current-buffer (or buf (current-buffer)) + (let ((inhibit-read-only t) + (prev nil)) + (erase-buffer) + (shortdoc-mode) + (button-mode) + (mapc + (lambda (data) + (cond + ((stringp data) + (setq prev nil) + (unless (bobp) + (insert "\n")) + (insert (propertize + (substitute-command-keys data) + 'face 'shortdoc-heading + 'shortdoc-section t + 'outline-level 1)) + (insert (propertize + "\n\n" + 'face 'shortdoc-heading + 'shortdoc-section t))) + ;; There may be functions not yet defined in the data. + ((fboundp (car data)) + (when prev + (insert (make-separator-line) + ;; This helps with hidden outlines (bug#53981) + (propertize "\n" 'face '(:height 0)))) + (setq prev t) + (shortdoc--display-function data)))) + (cdr (assq group shortdoc--groups)))))) + ;;;###autoload (defalias 'shortdoc #'shortdoc-display-group) =20 @@ -1521,7 +1527,8 @@ shortdoc--display-function "=3D>")) (single-arrow (if (char-displayable-p ?=E2=86=92) "=E2=86=92" - "->"))) + "->")) + (start-example (point))) (cl-loop for (type value) on data by #'cddr do (cl-case type @@ -1572,7 +1579,8 @@ shortdoc--display-function (:eg-result-string (insert " e.g. " double-arrow " ") (princ value (current-buffer)) - (insert "\n"))))) + (insert "\n")))) + (add-text-properties start-example (point) `(shortdoc-example ,funct= ion))) ;; Insert the arglist after doing the evals, in case that's pulled ;; in the function definition. (save-excursion diff --git a/lisp/help-fns.el b/lisp/help-fns.el index 50e60b68e17..843de957a5f 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -954,6 +954,34 @@ help-fns--mention-shortdoc-groups (fill-region-as-paragraph (point-min) (point-max)) (goto-char (point-max)))))) =20 +(add-hook 'help-fns-describe-function-functions + #'help-fns--shortdoc-example) +(defun help-fns--shortdoc-example (object) + (require 'shortdoc) + (when-let ((groups (and (symbolp object) + (shortdoc-function-groups object))) + (times 0)) + (mapc + (lambda (group) + (let ((buf (current-buffer))) + (with-temp-buffer + (shortdoc--insert-group-in-buffer group) + (goto-char (point-min)) + (setq match (text-property-search-forward + 'shortdoc-example object t)) + (let ((temp-buffer (current-buffer))) + (with-current-buffer buf + (when (zerop times) + (if (eq (length groups) 1) + (insert " Example:\n\n") + (insert " Examples:\n\n"))) + (setq times (1+ times)) + (insert-buffer-substring temp-buffer + (prop-match-beginning match) + (prop-match-end match)) + (insert "\n")))))) + groups))) + (defun help-fns-short-filename (filename) (let* ((abbrev (abbreviate-file-name filename)) (short abbrev)) --=20 2.34.1 --=-=-=-- ------------=_1693958642-32737-1--