* 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.