From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Daniel =?UTF-8?Q?Mart=C3=ADn?= via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays Date: Sat, 29 May 2021 16:29:16 +0200 Message-ID: References: Reply-To: Daniel =?UTF-8?Q?Mart=C3=ADn?= Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24377"; mail-complaints-to="usenet@ciao.gmane.io" To: 48730@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat May 29 16:30:13 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lmzye-0006Af-LU for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 29 May 2021 16:30:12 +0200 Original-Received: from localhost ([::1]:49164 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lmzyd-0006mT-IR for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 29 May 2021 10:30:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51524) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lmzyV-0006mJ-Sy for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 10:30:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:45965) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lmzyU-0005Rk-0N for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 10:30:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lmzyT-000627-SQ for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 10:30:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Daniel =?UTF-8?Q?Mart=C3=ADn?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 29 May 2021 14:30:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 48730 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.162229857423126 (code B ref -1); Sat, 29 May 2021 14:30:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 29 May 2021 14:29:34 +0000 Original-Received: from localhost ([127.0.0.1]:57511 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lmzy2-00060w-F8 for submit@debbugs.gnu.org; Sat, 29 May 2021 10:29:34 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:36662) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lmzy0-00060o-T8 for submit@debbugs.gnu.org; Sat, 29 May 2021 10:29:33 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51438) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lmzy0-0006kC-8H for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 10:29:32 -0400 Original-Received: from sonic304-22.consmr.mail.ir2.yahoo.com ([77.238.179.147]:43236) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lmzxu-00057I-5U for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 10:29:32 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1622298562; bh=lUOrWJOMi9ezYMRwGHz4NocpOJqrhleiiaQEhiadTe8=; h=From:To:Subject:Date:References:From:Subject:Reply-To; b=bGVCyY7oRg3UdJThsQEAFKKsYiDIkkQ/L9XpI0g89q+asCQiORkifDy5HgnP/ZU4X/E3jiKFb2VWlYXkdBGdEWvI1+TjTvPDJ0ZrYzVrR9GoGWmknLsUISoo7LlBbHfSnP4TCxnwLvpPcvdSvRdkUwMiycPOPW16iGWxhUTDvHzypdd8Zzodm9n+fgl73GILKvbnMl8u8Fw1Oi7YQSI5Xal+EHlpU5FBXfcMMNs0zBOB5a6YzIz/mPpPzfQ9hsDnQE/LTBDstClsbXp+t7EW3BewTWE/Os+dJi54v9XzX/9LU8hGybxgyQfHR4m7PkyaYlocWcpeXDnHJnjcr2Uepw== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1622298562; bh=E3hdn/sHepbAiaXbhglwpcqtty/J5ZL8AFdnqZyel+L=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=Gsl1j8MCHC9jJWF9cPPwAleMelRfDSPCBtcONyJhu/gho6K4UGG1/cG9HGAfPBy/WOY10O7GGWITEMbuslRia06Q0AbAPSIdPvpPbHOW7JSToEgdXb1Tg40ufS6mavh/PkRi+cqbO6b7jkLMrxdtMOJZZdELl7zjy2/g+le40LUX/+cgysWcG2zzRG05vgT7dKr/TeOdjp3UBqTVSlQ76A3BD7PECCnY89tdxVOqfmKmb076CS5z9PhIkkdaV/KPu5wodlm73r5AHKA3iK95/Usp6DKHlfnndfAQc1b/7/4lNaDJKs+w9D1yyGEOKTDUdqorTMw8Qd2933ZONGJRTQ== X-YMail-OSG: qwcj1JIVM1nhGlIdqfr7MeDlIOcvHwTyT25FKif.XpX7W1L34phsUF7g0Hb4RQX .tNPdFARYUIb4qEQ8sTrfjJaUdIUq31rQ6BeMtxvboyGV9Ewz5BXAf60Syvy9VFNh8TwamVwVDvY Qar881pebqciwefQOxh1ToDyez1ITs0h4i1HgxSG.K4YSZVKVxjU_bCUaluYk3tH.EXmsMp24syb jKySIm_iWDZWWDsx4PCJxfXZa3jHFuwFT7sYzva.2tJQStRpuJhQ5VYxg7meQVnBYm9P0aaMcX4o ZclimV58psnUWk_A82enX.ZEKRXnnEyVMG7405xrr4aQVrmL0E5zaEqqRQfecVuzIkY_tIcSyi7. b1AMjoj2f6GhTBOOoZWmb0Gi9PzEpm1OsbTCQ29Mmu7TP9S49d.qxVN4Zqn0K9fvCviseQNNXeeE NG67Sgw1pGZBvM63MyzAOm8hTBopyn_qBPSEe_CFsP9vsZZzDe.fSLif4pCqI9urO92q0ET.k__d mNEMZ7gWnv5unHSTHjAaErD3mIyRbAAMR0x9wHRA7NP2JH.eCbQDTG6jJ9r2_WJi29KG_AbQiXH7 xbRoFTPuoMLdGOwp0GqDktHniLG.ffXmvybB_nUCHjqhGnjK26x.k57bXfZixIjZEY6x2N3vzw6b LItqZRGzi5bVsQsGktcoGeImJhgTXZAzhEBl5t5z4az8oLOD7wLX8fbUH9bEFnX3K3LFjPji3ZHo XdR1ErSWOr5TMeM_OrusbYDvEuXaGKHLe4CyIlz4IPqjGlUp6EOEYulbVKxM9JbcuR9yj6gz49ka qCqtGOuimAhudvDFzTA9Qu2_ZqE9StORgE309jC6nR X-Sonic-MF: Original-Received: from sonic.gate.mail.ne1.yahoo.com by sonic304.consmr.mail.ir2.yahoo.com with HTTP; Sat, 29 May 2021 14:29:22 +0000 Original-Received: by kubenode518.mail-prod1.omega.ir2.yahoo.com (VZM Hermes SMTP Server) with ESMTPA ID 6045477525aee3f4d8b26b7a2443588f; Sat, 29 May 2021 14:29:16 +0000 (UTC) X-Mailer: WebService/1.1.18368 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Received-SPF: pass client-ip=77.238.179.147; envelope-from=mardani29@yahoo.es; helo=sonic304-22.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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:207536 Archived-At: --=-=-= Content-Type: text/plain I've attached to this mail two improvements for the documentation groups feature that is new in GNU Emacs 28: - Fixed a typo in the manual and improved a bit some explanations and docstrings that were not very clear to me when I read them. - Added a new documentation group that describes what you can do with buffer overlays in Emacs (should we have a similar one for text properties?). Thanks, I hope you find them useful. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Improve-the-documentation-of-documentation-groups.patch >From 4a65d6df3539b6f23f94f3584b9e7fa46133fed0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= Date: Sat, 29 May 2021 13:26:59 +0200 Subject: [PATCH 1/2] Improve the documentation of documentation groups * doc/lispref/help.texi (Documentation Groups): Fix typos and improve some of the explanations. * lisp/emacs-lisp/shortdoc.el (define-short-documentation-group): Add :no-eval* and :result-string keywords to the docstring. --- doc/lispref/help.texi | 20 ++++++++++++++------ lisp/emacs-lisp/shortdoc.el | 2 ++ 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 298bec5230..104d4f1756 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -866,14 +866,14 @@ Documentation Groups @end example @item :no-eval* -Like @code{:no-eval}, but alaways inserts @samp{[it depends]} as the -result. +Like @code{:no-eval}, but always inserts @samp{[it depends]} as the +result. For instance: @example :no-eval* (buffer-string) @end example -will result in: +will be printed as: @example (buffer-string) @@ -894,12 +894,20 @@ Documentation Groups @item :eg-result Used to output an example result from non-evaluating example forms. +For instance: @example :no-eval (looking-at "f[0-9]") :eg-result t @end example +will be printed as: + +@example +(looking-at "f[0-9]") +eg. @click{} t +@end example + @item :result-string @itemx :eg-result-string These two are the same as @code{:result} and @code{:eg-result}, @@ -917,8 +925,8 @@ Documentation Groups Indicates that this function is not documented in the manual. @item :args -By default, the function's actual argument list is shown. If -@code{:args} is present, they are used instead. +By default, the function's actual argument list is shown. If the +@code{:args} keyword is present, its value is shown instead. @example :args (regexp string) @@ -951,7 +959,7 @@ Documentation Groups @defun shortdoc-add-function shortdoc-add-function group section elem Lisp packages can add functions to groups with this command. Each -@var{elem} should be a function descriptions, as described above. +@var{elem} should be a function description, as described above. @var{group} is the function group, and @var{section} is what section in the function group to insert the function into. diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index 38d8ad6cc1..c9484dcb68 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -60,8 +60,10 @@ define-short-documentation-group :args ARGS :eval EXAMPLE-FORM :no-eval EXAMPLE-FORM + :no-eval* EXAMPLE-FORM :no-value EXAMPLE-FORM :result RESULT-FORM + :result-string RESULT-FORM :eg-result RESULT-FORM :eg-result-string RESULT-FORM) -- 2.31.0 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0002-Add-a-new-documentation-group-for-overlays.patch >From 2b042ea4740fb136cf42eed359dfe90312542826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= Date: Sat, 29 May 2021 13:31:06 +0200 Subject: [PATCH 2/2] Add a new documentation group for overlays * lisp/emacs-lisp/shortdoc.el (overlay): Add documentation group for buffer overlays. --- lisp/emacs-lisp/shortdoc.el | 46 +++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index c9484dcb68..16e8307476 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -889,6 +889,52 @@ buffer (unlock-buffer :no-value (lock-buffer))) +(define-short-documentation-group overlay + "Predicates" + (overlayp + :no-eval (overlayp some-overlay) + :eg-result t) + "Creation and Deletion" + (make-overlay + :args (beg end &optional buffer) + :no-eval (make-overlay 1 10) + :eg-result-string "#") + (delete-overlay + :no-eval (delete-overlay foo) + :eg-result t) + "Searching Overlays" + (overlays-at + :no-eval (overlays-at 15) + :eg-result-string "(#)") + (overlays-in + :no-eval (overlays-in 1 30) + :eg-result-string "(#)") + (next-overlay-change + :no-eval (next-overlay-change 1) + :eg-result 20) + (previous-overlay-change + :no-eval (previous-overlay-change 30) + :eg-result 20) + "Overlay Properties" + (overlay-start + :no-eval (overlay-start foo) + :eg-result 1) + (overlay-end + :no-eval (overlay-end foo) + :eg-result 10) + (overlay-put + :no-eval (overlay-put foo 'happy t) + :eg-result t) + (overlay-get + :no-eval (overlay-get foo 'happy) + :eg-result t) + (overlay-buffer + :no-eval (overlay-buffer foo)) + "Moving Overlays" + (move-overlay + :no-eval (move-overlay foo 5 20) + :eg-result-string "#")) + (define-short-documentation-group process (make-process :no-eval (make-process :name "foo" :command '("cat" "/tmp/foo")) -- 2.31.0 --=-=-=--