diff --git a/.hypb b/.hypb index 64db9c9a..8fdc058e 100644 Binary files a/.hypb and b/.hypb differ diff --git a/Changes b/Changes index 10c2c502..1e2b9b75 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,38 @@ +2020-09-21 Bob Weiner + +* hversion.el: Released 7.1.3. + +2020-09-06 Bob Weiner + +* hyperbole.el (hkey-define-key): Added to support help-map being + somewhere other than C-h. + (hkey-initialize): Updated to support the above. + hui-mini.el (hui:menu-doc): Updated to support the above. Trigger an + error if the 'hyperbole' command is not bound to a key. + +* hmouse-drv.el (hkey-help): Fix to properly reflect and describe mouse + drags and only reflect mouse usage if last-command-event was a + mouse event. Move clearing of action/assist key variables until + after the last specified action is recorded. + +* hib-kbd.el (kbd-key): Improve brace matching by temporarily tagging + braces with list delimiter syntax. + +* hypb.el (hypb:set-raw-syntax-descriptor): Add so can restore saved + syntax table entries. + (hypb:get-raw-syntax-descriptor): Add to get raw syntax + descriptors. Emacs does not provide these functions. + +* hui-window.el (smart-coords-in-window-p): Ensure any window returned is + still valid and fix eventp condition to return window rather than t. + +2020-08-03 Bob Weiner + +* hui.el (hui:ebut-delete-op, hui:ibut-delete-op): Display deletion msg + when used in a key series or kbd macro. + +* hbut.el (ibut:delete): Fix to pass key instead of but symbol to ibut:to. + 2020-08-02 Bob Weiner * hbut.el (hbut:key-src-set-buffer): Fixed explicit button creation in a new diff --git a/DEMO b/DEMO index c48d7dd4..60e9c6c8 100644 --- a/DEMO +++ b/DEMO @@ -222,7 +222,7 @@ There are two submodes of HyControl: one for controlling windows and one for controlling frames, although a number of commands are available in both modes where they are useful. -Hyperbole binds {C-c \\} to invoke HyControl windows control; otherwise, the +Hyperbole binds {C-c \ } to invoke HyControl windows control; otherwise, the Hyperbole minibuffer menu item, Screen/WindowsControl {C-h h s w}, will do the same thing. diff --git a/HY-NEWS b/HY-NEWS index 0d8b16ba..61400661 100644 --- a/HY-NEWS +++ b/HY-NEWS @@ -41,7 +41,7 @@ set to t and Magit is available, then when activating a git directory button, such as git#/hyperbole, use Magit rather than Dired. - - Explicit Buttons Work Immdiately: Previously you had to save the buffer + - Explicit Buttons Work Immediately: Previously you had to save the buffer in which you created an explicit button before it would work. Now they work immediately after creation. @@ -51,6 +51,9 @@ that works on helm completions. See "(hyperbole)Smart Key - Helm Mode". + - Hyperbole Slides: Slides used in a talk by the author on the history + and capabilities of Hyperbole, see "HY-TALK/HY-TALK.org". + - Magit Mode: Added Hyperbole Manual section, "Smart Key - Magit Mode" that expands/collapses/jumps to Magit items. See "(hyperbole)Smart Key - Magit Mode". diff --git a/HY-TALK/.hypb b/HY-TALK/.hypb new file mode 100644 index 00000000..ada57d5a --- /dev/null +++ b/HY-TALK/.hypb @@ -0,0 +1,4 @@ + +"HYPB" +("Hyperbole_Todos" nil nil link-to-file ("${hyperb:dir}/Todo.txt" 422) "rsw@gnu.org" "20200803:15:14:32" nil nil) +("line-count" nil nil eval-elisp ((message "Lines in %s = %s" (buffer-name) (count-lines (point-min) (point-max)))) "rsw@gnu.org" "20200301:17:56:53" nil nil) diff --git a/HY-TALK/HY-TALK.org b/HY-TALK/HY-TALK.org new file mode 100644 index 00000000..a9add8de --- /dev/null +++ b/HY-TALK/HY-TALK.org @@ -0,0 +1,456 @@ +* <(Make Your Text Come Alive)> + + + <(GNU Hyperbole)> + + Bob Weiner + + + NYC Emacs Meetup -- August 3, 2020 + + See the presentation at: + + https://www.youtube.com/watch?v=nC1eTgZE1oA + + +* Hyperbole - the Word + + Pronounciation: hī-pûr′b-lē + + Definition: An extravagant statement or assertion + not intended to be understood literally. + + -- + + "Seek not what is, but what can be." + + +* Hyperbole - the Mission + + - Provide productive, interactive and programmatic tools for + interlinking and and controlling the view of all kinds of Emacs + texts + + - Let the computer figure out what to do in many contexts, reducing + the number of key bindings to remember and enhancing flow time + + -- + + "Hyperbole lets me interact with information (as well as frames + and windows) in a consistent and predictable way, on any Emacs + install and it does this without my needing to think much about + it, because Hyperbole more or less knows what to do out of the + box." + + +* Hyperbole - the History + + - Designed and initially implemented in 1991, right before the start + of the web but actively developed now as well + + - Leverages Doug Engelbart's early work on knowledge management tools + + - Conceived as a hypertext toolbox as part of a larger vision of + Personalized Information Environments to deal with an anticipated + explosion of personally managed information + + - Became a GNU Project + + - Updated for Emacs 26 and 27 across the last 3 years + + +* Hyperbole - Why Use It + + Clean, flexible hyperbuttons everywhere with **very little markup** + + Simple, context-sensitive key bindings or mouse clicks and drags + reduce the cognitive load of Emacs, enhancing work focus + + Fast, key-driven minibuffer menu exposes you to the whole system + one piece at a time + + Now compatible with Org mode and highly complementary + + -- + + "We have too much information in our lives, and it's coming in + faster than we can organize it. Rather than manually specifying + relationships between bits of information, we need a system that + can see these connections simply by taking context and content + into account." -- John Wiegley, former Emacs Maintainer + + +* Hyperbole - What Is It + + | Hyperbole Component | Description | + |---------------------+----------------------------------------------------------| + | Action/Assist Keys | 2 global keys for hypertext everywhere in Emacs | + | | | + | Implicit Buttons | Text patterns automatically become hyperbuttons | + | | | + | Button Action Types | Buttons can execute arbitrary Lisp (do anything) | + | | | + | Button Files | Global and dir-specific quick access files of buttons | + | | | + | Minibuffer Menu | Keyboard-driven Hyperbole user interface | + | | | + | Koutliner | Live legal-type multi-level autonumbered outlining | + | | with hyper-anchors per node and multiple views | + | | | + | HyControl | Fast control of your windows and frames | + | | | + | HyRolo | Fast retrieval of hyperlinked records in * outline files | + + + +* Setup and Use + + - Install: {M-x install-package RET hyperbole RET} + + - Keyboard Menus: {C-h h} + + - Activate Text via Keyboard + Action Key: {M-RET} + Assist Key: {C-u M-RET} + + +* Mouse Buttons + + - Activate Text via Mouse + Action Mouse Key: {Shift-Button2} + Assist Mouse Key: {Shift-Button3} + + - To use Button2 and Button3 (unshifted instead), + add this to your Emacs init file: + + (eval-after-load "hyperbole" '(hmouse-add-unshifted-smart-keys)) + + or interactively after loading Hyperbole, press the Action Key + on this next button: + + + + - To toggle between Hyperbole Mouse buttons and their prior bindings, + press the Action Key on this next button: + + {M-x hmouse-toggle-bindings RET} + + +* Alright Already, Let's See Some Action + + "This isn't Mission Difficult Mr Hunt, it's Mission Impossible... + Difficult should be a walk in the park for you." + + +* Buttons + + Hyperbole offers 3 categories of buttons: + + - {Implicit Buttons}: automatically defined buttons, recognized by boolean type + predicates that match to text in a buffer and then + perform actions in response + + - <(Explicit Buttons)>: created one at a time and embedded within specific files + + - <(Global Buttons)>: stored in a personal button file, activated by name + + + All button categories can invoke arbitrary actions, not just link to resources. + + -- + + "It's cool to be able to turn arbitrary text into hyperlinks in + arbitrary modes, and have one keypress that does what I want on + all of them." + + +* Button Files + + Buttons can be stored in any kind of text file but for convenient access to + groups of often used buttons, Hyperbole provides two kinds of button files: + + - A single personal button file, "~/.hyperb/HYPB". Put all your bookmark-like + buttons in there, accessed via {C-h h b p}. + + - The same kind of file for each directory, also named HYPB, and accessed from + the directory with {C-h h b d}. + + More about these later. + + +* Implicit Buttons + +A Few Common Examples: + +** - Pathnames + + "DEMO#Global Buttons:2" - outline section anchor & relative line number + + "README.md#Hyperbole Components" - Markdown anchor with spaces intact + + "${hyperb:dir}/HY-NEWS" - Elisp or environment variable + + "subr.el" - edit any Elisp library in load-path + +** - Key Series + + {C-x 4 b *scratch* RET M-< "Insert any text. That's cool!" RET RET M-<} + +** - Shell Grep Messages, Stack Traces, Man Page Apropos + + {M-x shell RET grep SPC -n SPC gbut:label-list SPC *.el RET} + + {M-x shell RET python SPC /tmp/stack.py RET} + + {M-x shell RET apropos SPC windows RET} + + +* Action Buttons (generalized form of implicit buttons) + + + + + - Display variable values in the minibuffer + + + - execute Lisp expressions + + or the simpler: + + + + +* Many More to Learn Across Time + + Implicit Button Types + +| action | annot-bib | completion | +| cscope | ctags | debbugs-gnu-mode | +| debbugs-gnu-query | debugger-source | dir-summary | +| doc-id | elink | elisp-compiler-msg | +| etags | function-in-buffer | git-commit-reference | +| glink | gnus-push-button | grep-msg | +| hyp-address | hyp-source | id-cflow | +| ilink | Info-node | ipython-stack-frame | +| kbd-key | klink | mail-address | +| man-apropos | markdown-internal-link | org-mode | +| patch-msg | pathname | pathname-line-and-column | +| rfc | rfc-toc | ripgrep-msg | +| social-reference | texinfo-ref | text-toc | +| www-url | | | + +Stored in their own namespace, 'ibtypes::', so to see the doc on the +'pathname' ibtype, use {C-h f ibtypes::pathname RET}. + + +* Explicit Buttons + + All <(explicit buttons)> look the same. They are created individually with + {C-h h e c}. This prompts for a button name, action type and associated + arguments. + + Explicit link buttons can be created by dragging the Action Mouse Key from + a source buffer to a referent window. Hyperbole determines the link type + to use or prompts you to choose when there are multiple possibilities. + + +* Action Types + +| annot-bib | completion | www-url | +| debbugs-gnu-query | display-boolean | display-variable | +| eval-elisp | exec-kbd-macro | exec-shell-cmd | +| exec-window-cmd | function-in-buffer | hyp-config | +| hyp-request | hyp-source | kbd-key | +| link-to-Info-index-item | link-to-Info-node | link-to-bookmark | +| link-to-buffer-tmp | link-to-directory | link-to-doc | +| link-to-ebut | link-to-elisp-doc | link-to-file | +| link-to-file-line | link-to-file-line-and-column | link-to-gbut | +| link-to-ibut | link-to-kcell | link-to-kotl | +| link-to-mail | link-to-regexp-match | link-to-rfc | +| link-to-string-match | link-to-texinfo-node | link-to-web-search | +| man-show | org-internal-link-target | org-link | +| org-radio-target | rfc-toc | text-toc | + +Stored in their own namespace, 'actypes::', so to see the doc on the +'org-link' actype, use {C-h f actypes::org-link RET}. + + +* Global Buttons + + All explicit or named implicit buttons in your personal button file are + global buttons that are activated by name with {C-h h g a}. + + {C-u C-h h g c about-test RET RET} + + {C-h h g a about-test RET} + + {C-h h g d about-test RET} + + +* Local Find and Web Search Menu + + - Specialized web search is too hard to do manually, so people end up + just doing generalized searches that don't work as well. + + - Hyperbole's Find and Web Search features are meant to more easily + connect you to the information you desire. + + - Isn't that why we build hypertexts in the first place? + + +* Koutliner + +The Koutliner is the only Emacs outliner that has dynamic multi-level +node numbering, e.g. 1.4.3.2 and a permanent hyperlink anchor for each +node as well as view specifications that affect the outline view when +included in hyperlinks. It is great for todo lists, brainstorming, +requirement documents or anything that needs detailed structure. + + {C-x 0 C-x 2 C-x o C-h h k e} + + + + -- + + "Maybe think of Hyperbole as a bunch of primitives that help you + organize and display text the way you want to, like Emacs + outlining. Use that to structure sections within your personal + button file and then add appropriate explicit and implicit + buttons in each section. Or use the Koutliner so you can link + directly to autonumbered nodes. Or embed links within the + comments of your code so people can reference related material + quickly." + + +* HyRolo Matches + +HyRolo is an easy-to-use but advanced contact manager and record +lookup tool (now with BBDB and Google Contacts support). Contacts can +be spread across multiple files and use different formats if +desired. Hyperbole buttons can be embedded in entries and activated +from the buffer of search matches. HyRolo files are Emacs outlines, so +they can be quickly collapsed and re-organized in standard ways. + + {C-x 4 r} + + +* HyControl + + - Rapidly control windows and frames + + - Window Grids - fast, multi-window layout + {C-u 0 M-x hycontrol-windows-grid RET python-mode RET 23 RET} + + - Scriptable via Key Series implicit buttons + + - Fastest way to change face sizes for individual windows or frames + + "Because I’m trying to prevent my poor hands from turning into + gnarled, useless claws, I extensively use speech recognition + software. Hyperbole’s frame and window controls let me set up + workspaces and move stuff with a few vocal commands, without + having to type or use a mouse. + + In practice, fiddling with the frame sizes sounds like: + 'Hyperbole Frame Control. Press Period. Numeral 20. Go left + ten. Press H. Press W. Press Q.' It’s just… great. I can’t say + enough nice things about it. I always know I’ve found a killer + piece of functionality when I find myself desperately wishing I + had it everywhere." + + +* Other Package Integrations + + - Treemacs - control Treemacs with the Action and Assist Keys + + - Ace Window - additional throw and replace buffer commands + + - Org Mode - follow Org links with a single key + + +* Notes on Using with Org Mode + + - Updated to be compatible with Org + + - Action Key activates all kinds of Org links + + - {M-RET} behaves normally in Org mode in all other contexts + + - Org and Hyperbole are complementary not mutually exclusive + + +* Acknowledgements + + Mats Lidell - long-time co-maintainer of Hyperbole + https://tinyurl.com/y2g5fvdu + + John Wiegley - Using Hyperbole: A Motivation + https://tinyurl.com/y3vnsuef + + Adrien Brochard - Quick Hyperbole blog posting with animated gifs + https://blog.abrochard.com/hyperbole-intro.html + + The FSF and GNU Project - providing a home for Hyperbole in GNU Elpa + + +* Resources + + Potential Workflows + https://tinyurl.com/y57efmmr + + Summary of Hyperbole Uses + https://tinyurl.com/yxp3kv5s + + Or after installing Hyperbole, try: + {C-h h d w} + + Hyperbole Vision Quest Usage Articles + https://tinyurl.com/y5db5bpa + + The author's Youtube with 2 Hyperbole Videos + https://tinyurl.com/y453keke + + +* A Final Perspective on Hyperbole + + - Reduce Cognitive Burden + + - Network Effects + + - Globally Accessible + + +* Reduce Cognitive Burden + + From John Wiegley: + + "Hyperbole lifts some of the cognitive burden from Emacs users by + defining an extensible, large set of "recognizers" for various + types of informational references, and "actions" for doing things + with that information, such as visiting referenced documents, or + web pages, or dictionary definitions. It's quite easy to add new, + contextually-sensitive recognizers, and actions, so that you can + teach Emacs to become more aware of how you use it to manage + information. + + +* Network Effects + + "But what's more, with every new recognizer and action you add, + the more interactive all your information becomes. It's a + multiplying effect, turning inert, standalone documents into more + interactive, virtual semi-networks. And very few of these links + do you need to update and maintain, because most of the + information is inferred based on where you are when you hit the + 'action key'." + + +* Globally Accessible + + "Since this functionality is transparently added everywhere, not + just special buffer types specific to Hyperbole, it's able to + make Org-mode outlines richer, Gnus article reading more + interactive, and source code more accessible to new readers -- + provided they're using Emacs too." + + -- The End -- diff --git a/HY-TALK/HYPB b/HY-TALK/HYPB new file mode 100644 index 00000000..bf93c769 --- /dev/null +++ b/HY-TALK/HYPB @@ -0,0 +1,44 @@ +* Keystroke Display + +** Keypression - overlaying parts of buffer (shows trail of keys) + + + + + + + +* Pathname Prefixes + + "!${PATH)/date" - execute 'date' shell command + + "&Preview.app ${hyperb:dir}/man/hyperbole.pdf" + + "-subr.elc" - load an Elisp library + + +* Global Buttons + +<[Test ibut label]> {C-u C-n} + +<[Bufs]> {C-x C-b} + +<[iPython src]>: "/usr/local/Cellar/ipython/7.16.1/libexec/lib/python3.8/site-packages/IPython/" + +{C-x 4 t} - Goto <(Hyperbole Todos)> + +<[ib]> "(hyperbole)Implicit Buttons" +<[frm]> "(hyperbole)C-h h s f" + +"${hyperb:dir}/DEMO" + +"${hyperb:dir}/README.md#Programmer Quick Reference" +"${hyperb:dir}/README.md#programmer-quick-reference:4:2" + + \ No newline at end of file diff --git a/MANIFEST b/MANIFEST index 7a3931cd..cbc450a2 100644 --- a/MANIFEST +++ b/MANIFEST @@ -7,6 +7,7 @@ HY-ABOUT - Introductory description of GNU Hyperbole HY-ANNOUNCE - GNU Hyperbole release announcement HY-COPY - GNU Hyperbole Copyright HY-NEWS - What's new in each release of GNU Hyperbole +HY-TALK.org - Source slides and video link from the author's 2020 talk on Hyperbole HY-WHY.kotl - Quick list of great reasons to use Hyperbole INSTALL - GNU Hyperbole installation and invocation instructions Makefile - Build GNU Hyperbole directories and distributions diff --git a/TALK/HY-TALK.org b/TALK/HY-TALK.org deleted file mode 100644 index e430cfd9..00000000 --- a/TALK/HY-TALK.org +++ /dev/null @@ -1,264 +0,0 @@ -* [[file:../hyperbole-banner.png]] - - GNU Hyperbole - - Make Your Text Come Alive - - - Bob Weiner - - - NYC Emacs Meetup -- August 3, 2020 - - -* Hyperbole, the Word - - Pronounciation: hī-pûr′b-lē - - Definition: An extravagant statement or assertion - not intended to be understood literally. - - "Hyperbole lets me interact with information (as well as frames - and windows) in a consistent and predictable way, on any Emacs - install and it does this without my needing to think much about - it, because Hyperbole more or less knows what to do out of the - box." - -* Hyperbole, the Emacs Package - - | Hyperbole Component | Description | - |---------------------+----------------------------------------------------------| - | Action/Assist Keys | 2 global keys for hypertext everywhere in Emacs | - | | | - | Implicit Buttons | Text patterns automatically become hyperbuttons | - | | | - | Button Action Types | Buttons can execute arbitrary Lisp (do anything) | - | | | - | Button Files | Global and dir-specific quick access files of buttons | - | | | - | HyRolo | Fast retrieval of hyperlinked records in * outline files | - | | | - | HyControl | Fast control of your windows and frames | - | | | - | Koutliner | Live legal-type multi-level autonumbered outlining | - | | with hyper-anchors per node and multiple views | - - -* Setup and Use - - - Install: {M-x install-package RET hyperbole RET} - - - Activate Text - Action Key: {M-RET} or {Shift-Button2} or {Button2} - Assist Key: {C-u M-RET} or {Shift-Button3} or {Button3} - - - Keyboard Menus: {C-h h} - - -* Alright Already, Let's See Some Action - - "This isn't Mission Difficult Mr Hunt, it's Mission Impossible... - Difficult should be a walk in the park for you." - - https://www.youtube.com/watch?v=QMHMBX4KHp0 - - -* Quick Demo - - "Seek not what is, but what can be." - - "Wax on ... wax off." - - -* Buttons - - Hyperbole offers 3 categories of buttons: - - - {Implicit Buttons}: automatically defined buttons, recognized by boolean type - predicates that match to text in a buffer and then - perform actions in response - - - <(Explicit Buttons)>: created one at a time and embedded within specific files - - - <(Global Buttons)>: stored in a personal button file, activated by name - - - All button categories can invoke arbitrary actions, not just link to resources. - - -* Implicit Buttons - - - -* - - -* It's too hard to rapidly create and replicate display spaces for working with your hypertexts and code, so HyControl was born to simplify this process. Specialized web search is also too hard to do manually, so people end up just doing generalized searches. Hyperbole's Find and Web Search features are meant to more easily connect you to the information you desire. Isn't that why we build hypertexts in the first place? - -* For programming language modes, you do not need to add explicit buttons to each file to benefit from Hyperbole. When you press the special Action Key on an identifier, Hyperbole searches up the directory tree of the current file, finds the first matching TAGS file and uses it to jump to the definition of the identifier. If xref.el is in use, it uses that as well, all transparently. It also does this with Java documentation cross-refs and many other similar implicit links. - -Thank you for asking the question. I am the author of GNU Hyperbole so I use it all the time. Once in awhile I will start Emacs without Hyperbole loaded and it very quickly feels like it is missing many features that speed my editing and information retrieval. - -A major new release of Hyperbole is now available with many advancements, so have a look at that and assume anything mentioned here pertains to this release. - -Things I depend on all the time: - -The Smart Keys are two context-sensitive mouse key (or keyboard key) bindings that execute actions based on the textual context in which they are pressed, essentially finding patterns in text that operate as hyperbuttons (called implicit buttons in Hyperbole). So instead of having 20 different bindings for 20 major and minor modes, you have one global binding that does the right thing in many different contexts. This reduces learning time and lets you just press a Smart Key in many contexts. A help key always shows you what the Smart Keys will do in any context, so you can ensure things will work as you like before activating any implicit button. Advanced examples include: - -displaying pathnames with Lisp or environment variables in them and having them display in external applications if desired; - -creating explicit button hyperlinks by dragging from a source buffer to a destination buffer; this can even create links to files on remote servers; the hyperlink is then available for immediate use, no markup required - -activating links to git and github files and other object types, like issues - -jumping to source code definitions (utilizing several different cross-reference packages) without having to know any specifics about how to do the lookup - -displaying bug/issue discussions in debbugs and github - -copying and moving structured entities, e.g. double quoted text, brace delimited sections, HTML tag pair entities, with quick mouse drags - -navigating through files in a package MANIFEST - -writing a few lines of Lisp to create a new implicit button type and being able to then immediately activate matching implicit buttons within any documents I want; for example, "RFC-822" is a built-in implicit button to Hyperbole that when pressed upon: retrieves the Internet RFC specified and makes its table of contents live so you can jump to any section you want immediately. - -HyRolo is an easy-to-use but advanced contact manager and record lookup tool (now with BBDB and Google Contacts support). Contacts can be spread across multiple files and use different formats if desired. Hyperbole buttons can be embedded in entries and activated from the buffer of search matches. HyRolo files are Emacs outlines, so they can be quickly collapsed and re-organized in standard ways. - -The Koutliner is the only Emacs outliner that has dynamic multi-level node numbering, e.g. 1.4.3.2 and a permanent hyperlink anchor for each node as well as view specifications that affect the outline view when included in hyperlinks. It is great for todo lists, brainstorming, requirement documents or anything that needs detailed structure. - -HyControl lets me rapidly arrange my windows and frames as I want; together with Smart Key drags, I can drag items from the buffer menu or dired to whatever window I want or swap buffers rapidly; I can move windows to new frames quickly and many other things. A great new feature is window grids that let you lay out a series of windows in rows and columns with buffers chosen from either your current buffer list, a single major mode or selected items from the buffer menu or dired; you have to try it to get a feel for it. - -Hyperbole is mainly about productivity and the combination of its facilities can improve your ability to get work done in Emacs dramatically. The included Hyperbole interactive DEMO covers much of this. Practice with it and see your speed with Emacs soar across your first week of use and continue to improve after that. - -* HyControl - -"Because I’m trying to prevent my poor hands from turning into gnarled, useless claws, I extensively use speech recognition software. Hyperbole’s frame and window controls let me set up workspaces and move stuff with a few vocal commands, without having to type or use a mouse. - -In practice, fiddling with the frame sizes sounds like: “Hyperbole Frame Control. Press Period. Numeral 20. Go left ten. Press H. Press W. Press Q.” It’s just… great. I can’t say enough nice things about it. I always know I’ve found a killer piece of functionality when I find myself desperately wishing I had it everywhere. If I could control every window on my PC with the same ease as I can control Emacs frames, I’d be a very happy camper." - - -* Treemacs -* Ace Window -* Org Mode - -* Pathnames - - "DEMO#Global Buttons:2" - with section anchor and relative line number - - "${hyperb:dir}/HY-NEWS" - with Elisp or environment variable - -* Key Series - - {C-x 4 b *scratch* RET M-< "Insert any text. That's cool!" RET RET M-<} - -* Action Buttons - - - Display variable values in the minibuffer - - - execute Lisp expressions - - or the simpler: - - - -* Global Buttons - - {C-u C-h h g c test RET RET} - - {C-h h g a test RET} - - {C-h h g d test RET} - -* Grep or Error Messages - -hactypes.el:442: (let ((gbut-file (hpath:validate (hpath:substitute-value gbut:file))) -hactypes.el:451: (mapcar 'list (gbut:label-list)) -hactypes.el:455: (gbut:act (hbut:key-to-label key))) - -* Window Grids - - {C-u 0 M-x hycontrol-windows-grid RET python-mode RET 23 RET} - - -* Hyperbole Subsystems - -* HyRolo Matches - - {C-x 4 r linux RET} - - {C-x 4 r (and linux products) RET} - -* Koutliner - - {C-x o C-h h k e} - - - - -* Hyperbole, the Toolkit - - "Maybe think of Hyperbole as a bunch of primitives that help you - organize and display text the way you want to, like Emacs outlining. - Use that to structure sections within your personal button file and - then add appropriate explicit and implicit buttons in each - section. Or use the Koutliner so you can link directly to - autonumbered nodes. Or embed links within the comments of your code - so people can reference related material quickly." - - - -* Acknowledgements - - Mats Lidell - long-time co-maintainer of Hyperbole - https://tinyurl.com/y2g5fvdu - - - Chris Nuzum - first Hyperbole user who uses it to this day - "I've been using Hyperbole for over 20 years and can't imagine Emacs without it." - - John Wiegley - has written about Hyperbole concepts - - Adrien Brochard - Quick Hyperbole blog posting with animated gifs - https://blog.abrochard.com/hyperbole-intro.html - - The FSF and GNU Project - providing a home for Hyperbole in GNU Elpa - -* Resources - - Potential Workflows - https://tinyurl.com/y57efmmr - - Summary of Hyperbole Uses - https://tinyurl.com/yxp3kv5s - - Or after installing Hyperbole, try: - {C-h h d w} - - Hyperbole Vision Quest Usage Articles - https://tinyurl.com/y5db5bpa - - My Youtube with 2 Hyperbole Videos - https://tinyurl.com/y453keke - - -Hyperbole's subsystems build on a few primitives included with Hyperbole plus its button infrastructure but otherwise are self contained and easily updated individually. Having them as one package saves a lot of effort in separate documentation, packaging and installation requirements. - -Hyperbole is built so you can extend much of its behavior without understanding much about the underlying mechanics. For example, to add a new implicit button type, you write two new functions essentially: One that recognizes whether point is within whatever context represents a button of the type, i.e. whatever textual pattern you like. And then another function that applies an action to the text of the button, e.g. jumps to the definition of an identifier within some code. - -You do similar things to extend each subsystem. The only case where you really have to understand a lot of internals is when trying to extend the core hypertext system. For the major subsystems: the outliner, contact manager and display manager, you can extend these without really understanding anything about any other part. - -For instance, how is Window management and web search hub related? - -It's too hard to rapidly create and replicate display spaces for working with your hypertexts and code, so HyControl was born to simplify this process. Specialized web search is also too hard to do manually, so people end up just doing generalized searches. Hyperbole's Find and Web Search features are meant to more easily connect you to the information you desire. Isn't that why we build hypertexts in the first place? - -I understand the tool chest argument, but even then we should have multiple packages corresponding to each coherent component and a tool chest package that combines all of them. - -Emacs does not yet have a notion of subpackages within packages. In Hyperbole, we have one Emacs package, a number of subsystems and modules within the subsystems. Seems pretty well modularized to me. Subsystems pretty much load when you use them. - -3 months ago -I've recently started trying out ledger, which is a text file which records transactions (money went from here to there) and a program which reads that text file and makes sure everything balances out. - -Anyway, in the comments I've started to record the PayPal transaction ID with text like 'paypal:'. After defining a new implicit button, I can press M-RET over that text and Hyperbole will open a web browser to that transaction. I've also made one for games I've bought on GOG: Hyperbole will open the receipt ID in a web browser. - -Is that useful? I don't know. I could have just stored the URL directly, but I think that's a bit uglier and it's cool to be able to turn arbitrary text in to hyperlinks in arbitrary modes, and have one keypress that does what I want on all of them. - - diff --git a/TALK/HYPB b/TALK/HYPB deleted file mode 100644 index 347d27fb..00000000 --- a/TALK/HYPB +++ /dev/null @@ -1,11 +0,0 @@ -<[Bufs]> {C-x C-b} - -<[ib]> "(hyperbole)Implicit Buttons" -<[frm]> "(hyperbole)C-h h s f" - -"${hyperb:dir}/DEMO" - -"${hyperb:dir}/README.md#Programmer Quick Reference" -"${hyperb:dir}/README.md#programmer-quick-reference:4:2" - - \ No newline at end of file diff --git a/hbut.el b/hbut.el index 79078272..97bc2299 100644 --- a/hbut.el +++ b/hbut.el @@ -1405,7 +1405,7 @@ Return symbol for button deleted or nil." (when (and start end) (save-excursion (set-buffer (if (bufferp loc) loc (find-file-noselect loc))) - (when (ibut:to but-sym) + (when (ibut:to (ibut:key but-sym)) (let (buffer-read-only) (if (< (point) start) ;; Find beginning of button named label delimiter and delete diff --git a/hib-kbd.el b/hib-kbd.el index 02f55035..1016a489 100644 --- a/hib-kbd.el +++ b/hib-kbd.el @@ -79,33 +79,42 @@ Any key sequence must be a string of one of the following: or a valid key sequence together with its interactive arguments." (unless (or (br-in-browser) (and (looking-at "[{}]") (/= ?\\ (preceding-char)))) - ;; handle long series, e.g. eval-elisp actions - (let* ((hbut:max-len (max 3000 (hbut:max-len))) - (seq-and-pos (or (hbut:label-p t "{`" "'}" t) - (hbut:label-p t "{" "}" t) - ;; Regular dual single quotes (Texinfo smart quotes) - (hbut:label-p t "``" "''" t) - ;; Typical GNU manual key sequences; note - ;; these are special quote marks, not the - ;; standard ASCII characters. - (hbut:label-p t "‘" "’" t))) - ;; This excludes delimiters - (key-series (car seq-and-pos)) - (start (cadr seq-and-pos)) - binding) - ;; Match only when start delimiter is preceded by whitespace, - ;; double quotes or is the 1st buffer character, so do not - ;; match to things like ${variable}. - (when (memq (char-before start) '(nil ?\ ?\t ?\n ?\j ?\f ?\")) - (when (and (stringp key-series) - (not (eq key-series ""))) - (setq key-series (kbd-key:normalize key-series) - binding (kbd-key:binding key-series))) - (and (stringp key-series) - (or (and binding (not (integerp binding))) - (kbd-key:special-sequence-p key-series)) - (ibut:label-set seq-and-pos) - (hact 'kbd-key key-series)))))) + ;; Temporarily make open and close braces have list syntax for + ;; matching purposes. + (let ((open-brace-syntax (hypb:get-raw-syntax-descriptor ?\{)) + (close-brace-syntax (hypb:get-raw-syntax-descriptor ?\}))) + (unwind-protect + (progn (modify-syntax-entry ?\{ "(\}" (syntax-table)) + (modify-syntax-entry ?\} ")\}" (syntax-table)) + ;; Handle long series, e.g. eval-elisp actions + (let* ((hbut:max-len (max 3000 (hbut:max-len))) + (seq-and-pos (or (hbut:label-p t "{`" "'}" t) + (hbut:label-p t "{" "}" t) + ;; Regular dual single quotes (Texinfo smart quotes) + (hbut:label-p t "``" "''" t) + ;; Typical GNU manual key sequences; note + ;; these are special quote marks, not the + ;; standard ASCII characters. + (hbut:label-p t "‘" "’" t))) + ;; This excludes delimiters + (key-series (car seq-and-pos)) + (start (cadr seq-and-pos)) + binding) + ;; Match only when start delimiter is preceded by whitespace, + ;; double quotes or is the 1st buffer character, so do not + ;; match to things like ${variable}. + (when (memq (char-before start) '(nil ?\ ?\t ?\n ?\j ?\f ?\")) + (when (and (stringp key-series) + (not (eq key-series ""))) + (setq key-series (kbd-key:normalize key-series) + binding (kbd-key:binding key-series))) + (and (stringp key-series) + (or (and binding (not (integerp binding))) + (kbd-key:special-sequence-p key-series)) + (ibut:label-set seq-and-pos) + (hact 'kbd-key key-series))))) + (hypb:set-raw-syntax-descriptor ?\{ open-brace-syntax) + (hypb:set-raw-syntax-descriptor ?\} close-brace-syntax))))) ;;; ************************************************************************ ;;; Public functions diff --git a/hmouse-drv.el b/hmouse-drv.el index b445f360..131e5c33 100644 --- a/hmouse-drv.el +++ b/hmouse-drv.el @@ -836,13 +836,11 @@ Return non-nil iff a non-nil predicate is found." With optional ASSIST-FLAG prefix arg non-nil, display help for the Assist Key command. Return non-nil iff associated help documentation is found." (interactive "P") - (let* ((mouse-flag (or action-key-depress-position assist-key-depress-position)) + (let* ((mouse-flag (when (mouse-event-p last-command-event) + (or action-key-depress-position assist-key-depress-position))) + (mouse-drag-flag (hmouse-drag-p)) (hkey-forms (if mouse-flag hmouse-alist hkey-alist)) hkey-form pred-value call calls cmd-sym doc) - (unless (or action-key-depressed-flag action-key-help-flag) - (action-key-clear-variables)) - (unless (or assist-key-depressed-flag assist-key-help-flag) - (assist-key-clear-variables)) (while (and (null pred-value) (setq hkey-form (car hkey-forms))) (or (setq pred-value (eval (car hkey-form))) (setq hkey-forms (cdr hkey-forms)))) @@ -863,6 +861,11 @@ Return non-nil iff associated help documentation is found." (mapcar 'identity (cdr call)) (list cmd-sym))) + (unless (or action-key-depressed-flag action-key-help-flag) + (action-key-clear-variables)) + (unless (or assist-key-depressed-flag assist-key-help-flag) + (assist-key-clear-variables)) + (setq hkey-help-msg (if (and cmd-sym (symbolp cmd-sym)) (progn @@ -891,7 +894,9 @@ Return non-nil iff associated help documentation is found." (if assist-flag "Assist" "Action") (if mouse-flag "Mouse " ""))) (princ (format "A %s of the %s %sKey" - (if mouse-flag "click" "press") + (if mouse-flag + (if mouse-drag-flag "drag" "click") + "press") (if assist-flag "Assist" "Action") (if mouse-flag "Mouse " ""))) (terpri) diff --git a/hui-mini.el b/hui-mini.el index de12608b..436b2805 100644 --- a/hui-mini.el +++ b/hui-mini.el @@ -211,11 +211,13 @@ With optional HELP-STRING-FLAG, instead returns the one line help string for the (when (and (stringp key-sequence) (not (eq key-sequence "")) (kbd-key:hyperbole-mini-menu-key-p key-sequence)) - (let ((hargs:reading-p 'hmenu-help)) + (let ((hargs:reading-p 'hmenu-help) + (hmenu-key-seq (car (where-is-internal #'hyperbole)))) + (unless hmenu-key-seq + (hypb:error "(hui:menu-doc): The 'hyperbole' command must be bound to a key")) (setq unread-command-events (nconc unread-command-events - (mapcar 'identity (substring key-sequence - (length (or (car (where-is-internal #'hyperbole)) "\C-hh")))))) + (mapcar 'identity (substring key-sequence (length hmenu-key-seq))))) (prog1 (hui:menu-act 'hyperbole nil t help-string-flag) ;; Ignore any keys past the first menu item activation. (discard-input))))) diff --git a/hui-window.el b/hui-window.el index 17862fa9..1bc642da 100644 --- a/hui-window.el +++ b/hui-window.el @@ -695,19 +695,22 @@ Beep and print message if the window cannot be split further." (cond ((null coords) nil) ((eventp coords) (let ((w-or-f (posn-window (event-start coords)))) - (if (framep w-or-f) (setq w-or-f (frame-selected-window w-or-f))) - (eq w-or-f window))) + (when (framep w-or-f) + (setq w-or-f (frame-selected-window w-or-f))) + (when (and (eq w-or-f window) (window-valid-p window)) + window))) ((fboundp 'window-edges) (let* ((edges (window-edges window)) - (w-xmin (nth 0 edges)) - (w-ymin (nth 1 edges)) - (w-xmax (nth 2 edges)) - (w-ymax (nth 3 edges)) - (x (hmouse-x-coord coords)) - (y (hmouse-y-coord coords))) - (and (<= w-xmin x) (<= x w-xmax) - (<= w-ymin y) (<= y w-ymax) - window))))) + (w-xmin (nth 0 edges)) + (w-ymin (nth 1 edges)) + (w-xmax (nth 2 edges)) + (w-ymax (nth 3 edges)) + (x (hmouse-x-coord coords)) + (y (hmouse-y-coord coords))) + (and (<= w-xmin x) (<= x w-xmax) + (<= w-ymin y) (<= y w-ymax) + (window-valid-p window) + window))))) (defun smart-point-of-coords (coords) "Return point within window in which COORDS fall or nil if none. diff --git a/hui.el b/hui.el index e2863077..0490916b 100644 --- a/hui.el +++ b/hui.el @@ -885,7 +885,8 @@ within." (call-interactively 'hui:ebut-unmark) (message "Button deleted.")) (hui:ebut-unmark but-key key-src)) - (when (hmail:reader-p) (hmail:msg-narrow))) + (when (hmail:reader-p) (hmail:msg-narrow)) + (message "Button '%s' deleted." (ebut:key-to-label but-key))) (hypb:error "(ebut-delete): You may not delete buttons from this buffer")))) (defun hui:ebut-delimit (start end instance-str) @@ -1097,9 +1098,8 @@ within." (hypb:error "(ibut-delete): No valid %s button in %s" (ibut:key-to-label but-key) buf))) (progn (set-buffer buf) - (when interactive - (message "Button deleted.")) - (when (hmail:reader-p) (hmail:msg-narrow))) + (when (hmail:reader-p) (hmail:msg-narrow)) + (message "Button '%s' deleted." (ibut:key-to-label but-key))) (hypb:error "(ibut-delete): You may not delete buttons from this buffer")))) (defun hui:ibut-message (but-modify-flag) diff --git a/hycontrol.el b/hycontrol.el index 5844d0b3..cfb1f986 100644 --- a/hycontrol.el +++ b/hycontrol.el @@ -34,7 +34,7 @@ ;; zooming; if called interactively, it stores the current window ;; configuration for restoration via a press of the `)' key. ;; `hycontrol-enable-windows-mode' is typically bound by Hyperbole -;; to {C-c \} or just use {C-h h s w}. Then press {t} if you want +;; to {C-c \ } or just use {C-h h s w}. Then press {t} if you want ;; to switch to frame control. ;; ;; With a HyControl minor mode active, a multi-line help summary of diff --git a/hypb.el b/hypb.el index 6a226064..5522c338 100644 --- a/hypb.el +++ b/hypb.el @@ -344,6 +344,10 @@ are replaced. Returns body of modified FUNC-SYM." body)) body))) +(defun hypb:get-raw-syntax-descriptor (char &optional syntax-table) + "Return the raw syntax descriptor for CHAR using the current syntax table or optional SYNTAX-TABLE." + (aref (or syntax-table (syntax-table)) char)) + ;; Derived from pop-global-mark of "simple.el" in GNU Emacs. (defun hypb:goto-marker (marker) "Make MARKER's buffer and position current. @@ -613,6 +617,19 @@ The value returned is the value of the last form in BODY." (select-frame-set-input-focus (window-frame window))) (error "(hypb:select-window-frame): Argument must be a live window, not '%s'" window))) +(defun hypb:set-raw-syntax-descriptor (char raw-descriptor &optional syntax-table) + "Set the syntax of CHAR to RAW-DESCRIPTOR (syntax table value) in the current syntax table or optional SYNTAX-TABLE. +Return the RAW-DESCRIPTOR. Use the `syntax-after' function to +retrieve the raw descriptor for a buffer position. + +Similar to modify-syntax-entry but uses a raw descriptor +previously extracted from a syntax table to set the value rather +than a string. + +Syntax tables are char-tables whose values are encoded as raw +descriptors." + (aset (or syntax-table (syntax-table)) char raw-descriptor)) + (defun hypb:supercite-p () "Return non-nil iff the Emacs add-on supercite package is in use." (let (hook-val) diff --git a/hyperbole.el b/hyperbole.el index 2692ce5c..8c6f32c6 100644 --- a/hyperbole.el +++ b/hyperbole.el @@ -5,7 +5,7 @@ ;; Author: Bob Weiner ;; Maintainer: Bob Weiner , Mats Lidell ;; Created: 06-Oct-92 at 11:52:51 -;; Released: 02-Aug-20 +;; Released: 21-Sep-20 ;; Version: 7.1.3 ;; Keywords: comm, convenience, files, frames, hypermedia, languages, mail, matching, mouse, multimedia, outlines, tools, wp ;; Package: hyperbole @@ -212,6 +212,12 @@ Entry format is: (key-description key-sequence key-binding)." (mapcar (lambda (key) (hkey-binding-entry key)) (hkey-bindings-keys hkey-previous-bindings))) +(defun hkey-define-key (keymap key command &optional no-add) + "Same as `define-key' except saves prior binding for later restoration unless optional 4rd argument NO-ADD is given as a non-nil value." + (unless no-add + (add-to-list 'hkey-previous-bindings (hkey-binding-entry key))) + (define-key keymap key command)) + (defun hkey-global-set-key (key command &optional no-add) "Same as `global-set-key' except saves prior binding for later restoration unless optional 3rd argument NO-ADD is given as a non-nil value." (unless no-add @@ -227,18 +233,18 @@ Entry format is: (key-description key-sequence key-binding)." (unless (where-is-internal 'hkey-either) (hkey-global-set-key "\M-\C-m" 'hkey-either)) ;; - ;; Bind a key, {C-h A}, for Action Key help and {C-u C-h A} for Assist key + ;; Typically bind the key, {C-h A}, for Action Key help and {C-u C-h A} for Assist key ;; help. (or (where-is-internal 'hkey-help) - (hkey-global-set-key "\C-hA" 'hkey-help)) + (hkey-define-key help-map "A" 'hkey-help)) ;; ;; Setup so Hyperbole menus can be accessed from a key. If not - ;; already bound to a key, binds the function `hyperbole' to {C-h h}. + ;; already bound to a key, this typically binds the command `hyperbole' to {C-h h}. (or (where-is-internal 'hyperbole) ;; In GNU Emacs, this binding replaces a command that shows ;; the word hello in foreign languages; this binding makes this ;; key much more useful. - (hkey-global-set-key "\C-hh" 'hyperbole)) + (hkey-define-key help-map "h" 'hyperbole)) ;; ;; Provides a site standard way of emulating most Hyperbole mouse drag ;; commands from the keyboard. This is most useful for rapidly creating diff --git a/man/hyperbole.html b/man/hyperbole.html index 42014e39..79a9062a 100644 --- a/man/hyperbole.html +++ b/man/hyperbole.html @@ -3,7 +3,7 @@