* [PATCH] Add support for shortdoc link type
@ 2024-05-01 3:29 Bruno Cardoso
2024-05-01 11:00 ` Ihor Radchenko
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-01 3:29 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 73 bytes --]
Hi all,
This patch adds support for "shortdoc:" links.
Best,
Bruno.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 1865 bytes --]
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 8dbc3292d..cfe894448 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1357,6 +1357,10 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for ~shortdoc~ link type
+
+Add support for storing and inserting links to ~shortdoc~ groups.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index f6d656982..f0088ae5f 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1598,6 +1598,29 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+
+(defun org-link--open-shortdoc (group _)
+ "Open a \"shortdoc\" type link.
+GROUP is a symbol name."
+ (if (assoc (intern group) shortdoc--groups)
+ (shortdoc group)
+ (user-error "Unknown shortdoc group: %s" group)))
+
+(defun org-link--store-shortdoc (&optional _interactive?)
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (when (assoc (intern group) shortdoc--groups)
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)))))
+
+(org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc)
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-01 3:29 [PATCH] Add support for shortdoc link type Bruno Cardoso
@ 2024-05-01 11:00 ` Ihor Radchenko
2024-05-01 16:52 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Ihor Radchenko @ 2024-05-01 11:00 UTC (permalink / raw)
To: Bruno Cardoso; +Cc: emacs-orgmode
Bruno Cardoso <cardoso.bc@gmail.com> writes:
> This patch adds support for "shortdoc:" links.
Thanks!
> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS
You also need to document the new built-in link type in the manual.
> +(defun org-link--open-shortdoc (group _)
> + "Open a \"shortdoc\" type link.
> +GROUP is a symbol name."
> + (if (assoc (intern group) shortdoc--groups)
> + (shortdoc group)
> + (user-error "Unknown shortdoc group: %s" group)))
`shortdoc' function was only introduced in Emacs 29.
In Emacs 28, there is only `shortdoc-display-group'.
Please use the latter function, when `shortdoc' is not available.
In Emacs 27, shortdoc library is not yet present. So, please avoid
defining shortdoc: link type in Emacs <28.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-01 11:00 ` Ihor Radchenko
@ 2024-05-01 16:52 ` Bruno Cardoso
2024-05-01 17:55 ` Ihor Radchenko
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-01 16:52 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 70 bytes --]
Hi Ihor,
Thanks for your comments. See attached the updated patch.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 3052 bytes --]
diff --git a/doc/org-manual.org b/doc/org-manual.org
index d66d95a22..c9e307c94 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3372,6 +3372,10 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for a function group.
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3413,6 +3417,7 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 8dbc3292d..cfe894448 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1357,6 +1357,10 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for ~shortdoc~ link type
+
+Add support for storing and inserting links to ~shortdoc~ groups.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index f6d656982..b7b988581 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1598,6 +1598,30 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+
+(when (version< "27" emacs-version)
+ (defun org-link--open-shortdoc (group _)
+ "Open a \"shortdoc\" type link.
+GROUP is a symbol name."
+ (if (assoc (intern group) shortdoc--groups)
+ (shortdoc-display-group group)
+ (user-error "Unknown shortdoc group: %s" group)))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (when (assoc (intern group) shortdoc--groups)
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
[-- Attachment #3: Type: text/plain, Size: 1086 bytes --]
On 2024-05-01, 11:00 +0000, Ihor Radchenko <yantar92@posteo.net> wrote:
> Bruno Cardoso <cardoso.bc@gmail.com> writes:
>
>> This patch adds support for "shortdoc:" links.
>
> Thanks!
>
>> --- a/etc/ORG-NEWS
>> +++ b/etc/ORG-NEWS
>
> You also need to document the new built-in link type in the manual.
>
>> +(defun org-link--open-shortdoc (group _)
>> + "Open a \"shortdoc\" type link.
>> +GROUP is a symbol name."
>> + (if (assoc (intern group) shortdoc--groups)
>> + (shortdoc group)
>> + (user-error "Unknown shortdoc group: %s" group)))
>
> `shortdoc' function was only introduced in Emacs 29.
> In Emacs 28, there is only `shortdoc-display-group'.
> Please use the latter function, when `shortdoc' is not available.
>
> In Emacs 27, shortdoc library is not yet present. So, please avoid
> defining shortdoc: link type in Emacs <28.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-01 16:52 ` Bruno Cardoso
@ 2024-05-01 17:55 ` Ihor Radchenko
2024-05-01 19:24 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Ihor Radchenko @ 2024-05-01 17:55 UTC (permalink / raw)
To: Bruno Cardoso; +Cc: emacs-orgmode
Bruno Cardoso <cardoso.bc@gmail.com> writes:
> Thanks for your comments. See attached the updated patch.
Thanks for the update!
> +- =shortdoc= ::
> +
> + Link to short documentation summary for a function group.
Might be useful to throw a link to Emacs manual here - [[info:emacs#Name Help]]
> +*** =ol.el=: Support for ~shortdoc~ link type
> +Add support for storing and inserting links to ~shortdoc~ groups.
=shortdoc= I think. It is not ~code~, but rather =verbatim=.
> + (defun org-link--store-shortdoc (&optional _interactive?)
> + (when (eq major-mode 'shortdoc-mode)
> + (let* ((buffer (buffer-name))
> + (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
> + (match-string 1 buffer))))
> + (when (assoc (intern group) shortdoc--groups)
This will err when GROUP is nil (string-match does not match).
> + (org-link-set-parameters "shortdoc"
> + :follow #'org-link--open-shortdoc
> + :store #'org-link--store-shortdoc))
Maybe also implement :complete parameter? It should be relatively easy.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-01 17:55 ` Ihor Radchenko
@ 2024-05-01 19:24 ` Bruno Cardoso
2024-05-02 10:41 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-01 19:24 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1274 bytes --]
On 2024-05-01, 17:55 +0000, Ihor Radchenko <yantar92@posteo.net> wrote:
> Bruno Cardoso <cardoso.bc@gmail.com> writes:
>
>> Thanks for your comments. See attached the updated patch.
>
> Thanks for the update!
>
>> +- =shortdoc= ::
>> +
>> + Link to short documentation summary for a function group.
>
> Might be useful to throw a link to Emacs manual here - [[info:emacs#Name Help]]
>
>> +*** =ol.el=: Support for ~shortdoc~ link type
>> +Add support for storing and inserting links to ~shortdoc~ groups.
>
> =shortdoc= I think. It is not ~code~, but rather =verbatim=.
>
>> + (defun org-link--store-shortdoc (&optional _interactive?)
>> + (when (eq major-mode 'shortdoc-mode)
>> + (let* ((buffer (buffer-name))
>> + (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
>> + (match-string 1 buffer))))
>> + (when (assoc (intern group) shortdoc--groups)
>
> This will err when GROUP is nil (string-match does not match).
>
>> + (org-link-set-parameters "shortdoc"
>> + :follow #'org-link--open-shortdoc
>> + :store #'org-link--store-shortdoc))
>
> Maybe also implement :complete parameter? It should be relatively easy.
>
Thanks Ihor, here is the updated patch.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 3564 bytes --]
diff --git a/doc/org-manual.org b/doc/org-manual.org
index d66d95a22..15b79ae21 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3372,6 +3372,10 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+Link to short documentation summary for a function group. For more information, see [[info:emacs#Name Help][Help by Command or Variable Name]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3413,6 +3417,7 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 8dbc3292d..b0f4cb287 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1357,6 +1357,10 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= groups.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index f6d656982..dd95f5d4c 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1597,6 +1597,37 @@ PATH is a symbol name, as a string."
(org-link-set-parameters "help"
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version< "27" emacs-version)
+ (defun org-link--open-shortdoc (group _)
+ "Open a \"shortdoc\" type link.
+GROUP is a symbol name."
+ (if (assoc (intern group) shortdoc--groups)
+ (shortdoc-display-group group)
+ (user-error "Unknown shortdoc group: %s" group)))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-01 19:24 ` Bruno Cardoso
@ 2024-05-02 10:41 ` Max Nikulin
2024-05-03 21:41 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-02 10:41 UTC (permalink / raw)
To: Bruno Cardoso; +Cc: emacs-orgmode
On 02/05/2024 02:24, Bruno Cardoso wrote:
> +++ b/lisp/ol.el
> @@ -1597,6 +1597,37 @@ PATH is a symbol name, as a string."
> (org-link-set-parameters "help"
> :follow #'org-link--open-help
> :store #'org-link--store-help)
> +;;;; "shortdoc" link type
> +(when (version< "27" emacs-version)
> + (defun org-link--open-shortdoc (group _)
> + "Open a \"shortdoc\" type link.
> +GROUP is a symbol name."
> + (if (assoc (intern group) shortdoc--groups)
> + (shortdoc-display-group group)
> + (user-error "Unknown shortdoc group: %s" group)))
`condition-case' may help to avoid the internal `shortdoc--groups'
variable here. As to completion, it is better to ask for public API.
However emacs developers likely will decline such request.
Consider the following just as ideas.
- Support of search options. Buttons in help pages move point to
specific functions.
<shortdoc:file::#find-file>
- At first I considered adding shortdoc to help links that may call
either `describe-function' or `describe-variable', but it is unlikely
possible.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-02 10:41 ` Max Nikulin
@ 2024-05-03 21:41 ` Bruno Cardoso
2024-05-04 7:38 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-03 21:41 UTC (permalink / raw)
To: Max Nikulin; +Cc: emacs-orgmode
On 2024-05-02, 17:41 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> `condition-case' may help to avoid the internal `shortdoc--groups'
> variable here. As to completion, it is better to ask for public API.
> However emacs developers likely will decline such request.
>
> Consider the following just as ideas.
>
> - Support of search options. Buttons in help pages move point to
> specific functions.
>
> <shortdoc:file::#find-file>
>
> - At first I considered adding shortdoc to help links that may call
> either `describe-function' or `describe-variable', but it is unlikely
> possible.
Hi Max,
Thanks for your suggestions. Indeed `condition-case' might be better there.
I implemented the search option by borrowing the regexp from `ol-info':
(defun org-link--open-shortdoc (path _)
"Open a \"shortdoc\" type link.
PATH is a group name or \"group::#function\"."
(string-match "\\`\\([^#:]*\\)\\(?:[#:]:?\\(.*\\)\\)?\\'" path)
(let ((group (match-string 1 path))
(fn (match-string 2 path)))
(condition-case nil
(progn
(shortdoc-display-group group)
(when fn
(re-search-forward (concat "^(" (string-remove-prefix "#" fn))
nil t)
(beginning-of-line)))
(error (message "Unknown shortdoc group: %s" group)))))
It works, but I'm not quite sure if this is the best approach.
It curently matches all the cases below, as I got confused about the correct link syntax:
shortdoc:text-properties:get-pos-property
shortdoc:text-properties::get-pos-property
shortdoc:text-properties#get-pos-property
shortdoc:text-properties:#get-pos-property
shortdoc:text-properties::#get-pos-property
Best,
Bruno.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-03 21:41 ` Bruno Cardoso
@ 2024-05-04 7:38 ` Max Nikulin
2024-05-04 17:33 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-04 7:38 UTC (permalink / raw)
To: Bruno Cardoso; +Cc: emacs-orgmode
On 04/05/2024 04:41, Bruno Cardoso wrote:
> On 2024-05-02, 17:41 +0700, Max Nikulin wrote:
>>
>> <shortdoc:file::#find-file>
[...]
> I implemented the search option by borrowing the regexp from `ol-info':
It is necessary to maintain backward compatibility for `ol-info'. I do
not know what kind of separator was added earlier: "::" or "#". I
suppose, for new link type, rules more close to file: links may be used, see
(info "(org) Search Options")
https://orgmode.org/manual/Search-Options.html
That is why I suggested shortdoc:GROUP::#FUNCTION. This way
shrotdoc:GROUP::SEARCH_STRING is possible as well.
> (shortdoc-display-group group)
> (when fn
> (re-search-forward (concat "^(" (string-remove-prefix "#" fn))
> nil t)
Notice that `shortdoc-display-group' has optional FUNCTION argument.
> (beginning-of-line)))
> (error (message "Unknown shortdoc group: %s" group)))))
>
> It works, but I'm not quite sure if this is the best approach.
I do not have strong opinion as well. Some points to consider:
- Unambiguous parsing of link target.
- Flexibility it respect to later improvements.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-04 7:38 ` Max Nikulin
@ 2024-05-04 17:33 ` Bruno Cardoso
2024-05-05 11:01 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-04 17:33 UTC (permalink / raw)
To: Max Nikulin; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 745 bytes --]
On 2024-05-04, 14:38 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> It is necessary to maintain backward compatibility for `ol-info'. I do
> not know what kind of separator was added earlier: "::" or "#". I
> suppose, for new link type, rules more close to file: links may be used, see
> (info "(org) Search Options")
> https://orgmode.org/manual/Search-Options.html
>
> That is why I suggested shortdoc:GROUP::#FUNCTION. This way
> shrotdoc:GROUP::SEARCH_STRING is possible as well.
I see, thanks for pointing it out. I modified the regexp to match this pattern.
> Notice that `shortdoc-display-group' has optional FUNCTION argument.
Yes, I completely missed that. I updated the patch to use the optional function argument instead.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 3829 bytes --]
diff --git a/doc/org-manual.org b/doc/org-manual.org
index d66d95a22..61ee0c63d 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3372,6 +3372,10 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+Link to short documentation summary for a function group. For more information, see [[info:emacs#Name Help][Help by Command or Variable Name]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3413,6 +3417,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 87ebed751..f90c59ed3 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1369,6 +1369,10 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= groups.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index bc9682e4a..19ec7a32a 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,41 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version< "27" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name or \"group::#function\"."
+ (string-match "\\`\\([^#:]*\\)\\(::#?\\(.*\\)\\)?\\'" path)
+ (let ((group (match-string 1 path))
+ (fn (match-string 3 path)))
+ (condition-case nil
+ (shortdoc-display-group group (intern-soft fn))
+ (error (message "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-04 17:33 ` Bruno Cardoso
@ 2024-05-05 11:01 ` Max Nikulin
2024-05-05 21:35 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-05 11:01 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Bruno Cardoso
On 05/05/2024 00:33, Bruno Cardoso wrote:
>
> I updated the patch to use the optional function argument instead.
Thanks
> +++ b/doc/org-manual.org
> @@ -3372,6 +3372,10 @@ Here is the full set of built-in link types:
>
> Execute a shell command upon activation.
>
> +- =shortdoc= ::
> +
> +Link to short documentation summary for a function group. For more information, see [[info:emacs#Name Help][Help by Command or Variable Name]].
I would consider explicit mention that it is related to Emacs Lisp and
perhaps that the origin of its name is the ~shortdoc-display-group~ user
command. <info:elisp#Documentation Groups> might be a better link.
This line is rather long though I do not have a link where formatting
conventions are documented.
> +++ b/etc/ORG-NEWS
> @@ -1369,6 +1369,10 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
> =TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
> The old name is obsolete.
>
> +*** =ol.el=: Support for =shortdoc= link type
> +
> +Add support for storing and inserting links to =shortdoc= groups.
Again I am unsure that it is clear to all readers.
> +++ b/lisp/ol.el
> @@ -1582,6 +1582,41 @@ PATH is a symbol name, as a string."
> :follow #'org-link--open-help
> :store #'org-link--store-help)
>
> +;;;; "shortdoc" link type
> +(when (version< "27" emacs-version)
Is it correct?
2a7488d42d8 2020-10-11 05:51:16 +0200 Lars Ingebrigtsen: Add support for
displaying short documentation for function groups
git tag --contains 2a7488d42d8
emacs-28.0.90
> + (defun org-link--open-shortdoc (path _)
> + "Open a \"shortdoc\" type link.
> +PATH is a group name or \"group::#function\"."
> + (string-match "\\`\\([^#:]*\\)\\(::#?\\(.*\\)\\)?\\'" path)
I think, it is enough to use [^:] since next group is started from "::".
You may use use non-capturing group \\(?:::# ...\\) (requires update of
next index below) unless you are going add search code back. I am unsure
concerning your intentions. You dropped search code, but "#" after "::"
is still optional.
> + (let ((group (match-string 1 path))
> + (fn (match-string 3 path)))
> + (condition-case nil
> + (shortdoc-display-group group (intern-soft fn))
> + (error (message "Unknown shortdoc group: %s" group)))))
I do not have strong opinion what is better here: `user-error' (used in
earlier revisions) or `error'. However I do not see the point of
capturing original error and signalling another one if it is not
`user-error'.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-05 11:01 ` Max Nikulin
@ 2024-05-05 21:35 ` Bruno Cardoso
2024-05-06 10:55 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-05 21:35 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1706 bytes --]
On 2024-05-05, 18:01 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> I would consider explicit mention that it is related to Emacs Lisp and
> perhaps that the origin of its name is the ~shortdoc-display-group~ user
> command. <info:elisp#Documentation Groups> might be a better link.
>
> This line is rather long though I do not have a link where formatting
> conventions are documented.
I expanded the description on `org-manual.org' and 'ORG-NEWS'.
>> +;;;; "shortdoc" link type
>> +(when (version< "27" emacs-version)
>
> Is it correct?
>
> 2a7488d42d8 2020-10-11 05:51:16 +0200 Lars Ingebrigtsen: Add support for
> displaying short documentation for function groups
>
> git tag --contains 2a7488d42d8
> emacs-28.0.90
Fixed.
> I think, it is enough to use [^:] since next group is started from "::".
> You may use use non-capturing group \\(?:::# ...\\) (requires update of
> next index below) unless you are going add search code back. I am unsure
> concerning your intentions. You dropped search code, but "#" after "::"
> is still optional.
Thanks. I updated the regexp.
I had dropped the search code because I wasn't considering the search option properly. If I understand correctly, both "::" and "::#" should match a function OR a search string? (e.g.: `shortdoc:text-properties::#pos-property' will also search for "pos-property" in the shortdoc buffer). This is the current behavior in the attached patch.
> I do not have strong opinion what is better here: `user-error' (used in
> earlier revisions) or `error'. However I do not see the point of
> capturing original error and signalling another one if it is not
> `user-error'.
Agreed. I replaced it with `user-error'.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 4127 bytes --]
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1feb5ed60..dd4cb6cd0 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3382,6 +3382,13 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ lists all known
+ documentation groups. For more information, see [[info:emacs#Name Help]]
+ and [[info:elisp#Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3423,6 +3430,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 99dd8839c..1623873c0 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1405,6 +1405,11 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index bc9682e4a..ff0b56378 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,44 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search_string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::#?\\(.*\\)\\)?\\'" path)
+ (let ((group (match-string 1 path))
+ (fn (match-string 2 path)))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group (intern-soft fn))
+ (unless (intern-soft fn)
+ (re-search-forward fn nil t)))
+ (user-error "Unknown shortdoc group: %s" group))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-05 21:35 ` Bruno Cardoso
@ 2024-05-06 10:55 ` Max Nikulin
2024-05-08 1:11 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-06 10:55 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Bruno Cardoso
On 06/05/2024 04:35, Bruno Cardoso wrote:
> Fixed.
I have tried the patch. It mostly works, so I do not insist on further
polishing. However it should be resent with proper description.
> I had dropped the search code because I wasn't considering the search
> option properly. If I understand correctly, both "::" and "::#" should
> match a function OR a search string? (e.g.:
> `shortdoc:text-properties::#pos-property' will also search for
> "pos-property" in the shortdoc buffer). This is the current behavior in
> the attached patch.
It seems my comments have led mostly to confusion rather than
improvements. I am sorry for that. I have in mind 2 kind of links:
- <shortdoc:string::#try-completion> that may be handled solely by
`shortdoc-display-group' with second argument.
- <shortdoc::string::identical contents> that should cause
(shortdoc-display-group group)
(search-forward fn nil t) ; or (word-search-forward fn nil t)
For `re-search-forward' used in the latest patch revision, from my point
of view, link should be <shortdoc::string::/identical contents/>
(similar to file: links).
Support of search variant may be dropped, but that case I would not
allow "::" as the separator. Mandatory "::#" allows to add text and
regexp search later.
> +++ b/doc/org-manual.org
> @@ -3382,6 +3382,13 @@ Here is the full set of built-in link types:
>
> Execute a shell command upon activation.
>
> +- =shortdoc= ::
> +
> + Link to short documentation summary for an Emacs Lisp function group.
> + Since Emacs 28, user command ~shortdoc-display-group~ lists all known
> + documentation groups. For more information, see [[info:emacs#Name Help]]
> + and [[info:elisp#Documentation Groups]].
I am unsure that links without description is a bright idea. Try
https://orgmode.org/manual/Activation.html
and M-: (info "(org) Activation") RET
to get an impression of export result.
> +++ b/lisp/ol.el
> @@ -1582,6 +1582,44 @@ PATH is a symbol name, as a string."
> :follow #'org-link--open-help
> :store #'org-link--store-help)
>
> +;;;; "shortdoc" link type
> +(when (version<= "28.0.90" emacs-version)
> + (defun org-link--open-shortdoc (path _)
> + "Open a \"shortdoc\" type link.
> +PATH is a group name, \"group::#function\" or \"group::search_string\"."
> + (string-match "\\`\\([^:]*\\)\\(?:::#?\\(.*\\)\\)?\\'" path)
I just have realized that it is better to ignore anything unexpected
after ":", e.g. if only ::# is allowed (no search text option)
(string-match "\\`\\([^:]*\\)\\(?:::#\\(.*\\).*\\'\\)?" path)
Try [[shortdoc:string:invalid]].
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-06 10:55 ` Max Nikulin
@ 2024-05-08 1:11 ` Bruno Cardoso
2024-05-08 11:20 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-08 1:11 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 676 bytes --]
On 2024-05-06, 17:55 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> It seems my comments have led mostly to confusion rather than
> improvements. I am sorry for that. I have in mind 2 kind of links:
> - <shortdoc:string::#try-completion> that may be handled solely by
> `shortdoc-display-group' with second argument.
> - <shortdoc::string::identical contents> that should cause
> (shortdoc-display-group group)
> (search-forward fn nil t) ; or (word-search-forward fn nil t)
I'm sure the confusion is mostly my fault :)
The following now work as expected:
- [[shortdoc:string]]
- [[shortdoc:string::#try-completion]]
- [[shortdoc:string::identical contents]]
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 4267 bytes --]
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1feb5ed60..8894f4231 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3382,6 +3382,15 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ lists all known
+ documentation groups.
+
+ For more information, see [[info:emacs#Name Help][Name Help]]
+ and [[info:elisp#Documentation Groups][Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3423,6 +3432,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 99dd8839c..1623873c0 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1405,6 +1405,11 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index bc9682e4a..ab6cb497a 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,46 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\).*\\'\\)?" path)
+ (let* ((group (match-string 1 path))
+ (str (match-string 2 path))
+ (fn (when (and str (string-match "^#" str))
+ (intern-soft (string-remove-prefix "#" str)))))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group fn)
+ (when (and str (not fn))
+ (search-forward str nil t)))
+ (user-error "Unknown shortdoc group: %s" group))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-08 1:11 ` Bruno Cardoso
@ 2024-05-08 11:20 ` Max Nikulin
2024-05-08 21:26 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-08 11:20 UTC (permalink / raw)
To: Bruno Cardoso, emacs-orgmode
On 08/05/2024 08:11, Bruno Cardoso wrote:
>
> The following now work as expected:
>
> - [[shortdoc:string]]
> - [[shortdoc:string::#try-completion]]
> - [[shortdoc:string::identical contents]]
Thanks.
Bruno, the patch should have proper commit message, see
<https://orgmode.org/worg/org-contribute.html#commit-messages>
Some minor notes:
> +++ b/doc/org-manual.org
> @@ -3382,6 +3382,15 @@ Here is the full set of built-in link types:
>
> Execute a shell command upon activation.
>
> +- =shortdoc= ::
> +
> + Link to short documentation summary for an Emacs Lisp function group.
> + Since Emacs 28, user command ~shortdoc-display-group~ lists all known
> + documentation groups.
I have not managed to get all known groups with `shortdoc-display-group'
in Emacs-28. Is it a feature of `shortdoc' in Emacs-29?
> + (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\).*\\'\\)?" path)
My bad. In
"\\`\\([^:]*\\)\\(?:::#\\(.*\\).*\\'\\)?"
second .* was unnecessary, it survived from an earlier variant with \\|
and \\' outside of the regex group.
Likely it is better to not allow empty group or function, so "+" instead
of "*"
"\\`\\([^:]+\\)\\(?:::\\(.+\\)\\'\\)?"
since <shortdoc:::file> is hardly a valid link. However it might be
search text link in the list of all groups (Emacs-29+ only?).
It is related to corner cases, so I do not insist.
> + (let* ((group (match-string 1 path))
> + (str (match-string 2 path))
> + (fn (when (and str (string-match "^#" str))
> + (intern-soft (string-remove-prefix "#" str)))))
Nitpick, feel free to ignore:
- `when' is redundant here due to `and' inside its condition.
- `string-patch-p' would not affect match groups, so it is a bit cheaper.
- Since it is already known that first character is "#", `substring'
instead of `string-remove-prefix' is an extra step in microoptimization
Untested: (fn (and str (eq ?# (string-to-char str)) (substring str 1)))
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-08 11:20 ` Max Nikulin
@ 2024-05-08 21:26 ` Bruno Cardoso
2024-05-10 11:09 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-08 21:26 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1384 bytes --]
On 2024-05-08, 18:20 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> I have not managed to get all known groups with `shortdoc-display-group'
> in Emacs-28. Is it a feature of `shortdoc' in Emacs-29?
In Emacs-29 `shortdoc' is an alias for `shortdoc-display-group'. Interactvely, it prompts the user for a group from `shortdoc--groups' (that's what I meant by "all known groups"). I'm unsure if `shortdoc-display-group' behaves differently in Emacs-28.
> Likely it is better to not allow empty group or function, so "+" instead
> of "*"
>
> "\\`\\([^:]+\\)\\(?:::\\(.+\\)\\'\\)?"
>
> since <shortdoc:::file> is hardly a valid link. However it might be
> search text link in the list of all groups (Emacs-29+ only?).
>
> It is related to corner cases, so I do not insist.
`shortdoc-display-group' already handles empty group or function. Replacing "*" by "+" will throw an "Args out of range" error in the corner case you mentioned ("shortdoc:::file"). So I think it's fine to keep "*" there.
> Nitpick, feel free to ignore:
> - `when' is redundant here due to `and' inside its condition.
> - `string-patch-p' would not affect match groups, so it is a bit cheaper.
> - Since it is already known that first character is "#", `substring'
> instead of `string-remove-prefix' is an extra step in microoptimization
Noted.
Thank you for all your comments and suggestions, Max!
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 4586 bytes --]
ol.el: Add support for `shortdoc' link type
* lisp/ol.el: Add support for storing and inserting links to `shortdoc'
documentation groups for Emacs Lisp functions.
* doc/org-manual.org (External Links): Add shortdoc link type
documentation.
* etc/ORG-NEWS (=ol.el=: Support for =shortdoc= link type): Document
the new feature.
---
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1feb5ed60..8894f4231 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3382,6 +3382,15 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ lists all known
+ documentation groups.
+
+ For more information, see [[info:emacs#Name Help][Name Help]]
+ and [[info:elisp#Documentation Groups][Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3423,6 +3432,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 99dd8839c..1623873c0 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1405,6 +1405,11 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index bc9682e4a..928db29e1 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,46 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\)\\'\\)?" path)
+ (let* ((group (match-string 1 path))
+ (str (match-string 2 path))
+ (fn (and str
+ (eq ?# (string-to-char str))
+ (intern-soft (substring str 1)))))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group fn)
+ (and str (not fn) (search-forward str nil t)))
+ (user-error "Unknown shortdoc group: %s" group))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-08 21:26 ` Bruno Cardoso
@ 2024-05-10 11:09 ` Max Nikulin
2024-05-11 16:58 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-10 11:09 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Bruno Cardoso
On 09/05/2024 04:26, Bruno Cardoso wrote:
> On 2024-05-08, 18:20 +0700, Max Nikulin wrote:
>
>> I have not managed to get all known groups with `shortdoc-display-group'
>> in Emacs-28. Is it a feature of `shortdoc' in Emacs-29?
>
> In Emacs-29 `shortdoc' is an alias for `shortdoc-display-group'.
> Interactvely, it prompts the user for a group from `shortdoc--groups'
> (that's what I meant by "all known groups").
Thank you for the explanation. Reading "lists all" I expected something
like list of all info manuals in the case of M-x info RET when there are
no info buffers yet.
>> "\\`\\([^:]+\\)\\(?:::\\(.+\\)\\'\\)?"
>
> `shortdoc-display-group' already handles empty group or function.
> Replacing "*" by "+" will throw an "Args out of range" error in the
> corner case you mentioned ("shortdoc:::file"). So I think it's fine to
> keep "*" there.
Out of range error happens because of `string-match' is called despite
`match-string' failure and match groups from some earlier regexp are
applied. Generally `match-string' should be inside `if', `when', `and',
etc., however I agree that the regexp with stars always succeeds,
perhaps really matching nothing. That is why I do not insist.
The following garbage in - garbage out case is a bit confusing:
<shortdoc::*file>
=> "No such documentation group "
> ol.el: Add support for `shortdoc' link type
Bruno, has you signed the copyright form? This patch is above the
TINYCHANGE limit.
<https://orgmode.org/worg/org-contribute.html#copyright>
It will be a bit less work for the maintainer if you attach result of
"git format-patch" command. It adds email-like headers allowing to
properly set commit author.
> * lisp/ol.el: Add support for storing and inserting links to `shortdoc'
> documentation groups for Emacs Lisp functions.
List of new functions is missed:
* lisp/ol.el (org-link--open-shortdoc org-link--store-shortdoc)
(org-link--complete-shortdoc): Add support...
> * doc/org-manual.org (External Links): Add shortdoc link type
> documentation.
>
> * etc/ORG-NEWS (=ol.el=: Support for =shortdoc= link type): Document
> the new feature.
Empty line is separator before free-form comments, so list of formal
changes should be dense.
> + (condition-case nil
> + (progn
> + (shortdoc-display-group group fn)
> + (and str (not fn) (search-forward str nil t)))
> + (user-error "Unknown shortdoc group: %s" group))))
Sorry, it does not work so. It means catch `user-error' however
`shortdoc-display-group' signals `error'. Try to enable debug-on-error
and to open a broken link. Either `condition-case' should be dropped or
proper signal should be captured.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-10 11:09 ` Max Nikulin
@ 2024-05-11 16:58 ` Bruno Cardoso
2024-05-13 11:14 ` Max Nikulin
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-11 16:58 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 899 bytes --]
On 2024-05-10, 18:09 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> Thank you for the explanation. Reading "lists all" I expected something
> like list of all info manuals in the case of M-x info RET when there are
> no info buffers yet.
I see. I replaced the term "lists all" with "shows all" to avoid this confusion.
> The following garbage in - garbage out case is a bit confusing:
> <shortdoc::*file>
> => "No such documentation group "
Fixed the error handling and the error message.
> Bruno, has you signed the copyright form? This patch is above the
> TINYCHANGE limit.
> <https://orgmode.org/worg/org-contribute.html#copyright>
I haven't yet. Will be glad to.
> It will be a bit less work for the maintainer if you attach result of
> "git format-patch" command. It adds email-like headers allowing to
> properly set commit author.
The attached patch is now in this format.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 5100 bytes --]
From 57ab6be64e227fcab24ad4c5b84873ed4e946cff Mon Sep 17 00:00:00 2001
From: Bruno Cardoso <cardoso.bc@gmail.com>
Date: Sat, 11 May 2024 13:42:56 -0300
Subject: [PATCH] Add support for shortdoc link type
ol.el: Add support for `shortdoc' link type
* lisp/ol.el (org-link--open-shortdoc org-link--store-shortdoc)
(org-link--complete-shortdoc): Add support for storing and inserting links
to `shortdoc' documentation groups for Emacs Lisp functions.
* doc/org-manual.org (External Links): Add shortdoc link type
documentation.
* etc/ORG-NEWS (=ol.el=: Support for =shortdoc= link type): Document
the new feature.
---
doc/org-manual.org | 11 +++++++++++
etc/ORG-NEWS | 5 +++++
lisp/ol.el | 41 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 57 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index f9d4c9a3f..8e99652b5 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3382,6 +3382,15 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ shows all known
+ documentation groups.
+
+ For more information, see [[info:emacs#Name Help][Name Help]]
+ and [[info:elisp#Documentation Groups][Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3423,6 +3432,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 36eeddda1..9b7ba96ba 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1428,6 +1428,11 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index 3d64b41b0..6b84957f4 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,7 +1582,47 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\)\\'\\)?" path)
+ (let* ((group (match-string 1 path))
+ (str (match-string 2 path))
+ (fn (and str
+ (eq ?# (string-to-char str))
+ (intern-soft (substring str 1)))))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group fn)
+ (and str (not fn) (search-forward str nil t)))
+ (error (message "Unknown shortdoc group or malformed link: `%s'"
+ path)))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
--
2.45.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-11 16:58 ` Bruno Cardoso
@ 2024-05-13 11:14 ` Max Nikulin
2024-05-13 13:04 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-13 11:14 UTC (permalink / raw)
To: Bruno Cardoso, emacs-orgmode
On 11/05/2024 23:58, Bruno Cardoso wrote:
> On 2024-05-10, 18:09 +0700, Max Nikulin wrote:
>> <https://orgmode.org/worg/org-contribute.html#copyright>
>
> I haven't yet. Will be glad to.
I hope, next patch revision will be the final one, so it can be
notification that the procedure is completed. (Rebase to main HEAD might
be necessary.)
> The attached patch is now in this format.
> +++ b/lisp/ol.el
> @@ -1582,7 +1582,47 @@ PATH is a symbol name, as a string."
> :follow #'org-link--open-help
> :store #'org-link--store-help)
>
Sorry, but did you manually edit the patch?
git apply /tmp/org/0001-ol-support-for-shortdoc-link-type.patch
error: patch failed: lisp/ol.el:1582
error: lisp/ol.el: patch does not apply
and I see only 6 context lines, not 7.
> + (condition-case nil
> + (progn
> + (shortdoc-display-group group fn)
> + (and str (not fn) (search-forward str nil t)))
> + (error (message "Unknown shortdoc group or malformed link: `%s'"
> + path)))))
If you wish to use `user-error' as in earlier revisions then you may use
(error (user-error "Unknown shortdoc group or malformed link: `%s'"
path)))))
An alternative might be something like (feel free to ignore)
(condition-case err
;; ...
(error (signal 'user-error (cdr err)))) ; more )
to preserve message generated by `shortdoc-display-group'.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-13 11:14 ` Max Nikulin
@ 2024-05-13 13:04 ` Bruno Cardoso
2024-05-16 10:58 ` Max Nikulin
2024-06-05 15:37 ` Max Nikulin
0 siblings, 2 replies; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-13 13:04 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 791 bytes --]
On 2024-05-13, 18:14 +0700, Max Nikulin <manikulin@gmail.com> wrote:
> Sorry, but did you manually edit the patch?
I didn't. I generated it again and applied without errors.
> If you wish to use `user-error' as in earlier revisions then you may use
>
> (error (user-error "Unknown shortdoc group or malformed link: `%s'"
> path)))))
Thanks, changed it.
> An alternative might be something like (feel free to ignore)
>
> (condition-case err
> ;; ...
> (error (signal 'user-error (cdr err)))) ; more )
>
> to preserve message generated by `shortdoc-display-group'.
The error message generated by `shortdoc-display-group' may be vague when group is empty ("No such documentation group "), which might be the result of a malformed link.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 5107 bytes --]
From beceb1b17d1c019cfeb987276e5a234c8f280e6b Mon Sep 17 00:00:00 2001
From: Bruno Cardoso <cardoso.bc@gmail.com>
Date: Mon, 13 May 2024 09:42:19 -0300
Subject: [PATCH] Add support for shortdoc link type
ol.el: Add support for `shortdoc' link type
* lisp/ol.el (org-link--open-shortdoc org-link--store-shortdoc)
(org-link--complete-shortdoc): Add support for storing and inserting links
to `shortdoc' documentation groups for Emacs Lisp functions.
* doc/org-manual.org (External Links): Add shortdoc link type
documentation.
* etc/ORG-NEWS (=ol.el=: Support for =shortdoc= link type): Document
the new feature.
---
doc/org-manual.org | 11 +++++++++++
etc/ORG-NEWS | 5 +++++
lisp/ol.el | 41 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 57 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index e3a2c9b70..c4873a79b 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3382,6 +3382,15 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ shows all known
+ documentation groups.
+
+ For more information, see [[info:emacs#Name Help][Name Help]]
+ and [[info:elisp#Documentation Groups][Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3423,6 +3432,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index ff58833d7..910f534ac 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1467,6 +1467,11 @@ place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
The old name is obsolete.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** New functions and changes in function arguments
*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
diff --git a/lisp/ol.el b/lisp/ol.el
index 3d64b41b0..5468a1939 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,47 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\)\\'\\)?" path)
+ (let* ((group (match-string 1 path))
+ (str (match-string 2 path))
+ (fn (and str
+ (eq ?# (string-to-char str))
+ (intern-soft (substring str 1)))))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group fn)
+ (and str (not fn) (search-forward str nil t)))
+ (error (user-error "Unknown shortdoc group or malformed link: `%s'"
+ path)))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (eq major-mode 'shortdoc-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
--
2.45.0
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-13 13:04 ` Bruno Cardoso
@ 2024-05-16 10:58 ` Max Nikulin
2024-05-17 14:55 ` Bruno Cardoso
2024-06-05 15:37 ` Max Nikulin
1 sibling, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-05-16 10:58 UTC (permalink / raw)
To: Bruno Cardoso, emacs-orgmode
On 13/05/2024 20:04, Bruno Cardoso wrote:
> On 2024-05-13, 18:14 +0700, Max Nikulin wrote:
>
>> Sorry, but did you manually edit the patch?
>
> I didn't. I generated it again and applied without errors.
Thank you. Now your patch can be applied on my side as well.
Please, proceed with the copyright agreement form.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-16 10:58 ` Max Nikulin
@ 2024-05-17 14:55 ` Bruno Cardoso
2024-06-04 23:59 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-05-17 14:55 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
On 2024-05-16, 17:58 +0700, Max Nikulin <manikulin@gmail.com> wrote:
>
> Thank you. Now your patch can be applied on my side as well.
>
> Please, proceed with the copyright agreement form.
Thank you very much, Max. Just sent the form.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-17 14:55 ` Bruno Cardoso
@ 2024-06-04 23:59 ` Bruno Cardoso
2024-06-05 15:14 ` Ihor Radchenko
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-06-04 23:59 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
On 2024-05-17, 11:55 -0300, Bruno Cardoso <cardoso.bc@gmail.com> wrote:
> On 2024-05-16, 17:58 +0700, Max Nikulin <manikulin@gmail.com> wrote:
>>
>> Thank you. Now your patch can be applied on my side as well.
>>
>> Please, proceed with the copyright agreement form.
>
> Thank you very much, Max. Just sent the form.
Hi all. My copyright assignment with the FSF is complete.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-06-04 23:59 ` Bruno Cardoso
@ 2024-06-05 15:14 ` Ihor Radchenko
2024-06-05 21:15 ` Bastien Guerry
0 siblings, 1 reply; 28+ messages in thread
From: Ihor Radchenko @ 2024-06-05 15:14 UTC (permalink / raw)
To: Bruno Cardoso, bzg; +Cc: Max Nikulin, emacs-orgmode
Bruno Cardoso <cardoso.bc@gmail.com> writes:
>>> Please, proceed with the copyright agreement form.
>>
>> Thank you very much, Max. Just sent the form.
>
> Hi all. My copyright assignment with the FSF is complete.
Bastien, may you please confirm?
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-05-13 13:04 ` Bruno Cardoso
2024-05-16 10:58 ` Max Nikulin
@ 2024-06-05 15:37 ` Max Nikulin
2024-06-05 22:21 ` Bruno Cardoso
1 sibling, 1 reply; 28+ messages in thread
From: Max Nikulin @ 2024-06-05 15:37 UTC (permalink / raw)
To: Bruno Cardoso, emacs-orgmode
On 13/05/2024 20:04, Bruno Cardoso wrote:
> +++ b/etc/ORG-NEWS
Bruno, I am sorry, but Org-9.7 has been released and your patch can not
be cleanly applied any more. Please, rebase it and check that the new
feature is described in the proper section for changes that have not
released yet.
A couple of notes that unlikely affect real life usage.
> + (defun org-link--store-shortdoc (&optional _interactive?)
> + "Store \"shortdoc\" type link."
> + (when (eq major-mode 'shortdoc-mode)
`derived-mode-p' is more reliable in general.
> + (let* ((buffer (buffer-name))
> + (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
> + (match-string 1 buffer))))
> + (if (and group (assoc (intern-soft group) shortdoc--groups))
> + (org-link-store-props :type "shortdoc"
> + :link (format "shortdoc:%s" group)
> + :description nil)
> + (user-error "Unknown shortdoc group: %s" group)))))
I believed that store link functions should fail silently if no suitable
link may be offered.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-06-05 15:14 ` Ihor Radchenko
@ 2024-06-05 21:15 ` Bastien Guerry
0 siblings, 0 replies; 28+ messages in thread
From: Bastien Guerry @ 2024-06-05 21:15 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Bruno Cardoso, Max Nikulin, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Bruno Cardoso <cardoso.bc@gmail.com> writes:
>>>> Please, proceed with the copyright agreement form.
>>>
>>> Thank you very much, Max. Just sent the form.
>>
>> Hi all. My copyright assignment with the FSF is complete.
>
> Bastien, may you please confirm?
I do. Thanks Bruno for contributing!
--
Bastien Guerry
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-06-05 15:37 ` Max Nikulin
@ 2024-06-05 22:21 ` Bruno Cardoso
2024-06-06 11:53 ` Ihor Radchenko
0 siblings, 1 reply; 28+ messages in thread
From: Bruno Cardoso @ 2024-06-05 22:21 UTC (permalink / raw)
To: Max Nikulin, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 395 bytes --]
On 2024-06-05, 22:37 +0700, Max Nikulin <manikulin@gmail.com> wrote:
>
> A couple of notes that unlikely affect real life usage.
>
>> + (defun org-link--store-shortdoc (&optional _interactive?)
>> + "Store \"shortdoc\" type link."
>> + (when (eq major-mode 'shortdoc-mode)
>
> `derived-mode-p' is more reliable in general.
Fixed.
The attached patch is now rebased to new Org version.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ol-support-for-shortdoc-link-type.patch --]
[-- Type: text/x-patch, Size: 4978 bytes --]
From 43de471e577d530ea76dc48460efea12864b5675 Mon Sep 17 00:00:00 2001
From: bruno <cardoso.bc@gmail.com>
Date: Wed, 5 Jun 2024 19:14:36 -0300
Subject: [PATCH] Add support for shortdoc link type
ol.el: Add support for `shortdoc' link type
* lisp/ol.el (org-link--open-shortdoc org-link--store-shortdoc)
(org-link--complete-shortdoc): Add support for storing and inserting links
to `shortdoc' documentation groups for Emacs Lisp functions.
* doc/org-manual.org (External Links): Add shortdoc link type
documentation.
* etc/ORG-NEWS (=ol.el=: Support for =shortdoc= link type): Document
the new feature.
---
doc/org-manual.org | 11 +++++++++++
etc/ORG-NEWS | 5 +++++
lisp/ol.el | 41 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 57 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 170eea506..e931e1cc1 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3393,6 +3393,15 @@ Here is the full set of built-in link types:
Execute a shell command upon activation.
+- =shortdoc= ::
+
+ Link to short documentation summary for an Emacs Lisp function group.
+ Since Emacs 28, user command ~shortdoc-display-group~ shows all known
+ documentation groups.
+
+ For more information, see [[info:emacs#Name Help][Name Help]]
+ and [[info:elisp#Documentation Groups][Documentation Groups]].
+
For =file:= and =id:= links, you can additionally specify a line
number, or a text search string, separated by =::=. In Org files, you
@@ -3434,6 +3443,8 @@ options:
| irc | =irc:/irc.com/#emacs/bob= |
| help | =help:org-store-link= |
| info | =info:org#External links= |
+| shortdoc | =shortdoc:text-properties= |
+| | =shortdoc:text-properties::#get-pos-property= |
| shell | =shell:ls *.org= |
| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) |
| | =elisp:org-agenda= (interactive Elisp command) |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 4b0b77ca8..a8f3a37f6 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -40,6 +40,11 @@ all the references are resolved in the generated png.
# This also includes changes in function behavior from Elisp perspective.
+*** =ol.el=: Support for =shortdoc= link type
+
+Add support for storing and inserting links to =shortdoc= documentation
+groups for Emacs Lisp functions.
+
** Miscellaneous
* Version 9.7
diff --git a/lisp/ol.el b/lisp/ol.el
index 20f1b89c0..4cda0cb60 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1582,6 +1582,47 @@ PATH is a symbol name, as a string."
:follow #'org-link--open-help
:store #'org-link--store-help)
+;;;; "shortdoc" link type
+(when (version<= "28.0.90" emacs-version)
+ (defun org-link--open-shortdoc (path _)
+ "Open a \"shortdoc\" type link.
+PATH is a group name, \"group::#function\" or \"group::search string\"."
+ (string-match "\\`\\([^:]*\\)\\(?:::\\(.*\\)\\'\\)?" path)
+ (let* ((group (match-string 1 path))
+ (str (match-string 2 path))
+ (fn (and str
+ (eq ?# (string-to-char str))
+ (intern-soft (substring str 1)))))
+ (condition-case nil
+ (progn
+ (shortdoc-display-group group fn)
+ (and str (not fn) (search-forward str nil t)))
+ (error (user-error "Unknown shortdoc group or malformed link: `%s'"
+ path)))))
+
+ (defun org-link--store-shortdoc (&optional _interactive?)
+ "Store \"shortdoc\" type link."
+ (when (derived-mode-p 'org-mode)
+ (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc \\(.*\\)\\*" buffer)
+ (match-string 1 buffer))))
+ (if (and group (assoc (intern-soft group) shortdoc--groups))
+ (org-link-store-props :type "shortdoc"
+ :link (format "shortdoc:%s" group)
+ :description nil)
+ (user-error "Unknown shortdoc group: %s" group)))))
+
+ (defun org-link--complete-shortdoc ()
+ "Create a \"shortdoc\" link using completion."
+ (concat "shortdoc:"
+ (completing-read "Shortdoc summary for functions in: "
+ (mapcar #'car shortdoc--groups))))
+
+ (org-link-set-parameters "shortdoc"
+ :follow #'org-link--open-shortdoc
+ :store #'org-link--store-shortdoc
+ :complete #'org-link--complete-shortdoc))
+
;;;; "http", "https", "mailto", "ftp", and "news" link types
(dolist (scheme '("ftp" "http" "https" "mailto" "news"))
(org-link-set-parameters scheme
--
2.45.1
^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-06-05 22:21 ` Bruno Cardoso
@ 2024-06-06 11:53 ` Ihor Radchenko
2024-06-06 23:11 ` Bruno Cardoso
0 siblings, 1 reply; 28+ messages in thread
From: Ihor Radchenko @ 2024-06-06 11:53 UTC (permalink / raw)
To: Bruno Cardoso; +Cc: Max Nikulin, emacs-orgmode
Bruno Cardoso <cardoso.bc@gmail.com> writes:
> The attached patch is now rebased to new Org version.
Thanks!
Applied, onto main, with amendments.
I re-worded the manual and news entries, moved the news entry to new
features, addressed compiler warnings, and added a FIXME marking the
Emacs version check for removal when we drop Emacs 27 support.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=55e8068d6
I also added you to our contributor list.
https://git.sr.ht/~bzg/worg/commit/392644ae
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH] Add support for shortdoc link type
2024-06-06 11:53 ` Ihor Radchenko
@ 2024-06-06 23:11 ` Bruno Cardoso
0 siblings, 0 replies; 28+ messages in thread
From: Bruno Cardoso @ 2024-06-06 23:11 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Max Nikulin, emacs-orgmode
On 2024-06-06, 11:53 +0000, Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Thanks!
> Applied, onto main, with amendments.
> I re-worded the manual and news entries, moved the news entry to new
> features, addressed compiler warnings, and added a FIXME marking the
> Emacs version check for removal when we drop Emacs 27 support.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=55e8068d6
>
> I also added you to our contributor list.
> https://git.sr.ht/~bzg/worg/commit/392644ae
Thank you!
^ permalink raw reply [flat|nested] 28+ messages in thread
end of thread, other threads:[~2024-06-06 23:12 UTC | newest]
Thread overview: 28+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-05-01 3:29 [PATCH] Add support for shortdoc link type Bruno Cardoso
2024-05-01 11:00 ` Ihor Radchenko
2024-05-01 16:52 ` Bruno Cardoso
2024-05-01 17:55 ` Ihor Radchenko
2024-05-01 19:24 ` Bruno Cardoso
2024-05-02 10:41 ` Max Nikulin
2024-05-03 21:41 ` Bruno Cardoso
2024-05-04 7:38 ` Max Nikulin
2024-05-04 17:33 ` Bruno Cardoso
2024-05-05 11:01 ` Max Nikulin
2024-05-05 21:35 ` Bruno Cardoso
2024-05-06 10:55 ` Max Nikulin
2024-05-08 1:11 ` Bruno Cardoso
2024-05-08 11:20 ` Max Nikulin
2024-05-08 21:26 ` Bruno Cardoso
2024-05-10 11:09 ` Max Nikulin
2024-05-11 16:58 ` Bruno Cardoso
2024-05-13 11:14 ` Max Nikulin
2024-05-13 13:04 ` Bruno Cardoso
2024-05-16 10:58 ` Max Nikulin
2024-05-17 14:55 ` Bruno Cardoso
2024-06-04 23:59 ` Bruno Cardoso
2024-06-05 15:14 ` Ihor Radchenko
2024-06-05 21:15 ` Bastien Guerry
2024-06-05 15:37 ` Max Nikulin
2024-06-05 22:21 ` Bruno Cardoso
2024-06-06 11:53 ` Ihor Radchenko
2024-06-06 23:11 ` Bruno Cardoso
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.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).