From debbugs-submit-bounces@debbugs.gnu.org Tue Feb 28 17:36:22 2023 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Mar 02 16:39:00 2023 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: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: 61877@debbugs.gnu.org Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information References: Date: Thu, 02 Mar 2023 22:38:42 +0100 In-Reply-To: ("Daniel =?utf-8?Q?Mart=C3=ADn=22'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-Debbugs-Envelope-To: 61877 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 debbugs-submit-bounces@debbugs.gnu.org Sat Mar 11 03:38:17 2023 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 To: Daniel =?utf-8?Q?Mart=C3=ADn?= In-Reply-To: (bug-gnu-emacs@gnu.org) Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information References: MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 61877 Cc: 61877@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: 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 debbugs-submit-bounces@debbugs.gnu.org Sat Mar 11 09:28:08 2023 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: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: Eli Zaretskii Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information 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-Debbugs-Envelope-To: 61877 Cc: 61877@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: -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 debbugs-submit-bounces@debbugs.gnu.org Sun Mar 12 04:30:40 2023 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 To: Daniel =?utf-8?Q?Mart=C3=ADn?= In-Reply-To: (message from Daniel =?utf-8?Q?Mart?= =?utf-8?Q?=C3=ADn?= on Sat, 11 Mar 2023 15:27:54 +0100) Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information 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-Debbugs-Envelope-To: 61877 Cc: 61877@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 (---) > 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 debbugs-submit-bounces@debbugs.gnu.org Sun Mar 12 08:56:02 2023 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: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: Eli Zaretskii Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information 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-Debbugs-Envelope-To: 61877 Cc: 61877@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: -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 debbugs-submit-bounces@debbugs.gnu.org Sun Mar 12 09:25:48 2023 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 To: Daniel =?utf-8?Q?Mart=C3=ADn?= In-Reply-To: (message from Daniel =?utf-8?Q?Mart?= =?utf-8?Q?=C3=ADn?= on Sun, 12 Mar 2023 13:55:49 +0100) Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc information 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-Debbugs-Envelope-To: 61877 Cc: 61877@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 (---) > 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 debbugs-submit-bounces@debbugs.gnu.org Tue Sep 05 20:03:49 2023 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. From unknown Sat Aug 09 21:22:27 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 04 Oct 2023 11:24:38 +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