Subject: bug#76992: Docs lack sufficient examples of programmatic use-cases ....

From: Mats Lidell <[email-masked]>
Date: Thu, 13 Mar 2025 22:29:58 +0100

Hi Keith,

Thanks for your interest in Hyperbole.

> Keith David Bershatsky writes:
> Dear Support:
>
> The docs lack sufficient examples of programmatic use-cases ....

Agreed. We have focused on trying to make it easier for non programmers. My
presentation on Emacs Conf 2022 is an example of that
(https://emacsconf.org/2022/talks/buttons/). It mentions defib once but that
is all.

There are unfortunately no coding examples on how to use defib. The info pages
explains defib here: "(hyperbole)Programmatic Implicit Button Types". As for
examples you will have to look at the internal usage of defib in the Hyperbole
sources themselves.  There are over 40 definitions to look at but requires you
to scan through the code.

> Here is something that I could not have figured out without a stroke
> of luck by locating one (1) lone example on Google of a use-case with
> link-to-string-match, a clip from a video tutorial, and a portion of
> the doc string of defil.  The following reddit thread describes my
> journey down the rabbit hole, and the only response after 12 hours has
> been from one participant who said he/she recommends not using
> Hyperbole for this particular use-case ...
>
> https://www.reddit.com/r/emacs/comments/1j9pohx/hyperbole_jump_to_unique_id_in_file_nonorg/?ref=share&ref_source=link

I'm sorry. I don't follow redit so things there is missed by me. Could you
consider to ask questions on the hyperbole-users mail list?

> In fact, there was only one thread that I found from about 21 years
> ago that was remotely on-point, but there were no examples posted of
> the eventual solution by the OP ...
>
> Glad that I found / wrote the solution I needed, and I am looking
> forward to using this package in the future.  As it stands now,
> customization of this package appears to be only for expert
> programmers who can figure most of it out just by studying the code.
> Thank God and Google!

I'm happy you found a solution.

We'll see what we can do to the improve the docs for using the programming
features in coming releases.

Yours
-- 
%% Mats