Re: [PATCH] Add support for shortdoc link type

[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:
- <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]].