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

Message received at 76992 <at> debbugs.gnu.org:

Received: (at 76992) by debbugs.gnu.org; 13 Mar 2025 21:30:12 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Mar 13 17:30:12 2025
Received: from localhost ([127.0.0.1]:58555 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1tsq84-0006pP-34
	for submit <at> debbugs.gnu.org; Thu, 13 Mar 2025 17:30:12 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:35046)
 by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.84_2) (envelope-from <matsl@HIDDEN>) id 1tsq81-0006iV-BS
 for 76992 <at> debbugs.gnu.org; Thu, 13 Mar 2025 17:30:10 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <matsl@HIDDEN>)
 id 1tsq7u-0001aP-Gk; Thu, 13 Mar 2025 17:30:03 -0400
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
 s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To:
 From; bh=yvNeq5NudVsGNFKqCC6bMer3vYQA3Rlqdd5mfTULAUo=; b=RQiZMEoWSwQBvJ3Z+EL0
 ZF7R8fgdMJS8uVA334+7B5BfpDWLKqxvrvKEURvRis8xxJSx0C7QEjZWkJeLuvMKovxPsuRi04fJe
 x5tr78CcuB83QFrM2xJAiBap0YE/yXpgGA4nhww/HUzzsty/DBL2MZdzhMh/Vs/Eyfc2b86njwxBT
 vitWizoriRCwIowbyLkGM/1MycuwfZ5GorBA5I1js4VmaD9BC7h9N2m5+/xg07MaENYTFPapUpp7g
 O2gj7wHWbfjtKs//EZDRTLsEm0LtNf5/oMUYsXfLdSEFNngHv26KYjPJsZlP59GqWcMib7E5swCCO
 5NFS63jm9iLnog==;
From: Mats Lidell <matsl@HIDDEN>
To: Keith David Bershatsky <esq@HIDDEN>
Subject: Re: bug#76992: Docs lack sufficient examples of programmatic
 use-cases ....
In-Reply-To: <87v7sdmu9j.wl%esq@HIDDEN>
References: <87v7sdmu9j.wl%esq@HIDDEN>
Date: Thu, 13 Mar 2025 22:29:58 +0100
Message-ID: <87cyek1uw9.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 76992
Cc: 76992 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

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

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 13 Mar 2025 04:26:11 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Mar 13 00:26:11 2025
Received: from localhost ([127.0.0.1]:52696 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1tsa95-0000qg-9b
	for submit <at> debbugs.gnu.org; Thu, 13 Mar 2025 00:26:11 -0400
Received: from lists.gnu.org ([2001:470:142::17]:52226)
 by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.84_2) (envelope-from <esq@HIDDEN>) id 1tsa92-0000qR-TJ
 for submit <at> debbugs.gnu.org; Thu, 13 Mar 2025 00:26:09 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <esq@HIDDEN>) id 1tsa8x-0003ob-9I
 for bug-hyperbole@HIDDEN; Thu, 13 Mar 2025 00:26:03 -0400
Received: from omta36.uswest2.a.cloudfilter.net ([35.89.44.35])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <esq@HIDDEN>) id 1tsa8v-0004qO-5x
 for bug-hyperbole@HIDDEN; Thu, 13 Mar 2025 00:26:02 -0400
Received: from eig-obgw-6004a.ext.cloudfilter.net ([10.0.30.197])
 by cmsmtp with ESMTPS
 id sZjnt3FCMMETlsa8gt2Zca; Thu, 13 Mar 2025 04:25:46 +0000
Received: from gator3053.hostgator.com ([50.87.144.69]) by cmsmtp with ESMTPS
 id sa8ft8hLQlqdtsa8ftXANA; Thu, 13 Mar 2025 04:25:45 +0000
