Re: Emacs NYC Video Release: Bring Your Text to Life the Easy Way with GNU Hyperbole

[Eduardo Ochs]

Hi Robert,

I gave Hyperbole another try but I did not get very far... I think I'm
in the category "If the examples provided in the DEMO are insufficient
for you to create your own Hyperbole-verse, please let us know what is
missing", so here are some questions - with lots of eev links to what
I discovered; for help on the eev functions that I used visit the URL
below and click on the function names.

  http://angg.twu.net/e/hyperbole.e.html#my-email-2020sep21

So: I installed hyperbole with `M-x list-packages' and then ran this
sexp to define some functions to access the Hyperbole directory and
the info file:

  (code-c-d "hyperbole" "~/.emacs.d/elpa/hyperbole-7.1.2/" "hyperbole")

for example:

  (find-hyperbolefile "DEMO")
  (find-hyperbolefile "DEMO" "\n* Smart Keys")
  (find-hyperbolefile "DEMO" "Press the Action Key within this")
  (find-hyperbolenode "Installation")
  (find-hyperbolenode "Installation" "(require 'hyperbole)")

According to "Installation" I can activate hyperbole for the current
Emacs session by running this by hand:

  (require 'hyperbole)

If I do that and I visit "DEMO" again,

  (find-hyperbolefile "DEMO" "Press the Action Key within this")

then the strings "<(button)>" and "<(Smart Mouse Keys)>" will be
highlighted. Running `M-x describe-text-properties' on them says:

  There is an overlay here:
   From 20344 to 20364
    face                 hbut

They are not "buttons" in the sense of:

  (find-node "(elisp)Buttons")

in particular, they don't have a special keymap. I search for M-RET,
and it turns out that it was installed in the _global_ keymap. I
looked for the other basic keys of Hyperbole,

  (find-elongkey-links "M-RET  ;; hkey-either")
  (find-elongkey-links "C-h h  ;; hyperbole")
  (find-elongkey-links "C-h A  ;; hkey-help")

and I found that they are defined here:

  (find-hyperbolefile "hmouse-drv.el" "(defun hkey-either ")
  (find-hyperbolefile "hui-mini.el"   "(defun hyperbole ")
  (find-hyperbolefile "hmouse-drv.el" "(defun hkey-help ")

and installed in the global keymap by:

  (find-hyperbolefile "hyperbole.el"  "(defun hkey-initialize ")

I looked for a way to turn Hyperbole mode off, and I couldn't find it.
It seems that `M-x hyperbole-toggle-bindings' can sort of do that,

  (find-hyperbolefile "hyperbole.el" "(defun hyperbole-toggle-bindings ")
  (find-hyperbolenode "Smart Key Bindings"  "hyperbole-toggle-bindings")

but I don't know how to turn off the thing that highlights strings
like "<(button)>" and "<(Smart Mouse Keys)>". They are highlighted
even in files where they are don't work... by a hook, I guess? if I
type M-RET on them in the file in which I am writing this e-mail I get
this error:

  (Hyperbole Action Key): No action defined for this context; try
another location

That's because they are "explicit buttons", it seems (?), and the
directory in which I am editing this e-mail doesn't have a ".hypb"
file. I was able to find more info about how these buttons work in
these links,

  (find-hyperbolenode "Explicit Buttons")
  (find-hyperbolenode "Explicit Buttons" ".hypb")
  (find-hyperbolenode "Explicit Buttons" ".hypb" "within the same directory")
  (find-hyperbolefile "hbdata.el" "hattr:filename")
  (find-hyperbolefile "hbdata.el" "hattr:filename" ".hypb")
  (find-hyperbolefile ".hypb")
  (find-hyperbolefile ".hypb" "DEMO")
  (find-hyperbolefile ".hypb" "DEMO" "button")
  (find-hyperbolefile ".hypb" "DEMO" "Smart_Mouse_Keys")

but I couldn't find - yet - a function that would show me lots of
information about the explicit button at point without following it.
OOPS, UPDATE: it seems that typing C-h A on a button would sort of do
that - I need to spend some time learning to read its output.

Another problem: the DEMO file refers to some commands that start with
C-h h - for example:

  (find-hyperbolefile "DEMO" "HY-ABOUT" "C-h h d a")
  (find-hyperbolefile "DEMO" "Hyperbole Glossary of terms" "C-h h d g")

Typing C-h h brings up a menu in the minibuffer that is quite nice to
navigate, but in which most tools that are familiar to me don't
work... for example, if I type C-x 4 C-h I get a buffer that says
this,

  Global Bindings Starting With C-x 4:
  key             binding
  ---             -------
  C-x 4 C-f find-file-other-window
  C-x 4 C-o display-buffer
  (...)

and I can use this sexp to go back to that listing whenever I want:

  (eek "C-x 4 C-h")

but `eek' doesn't work with Hyperbole's C-h h - for example, this just
inserts an `a':

  (eek "C-h h d a")

and my default way of creating hyperlinks to an interesting key
sequence stops at `C-h h'...

  (find-elongkey-links "C-h h  ;; hyperbole")
  (eek        "M-h M-k  C-h h  ;; hyperbole")

