From: "Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: 48730@debbugs.gnu.org
Subject: bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays
Date: Sat, 29 May 2021 16:29:16 +0200 [thread overview]
Message-ID: <m1mtsdobpf.fsf@yahoo.es> (raw)
In-Reply-To: m1mtsdobpf.fsf.ref@yahoo.es
[-- 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
next parent reply other threads:[~2021-05-29 14:29 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
[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 [this message]
2021-05-29 14:54 ` bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m1mtsdobpf.fsf@yahoo.es \
--to=bug-gnu-emacs@gnu.org \
--cc=48730@debbugs.gnu.org \
--cc=mardani29@yahoo.es \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.