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 18:00:08 +0200 Message-ID: References: <83fsy5615o.fsf@gnu.org> 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="13014"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (darwin) Cc: 48730@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat May 29 18:03:40 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 1ln1R6-00039U-Bt for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 29 May 2021 18:03:40 +0200 Original-Received: from localhost ([::1]:38088 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ln1R5-0001u8-Dd for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 29 May 2021 12:03:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38072) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ln1OY-0005pz-EZ for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 12:01:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46053) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ln1OY-0003yX-4y for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 12:01:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ln1OY-0008KL-2b for bug-gnu-emacs@gnu.org; Sat, 29 May 2021 12:01:02 -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 16:01:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 48730 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 48730-submit@debbugs.gnu.org id=B48730.162230402031941 (code B ref 48730); Sat, 29 May 2021 16:01:02 +0000 Original-Received: (at 48730) by debbugs.gnu.org; 29 May 2021 16:00:20 +0000 Original-Received: from localhost ([127.0.0.1]:57596 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ln1Ns-0008J5-1a for submit@debbugs.gnu.org; Sat, 29 May 2021 12:00:20 -0400 Original-Received: from sonic304-22.consmr.mail.ir2.yahoo.com ([77.238.179.147]:40446) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ln1Np-0008Ij-Ic for 48730@debbugs.gnu.org; Sat, 29 May 2021 12:00:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.es; s=s2048; t=1622304011; bh=YykPifPkdmoodDwvaW1ZVM1AKYkeMJEo1qbrs3rOy18=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From:Subject:Reply-To; b=iT8OVermfzhVASK8V81PlsD2R8Cgub7UzoqWFN4o1HkO8no2jscbXPcqcKttQO1gg5jrGDfE1Q2cSmPe4Ru4BvbyD4i+WTSD5Wpz+LJGaaKeKZ9RhoULcZ3VExC83S/gi3HOSz4WY9QjynxBuXF2KfOG00zrKIC2XXAg4PdFsKyFYbm4zf3XJ/tef14MdaqQjAVk/UNO2dxqhqGGTz0M6K6l9UkM9RXcxSfBWZsAAQESnAG94B9V9ZFbHUo/lzuxeSADcWT1Mobi/2KYtK6MDnf9Vr/O2qV/JHjFOXtejYSe6axivqJAolGSCxJSUX1+47yPA1khiiP1Qk81/cEuag== X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1622304011; bh=No3JdbKwHIEa8pSrMw95b6WoteXvRsXyKbNGxMxebKP=; h=X-Sonic-MF:From:To:Subject:Date:From:Subject; b=JzlJT9NKvC1AkgPNcTpj7O9jSIqmBG7nfTTHT9jMy4HG42DJ/HrJEjM95gLqHA5ZaqmL8S0wxzUSpYfmRsZ8tE0o2hnJKXr2OiSLMWpA3ffydWhYhswuvYtZsCjogEL9nncQcTxmYB/RERtxonFpykknmstklrN4gDD5q0zrmIGuqIh65GGte6OXL7j5gvBrtwQfHwr+Qyxknz6olpfNQJlOhCSFhom4DXLqzK1PyBl5XOExh0sYD7W8oO0UVNc1ucP79Yb2tbrelJhE78pcs2dtegyB1D5q0N1TFSFAXl0L2M5jAUWLYLh7T0ZG8EjqhNdpqARqkt0FLQoOGgMVyQ== X-YMail-OSG: Ix6_01YVM1k5GS_A5P962UqADS77CcASFjAlaiti74nv7qhCCwB220b5bCYZV3Z 2dx0jgqmLgAT9Sw4GIoVOJRIJ6BBifuKyNYvkWPZ.aw7WfuUFqaxTa92qyIIcfq1T2_FlWW1UQGT zOAd4aAx.KsmBx4zWfCrX9BBN1GK2MITdr1TwSoX6fbYg9ZuYCDZV8gb_vfxusJihBtvaE0HZx8b 9j3MoA1utpJVuDIR4YV41RiqYbDsuGbtTu5naJThHo_LuRIKdp0H6q6.roMyJChHVaPojPMC760L Rju6NYmy3IMUJgbXVnAc_JBudG_jpGLgP6oOSwdqsIwMzifoHlv0drxy2zSApRAM.hINmHYUkANE E.bbP1rQK8dDvxwFSofrffdDNR2RWAG7u3rU5G2H1jbrJ8bMukfnNvhytRkKV3v2AtnasDVOwdB2 Xs03ZULxxMxMXlTvXWx5JOys6K5YBvQJBnUpaQIEpshTBue1wVmeqFEPtNASjSGt.djYw5q8oTzO YOtSHbsvqu3j2ZBwz1xvuBdEq.YSNmCOVEn2by3ippRzFq9il87whKFwilmDgByAUdFGzBvnRQ_7 6lXM8D2pU6KqggzR8a4tPD30bsDU.XQdJBCyM7kY7Hv1F55nSkKdRukkYt_sz0nn7lgCLTLMzOUN cHmQqRpfr3B7lHPkH18Dv2IjMZOd0zbf54XOW4AfIlfMLU0gEf_dXYZF.P8OLvrEMtmkLcQ6FwUV z88Q0XEEbNNzH7P79wXZ8yjVMHk309tXyUtmPFz0HALWCLLaH6jx7nYViwW05QpcLqrvbGZCzyOT u_Ne4wbi1hLvuLPmajTAox8d5jbI.bEopZwldkjyGv 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 16:00:11 +0000 Original-Received: by kubenode530.mail-prod1.omega.ir2.yahoo.com (VZM Hermes SMTP Server) with ESMTPA ID e2c92e334028d7fa40045b36a8206c0b; Sat, 29 May 2021 16:00:09 +0000 (UTC) In-Reply-To: <83fsy5615o.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 29 May 2021 17:54:27 +0300") X-Mailer: WebService/1.1.18368 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo 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:207542 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Eli Zaretskii writes: >> Date: Sat, 29 May 2021 16:29:16 +0200 >> From: Daniel Mart=C3=ADn via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" >>=20 >> - 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. > > Thanks. Not everything in this part is correct: > Thanks. I've reworked the first patch to avoid passive tense, include a missing @noindent, and revert some rewording I did. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Improve-the-documentation-of-documentation-groups.patch >From 9008dfbe3dc7fc338788d544ee2553b8367d13c6 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 add an example. * lisp/emacs-lisp/shortdoc.el (define-short-documentation-group): Add :no-eval* and :result-string keywords to the docstring. (Bug#48730) --- doc/lispref/help.texi | 18 ++++++++++++++---- lisp/emacs-lisp/shortdoc.el | 2 ++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 298bec5230..dbbc34fb3a 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -839,7 +839,7 @@ Documentation Groups @end example @noindent -will be printed as +will result in: @example (concat "foo" "bar" "zot") @@ -866,13 +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 +@noindent will result in: @example @@ -894,12 +895,21 @@ 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 +@noindent +will result in: + +@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}, @@ -951,7 +961,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 e402c2601a61d5f178a5ba7f0115664a091972de 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. (Bug#48730) --- 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 --=-=-=--