xuchunyang / elisp-demos

Demonstrate Emacs Lisp APIs

Elisp API Demos

Showing an Elisp demo of mapcar in C-h f mapcar:

Usage

To inject elisp demos into *Help*, such as C-h f (M-x describe-function), use

(advice-add 'describe-function-1 :after #'elisp-demos-advice-describe-function-1)

If you use Helpful, use

(advice-add 'helpful-update :after #'elisp-demos-advice-helpful-update)

Contributing

Put your awesome Elisp demos into elisp-demos.org. A demo is simply an Org heading. Here is mapcar's.

* mapcar

#+BEGIN_SRC elisp
(mapcar #'1+ '(1 2 3))
#+END_SRC

#+RESULTS:
: (2 3 4)

You can use M-x elisp-demos-add-demo to insert a new demo or edit an existing one.

elisp-demos's Issues

Link to other functions/variables produces Buffer is read-only: #<buffer *Help*>

Is there a way to link to other functions or variables in the documentation?

demos.org

* my/function

Before you run this function make sure `my/variables' is set.

#+BEGIN_SRC elisp
(my/function :dir "~/Documents" :args nil)
#+END_SRC

In this case if I try to click on my/variables I will get:

Buffer is read-only: #<buffer *Help*>

However, if I click any documentation above the demos it will take me to the docs.

Funny thing about it is on doom the documentation link does not come up but on my vanilla
Emacs my/variables does come up as a link but clicking on it will give me read-only.

integration with testing

I end up writing tests for functions that are also incidentally demos of how those functions work. It'd be really convenient to write ert tests while simultaneously registering those tests as demos. I don't have a concrete idea of how to do this yet. But, food for thought.

elisp-demos breaks describe-key & helpful-key

elisp-demos--search throws a wrong-type-argument error when passed a closure from helpful-key or describe-key.

Steps to reproduce:

1. Advise describe-function-1 and/or helpful-update, as advised in elisp-demos' readme:

   (advice-add 'describe-function-1 :after #'elisp-demos-advice-describe-function-1)
   (advice-add 'helpful-update :after #'elisp-demos-advice-helpful-update)

2. Bind a key to a closure:

   (global-set-key (kbd "C-c ;") (lambda () (interactive) (message "Hi")))

3. Invoke describe-key or helpful-key on C-c ;.

Backtrace:

On M-x helpful-key RET C-c ;

Debugger entered--Lisp error: (wrong-type-argument symbolp (closure (t) nil (interactive) (message "Hi")))
  symbol-name((closure (t) nil (interactive) (message "Hi")))
  elisp-demos--search((closure (t) nil (interactive) (message "Hi")))
  elisp-demos-advice-helpful-update()
  apply(elisp-demos-advice-helpful-update nil)
  helpful-update()
  helpful-key("\003;")
  funcall-interactively(helpful-key "\003;")
  call-interactively(helpful-key nil nil)
  command-execute(helpful-key)

On M-x describe-key RET C-c ;

Debugger entered--Lisp error: (wrong-type-argument symbolp (closure (t) nil (interactive) (message "Hi")))
  symbol-name((closure (t) nil (interactive) (message "Hi")))
  elisp-demos--search((closure (t) nil (interactive) (message "Hi")))
  elisp-demos-advice-describe-function-1((closure (t) nil (interactive) (message "Hi")))
  apply(elisp-demos-advice-describe-function-1 (closure (t) nil (interactive) (message "Hi")))
  describe-function-1((closure (t) nil (interactive) (message "Hi")))
  describe-key("\003;" 1 nil)
  funcall-interactively(describe-key "\003;" 1 nil)
  call-interactively(describe-key record nil)
  command-execute(describe-key record)
  #f(compiled-function (cmd) #<bytecode 0x1f6f6c1>)("describe-key")
  ...

premature EOF parsing tar file

Having this issue when the package is being installed.

Contacting host: melpa.org:443
Contacting host: melpa.org:443
Parsing tar file... 
Warning: premature EOF parsing tar file
Error (use-package): Failed to install elisp-demos: Package does not untar cleanly into directory elisp-demos-20190720.1301/

Not really sure what's causing this.

Demo result of -union is wrong

#+BEGIN_SRC elisp
(-union '(1 1 2 2) '(3 2 1))
#+END_SRC

#+RESULTS:
: (1 1 2 2 3)

The correct result is (1 2 3).

[feature request] support browse demos via web

Some example:

• https://clojuredocs.org/

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

Add results and doc

Why don’t you show the result value of each expression in the Elisp API Demos. Then people could immediately have an idea of what each does, also the first line of doc or a summary would be helpful.

You shouldn’t have to run everything to get an idea of what each function does.

elisp-demo-help-find-demo-at-point couldn't use.

Making the elisp demos file a custom variable

Could the elisp demos org file be a custom variable? I'd be nice if I could conveniently make it a file of my choosing instead of editing the file that comes with the package.