* bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays [not found] <m1mtsdobpf.fsf.ref@yahoo.es> @ 2021-05-29 14:29 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-05-29 14:54 ` Eli Zaretskii 0 siblings, 1 reply; 4+ messages in thread From: Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-05-29 14:29 UTC (permalink / raw) To: 48730 [-- Attachment #1: Type: text/plain, Size: 436 bytes --] 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. [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Improve-the-documentation-of-documentation-groups.patch --] [-- Type: text/x-patch, Size: 2864 bytes --] From 4a65d6df3539b6f23f94f3584b9e7fa46133fed0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es> 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 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #3: 0002-Add-a-new-documentation-group-for-overlays.patch --] [-- Type: text/x-patch, Size: 2097 bytes --] From 2b042ea4740fb136cf42eed359dfe90312542826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es> 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 "#<overlay from 1 to 10 in *foo*>") + (delete-overlay + :no-eval (delete-overlay foo) + :eg-result t) + "Searching Overlays" + (overlays-at + :no-eval (overlays-at 15) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (overlays-in + :no-eval (overlays-in 1 30) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (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 "#<overlay from 5 to 20 in *foo*>")) + (define-short-documentation-group process (make-process :no-eval (make-process :name "foo" :command '("cat" "/tmp/foo")) -- 2.31.0 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays 2021-05-29 14:29 ` bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-05-29 14:54 ` Eli Zaretskii 2021-05-29 16:00 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors 0 siblings, 1 reply; 4+ messages in thread From: Eli Zaretskii @ 2021-05-29 14:54 UTC (permalink / raw) To: Daniel Martín; +Cc: 48730 > 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" <bug-gnu-emacs@gnu.org> > > - 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. ^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays 2021-05-29 14:54 ` Eli Zaretskii @ 2021-05-29 16:00 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-05-30 4:42 ` Lars Ingebrigtsen 0 siblings, 1 reply; 4+ messages in thread From: Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-05-29 16:00 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 48730 [-- Attachment #1: Type: text/plain, Size: 541 bytes --] Eli Zaretskii <eliz@gnu.org> writes: >> 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" <bug-gnu-emacs@gnu.org> >> >> - 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. [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Improve-the-documentation-of-documentation-groups.patch --] [-- Type: text/x-patch, Size: 2587 bytes --] From 9008dfbe3dc7fc338788d544ee2553b8367d13c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es> 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 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #3: 0002-Add-a-new-documentation-group-for-overlays.patch --] [-- Type: text/x-patch, Size: 2110 bytes --] From e402c2601a61d5f178a5ba7f0115664a091972de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=ADn?= <mardani29@yahoo.es> 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 "#<overlay from 1 to 10 in *foo*>") + (delete-overlay + :no-eval (delete-overlay foo) + :eg-result t) + "Searching Overlays" + (overlays-at + :no-eval (overlays-at 15) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (overlays-in + :no-eval (overlays-in 1 30) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (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 "#<overlay from 5 to 20 in *foo*>")) + (define-short-documentation-group process (make-process :no-eval (make-process :name "foo" :command '("cat" "/tmp/foo")) -- 2.31.0 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays 2021-05-29 16:00 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-05-30 4:42 ` Lars Ingebrigtsen 0 siblings, 0 replies; 4+ messages in thread From: Lars Ingebrigtsen @ 2021-05-30 4:42 UTC (permalink / raw) To: Daniel Martín; +Cc: 48730 Daniel Martín <mardani29@yahoo.es> 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. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-05-30 4:42 UTC | newest] Thread overview: 4+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <m1mtsdobpf.fsf.ref@yahoo.es> 2021-05-29 14:29 ` bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-05-29 14:54 ` Eli Zaretskii 2021-05-29 16:00 ` Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-05-30 4:42 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.