X-Authority-Analysis: v=2.4 cv=JIzwsNKb c=1 sm=1 tr=0 ts=67d25e49
 a=rBgtZlU+0z8E5/GFQ55d2w==:117 a=NjPzZg3MCp/4jU+Frw/LwQ==:17
 a=kj9zAlcOel0A:10 a=Vs1iUdzkB0EA:10 a=rdHWtVfCDxwA:10 a=PjuYqXk4AAAA:8
 a=xzrfmH8qt5ixZMhzPU8A:9 a=CjuIK1q_8ugA:10 a=jozpo1UKehchOViSjio2:22
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lawlist.com
 ; s=default;
 h=Content-Type:MIME-Version:Subject:To:From:Message-ID:Date:
 Sender:Reply-To:Cc:Content-Transfer-Encoding:Content-ID:Content-Description:
 Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:
 In-Reply-To:References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:
 List-Post:List-Owner:List-Archive;
 bh=7XA+LIbL/2k5pjCgqW5OBTEwXU2aSgFmNO+nYIl+VgY=; b=gN49G0ydOdN8w4Upolpe5YFHAK
 1pdeYK/TnHYmJ8msop3lKS/LaLJfA5IvLgsgV+3HhalMKu3pBqKT62rT1BFpGm7ED8c7uIJLa2Gtp
 wnDvITUlxH2pf5d0hCzA4BkXKo/OFLQBBpQ7Y5jy+L6Uei6DrFcytt1MIA5kLQpHY/ACwmUS7WYDe
 5zXzmDbdzO80TxNtlhIRTRfB3T45Cvb575xU4o6ywqgSosE0gKf3+kLErvV5RlW3SYbGJWmV6BQmt
 XL4fXb/3ugKBxHHKp5RYl3mb8uxp5JG4oS9pW76uEtYbINo3pmIFZNYDlCid6fJvj5ufjQkpPjXQO
 2x9xGwlg==;
Received: from syn-045-048-245-070.res.spectrum.com ([45.48.245.70]:40843
 helo=debian) by gator3053.hostgator.com with esmtpsa (TLS1.2) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.98.1)
 (envelope-from <esq@HIDDEN>) id 1tsa8e-00000001mp7-3JpY
 for bug-hyperbole@HIDDEN; Wed, 12 Mar 2025 23:25:44 -0500
Date: Wed, 12 Mar 2025 21:25:44 -0700
Message-ID: <87v7sdmu9j.wl%esq@HIDDEN>
From: Keith David Bershatsky <esq@HIDDEN>
To: bug-hyperbole@HIDDEN
Subject: Docs lack sufficient examples of programmatic use-cases ....
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
X-AntiAbuse: This header was added to track abuse,
 please include it with any abuse report
X-AntiAbuse: Primary Hostname - gator3053.hostgator.com
X-AntiAbuse: Original Domain - gnu.org
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - lawlist.com
X-BWhitelist: no
X-Source-IP: 45.48.245.70
X-Source-L: No
X-Exim-ID: 1tsa8e-00000001mp7-3JpY
X-Source: 
X-Source-Args: 
X-Source-Dir: 
X-Source-Sender: syn-045-048-245-070.res.spectrum.com (debian)
 [45.48.245.70]:40843
X-Source-Auth: lawlist
X-Email-Count: 1
X-Org: HG=hgshared;ORG=hostgator;
X-Source-Cap: bGF3bGlzdDtsYXdsaXN0O2dhdG9yMzA1My5ob3N0Z2F0b3IuY29t
X-Local-Domain: yes
X-CMAE-Envelope: MS4xfNnMzfUsndrN8BPpqKNPOe+O5p0rX8uf8Gpv+mAtj+Guq804QjdoJ5y8TTTi/6xzG5YAGeE3OCW2j8SQ7x/yBt9bDsCqdTlyW9eE2mM802tFpST8OzRv
 /fvkN2Q1Vtz7/+Ui4gmRZISIhkjbHxO6Ti7T80w1uv67VNXb60kz35kmy/GNwT3kmtDo8IC5FTQMMhD7WX/8MGRgKG07eoV+BOw=
Received-SPF: pass client-ip=35.89.44.35; envelope-from=esq@HIDDEN;
 helo=omta36.uswest2.a.cloudfilter.net
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001,
 RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001,
 SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.0 (/)

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