From: "Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 48730@debbugs.gnu.org
Subject: bug#48730: 28.0.50; [PATCH] Add a documentation group section about buffer overlays
Date: Sat, 29 May 2021 18:00:08 +0200 [thread overview]
Message-ID: <m1v971msxj.fsf@yahoo.es> (raw)
In-Reply-To: <83fsy5615o.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 29 May 2021 17:54:27 +0300")
[-- 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
next prev parent reply other threads:[~2021-05-29 16:00 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 ` 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 [this message]
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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m1v971msxj.fsf@yahoo.es \
--to=bug-gnu-emacs@gnu.org \
--cc=48730@debbugs.gnu.org \
--cc=eliz@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 public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).