I'll have to find another way to create hyperlinks to key sequences
like `C-h h d a' and to the function bound to it - possibly by
pointing to code in hui-mini.el...

  (find-hyperbolefile "hui-mini.el" "(defun hyperbole ")
  (find-hyperbolefile "hui-mini.el" "(defun hyperbole-minibuffer-menu ")

That's it for the moment. I think that the chances of other people
finding Hyperbole difficult to learn for reasons similar to mine are
tiny, but I thought that I should report all this anyway... and any
hints would be welcome, of course...

  Cheers!
    Eduardo Ochs
    http://angg.twu.net/emacsconf2019.html
    http://angg.twu.net/eev-intros/find-emacs-keys-intro.html
    http://angg.twu.net/eev-intros/find-eev-intro.html#1


On Sun, 20 Sep 2020 at 13:53, Robert Weiner <rsw@gnu.org> wrote:
>
> Hi Jean:
>
> From the start, Hyperbole was designed as a toolkit to allow people to manage 
> unstructured and semi-structured textual information, namely personaliz 
> day-to-day information, that doesn't fit neatly in databases.  Most of this 
> information and the way people want to structure it is highly personal, so 
> the custom button types and the information underlying the buttons would not 
> typically be shared publicly.  People wouldn't normally share their contact 
> lists, emails or even personal writings nor the buttons within.
>
> What is public of course are the button and action types included with 
> Hyperbole and associated demos/tutorials as you see in the DEMO file {C-h h d 
> d} and potential applications listed in the Why Use Hyperbole writeup, {C-h h 
> d w}.
>
> If the examples provided in the DEMO are insufficient for you to create your 
> own Hyperbole-verse, please let us know what is missing.  Basincally, you 
> just create your global personal button file, HYPB, with {C-h h b p}, place 
> explicit and named implicit buttons in here that you want to reference 
> frequently, organizing it as an Emacs outline if you like, and then all of 
> these buttons become global buttons automatically that you can reference from 
> anywhere with {C-h h g a}.  As you get more advanced, you embed buttons in 
> other files including your hyrolo, {C-h h r a} and Koutlines, {C-h h k c}, 
> both of which are documented in the Hyperbole manual.
>
> The Hyperbole manual presently lacks a section describing how to build your 
> own buttons types as this is pretty simple for anyone who can program in 
> Elisp because definitions are almost just like regular defuns (just look at 
> "hibtypes.el" and "hactypes.el").  But as time allows, we plan to add this 
> section.
>
> Hyperbole is an easy-to-use toolkit you mold to your needs, like simple 
> Python scripts or functions for comparison.  Although it has some pre-built 
> uses, just as programming languages don't come with extensive applications as 
> examples, neither does Hyperbole.
> If you would like to see one specific application, have a look at 
> "hib-doc.el" in the Hyperbole distribution which shows how to implement a 
> simple document-index that can display multi-media documents based on 
> document ids.
>
> I think you'll find that most current uses are the simplest ones: activating 
> implicit buttons in existing documents or shell output text, using HyRolo for 
> contact management, structuring documents with Koutlines and looking up 
> programming definitions or cross-references with the Action Key.
>
> Cheers,
>
> Bob
>
>
> On Tue, Sep 15, 2020 at 8:35 AM Jean Louis <bugs@gnu.support> wrote:
>>
>> * Robert Weiner <rswgnu@gmail.com> [2020-08-15 18:33]:
>> > https://www.reddit.com/r/emacs/comments/i9kscx/emacs_nyc_video_release_bring_your_text_to_life/?utm_source=share&utm_medium=ios_app&utm_name=iossmf
>> >
>> > Initial comments on reddit.
>>
>> I have got the video, downloaded it. What I hoped to see is the real
>> world workflow for buttons, is there any real world application using
>> Hyperbole buttons? I am not referring to software application but to
>> texts and files containing Hyperbole buttons.
>>
>> How are people using it?
>>
>> Jean
>>
>>