Re: [PATCH] Add support for shortdoc link type

2024-06-06 Thread Bruno Cardoso 


On 2024-06-06, 11:53 +, Ihor Radchenko  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!

Re: [PATCH] Add support for shortdoc link type

2024-06-06 Thread Ihor Radchenko 
Bruno Cardoso  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 .
Support Org development at ,
or support my work at

Re: [PATCH] Add support for shortdoc link type

2024-06-05 Thread Bruno Cardoso 

On 2024-06-05, 22:37 +0700, Max Nikulin  wrote:
>
> A couple of notes that unlikely affect real life usage.
>
>> +  (defun org-link--store-shortdoc ( _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.

>From 43de471e577d530ea76dc48460efea12864b5675 Mon Sep 17 00:00:00 2001
From: bruno 
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 ( _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."
+(conca

Re: [PATCH] Add support for shortdoc link type

2024-06-05 Thread Bastien Guerry 
Ihor Radchenko  writes:

> Bruno Cardoso  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

Re: [PATCH] Add support for shortdoc link type

2024-06-05 Thread Max Nikulin 

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

Re: [PATCH] Add support for shortdoc link type

2024-06-05 Thread Ihor Radchenko 
Bruno Cardoso  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 .
Support Org development at ,
or support my work at

Re: [PATCH] Add support for shortdoc link type

2024-06-04 Thread Bruno Cardoso 


On 2024-05-17, 11:55 -0300, Bruno Cardoso  wrote:

> On 2024-05-16, 17:58 +0700, Max Nikulin  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.

Re: [PATCH] Add support for shortdoc link type

2024-05-17 Thread Bruno Cardoso 


On 2024-05-16, 17:58 +0700, Max Nikulin  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.

Re: [PATCH] Add support for shortdoc link type

2024-05-16 Thread Max Nikulin 

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.

Re: [PATCH] Add support for shortdoc link type

2024-05-13 Thread Bruno Cardoso 

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.

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

>From beceb1b17d1c019cfeb987276e5a234c8f280e6b Mon Sep 17 00:00:00 2001
From: Bruno Cardoso 
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 ( _interactive?)
+"Store \"shortdoc\" type link."
+(when (eq major-mode 'shortdoc-mode)
+  (let* ((buffer (buffer-name))
+ (group (when (string-match "*Shortdoc

Re: [PATCH] Add support for shortdoc link type

2024-05-13 Thread Max Nikulin 

On 11/05/2024 23:58, Bruno Cardoso wrote:

On 2024-05-10, 18:09 +0700, Max Nikulin wrote:




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

Re: [PATCH] Add support for shortdoc link type

2024-05-11 Thread Bruno Cardoso 

On 2024-05-10, 18:09 +0700, Max Nikulin  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:
> 
> => "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.

>From 57ab6be64e227fcab24ad4c5b84873ed4e946cff Mon Sep 17 00:00:00 2001
From: Bruno Cardoso 
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 ( _interactive?)
+"Store \"shortdoc\" type link."
+(when (eq m

Re: [PATCH] Add support for shortdoc link type

2024-05-10 Thread Max Nikulin 

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:

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



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.

Re: [PATCH] Add support for shortdoc link type

2024-05-08 Thread Bruno Cardoso 

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"). 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  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!

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 ( _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

Re: [PATCH] Add support for shortdoc link type

2024-05-08 Thread Max Nikulin 

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


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

Re: [PATCH] Add support for shortdoc link type

2024-05-07 Thread Bruno Cardoso 

On 2024-05-06, 17:55 +0700, Max Nikulin  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:
> -  that may be handled solely by 
> `shortdoc-display-group' with second argument.
> -  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]]

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 ( _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

Re: [PATCH] Add support for shortdoc link type

2024-05-06 Thread Max Nikulin 

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:
-  that may be handled solely by 
`shortdoc-display-group' with second argument.

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

Re: [PATCH] Add support for shortdoc link type

2024-05-05 Thread Bruno Cardoso 

On 2024-05-05, 18:01 +0700, Max Nikulin  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.  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'.

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 ( _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

Re: [PATCH] Add support for shortdoc link type

2024-05-05 Thread Max Nikulin 

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

Re: [PATCH] Add support for shortdoc link type

2024-05-04 Thread Bruno Cardoso 

On 2024-05-04, 14:38 +0700, Max Nikulin  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.

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 ( _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

Re: [PATCH] Add support for shortdoc link type

2024-05-04 Thread Max Nikulin 

On 04/05/2024 04:41, Bruno Cardoso wrote:

On 2024-05-02, 17:41 +0700, Max Nikulin wrote:




[...]

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.

Re: [PATCH] Add support for shortdoc link type

2024-05-03 Thread Bruno Cardoso 


On 2024-05-02, 17:41 +0700, Max Nikulin  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.
>
> 
>
> - 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.

Re: [PATCH] Add support for shortdoc link type

2024-05-02 Thread Max Nikulin 

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.




- At first I considered adding shortdoc to help links that may call 
either `describe-function' or `describe-variable', but it is unlikely 
possible.

Re: [PATCH] Add support for shortdoc link type

2024-05-01 Thread Bruno Cardoso 

On 2024-05-01, 17:55 +, Ihor Radchenko  wrote:

> Bruno Cardoso  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 ( _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.

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 ( _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"))

Re: [PATCH] Add support for shortdoc link type

2024-05-01 Thread Ihor Radchenko 
Bruno Cardoso  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 ( _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 .
Support Org development at ,
or support my work at

Re: [PATCH] Add support for shortdoc link type

2024-05-01 Thread Bruno Cardoso 

Hi Ihor,

Thanks for your comments. See attached the updated patch.

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 ( _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


On 2024-05-01, 11:00 +, Ihor Radchenko  wrote:

> Bruno Cardoso  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 .
> Support Org development at ,
> or support my work at

Re: [PATCH] Add support for shortdoc link type

2024-05-01 Thread Ihor Radchenko 
Bruno Cardoso  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 .
Support Org development at ,
or support my work at

[PATCH] Add support for shortdoc link type

2024-04-30 Thread Bruno Cardoso 

Hi all,

This patch adds support for "shortdoc:" links.

Best,

Bruno.

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 ( _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