GNU bug report logs - #76992
Docs lack sufficient examples of programmatic use-cases ....

Previous Next

To reply to this bug, email your comments to 76992 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Keith David Bershatsky <esq <at> lawlist.com>
To: bug-hyperbole <at> gnu.org
Subject: Docs lack sufficient examples of programmatic use-cases ....
Date: Wed, 12 Mar 2025 21:25:44 -0700

Dear Support:

The docs lack sufficient examples of programmatic use-cases ....

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

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!

Sincerely,

Keith David Bershatsky

Message #8 received at 76992 <at> debbugs.gnu.org (full text, mbox):

From: Mats Lidell <matsl <at> gnu.org>
To: Keith David Bershatsky <esq <at> lawlist.com>
Cc: 76992 <at> debbugs.gnu.org
Subject: Re: bug#76992: Docs lack sufficient examples of programmatic
 use-cases ....
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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.