GNU Hyperbole: The Everyday, Hypertextual Information Manager
** ACE WINDOW PACKAGE INTEGRATION - fast window and buffer switching
*** After installing the ace-window package and loading Hyperbole, execute (hkey-ace-window-setup "\M-o") to enable the following capabilities:
*** Fast Window Links: The hkey-window-link command quickly creates links to other windows:
{M-o w <window>} - creates an explicit button linked to point in <window>
{C-u M-o w <window>} - creates an unnamed implicit button linked to point
in <window>
{M-1 M-o w <window>} - creates a named implicit button linked to point
in <window>
See "(hyperbole)Create Link Button".
** ACTION AND ASSIST (SMART) KEYS (See "(hyperbole)Smart Keys").
*** Angle Bracket and Braces Thing Selection: In text and fundamental modes, an Action Key press on an angle bracket or a curly brace selects the region between a matching pair. See "(hyperbole)Smart Key Thing Selection".
*** Drag Button Referents to Specific Windows: Just as you previously could drag Dired or Buffer Menu items to display in a specific window, you can now do the same with Hyperbole Buttons. Action or Assist Key drag from a Hyperbole button and release in another window where you want the button's referent (or the result of its action) displayed. If you release the Smart Key outside of an Emacs window, the referent is displayed in a new frame. See "(hyperbole)Displaying Items".
Visual pulsing of the source line and the destination buffer highlights
the transfer taking place (hmouse-pulse-flag controls this).
Dragging a button to a modeline splits the window of the modeline and
displays the referent in the leftmost or uppermost of the split windows.
*** Drag to Create Implicit Link Buttons: An Assist Mouse Key drag across windows (when not starting from a draggable item) creates an implicit link button with an action type determined by the referent at the point of button release. This parallels the same Action Mouse Key drag which creates explicit link buttons. See "(hyperbole)creating implicit links".
Previously this drag would swap buffers in windows. Now you must drag
from open space in a modeline of the depress window to the buffer text
in the release window to swap buffers in windows.
Alternatively, with two windows in a frame, you can create an implicit
link button from point to the point of the other buffer with {C-h h i l}.
*** Hyperbole Symbol Tags: Hyperbole now includes a pre-built TAGS file so that an Action Key press on any Hyperbole symbol jumps to its definition without the need for any additional support. This also works on Hyperbole type names (which have a hidden prefix) in a help buffer where an Action Key press displays the type definition.
*** Lisp Load, Autoload and Require Expressions: Action Key press on any named target in such expressions displays the associated library.
*** Lisp Action Button Help: Action Buttons that utilize regular Lisp functions (rather than Hyperbole Action Types) can now have :help functions run with a press of the Assist Key on such buttons. See "(hyperbole)Action Buttons".
*** Smart Dired: Action Key subdirectory selection at point now works on any dired header line, not just the first one. Use {i} to insert multiple subdirectories in Dired mode. Smart Key end-of-line behavior is no longer specified in Dired mode but handled globally for consistency across modes. See "(hyperbole)Smart Key - Dired Mode".
** ACTION TYPES (See "(hyperbole)Action Types").
*** display-boolean, display-value, display-variable: Made all of these interactive, so can be used as button actypes. See "(hyperbole) actypes display-boolean".
*** Long Action Buttons: The length limit on action buttons has been removed to allow for long, multi-line sexpressions.
** DOCUMENTATION
*** Hyperbole Concepts: New writeup in Koutline format for those who want a quick read about how Hyperbole concepts all interrelate. View it with {C-h h d c}.
*** Action Types: Add newer types and updated existing doc summaries in the Hyperbole manual. See "(hyperbole)Action Types".
*** Doc Viewing: Updated to display many files from the Doc> menu in Org mode, so can cycle through expanding and collapsing entries with TAB when point is at the beginning of the buffer, allowing you to view just the sections of interest. View minor mode is also enabled so you can scroll forward and backward with SPC and DEL.
This includes DEMO, FAST-DEMO, HY-ABOUT, HY-NEWS and the Hyperbole
Files MANIFEST.
*** Emacs 2023 Talk Videos:
- Hyperbole Amps Up Emacs: Org slide file is included in
"HY-TALK/HYPERAMP.org" with the video at
"https://emacsconf.org/2023/talks/hyperamp/".
- Koutline for Stream of Thought Journaling: The video is at
"https://emacsconf.org/2023/talks/koutline/".
- What I learned by writing test cases for GNU Hyperbole: The video
is at "https://emacsconf.org/2023/talks/test/".
*** Emacs 2022 Talk Videos:
- Hyperbole and Org Mode: Org slide file is included in
"HY-TALK/HYPERORG.org" with the video at
"https://emacsconf.org/2022/talks/hyperorg/".
- Linking Personal Info with Implicit Buttons: The video is at
"https://emacsconf.org/2022/talks/buttons/".
- Build a Zettelkasten with HyRolo: The video is at
"https://emacsconf.org/2022/talks/rolodex/".
*** FAST-DEMO: Add
*** New Menu Key Doc: Documented these Hyperbole minibuffer menu keys:
- {Q} always quits from the menu without selecting anything
- {X} both quits from the menu and disables Hyperbole minor
mode; {C-h h} re-enables it. See "(hyperbole)menu,
entry/exit commands".
*** Updated 150-page Reference Manual: Includes multiple indexes for easy cross-referencing, Info viewer version and PDF for printing. View it:
- with the Emacs Info reader: {C-h h d i}.
- locally with a web browser: <browse-url "man/hyperbole.html">
- in pdf form: "man/hyperbole.pdf".
Some of the updates include:
**** HyRolo Searching: Update this section with doc on auto-expansion and how to hide entries again.
**** Ibut Menu: Document in the manual, notably the new Ibut/Create menu item. See "(hyperbole)menu, Ibut/Create". For the Ibut/Link menu item, see "(hyperbole)menu, Ibut/Link".
**** Implicit Button Types: Add doc for 'hib-python-traceback' and 'hyrolo-stuck-msg'. See "(hyperbole)Implicit Button Types".
**** Link Menu Items: With two windows on screen, link from source window point to referent window point. Do a similar thing when more windows are on screen via an Action Mouse Key drag between windows. See "(hyperbole)Smart Mouse Drags between Windows".
**** Manual Glossary: Added Ace Window, Consult, Org Mode, and Org Roam entries. See "(hyperbole)Glossary".
**** Smart Key - Org Mode: Expanded with doc for more extensive behavior. See "(hyperbole)Smart Key - Org Mode".
*** README.md: Unify this as the only readme file and remove "README".
** EXPLICIT BUTTONS (See "(hyperbole)Explicit Buttons").
*** Ebut/Link Menu Item {C-h h e l}: Inserts a named ebutton that links to point in another window. See "(hyperbole)menu item, Ebut/Link".
** GLOBAL BUTTONS (See "(hyperbole)Global Buttons").
*** Gbut/Link Menu Item: A single name creates a new global link button to point. See "(hyperbole)menu item, Gbut/Link".
*** Auto Save: Automatically save the global button file after any edit.
** HYCONTROL (See "(hyperbole)HyControl").
*** I/J/K/M Key Bindings: In Window Control mode, move directionally (based on QUERTY keyboard layout) among windows in the selected frame. In Frame Control mode, move directionally among active frames. These keys utilize and prompt to install the windmove and framemove packages if not installed. See "(hyperbole)I/J/K/M".
** HYPERBOLE SYSTEM (See "(hyperbole)").
*** Any Colorized Display: Face display and colorization of Hyperbole buttons now works on any display capable of displaying colors. See "(hyperbole)Button Colors".
*** Create Buttons in Current Buffer: Stop prompting for a source buffer when creating a Hyperbole button. Always use the current buffer and point. See "(hyperbole)Creation".
*** DuckDuckGo Web Search: {C-h h f w k} runs a DuckDuckGo web search.
*** Hyperbole Keys Defer to Current Modes: Hyperbole bindings of {C-c RET}, {C-c .}, {C-c @}, and {C-c /} defer to any major mode, like org-mode, outline-mode or kotl-mode that binds them to other commands. This also works for outline-minor-mode.
*** Improved Button Help: {C-h A} now says whether a button is explicit or implicit. For implicit buttons, it displays the doc from both its implicit button type and its associated action type.
{C-h A} now also works on Emacs push-buttons and text property
buttons, displaying their attributes and associated action. See
"(hyperbole)Smart Key help".
*** Flymake Lint Warning Display: The new "hsys-flymake" library provides commands to display the flymake warning at point as well as the full list of warnings for the current buffer. See "(hyperbole)Smart Key - Flymake Mode" for details.
*** Makefile (eln): Use echo target for showing build info as part of the eln build. (echo): Show Emacs location and version in build environment info. (lint): Use "package-lint" to lint Hyperbole source code.
*** mhtml-mode Markup Selection: Hyperbole's matching markup pair selection, copying and movement now works with Emacs' builtin mhtml-mode. See "(hyperbole)HTML tag pair".
*** Native Compilation: Hyperbole now may be natively compiled (.eln files). It works around an Emacs bug where async native comp of a package being installed does not load "hyperbole-autoloads.el". When building Hyperbole without a package manager, 'make eln' now builds it natively.
*** Natively Compiled Functions as Action Types: Now may be used as Hyperbole button action types. See "(hyperbole)Action Types".
*** Warnings Removed: Almost all byte-compiler and native compiler warnings have been eliminated when building the Hyperbole package. None of the remaining warnings should affect use of Hyperbole. Most open Hyperbole issues have also been resolved.
*** XEmacs: Removed old XEmacs-compatibility code; everyone should use GNU Emacs nowadays.
** HYROLO (See "(hyperbole)HyRolo").
*** Koutline and Markdown File Support: The hyrolo-file-list' can now contain Koutline or Markdown files and will search their outline entries just like it does for Org and Emacs outline files. The markdown-mode'
package will be auto-installed if a Markdown file is searched by HyRolo.
See "(hyperbole)HyRolo Concepts".
*** hyrolo-file-list Support for File Wildcards, Variables and Dirs:
The `hyrolo-file-list' variable that HyRolo uses to determine the files
to search for pattern matches may not contain file patterns itself.
If you include file wildcards in pathnames and `find-file-wildcards' is
non-nil (the default), they will be expanded into matching files
internally by HyRolo. See "(emacs)Wildcards".
If you include an Environment variable or Emacs Lisp variable with the
${var} format in a path, it will be resolved prior to searching the path.
Variables with values that include multiple paths, e.g. PATH, are resolved
to the first existing entry that matches. See "(hyperbole)pathname".
If you include an existing directory (invalid ones are ignored) in your
hyrolo list, hyrolo will search recursively across all of its files
that match `hyrolo-file-suffix-regexp'. See `hpath.el#hpath:expand-list'.
HyRolo will display a detailed error list if any invalid file type is
included in the `hyrolo-file-list' after expansion. See
`hyrolo-any-file-type-problem-p'.
*** HyRolo Match Buffer Key Bindings:
Improved movement keys:
- {TAB} Move to next search match; works across all supported file types
- {b} Move backward at the same outline level
- {f} Move forward at the same outline level
- {n} Move to the next visible outline heading
- {p} Move to the previous visible outline heading
- {u} Move up a heading level
- {,} Move to the beginning of the current entry
- {.} Move to the end of the current entry
- {[} Move to previous @loc> line of previous file header
- {]} Move to next @loc> line of next file header
Improved hide/show commands now work when in file headers:
- {h} Hide the rest of the file header and matches after this line
- {s} Show all of the file header and matches
See "(hyperbole)HyRolo Keys".
*** Koutline Fast Search: Koutlines may now be included in `hyrolo-file-list' and individual cells extracted properly with any HyRolo query. Then the interactive commands:
{t} show the top-level (highest matching level) matches
{o} show an outline of matches
{s} show/expand current match
{h} hide current match
{f/b/n/p} move to another match
all work on Koutline cells displayed in the match buffer. See
"(hyperbole)HyRolo Concepts".
*** Match Buffer Name Change: Changed match buffer name from "Hyperbole Rolo" to "HyRolo".
*** Auto-Expand Hidden Text: Whenever point moves into a hidden/invisible part of the HyRolo buffer, the entire tree of entries below that point is auto-expanded/shown. Presently, there is no auto-hide functionality. You must press {h} to hide entries or an entire file of matches when in the file header.
*** Editing Entries Jumps to Current Position: The {e} command in the HyRolo match buffer now lets you edit the current point within the entry's source buffer, rather than jumping to the start of the entry.
*** New HyRolo menu items ConsultFind and HelmFind: These appear when you
independently load the consult' or helm-org-rifle' package.
These menu items then use the related interactive search functions to
search over the HyRolo file list.
ConsultFind utilizes `consult-ripgrep' or `consult-grep'. HelmFind uses
the helm-org-rifle package and searches over .org and .otl files
exclusively. See "(hyperbole)ConsultFind".
*** .otl and .outl Suffixed Files: Setup to auto-invoke `outline-mode'.
*** hyrolo-date-format Empty String: Setting this variable to an empty string will disable adding and updating modification dates in HyRolo entries.
*** hyrolo-hdr-and-entry-regexp: Rename to 'hyrolo-hdr-and-entry-regexp' and in 'hyrolo-mode' extend its value to include all multiple trailing whitespace chars after the entry delimiter. Make variable `hyrolo-entry-regexp' which does not match to file headers.
** IMPLICIT BUTTONS (See "(hyperbole)Implicit Buttons").
*** Action Button Result Display: Action buttons now display in the minibuffer the result of evaluating any type of action expression, using Lisp readable values.
*** Compilation and Grep Error Lines: Error lines in the Emacs Regression
Test buffer, ert, are now supported, as well as the 'Compiling
Added support for ERT "Test <symbol>" lines to jump to the def of the
symbol and for symbol and pathname references from backtraces in ERT
output.
Added jumping to the referenced location from Ruby traceback stack
messages.
*** Emacs Regression Test Runs: New 'hyperbole-run-test-definition' implicit button type defined in "hypb-ert.el". An Action Key press on the first line of an ert test definition (ert-deftest) within the test name, evaluates the definition and runs the test; this ensures that the latest version is always run. An Assist Key press does likewise but runs the test with edebug, stepping through it. This also works for tests defined with `ert-deftest-async' from the "ert-async" package. See also "#Action Link Types to Run Tests".
With the optional package, "ert-results", the Smart Keys can be used
within the ERT results buffer to filter the display and to show the
documentation for each test. See "(hyperbole)Smart Key - ERT Results
Mode".
*** Highlighting of Ibut Names: New property:ibut-face' used to highlight any <[name]> prefixing an implicit button. All hproperty functions now support this face as well as the hproperty:but-face' used for explicit
buttons.
*** Info Nodes: Better handling of embedded double quotes and added support for HTML " quoting.
*** Improved # and Embedded Space Path Handling: If a path exists, don't treat its # hash marks as section markers, notably for #autosave# files. Allow for unquoted filenames with spaces in them in ls listings in shell buffers (assume files are tab-delimited).
*** Ibut/Create Menu Item {C-h h i c}: Creates a named/labeled implicit button of any type. Separates the name and the implicit button with " - ". See "(hyperbole)menu item, Ibut/Create".
*** Ibut/Link Menu Item {C-h h i l} - Inserts an ibutton that links to point in another window. With a C-u prefix argument, prompts for a name as well. See "(hyperbole)menu item, Ibut/Link".
*** Jump to Lisp Identifier Definition in More Buffers: Lisp identifiers are now recognized as programming etags in the Warnings byte-compilation buffer and in Flymake log and diagnostics buffers.
*** Path Implicit Buttons: Much improved relative path handling, including expanding into executable paths when pathname is prefixed by ! or &, and handling info paths outside `Info-directory-list', like "man/hyperbole.info". Also, prioritize 'load-path' and 'exec-path' above 'Info-directory-list' within 'hpath:variables' when expanding pathnames. Remove outdated 'Info-directory' from 'hpath:variables' as well.
Automatically invoke `outline-mode' on files with ".outl" suffix;
previously, only ".otl" suffixes did this.
*** Read-only Context Errors: Trigger errors when trying to create an implicit button with point on read-only text, read-only Org contexts, explicit buttons, or emacs push-buttons.
*** Relative Info Paths: Info files with relative pathnames outside of the `Info-directory-list' now resolve properly, e.g. "man/hyperbole.info".
*** Table of Contents Sections: Hyperbole now recognizes TOCs in any text derived major mode with the text-toc implicit button type. An Action Key press on a line with a section name displays the section according to the Hyperbole referent display setting, typically leaving the TOC untouched in the selected window. This also works in Internet standard RFC buffers.
*** Youtube Snippet Links: Compact Action Buttons to play parts or whole Youtube videos and to search for videos by keyword. See "hsys-youtube.el".
** KOUTLINER (See "(hyperbole)Koutliner").
*** New Klink Format: Hash character, #, may now be used to separate a pathname from a Koutline cell reference. Both <koutline-path#cell-ref> and "koutline-path#cell-ref" work, e.g. "${hyperb:dir}/kotl/EXAMPLE.kotl#2a"
*** Link to Cell Headings: A cell heading is a string at the beginning of the editable portion of a cell that ends with a colon or a newline. Links to complete heading names now work: "${hyperb:dir}/kotl/EXAMPLE.kotl#Klinks"
*** {M-S-
*** {C-c s} Deletes Surrounding Whitespace: When a cell is split, it now deletes surrounding whitespace before performing the split.
*** Star Outline Import Indented Headings: Added support for Emacs/Org star-based headings whose stars do not start at the beginning of a line, i.e. are indented. See "(hyperbole)Inserting and Importing".
*** Transpose Lines Down: Add 'kotl-mode:transpose-lines-down' command.
** MENUS (See "(hyperbole)Menus").
*** Minibuffer Menu Changes:
- Instant Link Creation:
Ebut/Link - Inserts a named ebutton that links to point in another
window. See "(hyperbole)menu item, Ebut/Link".
Gbut/Link - A single name creates a new global link button to point.
See "(hyperbole)menu item, Gbut/Link".
Ibut/Link - Inserts an ibutton that links to point in another window.
With a C-u prefix argument, prompts for a name as well. See
"(hyperbole)menu item, Ibut/Link".
- Reload Menus and Smart Keys: Action Key press on top-level menu prefix
reloads Hyperbole minibuffer menus and Smart Key handlers to reflect
any recent edits.
- Multi-line Menus: When a menu line is too long for the screen, it is
automatically split into multiple lines and aligned by column for
ease of access.
*** Move Prefix Arg Number of Items: {M-b} and {M-f} move backward and forward by the number of items specified by any given prefix argument, as do {TAB} and {Shift-TAB}. See "(hyperbole)minibuffer menu".
** ORG MODE INTEGRATION (See "(hyperbole)Smart Key - Org Mode").
*** Automatic Fix of Mixed Org Versions: Loading Hyperbole (via its
hyperb:init' function) automatically detects and resolves the hard-to-fix problem when some older builtin Org libraries are loaded before a newer version of the Org package is loaded. The fix utilizes libraries exclusively from the newer Org package. See the doc for hsys-org-fix-version'.
*** Org Links Outside Org Buffers: The `org-link' actype now opens links found inside and outside of Org buffers.
*** Interactive Org Directory Consult Grep: {M-x hsys-org-consult-grep RET} interactively greps your `org-directory' files with live in-buffer display as you move through matching lines.
*** Interactive Org-Roam DB Consult Grep: {M-x hsys-org-roam-consult-grep RET} interactively greps org-roam files with live in-buffer display as you move through matching lines. It uses the automatically installed consult-org-roam package when invoked. See "(hyperbole)hsys-org-roam-consult-grep".
*** Org and Org Roam IDs: New org-id' implicit button type and link-to-org-id-marker' action type that jump to the referent of an Org
ID or Org Roam ID at point. If a marker does not yet exist, there is
the `link-to-org-id' action type. An Action Key drag across windows
ending at an Org ID will create a link button with this last action
type, which will jump to the ID's definition regardless of whether the
link was to the definition or a reference. See "(hyperbole) ibtypes
org-id".
*** Org Code Blocks: On a header :dir directory, the Action Key displays that directory in dired. The Assist Key anywhere in the header removes any results for the code block. Smart Keys work the same when on a #+RESULTS header as when on a code source header. Smart Key tag lookup now works in Org code blocks. Smart Keys on Org internal targets now work just as they do on radio button targets.
*** HyRolo Integration with Org 9.7 and Up: Support "org-fold.el" and other newer features fo Org mode.
*** Todo Cycling: An Action Key press on an Org mode todo state keyword, cycles to the next state. An Assist Key press in the same place cycles to the next set of states, if any.
*** Bobp Hyperbole Doc File Cycling: Allow for org global cycling at the start of a buffer on a non-heading line within Hyperbole Doc/ files when displayed from Hyperbole menu items.
*** {C-c /}: The Hyperbole {C-c /} web search binding defers to the org-mode
binding, org-show-todo-tree', when in Org mode, but uses the improved Hyperbole command version, hsys-org-todo-occur', which allows filtering
to specific todo states.
** TEST CASES (See "${hyperb:dir}/test").
*** Hyperbole Automated Testing: Over 400 automated test cases. Simply run 'make test-all' or 'make test' from the command-line when in the Hyperbole source directory and you should see all tests pass. If any fail, you can press the Action Key to see the source of the failure. Full testing is supported under POSIX systems only. See "Makefile" and "test/MANIFEST".
*** The Hyperbole team's CI/CD process automatically runs all test cases against Emacs major versions 27, 28 and 29 and the current master branch tip whenever a Hyperbole code change is checked in against git.
*** ERT Test Case Symbols Jump to Definition: In Elisp and Lisp interaction
buffers, the Action Key jumps to the definition of any such symbol while
the Assist Key displays the symbol's documentation. This requires that
a TAGS table be built in the project root directory with the following
etags command-line option:
etags --regex={lisp}'/(ert-deftest[ \t]+([^ \t\n\r\f()]+)/'
For the Hyperbole source code itself, you can do this via 'make tags' from
within the Hyperbole source directory, `hyperb:dir'.
*** Run Hyperbole Tests via Make: Use the 'test' target and provide a pattern of test names to match like so:
make test test=hyrolo
to run just the HyRolo associated tests.
To enable, full backtraces and not truncated ones, add 'FULL_BT=' at the end:
make test test=hyrolo FULL_BT=
*** QA: Many quality improvements across Hyperbole and integration with Emacs updates with backward compatibility from Emacs 27 through Emacs 29 releases.
** WINDOW GRIDS (See "(hyperbole)grid of windows").
*** Grid by File Pattern: Fixed so prompt for a string pattern rather than a file name and forced use of full pathnames to avoid improper relative path resolution.
Updated to use prefix arg as grid size or to autosize when not given or
given an invalid value.
See "(hyperbole)hycontrol-windows-grid-by-file-pattern".
Full Changelog: https://github.com/rswgnu/hyperbole/compare/hyperbole-8.0.2pre...hyperbole-9.0.1
kotl-autoloads by @matsl in https://github.com/rswgnu/hyperbole/pull/355
Full Changelog: https://github.com/rswgnu/hyperbole/compare/hyperbole-8.0.0...hyperbole-8.0.2pre
** HYPERBOLE SYSTEM
*** Installation: Hyperbole package installation options are greatly expanded.
Stable or in-development branches may be installed with the Emacs package
manager. The Straight package manager may be used to keep up with
git-based development and submit pull requests. And stable and
in-development tar balls are available for manual installation. See
"(hyperbole)Installation".
*** Global Minor Mode: Hyperbole is now a global minor mode that can be
toggled with {M-x hyperbole-mode RET}, meaning all of its key bindings
can easily be enabled or disabled whenever desired. Your init file needs
to have (hyperbole-mode 1) in it instead of (require 'hyperbole) or
Hyperbole will not be enabled upon startup. See "(hyperbole)Usage".
Modeline Indicator: In the modeline where minor modes are shown,
"Hypb" now appears whenever Hyperbole is active.
Hooks: When hyperbole-mode is enabled, hyperbole-mode-hook and
hyperbole-mode-on-hook are run. When hyperbole-mode is disabled,
hyperbole-mode-hook and hyperbole-mode-off-hook are run.
Lexical Binding: All code is now largely lexically bound, improving
quality and debugability.
** ORG MODE
*** M-RET: Reworked M-RET interface so can control how much or little of
Hyperbole works in Org mode when Hyperbole minor mode is enabled.
See "(hyperbole)enable org-mode support" and "hsys-org.el".
*** hsys-org-enable-smart-keys: New customization to replace
'inhibit-hsys-org'. This applies only in Org major/minor modes when
hyperbole-mode is active. t means enable Smart Key support
everywhere. The symbol, buttons, is the default; it means the Smart
Keys are active only when point is within a Hyperbole button. A nil
value means no Smart Key support so {M-RET} behaves just as it does
normally in Org mode. See "(hyperbole)Org-mode". Use {C-h h c o}
to customize this setting.
This table summarizes the operation:
|--------------+-------------------+------------------+----------+------------------|
| Set To | Smart Key Context | Hyperbole Button | Org Link | Fallback Command |
|--------------+-------------------+------------------+----------+------------------|
| buttons | Ignore | Activate | Activate | org-meta-return |
| nil | Ignore | Ignore | Ignore | org-meta-return |
| t | Activate | Activate | Activate | None |
|--------------+-------------------+------------------+----------+------------------|
** EASILY CREATE YOUR OWN BUTTON TYPES
*** Simple Action Link Button Type Creation: `defal' is a new,
easy-to-use construct that generates new action button types from
a type name and a single simple format expression, allowing
non-programmers to create their own implicit action button link
types that execute key series, display URLs, display the contents
of pathnames or invoke functions. See "(hyperbole)Action Button
Link Types" or the "DEMO2#Defining New Action Button Types"
section.
*** Easy Implicit Link Button Type Creation: 'defil' is a new
construct for those familiar with regular expressions but not
much Emacs Lisp. This creates more flexible implicit button
types than 'defal' where the delimiters and text substitution
can be specified with regular expressions. Actions are limited
to executing key series, displaying URLs, displaying the
contents of pathnames or invoking functions. See
"(hyperbole)Implicit Button Link Types".
Elisp programmers should use the existing 'defib' macro for full
flexibility in implicit button type creation. See "hibtypes.el"
for examples and "(hyperbole)Programmatic Implicit Button Types"
for documentation.
** TEST CASES
*** Hyperbole Automated Testing: Extensive quality improvements throughout
Hyperbole thanks in part to over 230 test cases now included in the
test/ subdirectory. Simply run 'make test-all' or 'make test' from the
command-line when in the Hyperbole source directory and you should see
all tests pass. If any fail, you can press the Action Key to see the
source of the failure. Full testing is supported under POSIX systems
only. See "Makefile" and "test/MANIFEST".
*** Implicit Button Types to Run Tests: The file "hypb-ert.el" contains two
action link types:
hyperbole-run-test - run a single Hyperbole test by name
hyperbole-run-tests - run one more tests matching a pattern
Example uses:
Run the test hbut-defal-url
<hyperbole-run-test hbut-defal-url>
Run the tests specified by the test selector hbut-defal
<hyperbole-run-tests hbut-defal>
Run all tests
<hyperbole-run-tests t>
*** Installation Testing: install-test/local-install-test.sh automatically
installs Hyperbole for testing from one or more of its releases or
development branches. See "Makefile" and "install-test/MANIFEST".
** HYROLO (See "(hyperbole)HyRolo").
*** Faster searching within HyRolo match buffer: After performing a HyRolo
search with point in the match buffer, if you want different results,
you can quickly do a new regular expression HyRolo search with {r} or
a string/logical search with {C-u r}. This key had moved to previous
matches but that is already bound to {Shift-TAB} and {M-TAB}.
*** Auto-Expansion of Entries: If an entry is collapsed/hidden, moving to
any hidden part auto-expands it and then re-collapses it when point is
moved to another entry (just like isearch). A side-effect of this is
that the {h} hide entry subtree command now moves to the beginning of
the entry.
*** hyrolo-find-file: New command that selects and edits a file in
'hyrolo-file-list', defaulting to the first listed file when not given
a prefix arg. Available in the minibuffer menu as Rolo/File and the
pulldown menu as Rolo/Find-HyRolo-File.
*** Sorting Entries Rewritten: {C-h h r o} re-ordering HyRolo entries has
been rewritten for compatibility and improved debugging with the latest
Emacs releases.
*** hyrolo-highlight-face: Now uses the Emacs 'match' face by default.
*** Under MS Windows, the default HyRolo file is now "~/.rolo.otl" like
all other operating systems, instead of "~/_rolo.otl". Any older file
name will be relocated to the newer name.
** KOUTLINER (See "(hyperbole)Koutliner").
*** Export Koutlines to Collapsible Web Pages: {C-h h k f d} or
{M-x kexport:display RET} command creates and displays a web-based
expandable/collapsible outline from the Koutline in the current buffer.
See "(hyperbole)Exporting" and the new Koutliner Format submenu.
*** Org File Importation: Org files may now be imported to a Koutline using
{M-x kimport:file RET}.
*** Org Table Support: Org table editing now automatically works in the
Koutliner via Org table minor mode. Use {M-x orgtbl-mode RET} to
toggle this on and off. A press of the Action Key on a | symbol,
also toggles this minor mode on or off. See "(Org)Tables" for details.
Use a prefix arg with {TAB} to promote/demote Koutline trees when in
a table since {TAB} moves between fields within a table.
*** New Tree Movement Commands: Like Org mode, {[M-down]} and {[M-up]} move
the current tree past or before other trees at the same level. With a
prefix argument, move past that many trees.
*** New Tree Promotion/Demotion Keys: Tree promotion and demotion keys now
match many of the defaults in Org mode and Outline mode, plus some
easier to type ones. The tables below summarize which keys work whether
inside an Org table or outside. See "(hyperbole)Promoting and Demoting".
|----------------------------+-----------------------------|
| Promotion Inside Org Table | Demotion Inside Org Table |
|----------------------------+-----------------------------|
| M-0 Shift-TAB or M-0 M-TAB | M-0 TAB |
| C-c C-, | C-c C-. |
| C-c C-< | C-c C-> |
|----------------------------+-----------------------------|
|-----------------------------+----------------------------|
| Promotion Outside Org Table | Demotion Outside Org Table |
|-----------------------------+----------------------------|
| Shift-TAB or M-TAB | TAB |
| M-left | M-right |
| C-c C-, | C-c C-. |
| C-c C-< | C-c C-> |
|-----------------------------+----------------------------|
*** New Mail Tree Key Binding: The 'kotl-mode:mail-tree' command that
extracts the current view of a Koutline in text-only format and
creates an outgoing email message with it, has moved from {C-c @}
to {C-c C-@} to prevent conflict with the global hycontrol-window-grid
command bound to {C-c @}.
*** New Copy Command: The new command, 'kotl-mode:copy-tree-or-region-to-buffer',
bound to {C-c M-c} copies a Koutline tree or the active region
to a specified buffer. Prompts dictate whether invisible text
is included or not. This allows copying parts of Koutlines
directly into other buffers without having to copy to a
mail/message buffer first.
*** Klink Copy: When 'transient-mark-mode' is enabled and there is no active region:
within a link to a Koutline cell (klink), {M-w} copies the klink; then
{C-y} yanks it into any buffer you desire.
{M-w} outside of a klink instead copies a reference to the current
Koutline cell.
{C-x r s} prompts for an Emacs register and saves either the current
klink or the current cell reference to the register; {C-x r i} with the
same register then inserts at point the saved Koutline reference.
The new commands that you can bind to your own keys for copying klink
references to the current cell to the kill ring and to registers are:
kotl-mode:copy-absolute-klink-to-kill-ring
kotl-mode:copy-relative-klink-to-kill-ring
kotl-mode:copy-absolute-klink-to-register
kotl-mode:copy-relative-klink-to-register
*** Klinks Ignored Outside Comments in Programming Language Modes: In
previous Hyperbole versions, this was true for C-based language
modes. Now it is true for any programming mode descended from
'prog-mode'.
*** Prevent Movement Outside Editable Cell Bounds: Add
kotl-mode:pre-self-insert-command as a pre-command-hook
to prevent Koutline editing with point in an invalid location,
after a mouse-set-point outside of editable bounds.
*** {C-h h k e} (kotl-mode:example): Update to allow for an optional
directory or absolute file path. Prompt for the path when interactive.
Given a prefix argument, archive any existing file and start with a
fresh EXAMPLE.kotl file for editing. Programmatically, give a 2nd
arg of t to force archiving of any existing file and starting with
a fresh EXAMPLE.kotl file.
*** Koutlines have a hidden top-level root cell 0 that allows referring
to the whole outline as a tree. Now attributes of this cell can be
set, retrieved or removed like any other cell.
{C-c h} prompts for a kcell id and displays its attributes.
{C-u C-c h} prompts for a kcell id and displays the attributes for it
and its subtree; use 0 as the kcell id to see attributes for all visible
cells in the outline.
{C-c C-i} sets an attribute of the cell at point.
{C-u C-c C-i} removes an attribute of the cell at point.
{C-0 C-c C-i} sets an attribute of the invisible 0 root cell.
{C--1 C-c C-i} removes an attribute of the invisible 0 root cell.
*** Modes to Ignore Klinks: C-style languages use <includes> that can be
mistaken for klinks. New customizations 'klink:ignore-modes' and
'klink:c-style-modes' set the modes where klink matches are ignored.
** MENUS
*** Minibuffer Menu Changes:
- Items Activated by First Capital Letter: Used to be by the first
letter. This allows more flexibility in naming, e.g.
where two items start with the same first letter.
- {X} exits Hyperbole mode: This disables the Hyperbole minor mode
completely and exits from the menu. {C-h h} re-enables the
global minor mode and display the top-level Hyperbole menu.
*** Minibuffer and Pulldown Menu Changes:
- Find/Web/Jump: Use the Emacs webjump library to select a URL by name
and jump to it.
- Koutliner Formatting Menus: Full set of commands to import
text and outline files to Koutlines and to export Koutlines
to HTML for web viewing. See "(hyperbole)Inserting and Importing"
and "(hyperbole)Exporting".
- Button Modify Commands Removed: Use the Edit commands instead.
This applies to the pull-down menu as well.
** SMART (ACTION AND ASSIST) KEYS (See "(hyperbole)Smart Keys").
*** Explicit buttons may be created in any kind of temporary buffer
without an attached file, similar to what already existed for mail
message buffers.
*** 'ls' and 'grep' Directory Changes: 'ls' listings are now recognized
properly, prepending the preceding directory to each entry for viewing.
Similarly, if a 'cd' or 'pushd' command is issued prior to a 'grep -n'
or 'ripgrep' command, Hyperbole will prepend that directory to the grep
output before jumping to the resultant path.
*** Git Log Grep: New commands, 'hypb:fgrep-git-log' and 'hypb:grep-git-log',
allow f/grepping over repo changesets and listing associated commit log
messages. The Action Key on any resulting log entry displays the commit
changeset.
*** Pathname Implicit Buttons: Much improved pathname handling including
multiple variables per path, embedded . or .. within paths, better
recognition of semicolon separated pathnames in Windows PATH variable.
Variable substitutions are now made with fixed case, so that the
case of a value with both upper and lower case characters is
never changed, for example a value of ${HOME}.
Generalized Anchored Pathnames: "pathname#anchor" now works in
programming modes as well as text and outlining modes where anchors
are prefixed with the comment character in each mode or a # symbol.
PATH-style Variable Support: An Action Key press on a defined PATH-style
variable name, e.g. MANPATH, will prompt with completion for one of the
paths and will then display that. If it is the colon or semicolon-
separated string of paths value from a PATH-style variable, the path at
point is displayed; empty paths, e.g. :: represents the current directory,
’.’. Must have at least four paths within the variable value for this
to work.
file:// URLs are now resolved properly.
*** Any Lisp or environment variable that stores a directory or set of
directories may be prepended to any "grep -n" output line with the form
"${var-name}/" and the Action Key will recognize the directory and display
the appropriate line.
*** Treat kbd Strings as Key Series Buttons: An Action Key press within
the string of (kbd "string") issues the keys in string as if they were
pressed individually, i.e. the same as the key series, {string}.
*** Mail Address Activation Everywhere: Email addresses are recognized as
implicit buttons in major modes descended from 'mail-address-mode-list'.
If you set that to nil, however, they will be recognized in all major
modes.
*** Magit Mode Support: Just click or press the Action Key somewhere and it
will typically display what you want. Extensive Action Key support in
Magit modes for cycling through display views and displaying items.
Action Mouse clicks on the modeline cycles display of commits/diffs in
a buffer. In Magit Log and Blame listing modes, the Action Key
displays the associated commit or file line. The Action Key also
handles single line log entries that begin with the word 'commit' ,
displaying their commits even from shell and compilation buffers.
*** Debugger Source: In Python tracebacks, may be on a line just below the
source reference line so if not on a Hyperbole button, move back a line
before checking.
*** Todotxt Mode Support: Smart key support for the todotxt mode
https://github.com/rpdillon/todotxt.el.
*** UNIX Shell Errors: Jump to associated source line from a shell error of the
form: "<pathname>: line <num>: ".
*** Internet RFC Links (e.g. RFC-822): Change to using http to retrieve RFCs
instead of ftp since this is disabled in many environments. Always display
with Emacs' web browser rather than externally.
*** Implicit Button Types Reprioritization: Modified "hibtypes.el" so if
evaluate: (symset:clear 'ibtypes) and then reload hibtypes.{el,elc},
the priority order of all implicit button types is reset.
** CUSTOMIZATION
*** Customizable Display Program File Mappings:
The variables:
hpath:internal-display-alist
hpath:external-display-alist-macos
hpath:external-display-alist-mswindows
hpath:external-display-alist-x)
are all customizable and their default values utilize the per operating
system generic 'open' commands based on file suffix associations (for file
types not handled by Emacs).
The new customizable variable, 'hpath:external-file-suffixes', holds a regular
expression of operating system independent file suffixes to open outside Emacs
with the Action Key when not handled by 'hpath:native-image-suffixes'.
** PROGRAMMING
*** With the Hyperbole menu Cust/Debug-Toggle enabled, the messages printed
for each Smart Key press now include the action type and its arguments
for improved debugging.
*** Edebuggable Hyperbole Types: 'defib' and 'defact' type definitions
are now interactively debuggable via edebug-defun {C-M-x}.
*** ebut:program: Programmatically create an explicit Hyperbole button at
point from LABEL, ACTYPE (action type), and optional actype ARGS.
*** gbut:ebut-program: Programmatically add global explicit buttons at the
end of the personal button file.
*** kbd-key implicit button type: Interactive creation now allows for
a full key series, not just a single key binding.
*** kbd-key:is-p: Added this new predicate to test whether point is within
a brace-delimited key series.
*** kbd-key:execute: Added to programmatically or interactively execute a
non-normalized key series stored in a string.
*** hypb:def-to-buffer: Quick copying of program definitions and insertion
at the start of another buffer. Can be bound and used in key series.
*** smart-lisp-find-tag: New function that automatically finds tags tables
and jumps to Emacs Lisp definitions. It can be used in any type
of file as an action button, e.g. <smart-lisp-find-tag "ibut:at-p">.
*** ibut:at-p: Trigger an error if any implicit button type predicate
permanently moves point to simplify debugging such predicates.
*** hypb:string-count-matches: Count regexp matches in a string.
** ACE WINDOW PACKAGE INTEGRATION - fast window and buffer switching
*** After installing the ace-window package and loading Hyperbole, execute
(hkey-ace-window-setup "\M-o") to enable the following capabilities:
*** Fast Window Links: The hkey-window-link command bound to {M-o w}
rapidly creates a link button at point in the selected window,
linking to point in the window chosen when prompted.
See "DEMO2#Displaying File and Buffer Items and Moving Buffers".
*** Throw A Region Elsewhere Within the Same Buffer: {M-o t <window-id>}
when used with a selected region can now throw to the source buffer
as long as point is outside the selected region in the target window.
Hyperbole V8 has many new features as well as improvements including Hyperbole is now a global minor mode so its key bindings are even easier to enable or disable when needed. See the README.md and HY-NEWS files for some details.
SMART (ACTION AND ASSIST) KEYS
- Global Org Link Activation: The Action Key now activates Org links in
non-Org buffers if 'inhibit-hsys-org' is nil (the default). The Assist
Key shows help.
- Org Agenda Item Display: The Action Key displays the Org node
associated with Agenda items such as TODOs in another window. The
Assist Key shows help.
- Org Mode: Raised to near top priority in implicit button types so that
pathnames, URLs, etc. within Org links are handled by Org rather than
Hyperbole.
- Smart Dired Sidebar: Smart Key support for the dired-sidebar
package. See "(hyperbole)Smart Key - Dired Sidebar Mode".
- Helm Mode: The Smart Keys do all sorts of things in helm completion buffers
and the associated minibuffer. See "(hyperbole)Smart Key - Helm Mode".
- Magit Mode: Action Key expands/collapses like {TAB} and Assist Key
jumps to items like {RET}. See "(hyperbole)Smart Key - Magit Mode".
BUTTON TYPES
- {Key Series} Button Support for Helm and Counsel: Key series buttons
with M-x commands now work properly when counsel-mode or helm-mode are
enabled and M-x is rebound.
- Markdown In-file Links: With point on the link title, in-file links are
now activated properly (previously point had to be on the link itself).
- Git#directory Buttons: New flag, hibtypes-git-use-magit-flag, which if
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 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.
DOCUMENTATION
- Helm Mode: Added Hyperbole Manual section, "Smart Key - Helm Mode"
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".
BUTTON TYPES
- In-buffer Labels: Fixed a number of in-buffer text handling issues with
the creation of explicit buttons, maximizing reuse of existing text in
labels.
- link-to-file Action Type: Extended to allow file path to include either
:line-num:column-num or just :line-num at the end (translated to character
location within the button).
DOCUMENTATION
- Bookmark Mode: Added Hyperbole Manual section, "Smart Key - Bookmark Mode"
that allows linking to Emacs Bookmarks. See "(hyperbole)Smart Key -
Bookmark Mode".
MENUS
- Activate Any Labeled Buffer Button: Hyperbole's top-level menu 'Act'
command either activates any button at point or prompts for the choice of
any labeled explicit or implicit button within the buffer to activate.
The pulldown menu item, Activate-Button-in-Buffer, behaves the same.
- Org-mode in Q&A Appendix: Rewrote this section to account for improved
integration.
Many issues were resolved in this test version as documented in the "Changes" file. Only new features are listed here.
ACE WINDOW PACKAGE INTEGRATION - fast window and buffer switching
- After installing the ace-window package and loading Hyperbole, execute
(hkey-ace-window-setup "\M-o") to enable the following capabilities:
- Region Throws: The hkey-throw command bound to {M-o t} now throws the
active (highlighted) region, if any, into the target window's buffer,
rather than replacing its buffer with the source window buffer. If
you don't use region highlighting, i.e. transient-mark-mode, then use
{C-u M-o t} for the same effect. The buffer in the target window
must differ from the one in the source window. With no region
active, this command still throws the source buffer to the target
window. See "DEMO#Displaying File and Buffer Items and Moving Buffers".
SMART (ACTION AND ASSIST) KEYS
- Modeline Drag Window Resizing: Smart Key window resizing now provides
live feedback during the drag.
- Bottommost Modeline Frame Moving: After adding a 'drag-with-mode-line'
frame parameter with a value of t, a drag of any of its bottommost
modelines with either Smart Mouse Key repositions the frame on screen.
See "(hyperbole)Moving Frames" for information on how to configure this
feature.
CUSTOMIZATON
- hproperty:flash-face: Face used when flashing a button; now customizable.
- hproperty:highlight-face: Face used to highlight a line; now customizable.
- inhibit-hsys-org: See ORG MODE section below.
GLOSSARY
- Hlink Definitions: Added Action Button, Elink, Ilink, Glink definitions.
HYCONTROL
- Buffer/Window Swapping: Improved {~} so current buffer remains the same but
the selected window changes. Also made frame buffer swapping work anytime
there are two or more frames regardless of how many windows in each. See
"DEMO#Swapping Buffers".
HYROLO
- Hyrolo Add: Fixed new entry addition to add in sorted order and make logic
operators perform properly, after a bug in level calculation had been
introduced.
IMPLICIT BUTTONS
- Double Quoting Key Series: Key series delimited by {} may now be in double
quotes, e.g. "{C-x o}".
- Windows to Posix Paths: Much improved conversion of MSWindows UNC paths to
existing Posix mount points when running Emacs under Windows Subsystem for
Linux. See
- Flashing Implicit Buttons: More types of implicit buttons now flash when
activated.
- Improved Grep Output Parsing: Recognizes file names with spaces followed by
the null (^@, ASCII 0) character.
- Texinfo @-Quoted Path Variables: Hyperbole now can resolve paths as
complicated as this: @file{$@{hyperb:dir@}/DEMO#POSIX and MSWindows Paths}
in Texinfo files if the Action Key is pressed on the / or after, i.e. after
the variable name.
KEYS
- Deleted C-c C-r Global Binding: Removed {C-c C-r} key binding for explicit
button renaming due to conflicts with some major modes
ORG MODE
- Implicit Button Support: Org-mode's local binding of {M-RET} by default
now activates Hyperbole implicit buttons when within them.
- inhibit-hsys-org: New customization that when set non-nil disables
all Smart Key support in any Org major or minor mode.
- hsys-org-hbut-activate-p: Added to org-metareturn-hook so local binding
of {M-RET} in org-mode activates Hyperbole buttons when point is over
them. (It doesn't run the full set of Action Key actions).
PROGRAMMING
- Auto Imenu Reindexing: If using Emacs imenu package, the Action Key
will look up in-buffer identifier references with imenu. If imenu's
index is rendered invalid due to large changes in a buffer, Hyperbole
will now automatically rebuild the index to have correct pointers.
(Does not require use of the imenu-auto-rescan setting.
- hypb:mark-object: Gives Hyperbole-specific strings and symbols
a hyperbole property that distinguishes them from other objects.
- hypb:object-p: Tests whether has the hyperbole property. This is useful
in hpath:relative-to and hpath:absolute-to where any string with a
hyperbole property is ignored as a potential path. For example, this
prevents removal of trailing whitespace from normalized key series.
- hbut:act: Hyperbole button parameter is now optional and defaults to
the located button, the symbol, 'hbut:current.
- ibtypes tag lookup: Implicit button type names such as ibtypes::grep-msg
are now properly found in tags tables using their defib names
(e.g. grep-msg).
- hmouse-drag-p: tests whether absolute Smart Mouse Key depress and
release positions differ (relative to display/screen coordinates).
- hycontrol-quit: Unified the two Hycontrol mode quit commands into this one.
hycontrol-abort: Renamed from hycontrol-abort-mode.
- hyperb:autoloads-exist-p
hyperb:maybe-generate-autoloads
hyperb:generate-autoloads: Added and called from hyperb:init when
initializing Hyperbole to generate auto-autoload files when
running from a non-packaged source download of Hyperbole.
BUTTONS
- Action Buttons: A new, universal syntax for creating implicit buttons
that execute any existing action types or Elisp functions. Such
buttons are delimited by angle brackets, < >, and come in three types:
action type invocations, function calls and variable displays. See
"(hyperbole)Action Buttons" for examples and details on this exciting
new capability.
- Labeled Implicit Buttons: Optional <[labels]> that precede implicit
buttons. This enables implicit buttons to be activated by name when
in the current buffer or anywhere when added to the global buttons
file (personal button file).
- Link to Buttons: New implicit button types that link to buttons based
on their categories and labels:
In Buffer Syntax Implicit Button Type
===========================================================================
<elink: explicit button label to link to: optional ebut file> link-to-ebut
<glink: global button label to link to> link-to-gbut
<ilink: implicit button label to link to: optional ibut file> link-to-ibut
- Other New Implicit Button Types:
debugger-source: Jump to the source of errors from the Python pytype package
ipython-stack-frame: Jump to the source of ipython stack traces and exceptions
- Other New Action Types:
link-to-bookmark: Display an Emacs bookmark
- Much Faster Implicit Buttons: Major speedup in implicit button identification
and activation even with the new generalized Action implicit button type
syntax, due to internal optimizations.
- Pathname Flashing: Pathname implicit buttons now flash when activated.
- Pathname References: Pathname implicit buttons may contain both link anchors
and line and column numbers. Format is:
"<path>[#<link-anchor>]:<line-num>[:<col-num>]"
- Shell Script Link Anchors: Link anchors now work for shell script editing modes
as well using comment lines as the anchors, e.g. "myscript.sh#Env Variables".
- Dir Variable Separators: Variables in paths no longer require a trailing directory
separator. Both of these are live Hyperbole paths:
"${hyperb:dir}DEMO#Smart Mouse Keys"
"${hyperb:dir}/DEMO#Smart Mouse Keys"
- Jump Thing: Added xml-mode support for pressing the Action Key when on a start or
end tag pair to select the whole region between them. {C-c .} also moves between
the start and matching end tag. See "(hyperbole)Smart Key Thing Selection".
DOCUMENTATION
- DEMO: New sections on Button Files and Global Buttons.
- Action Types: link-to-gbut, link-to-ibut - Added.
- hpath:native-image-suffixes: documented this setting for controlling
image types that Hyperbole displays within Emacs.
- Implicit Button Types: Split off type descriptions to this new
subsection and added these types: ripgrep-msg, ipython-stack-frame,
ilink (link to implicit button), glink (link to global button), and
elink (link to explicit button).
- DEMO (Action Buttons): Added description and examples.
- Path Variables: Better documented how these are handled.
- Hyperbole Manual, DEMO (Implicit Buttons): Added description and
example of implicit button labels.
- Glossary: Updated Implicit Button and Global Button entries with
changes.
KOUTLINER
- When 'c' (clip to lines per cell) is omitted from a viewspec, clipping
now changes to whatever the default number of lines per cell is
(typically, unlimited). The same goes for the 'l' spec (limit display
to a certain level of cells).
MENUS
- Pulldown Menus: Implicit-Button/Label: Added to add a label.
Implicit-Button/Rename - Added to rename the label
of an implicit button.
- Minibuffer Menus: hui-mini.el (hui:menus): Added Ibut/Label and
Ibut/Rename.
ORG MODE
- Radio Targets and Links: Smart Keys now handle these.
- Links: Smart Keys handle both internal and external Org mode links.
PROGRAMMING
- ibut:at-type-p: Added to test if point is on a specific type of
implicit button.
- hbut:key, ebut:key, ibut:key, hbut:rename, hui:hbut-rename,
hui:hbut-operate: Added to allow renaming of any type of labeled
Hyperbole button.
- hypb:region-with-text-property-value: Added and used in hysy-org.el.
- hsys-org-mode-function, hsys-org-mode-p: Added to determine when
hsys-org actions are activated.
- ebut:key-src-set-buffer, hbut:key-src-set-buffer, hbut:key-list,
hbut:ebut-key-list, hbut:ibut-key-list, hbut:label-list): Added
to allow selection of labeled Hyperbole buttons in currrent buffer by
name.
- gbut:get, hbut:map, ibut:label-map, ibut:key-src, ibut:key-to-label,
ibut:label-to-key, hui:ebut-act, ibut:summarize, ibut:label-start,
ibut:label-end, ibut:label-p, ibut:get, hui:ibut-label-create,
hui:ibut-rename, hui:ibut-message, ibut:alist, ibut:list, ibut:map,
ibut:next-occurrence, ibut:label-regexp, gbut:ibut-key-list, ebut:to,
gbut:to, ibut:to, ibut:label-separator, hbut:label-regexp,
ibut:rename, hbut:get: Added to support implicit button labels and
links to buttons.
hbut:label-p: Updated to handle implicit button labels.
ibut:label-separator-regexp, hbut:outside-comment-p: Added.
- elink, elink:start, elink:end: Added for in-buffer links to explicit buttons.
glink, glink:start, glink:end: Added for in-buffer links to global buttons.
ilink, ilink:start, ilink:end: Added for in-buffer links to implicit buttons.
- hsys-org-set-ibut-label: Added and used in org-mode ibtype.
org-mode, hsys-org-at-block-start-p: Added Action Key activation of
Org blocks when on 1st line of def.
SMART (ACTION AND ASSIST) KEYS
- Emacs Bookmark Menu Mode: Jump to the bookmark at point.
- hpath:find-program: Changed to prioritize hpath:native-image-suffixes
over hpath:internal-display-alist over hpath:external-display-alist-macos
instead of the reverse. This prevents external viewers from being
used when internal viewers are also in effect.
BUTTONS
- Action Buttons: A new, universal syntax for creating implicit buttons
that execute any existing action types or Elisp functions. Such
buttons are delimited by angle brackets, < >, and come in three types:
action type invocations, function calls and variable displays. See
"(hyperbole)Action Buttons" for examples and details on this exciting
new capability.
- Labeled Implicit Buttons: Optional <[labels]> that precede implicit
buttons. This enables implicit buttons to be activated by name when
in the current buffer or anywhere when added to the global buttons
file (personal button file).
- Link to Buttons: New implicit button types that link to buttons based
on their categories and labels:
In Buffer Syntax Implicit Button Type
========================================================================
<elink: explicit button label to link to: optional ebut file> link-to-ebut
<glink: global button label to link to> link-to-gbut
<ilink: implicit button label to link to: optional ibut file> link-to-ibut
- Other New Implicit Button Types:
debugger-source: Jump to the source of errors from the Python pytype package
ipython-stack-frame: Jump to the source of ipython stack traces and exceptions
- Much Faster Implicit Buttons: Major speedup in implicit button identification
and activation even with the new generalized Action implicit button type
syntax, due to internal optimizations.
- Pathname Flashing: Pathname implicit buttons now flash when activated.
- Pathname References: Pathname implicit buttons may contain both link anchors
and line and column numbers. Format is:
"<path>[#<link-anchor>]:<line-num>[:<col-num>]"
- Shell Script Link Anchors: Link anchors now work for shell script editing modes
as well using comment lines as the anchors, e.g. "myscript.sh#Env Variables".
- Dir Variable Separators: Variables in paths no longer require a trailing directory
separator. Both of these are live Hyperbole paths:
"${hyperb:dir}DEMO#Smart Mouse Keys"
"${hyperb:dir}/DEMO#Smart Mouse Keys"
DOCUMENTATION
- DEMO: New sections on Button Files and Global Buttons.
- Action Types: link-to-gbut, link-to-ibut - Added.
- hpath:native-image-suffixes: documented this setting for controlling
image types that Hyperbole displays within Emacs.
- Implicit Button Types: Split off type descriptions to this new
subsection and added these types: ripgrep-msg, ipython-stack-frame,
ilink (link to implicit button), glink (link to global button), and
elink (link to explicit button).
- DEMO (Action Buttons): Added description and examples.
- Hyperbole Manual, DEMO (Implicit Buttons): Added description and
example of implicit button labels.
- Glossary: Updated Implicit Button and Global Button entries with
changes.
KOUTLINER
- When 'c' (clip to lines per cell) is omitted from a viewspec, clipping
now changes to whatever the default number of lines per cell is
(typically, unlimited). The same goes for the 'l' spec (limit display
to a certain level of cells).
MENUS
- Pulldown Menus: Implicit-Button/Label: Added to add a label.
Implicit-Button/Rename - Added to rename the label
of an implicit button.
- Minibuffer Menus: hui-mini.el (hui:menus): Added Ibut/Label and
Ibut/Rename.
ORG MODE
- Radio Targets and Links: Smart Keys now handle these.
- Links: Smart Keys handle both internal and external Org mode links.
PROGRAMMING
- ibut:at-type-p: Added to test if point is on a specific type of
implicit button.
- hypb:region-with-text-property-value: Added and used in hysy-org.el.
- hsys-org-mode-function, hsys-org-mode-p: Added to determine when
hsys-org actions are activated.
- ebut:key-src-set-buffer, hbut:key-src-set-buffer, hbut:key-list,
hbut:ebut-key-list, hbut:ibut-key-list, hbut:label-list): Added
to allow selection of labeled Hyperbole buttons in currrent buffer by
name.
- gbut:get, hbut:map, ibut:label-map, ibut:key-src, ibut:key-to-label,
ibut:label-to-key, hui:ebut-act, ibut:summarize, ibut:label-start,
ibut:label-end, ibut:label-p, ibut:get, hui:ibut-label-create,
hui:ibut-rename, hui:ibut-message, ibut:alist, ibut:list, ibut:map,
ibut:next-occurrence, ibut:label-regexp, gbut:ibut-key-list, ebut:to,
gbut:to, ibut:to, ibut:label-separator, hbut:label-regexp,
ibut:rename, hbut:get: Added to support implicit button labels and
links to buttons.
hbut:label-p: Updated to handle implicit button labels.
ibut:label-separator-regexp, hbut:outside-comment-p: Added.
- elink, elink:start, elink:end: Added for in-buffer links to explicit buttons.
glink, glink:start, glink:end: Added for in-buffer links to global buttons.
ilink, ilink:start, ilink:end: Added for in-buffer links to implicit buttons.
- hsys-org-set-ibut-label: Added and used in org-mode ibtype.
org-mode, hsys-org-at-block-start-p: Added Action Key activation of
Org blocks when on 1st line of def.
SMART (ACTION AND ASSIST) KEYS
- hpath:find-program: Changed to prioritize hpath:native-image-suffixes
over hpath:internal-display-alist over hpath:external-display-alist-macos
instead of the reverse. This prevents external viewers from being
used when internal viewers are also in effect.
ACE WINDOW PACKAGE INTEGRATION - fast window and buffer switching
- Selected Window Buffer Replace: Added the ability to 'replace' the
selected window's buffer with the buffer of another window. Use
{M-o r <window-id>}. To swap the buffers between the same two windows,
use {M-o m <window-id>. See "(hyperbole)Keyboard Drags" for setup and
use instructions.
- New Frame Commands: Any of these M-o commands that involve two windows
can use a new frame as the target window by using a <window-id> of 'z'.
So, {M-o t z} throws the current buffer to a new frame with a single
window displaying that buffer. The new frame will be the same size as
the prior frame to match the behavior of HyControl.
- Integrated Ace Window commands with Smart Key Drags and added commands
for use with the mouse that select Ace Window source and target windows
by clicking with the mouse: hmouse-click-to-drag,
hmouse-click-to-drag-stay, hmouse-click-to-drag-to,
hmouse-click-to-replace, hmouse-click-to-swap, hmouse-click-to-throw.
- {M-o i <window-id>} is now for use only when on a listing item such as
in Dired or Buffer Menu. It no longer creates Hyperbole buttons in
non-item areas to avoid confusion. Now it will just trigger an error
if not on a listing item.
SMART (ACTION AND ASSIST) KEYS
- MSWindows Paths: Hyperbole now recognizes typical MSWindows paths (both
local and remote shares) and can convert an in-buffer path between POSIX
and MSWindows formats multiple times, even paths involving mount points.
See "DEMO#POSIX and MSWindows Paths".
MSWindows paths may be used within links and implicit path
buttons just like POSIX paths, whether running Emacs under a POSIX
system or MSWindows. If under POSIX, a remote MSWindows path must be
accessed through a mount point to the network share. Hyperbole caches
such mount points when it is loaded. Use {M-x
hpath:cache-mswindows-mount-points RET} to update them if more mounts
are made later. See also the NEW COMMANDS section herein for how to
convert a path between POSIX and MSWindows formats.
- GitLab and Github Links: Added Gitlab implicit links with equivalent
functionality to those of Github. Added "people" reference support to
list people who are part of a formal organization as well as a "staff"
alias. Added "contributors" reference support to list project
contributors as well. Improved Github implicit issue links: gh#gh-34
and gh#issue/34 now properly reference an issue in the current project.
- Ripgrep: Added new ripgrep-msg implicit button type which jumps
to the source referenced by ripgrep (rg) output. By default,
ripgrep outputs pathnames only once before all matching lines
within that path. Ripgrep may also be used with the Hyperbole
`hypb:rgrep' command by setting 'hypb:rgrep-command'. See
"https://github.com/BurntSushi/ripgrep".
- Markdown Mode: Smart Keys now support Markdown internal file link
references and navigation.
- Org Mode: When in an *Org Help* buffer, the Smart Keys now defer to
org-mode to handle jumps to its own locations for compatibility.
Similarly, in org-mode buffers when not on an org link or heading,
and the {M-RET} Action Key is pressed, Hyperbole defers to Org's
org-meta-return command.
- Drag-based Kill, Copy and Yank: Added support for dragging across
frames.
- Python Identifiers: If a Jedi server is running and the Action Key is
pressed on a Python identifier, Hyperbole will use Jedi to find the
definition even within nested module references, e.g. a.b.c. Also
improved basic identifier definition finding.
- Company Mode Completion: Support for the Emacs company-mode completion
package. An Action Key press on a company-mode completion item will
display the definition of that item and an Assist Key press will
display its documentation, if any.
- Treemacs Mode: Now supports standard Hyperbole end-of-line proportional
scrolling.
- ChangeLog Mode: Smart Keys now work on Emacs Lisp references in
changelogs.
- Improved String Matching: For lines that begin with part of a string
that started on another line, Hyperbole now presumes that point is
within a string rather than between two strings, even though the
delimiters on the line make this ambiguous. This provides more
accurate string recognition.
- Improved Path Matching: For quote delimited paths, other quote marks
are excluded from matches, so if checking for a doubly quoted path,
single quotes are not allowed in the string.
HYCONTROL
- Help Buffer Quitting: If HyControl is active, normally {q} quits
it, but now if point is in an Emacs help buffer, {q} will quit
from the help buffer instead. Use {Q} to quit from HyControl
unconditionally.
NEW COMMANDS
- Buffer Sliding: Four new commands are available that can be
bound to things like control arrow keys: hkey-buffer-move-left,
hkey-buffer-move-right, hkey-buffer-move-down and
hkey-buffer-move-up. Each one slides the current buffer one
window in the direction specified and all other buffers slide
around to match.
- MSWindows and POSIX Path Toggling: In "hpath.el", added
(hpath:substitute-posix-or-mswindows-at-point) and
(hpath:substitute-posix-or-mswindows) commands to toggle the
format of a path at point or in a string between POSIX and
MSWindows styles.
PROGRAMMING
- Added hypb:map-plist, equivalent to mapcar but maps over
key-value pairs in property lists (where the key and value are
individual elements in the list).
- In "hui-select.el", added functions to return info. on the
context-sensitive region that this library selects.
(hui-select-get-region) returns the region that would be
selected at point and (hui-select-get-region-boundaries)
returns a cons of the start and end position of the same region.
- In "hpath.el (hpath:delimited-possible-path), added optional
include-positions parameter which if non-nil, adds start and end
positions to returned value.
- In "hversion.el", added (hyperb:wsl-os-p) flag to test whether
Emacs is running under Microsoft Windows Subsystem for Linux (WSL)
since the system-type variable does not reflect this.
DOCUMENTATION
- Popup Menus: Documented how to invoke the Koutliner and
HyRolo popup menus in Emacs. See "(hyperbole)Menu Commands".
- DEMO: Added sections:
"DEMO#Gitlab (Remote) References"
"DEMO#POSIX and MSWindows Paths"
- Updated Hyperbole Manual with new features.