* [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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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; 21+ 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] 21+ 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 0 siblings, 1 reply; 21+ 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] 21+ 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 0 siblings, 1 reply; 21+ 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] 21+ 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 0 siblings, 0 replies; 21+ 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] 21+ messages in thread
end of thread, other threads:[~2024-05-17 14:57 UTC | newest] Thread overview: 21+ 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
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).