From debbugs-submit-bounces@debbugs.gnu.org Sat May 29 10:29:34 2021 Received: (at submit) by debbugs.gnu.org; 29 May 2021 14:29:34 +0000 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 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 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 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_ZqE9StORgE309jC6nROh8oFDcwFAVnyc7fYZhEiK.Zc_qvDYH5hK Cdc5g6vEPJR8U7QbIOxF.yzzBvEys9mc2yFmMZzScNUdA5nUvF9tMmPwBOa_3fyi7oZy4QUkqHQk aAjVK90dE6N6rne9zyt4q_SD04rlViukiTq_jVIfj.r5lQS6EQwVncG2d1DtH7PMSZ7JKei39xct LWgMEbKCk9YzcgUzLlMud45eDUPk0VgxDgw02vv.hAm2Ot3iwp56HsAUDccvVm5uQmS0b9eCHrg5 yTMjO_1kIxjJO5QDpG7QuZOSIrFSURgja8cVNcugHYU3hTQd9DrKIlYvI2q83ZptWTYRdc_paSyb tC0Yu8WSF26dR1oR0H3fbSHhwb5cB0kEK0Ez5qJNo38nVqdU3PK2V7ujAvDzTGyHXaJTsYRacwkC .ZR1q8Y755LnambsdAEQLksWVMlFNmOz7w0i3ATxyj.N2jYyxC7mzk9TvLuQpzFQ.A73cHVJNHl3 XYQv65FUVcoJhOVASI8qC3iOtiqiO5XEGU_.6j9x1wKBOMUBpoobtgepAJ_uP11a30yInjUgDjRr UeBS8RcYYn9Lcg1VJcbwan81cmLSeJ5uXZLzsWsDmbUzdG5XjiS20vuPNHf3xcrmUfVuV6HHeoiv hcQCQzhvzYE3lv0Qq2WktFSzJuprU.Z.OvnBDTwvwlnF3F7MxNfOFYQ1FJZrSjIi0SGSokg.C66h k6.o_KB4oCv7l5WrnET1PTNbIeoANg4xSTXtVENVQ4UIFAITKHk75EiHjKhcsZI0rHYPw8J3T4p4 whHvQ8AqCPk8db97RzOT1.X0WwUran5bps3Y3N5o5dKGoUUDTYuDd16QUrwMyibPP.dd_Pr_UGgU Y8JgexzCBnB_5JNanrVh_TwiNqBX83J.iN8fJqr4VcgAg.yoZDnfYvi1tN_avIGxWY6HUY2NfFUX XSOUv8DcPd2_3wyJvxsQvuESjBIm4cvxEUK_g9lGNKPNHv8lh3PI91gfS24zLpUziYn5EtYivHH6 GbE8ec9aDHRHWpVFyNBF.0g4Omv7Z5NqFo1NOpfz_.B2FDi_UqrL17pmHuT.oJ5.s833nMBCOCwa jQFZM1jHFogRebl_z7ZjKgPVA7IMEKx.GcaO8ORGrXzZBZrO41J845GpvovRjcfSRMji.ZPaDbY9 E4KXgeK6QK9NF_lqtv51AUVVqDEAbEudHe67Z5.O6J4W00.FqWL90SeR6aO4EJl4eNddgtOGW1Vs uo1X5QABxHUcdGGmjuIOXb37rjfy4BNc30mBjOYnOOn9tyUde8GQhC0XQqNUiIDBN9oyN_t30TDu iZDBOKwOeUnCxmT1pgiLop79s95ugxUkbq0UY7_nDCUNDoIDbvyiXWd8PrJBvhy6iABU.A6NHZDz qS6Dz2S7WOLRthaOFOoTkqYV3CXrY2qZWq1FpKWWhe7PRGALKeT5rt3IdOxNAP32hc7NsySRLqnN j0Mm7jUe4mVuMQb6wEhgojrYxZQAFauPfjwuF4F0Atl1STKqFQWHRPSs8zqx72umDUOkwkgEHMSm 8d_phBweCHEGBejUksHZ_Aps0UglP1Itl2snhbJ8Howe7MAOS3vYD7vymtJoyhegoCLrFi5MU_9k 55ev62ZQq X-Sonic-MF: 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 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) From: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: bug-gnu-emacs@gnu.org Subject: 28.0.50; [PATCH] Add a documentation group section about buffer overlays Date: Sat, 29 May 2021 16:29:16 +0200 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" References: X-Mailer: WebService/1.1.18368 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 5717 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-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 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat May 29 10:54:26 2021 Received: (at 48730) by debbugs.gnu.org; 29 May 2021 14:54:26 +0000 Received: from localhost ([127.0.0.1]:57539 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ln0M6-0006eh-GM for submit@debbugs.gnu.org; Sat, 29 May 2021 10:54:26 -0400 Received: from eggs.gnu.org ([209.51.188.92]:34232) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ln0M3-0006eO-If for 48730@debbugs.gnu.org; Sat, 29 May 2021 10:54:25 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:45104) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ln0Ly-0004Ed-6q; Sat, 29 May 2021 10:54:18 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2977 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 1ln0Lx-0007Cb-On; Sat, 29 May 2021 10:54:18 -0400 Date: Sat, 29 May 2021 17:54:27 +0300 Message-Id: <83fsy5615o.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#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays 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: 48730 Cc: 48730@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: Sat, 29 May 2021 16:29:16 +0200 > From: Daniel Martín via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > - 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: > @example > :no-eval* (buffer-string) > @end example > > -will result in: > +will be printed as: Not sure why this change is needed, they are equivalent, and your variant uses passive tense, which we try to avoid. > +For instance: > > @example > :no-eval (looking-at "f[0-9]") > :eg-result t > @end example > > +will be printed as: You need @noindent before the "will be printed" line. > -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. I think the original reads better, FWIW. From debbugs-submit-bounces@debbugs.gnu.org Sat May 29 12:00:20 2021 Received: (at 48730) by debbugs.gnu.org; 29 May 2021 16:00:20 +0000 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 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.bEopZwldkjyGve0XyjPKiRLqc5P24lc0kk3fAj1tuypW8Fg lD4ImFzuckEgAMcy3TKt7fSMabpN3FIkVkEYFx9eMMAJMgGnE5eY9iGwskZoSHUrXW.p9zEyxKMs CIACrfVhHM1zXNcc6z45w6fjS3i9xfOww59zV_ME9z60F79PuIz1Z4BSvTcPe0MH5bY.SowPnSab i4BIFO_tjH73Yng_xN5DRVc5Pr01Ia4NPZTGtetKhcRM68KlZf9Xlh1G1Ic6j8EfHNcyhbA61Pya gppdYTQHhi3vM1XO1YxqjSxnl3rQouESa3tnSiMlsjeoQ7lDSwSCvDeTiaiVtmDtMGZcmz9UGwc7 SylWHP1zYHmRYrb11h.G7la9WuhzWwgEFwHmsrr6ameT3i_4fVAW1cl26bsZw9tfL9Haci5FjwIq omKlDsKj0H_GwOO67EVTtNemDg5tNq9WHKgtk3S.16tgH04a.Ot9WgteWTguQIE_ve8C9KPFbeeF KsM.LBCZKkGds6zejnfWke553h6rf_5MRNaVM8G7kpRzzMB5ryaJT8BMOjx1v9NvwYYHN9KIBj7P qTX0mA0cnQ8P4SjuCVZPK7CZKJcsWICOwmkyfcM30lLRiNeLyIFI7gddn97ZB_4LP87b8ld7hgRP kqDbc5PrO3GC7LkGIxtJOrKGuCLdVK51.SC3cpXRyxgjuLNGHDBsMZBzO6tbSlaLkMAO_Ui_K52d OiqRBPXKyQhtRR7LwLcbcdTKEn9AnmXdK7EGUxz5baT8H8.tYpOYw0wzJRsnaq4ngdGj7mhyCyhf G1FnVS8Z7pf3Bs4MJDoN7lXkJ7Eu44LgFx0lTTOLgfHIDWtJeqhVvqfsBQtTxAT3gHV1MoFST2Jq lPMGtgKwYv91Rj.l.efcicp2sbLOBbDC993yaGegYgHZc1yrr.ESuQT7cci0QyxOsOAhVsvlRJOt klgyzFT26PxLNDJcOkkOKWjvwU5DOnuSPvmLPoBL7E27QMIIw.VuD_sY61K.NKAvAj9qt8G6eQos GqUOAuESHbeCIQSqZftm04NmqEKRPWk0hFxWjepJrz0_lfIYvmHZ.cdKlYQdWbg6qMNH98EF13Ci KNP9OC8taGfUaJLGfvq_dU17vuEyAA2OxP1OZbVpfRDP6UiAwpaULrx5uXpLUqhTpZ10lQj4bT.s 1mWPgLpgoQYISHGiYM1JhVM3BzYB1gcGGVmBtuTXE52bR1Ayx4RFwBJcozeYUTt2fw01qxrqLm7W KnPX7mU0XU9HUGqMAYzIz2kT8yhyMTItOZMCzWp9pTpcDbBPv7V7243OeKQuWO89jlrBeB.q4uVU IDhwKsh0t.0oe024sLr7b3fqFc9VKS6WplbQ8vDZx1PDNnpFagzwwVKjmjpZ_4d_pdiSv9SGKx9. v2pXyNDtSoBim0oIUynNlbpR_0BIv4LknAQ6AKF66psH_SQe66JfykTbDLA_WxM2TEVqa3_cdsCW yoimit67FRDjVUqrgMU06UGtfTXaKWa8xtGqsIqxuL2yPB7LOo2ucNTU1Ak83U9uiEGuKsyhwTBf enGk7w.JxLtv.wj9Hqta5UvLHFTu.f4Vit1Dl1ZohK3ephy69LScxriMSaP.KY1b7vjzYmdDt9YJ GH.l4n9G2ypiCA0LNesJtsR7u4JlelG9u3UtvECLBnuudVLUzZnhro0PfJVzeEghPs8A2CBo97ga lOWJM95w2Y0v78ZxRjFa_72XaC.0- X-Sonic-MF: 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 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) From: =?utf-8?Q?Daniel_Mart=C3=ADn?= To: Eli Zaretskii Subject: Re: bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays References: <83fsy5615o.fsf@gnu.org> Date: Sat, 29 May 2021 18:00:08 +0200 In-Reply-To: <83fsy5615o.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 29 May 2021 17:54:27 +0300") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (darwin) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Mailer: WebService/1.1.18368 mail.backend.jedi.jws.acl:role.jedi.acl.token.atz.jws.hermes.yahoo Content-Length: 5608 X-Spam-Score: 0.2 (/) X-Debbugs-Envelope-To: 48730 Cc: 48730@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.8 (/) --=-=-= 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sun May 30 00:42:15 2021 Received: (at 48730) by debbugs.gnu.org; 30 May 2021 04:42:15 +0000 Received: from localhost ([127.0.0.1]:58085 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lnDHD-0001x7-6F for submit@debbugs.gnu.org; Sun, 30 May 2021 00:42:15 -0400 Received: from quimby.gnus.org ([95.216.78.240]:44674) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lnDHB-0001wp-QC for 48730@debbugs.gnu.org; Sun, 30 May 2021 00:42:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Transfer-Encoding:Content-Type:MIME-Version:Message-ID :In-Reply-To:Date:References:Subject:Cc:To:From:Sender:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=NqmqJDmSt//eZoZ/n6NerW4rTguL6ZktyL9R1mC2knM=; b=jZWlxUmL/O0L3iJWoCo59pdAAE qUzUAG/lbBRFElA/5Jui6iPnWuphj4vyD8U2XgrmU0ofddndTdDMZQfSCm9P7VhXtdI7F5N/kUhlW K6MCW4f47udVGs7ZaphR0E3vmw9+MCVcB28i0ALTMcEhdlp2OBO7o0TfP+WEC7MyPijk=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lnDH2-0005y7-Uw; Sun, 30 May 2021 06:42:07 +0200 From: Lars Ingebrigtsen To: Daniel =?utf-8?Q?Mart=C3=ADn?= Subject: Re: bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays References: <83fsy5615o.fsf@gnu.org> X-Now-Playing: Crosby, Stills, Nash & Young's _So Far_: "Wooden Ships" Date: Sun, 30 May 2021 06:42:04 +0200 In-Reply-To: ("Daniel =?utf-8?Q?Mart=C3=ADn=22's?= message of "Sat, 29 May 2021 18:00:08 +0200") Message-ID: <87k0ng6der.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Daniel Martín writes: > Thanks. I've reworked the first patch to avoid passive tense, include a > missing @noindent, and revert some rewording I did. Thanks; applied to Emacs 28. Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 48730 Cc: 48730@debbugs.gnu.org, Eli Zaretskii 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 (-) Daniel Mart=C3=ADn writes: > Thanks. I've reworked the first patch to avoid passive tense, include a > missing @noindent, and revert some rewording I did. Thanks; applied to Emacs 28. --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Sun May 30 00:42:20 2021 Received: (at control) by debbugs.gnu.org; 30 May 2021 04:42:20 +0000 Received: from localhost ([127.0.0.1]:58088 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lnDHI-0001xO-Cd for submit@debbugs.gnu.org; Sun, 30 May 2021 00:42:20 -0400 Received: from quimby.gnus.org ([95.216.78.240]:44690) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lnDHG-0001x0-Nm for control@debbugs.gnu.org; Sun, 30 May 2021 00:42:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=IEt7ecfjjTpg4SNlXedjLzzPfzYHN31LDR6LpoPRrZs=; b=M6LVLc+1EO3Ug59gvn0ANS7RJx bFTokCdCABRuEP0lbmtya30L8C4rer+zhr6qA/JyR8gMKFWAETRm2hNc2AbZlf6qYhOBQzCnV+E1r iRV6wihadUZy9Kl1G24kYC8IgrXZ+mITnu7bDU0vaXUY5y74ERp9G9jvswz7SnBvMsPI=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lnDH9-0005yE-BF for control@debbugs.gnu.org; Sun, 30 May 2021 06:42:13 +0200 Date: Sun, 30 May 2021 06:42:10 +0200 Message-Id: <87im306del.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #48730 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: close 48730 28.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) close 48730 28.1 quit From unknown Tue Aug 19 21:02:44 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 27 Jun 2021 11:24:06 +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