[feature request] Integrate with shortdoc (new with 28.1)

Thank you for this package. A feature request or a request for discussion.

Emacs 28.1 has introduced the shortdoc feature. From the NEWS file:

* New system for displaying documentation for groups of functions. This can either be used by saying 'M-x shortdoc-display-group' and choosing a group, or clicking a button in the "Help*" buffers when looking at the doc string of a function that belongs to one of these groups.

In shortdoc, I like how related functions are grouped into themes like "sequence" or "alist". Also there is a capability to add "sections". I do not like how shortcut function buttons automatically opens to the Info manual (info-lookup-symbol function 'emacs-lisp-mode). It should just do a describe-function or helpful-function.

Desired new functionality:

(feature 1) Add elisp-demos to existing shortdoc entries (like seq-contains-p), in an optional way.
(feature 2) Reuse shortdoc examples into elisp-demos, in an optional way.
(feature 3) Group non-grouped functions via elisp-demos.el, in an optional way.

Feature 1: Directly showing a elisp-demo example alongside a shortdoc feature render would be great. I would mitigate this feature request by overriding the button to just show the result of describe-function or helpful-function.

Feature 2: Since elisp-demos are only shown in describe-function or helpful-function result buffers, and those buffers already show a link to the shortcut group, discoverability of the shortdoc example is only slightly enhanced.

Feature 3: This perhaps is not functionality that elisp-demos needs to support, but it would be nice. I notice despite cl-lib.el being a built-in library, there is no shortdoc. How would elisp-demos support this feature? In either elisp-demos.org or a new file, have a way to easily to say this feature belongs to a group and an optional section. If a non-shortdoc package becomes supported officially, the official support would take precedence. Also adding this support would make elisp-demos a place to collect the grouping/sectioning efforts of the community together.

Also shortdoc doesn't seem to require that a function belong to one group or subsection, so any associations defined by elisp-demos can be alternately offered as separate group, like "elisp-demos-sequence" or "user/sequence".

Since package authors sometimes offer an info file, the grouping of functions in the info file can be reused. Ultimately it would probably be better for the package author to support shortdoc directly, though.

I have a rough working draft of feature 1 "Add elisp-demos to existing shortdoc entries (like seq-contains-p), in an optional way". The results look unformatted but it's a step closer. Try it with group "number", "buffer" and "text-properties".

Example:

(/ number &rest divisors) Divide number by divisors and return the result. (/ 10 5) ⇒ 2 (/ 10 6) ⇒ 1 (/ 10.0 6) ⇒ 1.6666666666666667 (/ 10.0 3 3) ⇒ 1.1111111111111112 (/ 6 2) ⇒ "elisp-demos result: 3" (list (/ 3 2) (/ 3 2.0)) ⇒ "elisp-demos result: (1 1.5)"

Example:

(next-property-change position &optional object limit) Return the position of next property change. (next-property-change (point) (current-buffer)) (next-property-change 0 "hello") ⇒ "elisp-demos result: nil" (next-property-change 0 (concat "hello" (propertize "world" 'world t))) ⇒ "elisp-demos result: 5"

It also replaces the lookup button jump to Info to jump to describe-function.

(use-package shortdoc
  :config
  (defvar shortdoc-use-elisp-demos t)
  (defun shortdoc--advice-always-describe-function (data)
    "Override shortdoc default functionality."
    (let* ((new-data (copy-tree data)))
      (setf (cdar new-data)
            (append (cdar new-data)
                    (list :no-manual t)))
      ;; try to add new
      (when shortdoc-use-elisp-demos
        (require 'elisp-demos)
        (shortdoc--add-from-elisp-demos new-data))
      new-data))

  (defun shortdoc--add-from-elisp-demos (data)
    (when-let* ((edorg (elisp-demos--search (caar data))))
      (with-temp-buffer
        (insert edorg)
        (goto-char (point-min))
        ;; FIXME: use org functions to parse
        (while (search-forward "#+BEGIN_SRC" nil t)
          (let* (example-start example-end exam)
            (setq example-start (goto-char (1+ (line-end-position))))
            (search-forward "#+END_SRC" nil t)
            (setq example-end (1- (line-beginning-position)))
            (setq exam (string-trim
                        (buffer-substring-no-properties example-start example-end)))
            ;; do not use plist-set, for duplicates
            (setf (cdar data) (append (cdar data)
                                      (list :no-eval exam))))

          (let (results-start results)
            (when (search-forward "#+RESULTS:" nil t)
              (setq results-start (goto-char (1+ (line-end-position))))
              ;; FIXME: trying to parse #+RESULTS: is hard for now, so give up
              ;; pattern : (can be multiline!)
              ;; pattern #+BEGIN_EXAMPLE
              ;; pattern #+BEGIN_SRC
              ;; pattern | (a table)
              ;; FIXME: see re-search-forward results
              (cond (t
                     (let* ((found-next (point-max)))
                       (save-excursion
                         (when (search-forward "#+BEGIN_SRC" nil t)
                           (setq found-next (1- (line-beginning-position)))))
                       (setq result
                             (concat "elisp-demos result: " ;; FIXME
                                     (string-trim (buffer-substring (+ 2 (point)) found-next)))))))

              (setf (cdar data) (append (cdar data)
                                        (list :result result)))))))))

  (advice-add 'shortdoc--display-function :filter-args
              'shortdoc--advice-always-describe-function))

Wow, thanks for the idea. Unfortunately, I'm struggling with my job and life, thus I don't have extra energy for the project in one month or so. I've invited you to become collaborator to the project, if you accept the invitation then you should be able manage the project. but please feel free to reject the invitation if you don't want to.

xuchunyang / elisp-demos

[feature request] Integrate with shortdoc (new with 28.1) #14