bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays

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]

[-- 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

bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays

[Eli Zaretskii]

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

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]

[-- 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

bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays

[Lars Ingebrigtsen]

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