GNU Hyperbole ¶

1.1 Manual Overview ¶

Hyperbole is an efficient, programmable hypertextual information management system. It is intended for everyday work on any GNU Emacs platform. Hyperbole allows hypertext buttons to be embedded within unstructured and structured files, mail messages and news articles. It offers intuitive keyboard and mouse-based control of information display within multiple windows. It also provides point-and-click access to Info manuals, ftp archives, the World-Wide Web and much more.

This is a reference manual with extensive details about Hyperbole use. If you prefer a simpler, more interactive introduction to Hyperbole, the ../FAST-DEMO file included in the Hyperbole distribution demonstrates many of Hyperbole’s standard facilities without the need to read through this reference manual. The ../FAST-DEMO is a good way to rapidly understand some of what Hyperbole can do for you. Once Hyperbole is installed, (see Setup), you can access the ../FAST-DEMO with the key sequence {C-h h d d}.

See Glossary, for definitions of Hyperbole terms. In some cases, terms are not precisely defined within the body of this manual since they are defined within the glossary. Be sure to reference the glossary if a term is unclear to you. Although you need not have a keen understanding of all of these terms, a quick scan of the glossary helps throughout Hyperbole use.

See Setup, for explanations of how to obtain, install, configure and load Hyperbole for use. This appendix includes information on user-level settings that you may want to modify after you understand Hyperbole’s basic operation.

See Suggestion or Bug Reporting, for instructions on how to ask a question, suggest a feature or report a bug in Hyperbole. A few commonly asked questions are answered in this manual, see Questions and Answers. If you are interested in classic articles on hypertext, see References.

See Smart Keys, for an explanation of the innovative, context-sensitive mouse and keyboard Action and Assist Keys offered by Hyperbole. See Smart Key Reference, for a complete reference on what the Action and Assist Keys do in each particular context they recognize. See Smart Key Argument Selection, for how Hyperbole speeds selection of values when prompting for arguments.

Keep in mind as you read about using Hyperbole that in many cases, it provides a number of overlapping interaction methods that support differing work styles. In such instances, you need learn only one technique that suits you.

See Buttons, for an overview of Hyperbole buttons and how to use them. Hyperbole’s action-oriented button support is enabled via the global minor mode, hyperbole-mode.

See Menus, for summaries of Hyperbole menu commands and how to use the minibuffer-based menus that work on any display that Emacs supports.

See HyWiki, for Hyperbole’s markup-free, personal Wiki system for note-taking and automatic WikiWord highlighting and hyperlinking. It extends Org mode. HyWikiWord hyperlink buttons are automatically enabled for wiki pages below hywiki-directory. To enable them in text buffers outside of this directory, enable the global minor mode, hywiki-mode.

See HyNote, for a start on the very early stages of Hyperbole’s multi-format note taking system. HyNote supports Org, Markdown, Koutline and Emacs Outline file formats. HyNote works in any buffer where HyWiki support is active.

See HyControl, for how to quickly and interactively control what your Emacs windows and frames display and where they appear.

See Koutliner, for concept and usage information on the autonumbered, hypertextual outliner. It uses its own major mode. See Koutliner Keys, for a full summary of the outliner commands that are bound to keys.

See HyRolo, for concept and usage information on the rapid lookup, hierarchical, full-text record management system included with Hyperbole.

See Window Configurations, for instructions on how to save and restore the set of buffers and windows that appear within a frame. This feature lets you switch among working contexts easily, even on a dumb terminal. Such configurations last throughout a single session of editor usage only.

See Developing with Hyperbole, if you are a developer who is comfortable with Lisp.

See Future Work, for future directions in Hyperbole’s evolution.

1.2 Motivation ¶

Database vendors apply tremendous resources to help solve corporate information management problems. But the information that people deal with in their everyday worklife is seldom stored away in neatly defined database schemas. Instead it is scattered among local and remote files, e-mail messages, faxes, voice mail and web pages.

The rise of the web has demonstrated how hypertext technologies can be used to build massive organized repositories of scattered information. But assembling information for the web still remains a great challenge and the data formats of the web are too structured to de‘al with the wide variety of information that people process. Modern web development requires the use of many languages: HTML, JavaScript, and CSS. This in itself prevents its use as the prime means of organizing and interlinking the constant flows of daily information.

GNU Hyperbole takes a distinctly different approach. It has its own hypertext technology that can interface perfectly with web links but which are much easier to create (simply drag from the source to the destination of a link to create a new hyperlink). Hyperbole hyperbuttons can link not only to static information but can perform arbitrary actions (through the use of button types written in a single, highly interactive language, Emacs Lisp). Hyperbole adds all of this power to your written documents, e-mail, news articles, contact management, outlines, directory listings, and much more. Hyperbole works well with the very latest versions of GNU Emacs across every editing and viewing mode in Emacs. It’s core hypertext capabilities operate as a global minor mode available across most file types, unlike Org mode which is its own structured file format.

Unlock the power of GNU Hyperbole to make your information work for you. One system. One language. One manual. One solution. Learn Hyperbole and start moving further, faster.

1.3 Hyperbole Overview ¶

GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee), or just Hyperbole, is like Markdown for hypertext. Hyperbole automatically recognizes dozens of common, pre-existing patterns in any buffer regardless of mode and can instantly activate them as hyperbuttons with a single key: email addresses, URLs, grep -n outputs, programming backtraces, sequences of Emacs keys, programming identifiers, Texinfo and Info cross-references, Org links, Markdown links and on and on. All you do is load Hyperbole and then your text comes to life with no extra effort or complex formatting.

Hyperbole includes easy-to-use, powerful hypertextual button types without the need to learn a markup language. Hyperbole’s button types are written in Lisp and can be wholly independent of the web, i.e. web links are one type of Hyperbole link, not fundamental to its link architecture. However, Hyperbole is a great assistant when editing HTML or Javascript or when browsing web pages and links.

Hyperbole comes pre-built with most of the implicit button types you will need but with a little extra effort and a few lines of code (or even just a few words), you can define your own implicit button types to recognize your specific buttons and then activate them anywhere in Emacs. You press a single key, {M-RET} by default, on any kind of Hyperbole button to activate it, so you can rely on your muscle memory and let the computer do the hard work of figuring out what to do. {C-u M-RET} shows you what any button will do in any context before you activate it, so you can always be sure of what you are doing when needed or if someone emails you a button (Hyperbole allows embedding buttons in email messages too).

Hyperbole is something to be experienced and interacted with, not understood from reading alone. It installs normally as a single Emacs package with no dependencies outside of built-in Emacs libraries, see Installation. Most of Hyperbole is a single global minor mode that you can activate and deactivate at will. And it can be uninstalled quickly as well if need be, so there is no risk in giving it a spin.

Once you have it installed, try the interactive demo with {C-h h d d}. In fact, if you have Hyperbole loaded and you use the Emacs Info reader to read this manual, you can press {M-RET} inside any of the brace delimited series of keys you see in this document and Hyperbole will execute them on-the-fly (easy keyboard-macro style buttons in any text).

Hyperbole can dramatically increase your productivity and greatly reduce the number of keyboard/mouse keys you’ll need to work efficiently.

Hyperbole consists of five parts.

Buttons and Smart Keys

There are three categories of buttons:

explicit buttons

may be added to documents with a simple drag between windows, no markup language needed. With two windows on screen, an explicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h e l}.

Implicit buttons

are patterns automatically recognized within existing text that perform actions, e.g. bug#24568 displays the bug status information for that Emacs bug number, without the need for any additional markup. Implicit link buttons can be added to documents with a simple drag between windows too.

Or from the keyboard, With two windows on screen, an implicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h i l}. Use {M-1 C-h h i l} instead to be prompted for a name for the implicit button.

Global buttons

are buttons that are activated by name from anywhere within Emacs. They may be either explicit or named implicit buttons. They are the named buttons stored in the a user’s personal button file, directly editable from the minibuffer menu with {C-h h b p}.

With two windows on screen, a global explicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h g l}. Use {C-u C-h h g l} instead to create a named global implicit button.

Buttons are activated by pressing {M-RET} on them, clicking them with a dedicated mouse button, or by referencing them by name (global buttons that can be activated regardless of what is on screen). Users create and activate Hyperbole buttons; see Buttons. Emacs Lisp programmers can develop new button types and actions. See Creating Types.

Hyperbole includes two special Smart Keys, the Action Key and the Assist Key, that perform an extensive array of context-sensitive operations across emacs usage, including activating and showing help for Hyperbole buttons. In many popular Emacs modes, they allow you to perform common, sometimes complex operations without having to use a different key for each operation. Just press a Smart Key and the right thing happens. The mouse versions of these keys additionally allow for drag actions. We call these the Action Mouse and Action Assist keys or buttons. See Smart Keys.

HyRolo

a powerful, hierarchical contact manager which anyone can use, is also included. It is easy to learn since it introduces only a few new mechanisms and has a menu interface, which may be operated from the keyboard or the mouse. It may also be used for full-text searching over any record-based information in any number of Org, Markdown, Koutline or Emacs Outline files. Hyperbole buttons may be embedded in any records. See HyRolo.

HyControl

the fastest, easiest-to-use window and frame control available for GNU Emacs. With just a few keystrokes, you can shift from increasing a window’s height by 5 lines to moving a frame by 220 pixels or immediately moving it to a screen corner. Text in each window or frame may be enlarged or shrunk (zoomed) for easy viewing, plus many other features; this allows Hyperbole to quickly control the way information is presented on-screen. See HyControl.

Koutliner

an advanced outliner with multi-level autonumbering and permanent identifiers attached to each outline node for use as hypertext link anchors, per node properties and flexible view specifications that can be included in links or used interactively. See Koutliner.

Hyperbole API

a set of programming libraries for system developers who want to integrate Hyperbole with another user interface or as a back-end to a distinct system. (All of Hyperbole is written in Emacs Lisp for ease of modification. It has been engineered for real-world usage and is well structured). See Developing with Hyperbole.

Hyperbole may be used simply for browsing through documents pre-configured with Hyperbole buttons, in which case, you can safely ignore most of the information in this manual. Jump right into the Hyperbole fast demonstration by typing {C-h h d d}, assuming Hyperbole has been installed at your site. If you need to install Hyperbole, see Setup, for Hyperbole installation and configuration information. The demo offers a much less technical introduction to Hyperbole by supplying good examples of use.

Image 1.1: Hyperbole Minibuffer Menu and Demonstration Screenshot

You likely will want to do more than browse with Hyperbole, e.g. create your own buttons. The standard Hyperbole button editing user interface is Emacs-based, so a basic familiarity with the Emacs editing model is useful. The material covered in the Emacs tutorial, normally bound to {C-h t}, is more than sufficient as background. See Glossary in the GNU Emacs Manual, if some emacs-related terms are unfamiliar to you.

A Hyperbole user works with chunks of information that need to be organized, interlinked, and processed. Such chunks can be hyperbuttons, address book contacts, items in an outline, or even database query results. Hyperbole does not enforce any particular hypertext or information management model, but instead allows you to organize your information in large or small chunks as you see fit. The Hyperbole outliner organizes information into hierarchies which may also contain links to external information sources. See Koutliner.

Some of Hyperbole’s most significant features are:

• Buttons may link to information or may execute functions, such as starting or communicating with external programs;
• A simple mouse drag from a button source location to its link destination is often all that is needed to create a new link. The keyboard can also be used to emulate such drags;
• Buttons may be embedded within electronic mail messages;
• Outlines allow rapid browsing, editing and movement of chunks of information organized into trees (hierarchies);
• Other hypertext and information retrieval systems may be encapsulated under a Hyperbole user interface (a number of samples are provided).

Typical Hyperbole applications include:

personal information management

Hyperlinks provide a variety of views into an information space. A search facility locates hyperbuttons in context and permits quick selection.

documentation and code browsing

Cross-references may be embedded within documentation and code. Existing documentation may be augmented with point-and-click interfaces to link code with associated design documents, or to permit direct access to the definition of identifiers by selecting their names within code or other documents.

brainstorming

The Hyperbole outliner (see Koutliner) is an effective tool for capturing ideas and then quickly reorganizing them in a meaningful way. Links to related ideas are easy to create so the need to copy and paste information is greatly reduced.

help/training systems

Tutorials with buttons can show students how things work while explaining the concepts, e.g. an introduction to the commands available on a computer system. This technique can be much more effective than written documentation alone.

archive managers

Programs that manage archives from incoming information streams may be supplemented by having them add topic-based buttons that link to the archive holdings. Users can then search and create their own links to archive entries.

1.4 Mail Lists ¶

If you use Hyperbole, you may join the mailing list <hyperbole-users@gnu.org> to discuss Hyperbole with users and maintainers. There is a separate mail list to report problems or bugs with Hyperbole, <bug-hyperbole@gnu.org>. For more details, see Suggestion or Bug Reporting.

2.1 Invocation ¶

You can invoke Hyperbole’s commands in one of three ways:

• use the Hyperbole entry on your menubar;
• type {C-h h} or {M-x hyperbole RET} to display the Hyperbole minibuffer menu;
• use a specific Hyperbole command, for example, a press of {M-RET} on a pathname to display the associated file or directory.

{C-h h} enables Hyperbole if it has been disabled and displays a Hyperbole menu in the minibuffer for quick keyboard or mouse-based selection. Select an item from this menu by typing the item’s first capital letter. Use {Q} (note this is capitalized) to quit from the minibuffer menu while leaving Hyperbole enabled. Use {X} (note this is capitalized) to quit from the minibuffer menu and disable Hyperbole’s minor mode.

Use {C-h h d d} for an interactive demonstration of standard Hyperbole button capabilities.

Type {C-h h k e} for an interactive demonstration of the Koutliner, Hyperbole’s multi-level autonumbered hypertextual outliner.

To try out HyControl, Hyperbole’s interactive frame and window control system, use {C-h h s w} for window control or {C-h h s f} for frame control. Pressing {t} switches between window and frame control once in HyControl. Hyperbole also binds {C-c \} for quick access to HyControl’s window control menu if it was not already bound prior to Hyperbole’s initialization.

Videos demonstrating Hyperbole’s features are listed at https://gnu.org/s/hyperbole.

The above are the best interactive ways to learn about Hyperbole.

2.2 Documentation ¶

The Hyperbole Manual is a reference manual, not a simple introduction. It is included in the man/ subdirectory of the Hyperbole package directory in four forms:

man/hyperbole.info   - online Info browser version
man/hyperbole.html   - web HTML version
man/hyperbole.pdf    - printable version
man/hyperbole.texi   - source form

The Hyperbole package installation places the Info version of this manual where needed and adds an entry for Hyperbole into the Info directory under the Emacs category. {C-h h d i} will let you browse the manual. Then use {s} to search for anything throughout the manual. For web browsing, point your browser to ${hyperb:dir}/man/hyperbole.html, wherever the Hyperbole package directory is on your system; often this is: ~/.emacs.d/elpa/hyperbole-${hyperb:version}/.

2.3 Hyperbole Hooks ¶

When Hyperbole’s code is first loaded and initialized, hyperbole-init-hook is run. 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.

If you prefer a different key to activate Hyperbole, you can bind it as part of any setting of hyperbole-init-hook within your personal ~/.emacs file. For example:

(add-hook 'hyperbole-init-hook
   (lambda () (global-set-key
                "\C-ch" 'hyperbole--enable-mode)
              (global-set-key
                "\C-hh" 'view-hello-file)))

then restart Emacs.

3.1 Smart Key Bindings ¶

With hyperbole-mode enabled, {M-RET} is the Action Key and {C-u M-RET} is the Assist Key. These keys allow context-sensitive operation from any keyboard.

Mouse configuration of the Smart Keys is automatic for GNU Emacs under Mac OS X, the X Window System and MS Windows, assuming your emacs program has been built with support for any of these window systems.

The Action Mouse Key is bound to your shift-middle mouse key (or shift-left on a 2-button mouse). The Assist Mouse Key is bound to your shift-right mouse key, assuming Hyperbole is run under an external window system. These keys support Drag Actions, see Smart Mouse Keys, as well as the standard Smart Key presses.

If you set the variable, hmouse-middle-flag, to ‘t’ before loading Hyperbole, then you may also use the middle mouse key as the Action Key. If you want both the middle mouse key as the Action Key and the right mouse key as the Assist Key for ease of use, then within your personal ~/.emacs file, add:

(add-hook 'hyperbole-init-hook
          'hmouse-add-unshifted-smart-keys)

and then restart Emacs.

If you prefer other Smart Key bindings, simply bind the commands action-key and assist-key to keyboard keys. Hyperbole binds {M-RET} to the command hkey-either; this provides a single key binding for both Smart Key commands; a prefix argument, such as {C-u}, then invokes assist-key actions.

You may also bind action-mouse-key and assist-mouse-key to other mouse keys, though you won’t be able to execute mouse drag actions with such key bindings. See Smart Mouse Key Drags, and see Keyboard Drags.

To permanently change any of these key bindings, use:

(add-hook 'hyperbole-init-hook
          (lambda () (hkey-set-key <KEY> '<CMD>)

for example, (hkey-set-key "\M-'" 'hkey-either).

3.2 Smart Key Operations ¶

The Action Key generally selects entities, creates links and activates buttons. The Assist Key generally provides help, such as reporting on a button’s attributes, or serves a complementary function to whatever the Action Key does within a context.

The Hyperbole Doc/SmartKeys menu entry, {C-h h d s}, displays a summary of what the Smart Keys do in all of their different contexts. Alternatively, a click of the Assist Mouse Key in the right corner of a window modeline (within the rightmost 3 characters) toggles between displaying this summary and hiding it. Reference this summary whenever you need it.

The following table is the same summary. Much of the browsing power of Hyperbole comes from the use of the Smart Keys, so spend some time practicing how to use them. Study what modeline clicks and window drag actions do as these will give you a lot of power without much effort. This table may appear daunting at first, but as you practice and notice that the Smart Keys do just a few context-sensitive things per editor mode, you will find it easy to just press or point and click and let Hyperbole do the right thing in each context.

========================================================================================
                                              Smart Keys
Context                         Action Key                 Assist Key
========================================================================================
Hyperbole
  On a minibuffer menu item     Activates item             Item help
  On an explicit button         Activates button           Button help
  Reading argument
    1st press at an arg value   Copies value to minibuffer <- same
    2nd press at an arg value   Uses value as argument     <- same
    In minibuffer at eol        Accepts minibuffer arg     List completions
    In minibuffer before eol    Deletes rest of arg        Deletes rest of arg
  On an implicit button/path    Activates button/path      Button help
  Within a koutline cell        Collapses and expands      Shows tree props
  Left of a koutline cell       Creates a klink            Moves a tree
  HyRolo Match Buffer           Edits entries and mails to e-mail addresses

Mouse or Keyboard Display Control
  Line end, not end of buffer
    smart-scroll-proportional
      = t   (default)           Makes curr line top line   Bottom line
      = nil                     Scrolls up a windowful     Scrolls down
  End of Any Help buffer        Restores screen to the previous state
  Read-only View Mode           Scrolls up a windowful     Scrolls wind down

Mouse-only Control
  Drag from thing start or end  Yanks thing at release     Kills thing and yanks
    A thing is a delimited                                 at release
    expression, such as a
    string, list or markup
    language tag pair

  Drag from bottom Modeline     Repositions frame as       <- same
  in frame with non-nil         drag happens
  drag-with-mode-line param

  Drag from shared window side
    or from left of scroll bar  Resizes window width       <- same
  Modeline vertical drag        Resizes window height      <- same

  Other Modeline drag to        Replaces dest. buffer      Swaps window buffers
    another window                with source buffer

  Drag to a Modeline from:
    but/buffer/file menu item   Displays ref/buffer/file   Swaps window buffers
                                  in new window by release
    buffer/file menu 1st line   Moves buffer/file menu to  Swaps window buffers
                                  new window by release
    anywhere else               Displays buffer in         Swaps window buffers
                                  new window by release

  Drag between windows from:
    but/buffer/file menu item   Displays ref/buffer/file   <- same
                                  in window of button release 
    buffer/file menu 1st line   Moves buffer/file menu     <- same
    anywhere else               Creates an ibut link       Creates an ebut link

  Drag outside of Emacs from:
    but/buffer/file menu item   Displays ref/buffer/file   Moves window to new frame
                                  in a new frame
    Modeline or other window    Clones window to new frame Moves window to new frame

  Modeline Click
    Left modeline edge          Buries current buffer      Unburies bottom buffer
    Right modeline edge         Displays GNU Info manuals  Displays Smart Key summary
    Buffer ID                   Dired on buffer's dir      Displays next buffer
                                  or on parent when a dir
    Other blank area            Action Key modeline hook   Assist Key modeline hook
                                  Shows/Hides Buffer Menu    Popups Screen & Jump Menus

  Drag in window, region active Error, not allowed         Error, not allowed
  Horizontal drag in a window   Splits window below        Deletes window
  Vertical drag in a window     Splits window side-by-side Deletes window
  Diagonal drag in a window     Saves wconfig              Restores wconfig from ring

  Active region exists, click   Yanks region at release    Kills and yanks at release
   outside of the region

Hyperbole Key Press/Click in Special Modes
  Region Active                 Yanks region at release    Kills and yanks at release
  Company Mode Completion       Displays definition        Displays documentation
  Helm Completion               Displays item              Displays item
  Emacs Push Button             Activates button           Button help
  Emacs Regression Test Def     Evals and runs test        Edebugs and runs test
  Thing Begin or End            Marks thing region         Marks & kills thing region
  Flymake Linter Mode           Jumps to issue at point    Displays issue at point
  Page Directory Listing        Jumps to page              <- same
  C,C++,Objective-C,Java Modes  Jumps to id/include def    Jumps to next def
  Assembly Language Mode        Jumps to id/include def    Jumps to next def
  Java Cross-reference Tag      Jumps to identifier def    Jumps to next def
  JavaScript and Python Modes   Jumps to identifier def    Jumps to next def
  Any Known Lisp or ChangeLog   Jumps to identifier def    Referent Doc
  Fortran Mode                  Jumps to identifier def    Jumps to next def
  Imenu Programming Identifier  Jumps to in-buffer def     Prompts for id to jump to
  Emacs Lisp Compiler Error     Jumps to def with error    <- same
  Emacs Regression Test (ERT)   Jumps to def with error    <- same
  Other Compiler Error          Jumps to src error line    <- same
  Grep or Occur Match           Jumps to match source line <- same
  Multi-buffer Occur Match      Jumps to match source line <- same
  Etags `TAGS' file entry       Jumps to source line       Button help
  Ctags file entry              Jumps to source line       Button help
  Texinfo Cross-reference
    Before opening brace        Jumps to Texinfo referent  Button help
    Within braces               Jumps to Info referent     Button help
    Menu Item or node hdr       Jumps to Texinfo referent  Button help
    Include file                Jumps to Texinfo referent  Button help
    code/var reference          Displays doc for referent  Button help
  Org Mode                      Follows links, cycles headings and Org Meta Return
  Org/Roam ID                   Jumps to ID referent       Button help
  Outline Major/Minor Modes     Collapses, expands, and moves outline entries
  Man Apropos                   Displays man page entry    <- same
  Man Pages                     Follows cross refs, file refs and C code refs
  I/Buffer Menu                 Saves, deletes and displays buffers
  Todotxt Mode                  Toggles item completion    Edit and archive items

Emacs Info Reader
  Menu Entry or Cross Ref       Jumps to referent          <- same
  Up, Next or Prev Header       Jumps to referent          Jumps to prior node
  File entry of Header          Jumps to top node          Jumps to (DIR) node
  End of current node           Jumps to next node         Jumps to previous node
  Anywhere else                 Scrolls up a windowful     Scrolls down a windowful

Subsystems
  Calendar                      Scrolls or shows appts     Scrolls/marks date
  GNU Debbugs Tracker           Displays issue discussion  Displays issue status
  Treemacs                      Displays item              Displays item
  Dired Sidebar                 Displays item              Displays item
  Dired Mode                    Views and deletes files from dir listing
  Magit Modes                   Collapses, expands and jumps to things
  GNUS News Reader              Toggles group subscriptions, gets new news,
                                  and browses articles
  Mail Reader and Summaries     Browses, deletes and expunges messages
  OO-Browser                    Browses object classes and elements
  Tar Mode                      Views and edits files from tar archive files

Any other context (defaults)    Invalid context error      Invalid context error
========================================================================================

See Smart Key Reference, for extensive reference documentation on the Smart Keys.

Note how the last line in the table explains that the default behavior of the Smart Keys in an unknown context is to report an error. You can change these behaviors by setting two variables. See the documentation for the variables action-key-default-function and assist-key-default-function for information on how to customize the behavior of the Smart Keys within default contexts.

When you use a mouse and you want to find out what either of the Smart Keys does within a context, depress the one you want to check on and hold it down, then press the other and release as you please. A help buffer will pop up explaining the action that will be performed in that context and attributes of the button, if any. A press of either Smart Key at the end of that help buffer will restore your display to its configuration prior to invoking help.

On the keyboard, {C-h A} displays this same context-sensitive help for the Action Key while {C-u C-h A} displays the help for the Assist Key. Note that {C-h a} performs a function unrelated to Hyperbole, so you must press the shift key when you type the A character.

3.3 Smart Key Argument Selection ¶

A prime design criterion of Hyperbole’s user interface is that you should be able to see what an operation will do before using it. The Assist Key typically shows you what a button or minibuffer menu item will do before you activate it. Hyperbole also displays the result of directly selecting an argument value with the Action Key, to provide feedback as to whether the correct item has been selected. A second press/click is necessary before an argument is accepted and processed.

Many Hyperbole commands prompt you for arguments. The standard Hyperbole user interface has an extensive core of argument types that it recognizes. Whenever Hyperbole is prompting you for an argument, it knows the type that it needs and provides some error checking to help you get it right. More importantly, it allows you to press the Action Key within an entity that you want to use as an argument. Hyperbole will copy the appropriate thing to the minibuffer as the argument. If you press (click with a mouse) the Action Key on the same thing again, e.g. within a list of possible completions, Hyperbole exits the minibuffer and uses the current argument. Thus, a double click registers a desired argument. Double-quoted strings, pathnames, mail messages, Info nodes, dired listings, buffers, numbers, completion items and so forth are all recognized at appropriate times. All of the argument types mentioned in the documentation for the Emacs Lisp interactive function are recognized. Experiment a little and you will quickly get used to this direct selection technique.

Wherever possible, standard Emacs completion is offered, as described in Completion in the GNU Emacs Manual. Remember to use {?} to see what your possibilities for an argument are if completions are not automatically shown to you. Once you have a list of possible completions on screen, press the Action Key twice on any item to enter it as the argument. If you are using the Vertico completion library with completions displayed in the minibuffer, selection of completions works the same as if they were displayed in a separate buffer as in standard Emacs.

Within the minibuffer itself, the Smart Keys are also context-sensitive. A press of the Action Key at the end of the argument line tries to accept the argument and when successful, exits the minibuffer. A press of the Assist Key at the end of the argument line displays matching completions for times when they are not automatically displayed or need updating. A press of the Action or Assist Key on part of the argument, deletes from point to the end of the line, expanding the set of available completions and redisplaying them.

3.4 Smart Key Debugging ¶

Typically, {C-h A} and {C-u C-h A} which show Action and Assist Key help for the current context, are sufficient for seeing how the Smart Keys behave no matter where they are used.

However, if a Smart Key ever behaves differently than you think it should or if you want to test how the Smart Keys respond in a new context, then the Smart Key debugging flag may be of use. You toggle it on and off with {C-h h c d} (minibuffer menu Cust/Debug-Toggle). Once enabled, this displays a message in the minibuffer each time the Action or Assist Key is released, showing the context of the press and its associated action, so you can see exactly what is happening whenever you use a Smart Key. These messages are all prefaced with “(HyDebug)” and logged to the “*Messages*” buffer for later viewing.

If you do find a problem with the Smart Keys and want to report a bug, use {C-h h m r} to compose an email message to the bug-hyperbole list. Hyperbole will automatically include all of the “(HyDebug)” messages from your current emacs session into your email. Similarly, when you compose an email to the hyperbole-users mailing list with {C-h h m c}, these messages are also included.

3.5 Smart Key Thing Selection ¶

Hyperbole has some radically cool ways to select regions of structured text or source code and to copy or move them between buffers with a single mouse drag or two key presses. A great deal of smarts are built-in so that it does the right thing most of the time; many other attempts at similar behavior such as thingatpt.el fail to deal with many file format complexities.

We use the term things to refer to structured entities that Hyperbole can select. These include: delimited pairs of (), {}, <>, [] and quote marks, source code functions, source code comments and matching tag pairs in HTML and SGML modes. Delimited things are those things that contain a selectable delimiter such as an opening parenthesis.

The best way to mark a delimited thing is to move your cursor to the starting delimiter of the thing and then press the Action Key. Typically, you will see the thing highlight. You can then operate upon it as you would any Emacs region. In many cases, you can do the same thing upon the closing delimiter, but this is not as reliable. An Action Key press on the start of an HTML, XML, or SGML tag pair marks the entire region span of the pair. If you use the Assist Key instead, it will mark and kill (delete) the thing.

Even better are Smart Mouse Key thing drags which let you copy or move delimited things in one operation without having to select a region. To copy, simply drag with the Action Key from a thing’s opening delimiter and release somewhere outside of the thing, either within the same window or within another window. The thing will be copied to the point of release. If you want to move a thing, simply perform the same drag but with the Assist Mouse Key. Ensure that you do not move any explicit buttons from one buffer to another as that does not work.

Hyperbole also binds two convenience keys for working with things.

The first such key is {C-c RET} hui-select-thing which selects bigger and bigger syntactic regions with each successive use. Double or triple clicks of the Selection Key (left mouse key) do the same thing. The first press selects a region based upon the character at point. For example, with point over an opening or closing grouping character, such as { or }, the whole grouping is selected, e.g. a C function. When on an _ or - within a programming language identifier name, the whole name is selected. The type of selection is displayed in the minibuffer as feedback. When using a language in which indentation determines nesting level like Python, a double click on the first alpha character of a line, such as an if statement, selects the current clause (until the next line at the same or lesser indentation). Use {C-g} to unmark the region when done. Use, hui-select-thing-with-mouse if you want to bind this to a different mouse key to use single clicks instead of double clicks.

This key defers to any currently active major-mode which also binds it.

The second convenience key is bound in HTML/XML/SGML/web modes. {C-c .} hui-select-goto-matching-tag jumps between the opening and closing tag of a pair. It moves point to the start of the tag paired with the closest tag that point is within or which it precedes. A second press moves point to the matching tag of the pair, allowing you to quickly jump back and forth between opening and closing tags.

This key defers to any currently active major-mode which also binds it.

3.6 Smart Mouse Key Modeline Clicks ¶

Smart Mouse Key clicks on a window’s modeline offer many powerful browsing features, including directory editing (dired), user manual browsing, and window, buffer and frame selection. Generally, only Hyperbole-specific modeline actions are discussed herein.

• Leftmost Character

  Action Key clicks on the first (usually blank) character of the modeline bury the current buffer in the buffer list and display the next buffer in the list. Assist Key clicks do the reverse and unbury the bottom buffer.

  A similar effect can be achieved with the standard Emacs mouse 1 (left) and 3 (right) buttons on the Buffer ID element of modeline to cycle through previous and next buffers, respectively. This may be easier to use since you can click anywhere on the buffer identifier.

• Buffer ID Element

  On the left part of the modeline is the buffer identification, generally the name of the buffer in use. An Action Key click on that switches the window to edit the buffer’s directory using dired. Then Action Key clicks on directory items in the dired buffer display the items selected in other windows. An Action Key drag from an item to another window displays the item in that window.

  An Action Key click on the first line in a dired buffer which contains the current directory path, specifically on any ancestor part of the path (the part to the left of the click point), starts another dired session on the ancestor directory. Click at the end of this line or on the last line to end the dired session (bury its buffer).

  If you use the Treemacs file viewer Emacs package, you can configure Hyperbole to use this instead of Dired when you click on a modeline buffer id.

  Since this is a customization option, it may be changed permanently like so. Use {M-x customize-set-variable RET action-key-modeline-buffer-id-function RET}. Change the value to smart-treemacs-modeline. Then press RET. To change it back to Hyperbole’s default, use the value, dired-jump.

• Large Blank Area

  An Action Mouse Key click in a blank area of a window modeline (away from left and right edges) toggles between displaying and hiding a list of all buffers. Once displayed, an Action Key click on a buffer item will display it in another window. You can drag items to specific windows for display as well.

  Alternatively, you may (1) display the buffer menu, (2) use its {m} command to mark buffers, and (3) use the Hyperbole {@} command to display the marked buffers in a grid of popup windows whose number of rows and columns you specify at the prompt or via a prefix argument. This also works in ibuffer-menu and dired modes. See HyControl.

  An Assist Key click in the blank area of the modeline displays a quick access menu of display-oriented commands. You can jump to buffers categorized by major mode, jump to windows by buffer name, or to frames by name. Manage your windows and frames quickly with this menu as well. As always with Hyperbole, just try it and you’ll begin to wonder how you lived without it before.

• Right Corner

  A click of the Action Mouse Key in the right corner of a window modeline (within the rightmost 3 characters) displays or hides the GNU Info Manual Browser, giving you quick point and click access to an amazing wealth of documentation, since the Action Key also browses through these manuals and follows their hyperlinked cross-references. A click of the Assist Key in the same location displays or hides the Smart Key summary, as noted earlier.

• Customizable Variables

  Hyperbole modeline mouse click actions are controlled by the two functions, action-key-modeline and assist-key-modeline. If you know a little Emacs Lisp you can change these to do whatever you like. When a Smart Key press is on a blank part of a modeline but not at the left or right, the function given by one of these two variables is executed: action-key-modeline-function or assist-key-modeline-function. By default, the Action Key toggles between displaying and hiding the buffer menu. If you like the more advanced features of Ibuffer Mode, you can change the buffer menu to use that with the following in your Emacs initialization file: (setq action-key-modeline-function #'hmouse-context-ibuffer-menu). To set it back to the default use: (setq action-key-modeline-function #'hmouse-context-menu).

  The default assist-key-modeline-function is to pop up a menu of convenient screen commands that lets you select buffers grouped by major mode, use HyControl, or jump to specific windows, window configurations or frames.

  Since these are customization options, they may be change permanently like so. Use {M-x customize-set-variable RET assist-key-modeline-function RET}. Change the value to your desired command. Then press RET.

3.7 Smart Mouse Key Drags ¶

As mentioned in the section on Thing Selection, Hyperbole Smart Mouse Key drag actions can be quite useful. This section summarizes other drag contexts and actions; for complete documentation, see Smart Mouse Keys.

• Creating and Deleting Windows
• Saving and Restoring Window Configurations
• Resizing Windows
• Moving Frames
• Dragging Buffers, Windows and Items

4.1 Explicit Buttons ¶

Hyperbole creates and manages explicit buttons which perform specific actions when activated (typically through a button press). They look like this ‘<(fake button)>’. They are quickly recognizable, yet relatively non-distracting as you scan the text in which they are embedded. The text between the ‘<(’ and ‘)>’ delimiters is called the button label or button name. Spacing between words within a button label is irrelevant to Hyperbole. Button labels may wrap across several lines without causing a problem; just be sure to select the first line of the button to activate it.

Explicit buttons may be added to any editable buffer including temporary buffers without any attached files (such buttons will last only the length of a single Emacs session). For source code files, simply place Hyperbole explicit buttons within comments. Buttons that you use for quick navigation to websites or other things you do often should be added to your personal button file. See Button Files.

Explicit buttons may be freely moved about within the buffer in which they are created. (No present support exists for moving buttons between buffers). A single button may also appear multiple times within the same buffer; simply copy the button label with its delimiters to a new location if you need another copy of it.

For details on how to create, activate, delete or edit explicit buttons, see Utilizing Explicit Buttons.

Each explicit button is assigned an action type that determines the actions it performs. Hyperbole includes its own set of useful action types but any named, interactive Emacs Lisp command may be used. For example, Link action types connect buttons to particular types of referents, the targets of their links. Link action type names all begin with link-. Link action button referents are displayed when such buttons are activated with a press or a click. See Action Types, for a list of Hyperbole action types, including link types.

Hyperbole does not manage referent data; this is left to the applications that generate the data. This means that Hyperbole provides in-place linking and does not require reformatting data to integrate it with Hyperbole.

Hyperbole stores the button data that gives an explicit button its behavior, separately from the button label, in a file named .hypb (_hypb under MS Windows) within the same directory as the file in which the button is created. Thus, all files in the same directory share a common button data file. Button data is comprised of individual button attribute values. A user never sees this data in its raw form but may see a formatted version by asking for help on a button.

4.2 Global Buttons ¶

Sometimes it is useful to activate buttons without regard to the information with which you are working. In such instances, you use global buttons, which are buttons that may be activated or otherwise operated upon by typing their names/labels when they are prompted for, rather than selecting the buttons within a buffer. In contrast, activation of explicit buttons depends upon the information on your screen since they are accessible only from within their particular buffers.

If you want a permanent link to a file section that you can follow at any time, you can use a global button. Or what about an Emacs keyboard macro that you use frequently? Create a global button with an action type of exec-kbd-macro button and an easy to type name. Then you can activate it whenever the need arises.

Global buttons are managed with the Hyperbole Gbut/ menu accessed with {C-h h g}. The Create item, {C-h h g c}, prompts for a global button name, an action type, and the action’s associated arguments, such as a file to which to link. It then creates the button. To activate the button, use the Act menu item, {C-h h g a}. Type the button’s name, press {RET}, and then Hyperbole prompts you for its action type and associated arguments. {C-h h g e} to edit an existing global button. To remove a button, use the Delete menu item, {C-h h g d}; see Deletion.

To create a global button that links to point in one of your Emacs windows, use the Link menu item, {C-h h g l}.

By default this will create a global explicit link button. Give it a prefix argument to create a global implicit link button.

With a single window visible on-screen or a single window within your current frame, this will prompt you for a button name or label (temporarily showing you your global/personal button file) and then will insert a button that links to the current point within that window.

If you have exactly two Emacs windows in your current frame or exactly two windows visible across two Emacs frames, then the link referent will be to the point in the other, non-selected window.

With more than two windows on screen, Hyperbole will prompt you to choose the referent window and its associated point to which to link. If the Ace Window package is installed and active, this will be used to choose the window via keyboard; otherwise, you will be prompted to select it by mouse.

Global buttons are actually explicit buttons stored at the end of your personal button file, see Button Files. You can always go into that file and activate, edit or annotate these buttons with comments.

Emacs has a built-in feature similar to Global Buttons called Bookmarks. Bookmarks store places in files or link to URLs, so they are more limited than Hyperbole’s global buttons and cannot utilize all of Hyperbole’s capabilities for performing actions. Hyperbole has an action type, link-to-bookmark, for using an Emacs bookmark as a Hyperbole button referent. See Bookmarks in the Emacs Manual, for details on bookmarks.

4.3 Implicit Buttons ¶

Hyperbole can recognize and activate implicit buttons within documents that require no special markup, e.g. pathnames or URLs, and many other types. For example, an Action Key press on a web URL will display its link in a browser, regardless of the format of the document. Similarly, an Action Key press on an email address starts composing mail to that address.

Implicit buttons are identified by implicit button type contextual pattern matchers that identify appropriate textual patterns at point. An implicit button type utilizes Emacs Lisp to identify a pattern or state that when matched triggers an action associated with the implicit button type. The action is specified by either a Hyperbole action type (see Action Types) or an Emacs Lisp command. Implicit button types may use the same action types that explicit buttons use. As an example, the pathname implicit button type matches to any existing local filename or directory name and its action type, link-to-file, displays the associated file or directory, typically in another window. An explicit button could do the same thing but has to be created manually, rather than recognized as part of the buffer text.

Implicit buttons are managed with the Hyperbole Ibut/ menu accessed with {C-h h i}. The Create item, {C-h h i c}, prompts for an implicit button name (default is any selected region), an action type, and the action’s associated arguments. It then creates the button at point. Use this to create a button with any implicit button type, not just links.

Alternatively, to create an implicit link button to something displayed within an Emacs window (the referent), simply drag with the Action Mouse Key depressed from an editable source window to another window with the desired link referent and then release. The drag must start outside of a draggable item, see Displaying Items. Hyperbole will either automatically select the button type based on the referent context or will prompt you to select from one of a few possible link types.

If you have exactly two Emacs windows in your current frame or exactly two windows visible across two Emacs frames, this is even easier. Simply use the Link menu item, {C-h h i l}, to create a new unnamed implicit link button or to edit the one at point. {C-u C-h h i l} will additionally prompt to add a name or rename the button at point. With more than two windows, Hyperbole will prompt you to choose the referent window and its associated point to which to link. If the Ace Window package is installed and active, this will be used to choose the window via keyboard; otherwise, you will be prompted to select it by mouse.

To activate an implicit button with point on its name or button text, use the Act menu item, {C-h h i a} or press the Action Key. You can use {C-h h i e} to edit an implicit button (or simply edit it manually). If you want to add a name to an existing implicit button without one, use {C-h h i n} to name it. Rename an existing named implicit button with {C-h h i r}.

Unlike explicit buttons, implicit buttons have no individual button data other than their text and optional labels. You use implicit button types which include boolean expressions (predicates) that match to both the label and the context required of any button of the type. Each time a Smart Key is pressed at a location, Hyperbole evaluates the predicates from the list of implicit button types and the first one that evaluates true is selected and its associated action is triggered.

All of this happens transparently and is easy to use once you try it. The Hyperbole Smart Keys offer additional extensive context-sensitive point-and-click type behavior beyond implicit button types. See Smart Key Operations.

Individual implicit buttons may be labeled/named, allowing activation by name or use as a link target by other buttons. Such names are highlighted similarly to explicit button names. Here is a pathname button with a label of ’My Emacs Files’:

<[My Emacs Files]>: "~/.emacs.d"

The name is delimited by ‘<[’ and ‘]>’ and can be followed by any number of :, - or = separator characters, including none.

• Implicit Button Types
• Action Buttons

|--------------+-------------------+------------------+----------+------------------|
| This Setting | 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             |
|--------------+-------------------+------------------+----------+------------------|

4.4 Button Files ¶

It is often convenient to create files filled with buttons as a means of navigating distributed information pools or for other purposes. These files can also serve as useful roadmaps that guide a user through both unfamiliar and highly familiar information spaces. Files that are created specifically for this purpose are called Hyperbole button files.

The Hyperbole menu system provides quick access to two types of these button files: personal and directory-specific, through the ButFile menu. (The variable, hbmap:filename, contains the base name of these button files. Its standard value is HYPB.)

A personal button file may serve as a user’s own roadmap to frequently used resources, like a personal home page. Selection of the ButFile/PersonalFile menu item, {C-h h b p}, displays this file for editing. The default personal button file is stored within the directory given by the hbmap:dir-user variable whose standard value is ~/.hyperb. The default Hyperbole configuration also appends all global buttons to the end of this file, one per line, as they are created. So you can edit or annotate them within the file.

A directory-specific button file may exist for each file system directory. Such files are useful for explaining the contents of directories and pointing readers to particular highlights within the directories. Selection of the ButFile/DirFile menu item, {C-h h b d}, displays the button file for the current directory; this provides an easy means of updating this file when working on a file within the same directory. If you want to view some other directory-specific button file, simply use the normal Emacs file finding commands.

If you want group and site-specific button files, simply place links to such files at the top of your personal button file and do so for your colleagues. This provides a flexible means of connecting to such resources.

4.5 Action Types ¶

Action types are Emacs Lisp commands that specify Hyperbole button behaviors. Hyperbole includes a useful set of action types defined within their own namespace and created with the defact macro. See the Hyperbole file, hactypes.el, for examples of how to define your own Hyperbole action types.

Each action type may be used by any category of button: global, explicit, or implicit. The arguments needed by an action type are prompted for at button creation time or in the case of an implicit button, computed when the button is activated. During button activation, the arguments are fed to the action type’s body to achieve the desired result. This body is called the button action.

Hyperbole handles all of this processing transparently. As a user, all you need know is the set of action types that you can work with when creating explicit or global buttons.

Hyperbole action types in alphabetical order are:

annot-bib ¶

Follow an internal reference KEY within an annotated bibliography, delimiters = [ ].

completion ¶

Insert a completion at point into the minibuffer or a buffer. Unless point is at the end of buffer or if a completion has already been inserted, in which case, delete the completions window.

debbugs-gnu-query ¶

Display the discussion of Gnu debbugs ID (a positive integer).

display-boolean ¶

Display a message showing the result value of a BOOL-EXPR. Return any non-‘nil’ value or ‘t’.

display-value ¶

Display a message showing VALUE (a symbol) and its value. Return any non-‘nil’ value or ‘t’.

display-variable ¶

Display a message showing the given variable name and its value.

eval-elisp ¶

Evaluate a Lisp expression LISP-EXPR for its side-effects and return any non-nil value.

exec-kbd-macro ¶

Execute a KBD-MACRO REPEAT-COUNT times. KBD-MACRO may be a string of editor command characters, a function symbol or nil to use the last defined keyboard macro. Optional REPEAT-COUNT nil means execute once, zero means repeat until error.

exec-shell-cmd ¶

Execute a SHELL-CMD string asynchronously. Optional non-nil second argument INTERNAL-CMD inhibits display of the shell command line executed. Optional non-nil third argument KILL-PREV means kill the last output to the shell buffer before executing SHELL-CMD.

exec-window-cmd ¶

Asynchronously execute an external window-based SHELL-CMD string.

git-reference ¶

Display the git entity associated with REFERENCE and optional PROJECT. See ${hyperb:dir}/DEMO#Git (Local) References for examples.

REFERENCE is a string of one of the following forms:

• <ref-item>
• /?<project>/<ref-item>
• /<project>.

<ref-item> is one of these:

one of the words: branches, commits, or tags

the associated items are listed

one of the words: branch, commit, or tag followed by a ’/’ and item id

the item is shown

a commit reference given by a hex number, 55a1f0

the commit diff is displayed

a branch or tag reference given by an alphanumeric name, e.g. hyper20

the files in the branch are listed.

If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-git-default-project.

github-reference ¶

Display the Github entity associated with REFERENCE and optional USER and PROJECT. See ${hyperb:dir}/DEMO#Github (Remote) References for examples.

REFERENCE is a string of one of the following forms:

• <ref-item>
• <user>/<project>/<ref-item>
• <project>/<ref-item>
• /<project>.

<ref-item> is one of these:

• one of the words: branches, commits, issues, pulls, or tags

the associated items are listed

• one of the words: branch, commit, issue, pull or tag followed by a ’/’, ’-’, or ’=’, and item id

the item is shown

• an issue reference given by a positive integer, e.g. 92 or prefaced with GH-, like GH-92

the issue is displayed

• a commit reference given by a hex number, 55a1f0

the commit diff is displayed

• a filename reference given by an alphanumeric name; the file

is displayed.

USER defaults to the value of hibtypes-github-default-user. If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-github-default-project.

gitlab-reference ¶

Display the Gitlab entity associated with REFERENCE and optional USER and PROJECT. See ../DEMO#Gitlab (Remote) References for examples.

REFERENCE is a string of one of the following forms:

• <ref-item>
• <user>/<project>/<ref-item>
• <project>/<ref-item>
• /<group>/<project>. or
• /<project-or-group> (where a group is a collection of projects)

<ref-item> is one of these:

• one of the words: activity, analytics, boards or kanban, branches, commits, contributors, groups, issues or list, jobs, labels, merge_requests, milestones, pages, pipelines, pipeline_charts, members or people or staff, projects, pulls, schedules, snippets, status or tags

the associated items are listed

• one of the words: branch, commit(s), issue(s), milestone(s), pull(s), snippet(s) or tag(s) followed by a ’/’, ’-’, or ’=’, and an item-id

the item is shown

• an issue reference given by a positive integer, e.g. 92 or prefaced with GL-, like GL-92

the issue is displayed

• a commit reference given by a hex number, 55a1f0

the commit diff is displayed

• a branch or tag reference given by an alphanumeric name, e.g. hyper20

the files in the branch are listed.

USER defaults to the value of hibtypes-gitlab-default-user. If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-gitlab-default-project.

hyp-config ¶

Insert Hyperbole configuration and debugging information at the end of the current buffer or within optional OUT-BUF.

hyp-request ¶

Insert help for composing a Hyperbole support/discussion message into the current buffer or the optional OUT-BUF.

hyp-source ¶

Display a buffer or file from a line beginning with hbut:source-prefix.

kbd-key ¶

Execute a normalized KEY-SERIES (series of key sequences) without curly braces. Each key sequence within KEY-SERIES must be a string of one of the following:

• a Hyperbole minibuffer menu item key sequence,
• a HyControl key sequence,
• a M-x extended command,
• or a valid key sequence together with its interactive arguments.

Return ‘t’ if the sequence appears to be valid, else ‘nil’.

link-to-bookmark ¶

Display an Emacs BOOKMARK. When creating the button, if in Bookmark Menu mode, use the bookmark nearest point as the default. Otherwise, utilize the most recently used bookmark in the current file (bookmark-current-bookmark) as the default, if any.

link-to-buffer-tmp ¶

Display a BUFFER. This type of link is for use in a single editor session. Use link-to-file instead for a permanent link.

link-to-directory ¶

Display a DIRECTORY in Dired mode.

link-to-doc ¶

Display an online version of a document given by DOC-ID. If the online version of a document is not found in doc-id-indices, signal an error.

link-to-ebut ¶

Perform an action given by an explicit button, specified by KEY and KEY-FILE.

link-to-elisp-doc ¶

Display the documentation for FUNC-SYMBOL.

link-to-file ¶

Display a file given by PATH scrolled to optional POINT. If POINT is given, display the buffer with POINT at the top of the window.

link-to-file-line ¶

Display a file given by PATH scrolled to LINE-NUM.

link-to-gbut ¶

Perform an action given by an existing global button, specified by KEY.

link-to-Info-index-item ¶

Display an Info index ITEM cross-reference. ITEM must be a string of the form (filename)item-name. During button creation, completion for both filename and item-name is available. Filename may be given without the .info suffix."

link-to-Info-node ¶

Display an Info NODE. NODE must be a string of the form (filename)nodename. During button creation, completion for both filename and nodename is available. Filename may be given without the .info suffix.

link-to-ibut ¶

Perform implicit button action specified by KEY, optional BUT-SRC and POINT. BUT-SRC defaults to the current buffer’s file or if there is no attached file, then to its buffer name. POINT defaults to the current point.

When the button with this action type is created, point must be on the implicit button to which to link.

link-to-kcell ¶

Display a Hyperbole outline cell, given by FILE and CELL-REF, at the top of a window. See the documentation for (kcell:ref-to-id) for valid CELL-REF formats.

If FILE is ‘nil’, use the current buffer. If CELL-REF is ‘nil’, show the first cell in the view.

link-to-kotl ¶

Display at the top of a window the referent pointed to by LINK. LINK may be of any of the following forms:

  < pathname [, cell-ref] >
  < [-!&] pathname >
  < @ cell-ref >

See the documentation for (kcell:ref-to-id) for valid cell-ref formats.

link-to-mail ¶

Display a mail message with MAIL-MSG-ID from optional MAIL-FILE. See the documentation for the variable hmail:init-function for information on how to specify the mail reader to use.

link-to-regexp-match ¶

Find REGEXP’s Nth occurrence in SOURCE and display the location at the top of the selected window. SOURCE is a pathname unless optional BUFFER-P is non-nil, then SOURCE must be a buffer name or buffer. Return ‘t’ if found, signal an error if not.

link-to-rfc ¶

Retrieve and display an Internet rfc given by RFC-NUM. RFC-NUM may be a string or an integer.

link-to-string-match ¶

Find STRING’s Nth occurrence in SOURCE and display the location at the top of the selected window. SOURCE is a pathname unless optional BUFFER-P is non-nil, then SOURCE must be a buffer name or buffer. Return ‘t’ if found, ‘nil’ if not.

link-to-texinfo-node ¶

Display the Texinfo node with NODENAME (a string) from the current buffer.

link-to-web-search ¶

Search web SERVICE-NAME for SEARCH-TERM. Uses hyperbole-web-search-alist to match each service to its search url or Emacs command. Uses hyperbole-web-search-browser-function and the browse-url package to display search results.

man-show ¶

Display a man page on TOPIC, which may be of the form ‘<command>(<section>’). Use hpath:display-where setting to control where the man page is displayed.

org-internal-target-link ¶

Follow an optional Org mode <<INTERNAL-TARGET>> back to any first link to it. If INTERNAL-TARGET is nil, follow any internal target link at point. Otherwise, trigger an error.

org-link ¶

Follow an optional Org mode LINK to its target. If LINK is nil, follow any link at point. Otherwise, trigger an error.

org-radio-target-link ¶

Follow an optional Org mode radio <<TARGET>> back to any first link to it. If TARGET is nil, follow any radio target link at point. Otherwise, trigger an error.

rfc-toc ¶

Compute and display a summary of an Internet rfc in BUF-NAME. Assume point has already been moved to the start of the region to summarize. Optional OPOINT is the point to return to in BUF-NAME after displaying the summary.

text-toc ¶

Jump to the text file SECTION referenced by a table of contents entry at point.

www-url ¶

Follow a link given by a URL. The variable, browse-url-browser-function, customizes the url browser that is used. Valid values of this variable include browse-url-default-browser and browse-url-generic. See its documentation string for details.

yt-info ¶

Display a web page with the metadata information about VIDEO-ID.

yt-play ¶

Play a VIDEO-ID from the point specified by optional START-TIME-STRING. If not given, START-TIME-STRING is set to "0s" representing the beginning of the video. START-TIME-STRING is a colon-separated hours:minutes:seconds string, e.g. 1:2:44 (1 hour, two minutes, 45 seconds), where the hours and minutes are optional.

yt-search ¶

Search Youtube for SEARCH-TERM.

yt-url ¶

Return url to play VIDEO-ID from point specified by optional START-TIME-STRING. Return nil if START-TIME-STRING is given but is invalid. If not given, START-TIME-STRING is set to "0s" representing the beginning of the video.

START-TIME-STRING is a colon-separated hours:minutes:seconds string, e.g. 1:2:44 (1 hour, two minutes, 45 seconds), where the hours and minutes are optional.

Action types create a convenient way of specifying button behavior without the need to know how to program. Expert users who are familiar with Emacs Lisp, however, may find that they often want to tailor button actions in a variety of ways not easily captured within a type system. In such cases, hui:ebut-prompt-for-action should be set to ‘t’. This will cause Hyperbole to prompt for an action to override the button’s action type at each explicit button creation. For those cases where the action type is sufficient, a ‘nil’ value should be entered for the action. An action may be any Lisp form that Emacs Lisp can evaluate.

4.6 Button Type Precedence ¶

Explicit buttons always take precedence over implicit buttons. Thus, if a button selection is made which falls within both an explicit and implicit button, only the explicit button will be selected. Explicit button labels are not allowed to overlap; Hyperbole’s behavior in such cases is undefined.

If there is no explicit button at point during a selection request, then each implicit button type predicate is tested in turn until one returns non-nil or all are exhausted. Since two implicit button types may have overlapping domains, those contexts in which their predicates are true, only the first matching type is used. The type predicates are tested in reverse order of definition, i.e. most recently entered types are tested first, so that personal types defined after standard system types take precedence. It is important to keep this order in mind when defining new implicit button types. By making match predicates as specific as possible, one can minimize any overlapping implicit button domains.

Once a type name is defined, its precedence relative to other types remains the same even if its body is redefined, as long as its name is not changed. This allows incremental modifications to types without any worry of altering their precedences. See Creating Types, for information on how to develop or modify types.

4.7 Utilizing Explicit Buttons ¶

Explicit buttons are a fundamental building block for creating personal or organizational hypertext networks with Hyperbole. This section summarizes the user-level operations available for managing these buttons.

• Creation
• Renaming
• Deletion
• Editing
• Searching and Summarizing
• Buttons in Mail
• Buttons in News

Referent Context         Link Type
----------------------------------------------------
Org Roam or Org Id       link-to-org-id
Global Button            link-to-gbut
Explicit Button          link-to-ebut
Implicit Button          link-to-ibut
Bookmarks List           link-to-bookmark
Info Index Item          link-to-Info-index-item
Info Node                link-to-Info-node
Texinfo Node             link-to-texinfo-node
Mail Reader Message      link-to-mail
Directory Name           link-to-directory
Filename                 link-to-file
Koutline Cell            link-to-kcell
Outline Heading          link-to-string-match
Buffer attached to File  link-to-file
Buffer without File      link-to-buffer-tmp

(setq smail:comment
 (format "Comments: GNU Hyperbole mail buttons accepted, v%s.\n"
          hyperb:version))

Comments: GNU Hyperbole mail buttons accepted, vX.X.X.

6.1 HyWikiWords ¶

A HyWikiWord is a capitalized word that contains upper and lowercase letters only and has a corresponding HyWikiWord.org wiki page file below hywiki-directory. HyWikiWords in HyWiki pages are automatically highlighted and turned into hyperlinks as soon as you type them, without the need for any delimiters. However, if you prefer to use Org-style links, simply delimit them with double square brackets and the ‘hy:’ prefix like so: [[hy:MyWikiWord]].

To create a new HyWikiWord, insert it into a text buffer, move point onto the word and press {C-h h h c} to create a new blank HyWiki page that you can immediately start editing. HyWiki is built for scalability and has been tested to be performant with 10,000 HyWikiWords.

The Action Key can create new HyWiki pages when on an undefined HyWikiWord if you change the setting that controls the Org mode {M-RET} binding. Have Hyperbole override Org’s control of that key in all Action and Assist Key contexts with the ‘All-Hyperbole-Contexts’ setting bound to {C-h h h o a}.

To jump to a HyWiki page, simply move point onto any highlighted HyWikiWord and press the Action Key {M-RET}. This also highlights any other instances of HyWikiWords across all visible Emacs windows. If you have set the Org {M-RET} option to ‘None’ with {C-h h h o i}, then you will have to use the HyWiki Act menu command {C-h h h a} instead to jump to HyWiki pages.

HyWikiWord links can also jump to a section headline within a page by following the page name with a ’#’ character and then the full section headline name (sans any leading asterisks). For example, if your Emacs page has a "Major Modes" section, then either Emacs#Major-Modes or [[hy:Emacs#Major Modes]] will work as a link to that section. Note that without the square bracket delimiters, you must convert spaces in section names to ’-’ characters. As long as the page exists, section links are highlighted regardless of whether associated sections exist or not. When activating a link with a section reference, you will get an error if the section does not exist.

HyWikiWords can also be highlighted and treated as hyperlinks in non-special text and programming buffers outside of the hywiki-directory when the global minor mode, hywiki-mode is enabled. Toggle it via {C-h h h t} or {M-x hywiki-mode RET}.

If you prefer Org-style links in buffers outside of hywiki-directory, use the ’hy:’ prefix, as in: [[hy:MyWikiWord]]. If you set hywiki-org-link-type-required to ‘nil’, then you don’t need the prefix, e.g. [[MyWikiWord]]; existing HyWiki page names then will override Org’s standard handling of such links. To prevent Org mode’s binding of {M-RET} from splitting lines and creating new headlines when on a HyWikiWord whose page has not yet been created, set hsys-org-enable-smart-keys to ‘t’ so that Hyperbole’s Action Key does the right thing in this context.

Once Hyperbole has been loaded and activated, HyWikiWords (with or without delimiters) are automatically highlighted and active in the following contexts:

• HyWiki page buffers;
• non-special text buffers, after ‘hywiki-mode’ is enabled;
• comments of programming buffers, after ‘hywiki-mode’ is enabled.

As HyWikiWords are typed, highlighting occurs after a trailing whitespace or punctuation character is added, or when the HyWikiWord is surrounded by a matching pair of characters such as curly braces or single square brackets. Since Org links use double square brackets and Org targets use double or triple angle brackets, HyWikiWords within these delimiters are ignored once the brackets are in place.

The custom setting, hywiki-word-highlight-flag (default = ‘t’), means HyWikiWords will be auto-highlighted within HyWiki pages. Outside of such pages, hywiki-mode must also be enabled for such auto-highlighting.

The custom setting, hywiki-exclude-major-modes (default = ‘nil’), is a list of major modes to exclude from HyWikiWord auto-highlighting and recognition.

Within programming modes, HyWikiWords are highlighted and hyperlinked within comments only. For programming modes in which you want HyWikiWords recognized everywhere, add them to the custom setting, hywiki-highlight-all-in-prog-modes (default = '(lisp-interaction-mode)).

HyWiki adds one implicit button type to Hyperbole: hywiki-word, which creates and displays HyWikiWord pages. This is one of the lowest priority implicit button types so that it triggers only when other types are not recognized first.

6.2 Publish HyWiki ¶

A HyWiki can be exported to HTML for publishing to the web via Org mode’s publish a project feature. {C-h h h p} or {M-x hywiki-publish-to-html RET} publishes any changed files in the HyWiki. Give that command a prefix argument to force republishing of all HyWiki pages.

The full set of HyWiki-specific Org publish properties are set in the variable hywiki-org-publish-project-alist. When the HyWiki code is loaded into Emacs, it automatically integrates these properties with Org’s publishing framework, so when in a HyWiki page, you can use Org’s standard {C-c C-e P p} current project publish command if you prefer.

There are a few publishing settings you can customize prior to loading Hyperbole’s HyWiki code.

HyWiki html files are saved in: (hywiki-org-get-publish-property :publishing-directory) Customize this directory with: {M-x customize-variable RET hywiki-org-publishing-directory RET}

HyWiki html files are generated by the function given by: (hywiki-org-get-publish-property :publishing-function) Customize the value of this function if necessary with: {M-x customize-variable RET hywiki-org-publishing-function RET}

6.3 HyWiki Menu ¶

The HyWiki minibuffer menu offers quick access to important HyWiki features. It looks like this:

HyWiki>  Act Create EditPages FindPage GrepConsult Help Info Link ModeToggle Org-M-RET/ Publish TagFind WikiWordConsult

The GrepConsult and WikiWordConsult items appear only when the Consult package is installed prior to loading Hyperbole. These commands are especially useful as they allow for fast line-level searching across many files with interactive search pattern narrowing.

Below are descriptions of each menu item.

Act ¶

Activate HyWikiWord link at point.

Create ¶

Create and display a new HyWiki page. Shows existing page names to aid in new naming.

EditPages ¶

Display and edit HyWiki pages in current hywiki-directory. Use dired unless action-key-modeline-buffer-id-function is set to smart-treemacs-modeline, then use the treemacs package.

FindPage ¶

Prompt with completion for and find a HyWiki page, typically editable. If the page is already in a buffer, point is left unchanged.

GrepConsult ¶

Grep over HyWiki pages with interactive hywiki-consult-grep. Any words may be used.

Help ¶

Report on a HyWikiWord’s attributes.

Info ¶

Display Hyperbole manual section on HyWiki.

Link ¶

Prompt for and add a link at point to a HyWiki page.

ModeToggle ¶

Toggle global minor mode hywiki-mode that enables HyWikiWord hyperlinks in buffers outside of hywiki-directory.

Org-M-RET/ ¶

Menu to customize contexts in which Hyperbole Action and Assist Keys override Org’s {M-RET} command. The default is when on ‘Hyperbole-Buttons-Only’. Use ‘All-Hyperbole-Contexts’ to make the Action Key create new HyWiki pages when pressed on as-yet undefined HyWikiWords; otherwise, you must use {C-h h h c} to create a new HyWiki page instead. Use ‘None’ if you want to use Org’s {M-RET} command in every context within Org mode.

Publish ¶

Publish modified pages in the HyWiki to HTML; prefix arg to publish all pages.

TagFind ¶

Find a matching Org tag across all HyWiki pages.

WikiWordConsult ¶

Use hywiki-consult-grep to prompt for a HyWikiWord and then consult grep for and select an occurrence within the HyWiki.

9.1 Menu Commands ¶

The Kotl/ menu entry on the Hyperbole minibuffer menu provides access to a number of major Koutliner commands:

Menu Item    Command                    Description
====================================================================
All          kotl-mode:show-all         Expand all cells
Blanks       kvspec:toggle-blank-lines  Toggle blank lines on or off
Create       kfile:find                 Edit or create an outline
Downto       kotl-mode:hide-sublevels   Hide cells deeper than a level
Examp        <sample outliner file>     Show self-descriptive example
Format/      Submenu                    Import/Export commands
Hide         kotl-mode:hide-tree        Hide tree with root at point
Info         <outliner documentation>   Show outliner manual section
Kill         kotl-mode:kill-tree        Kill the current tree
Link         klink:create               Create a link to another cell
Overvw       kotl-mode:overview         Show first line of each cell
Show         kotl-mode:show-tree        Show tree with root at point
Top          kotl-mode:top-cells        Collapse to top-level cells
Vspec        kvspec:activate            Set a view specification
====================================================================

The popup and menubar Koutline menu, as displayed here, offers a more complete set of the Koutliner commands. {C-mouse-3} pops up the mode-specific menu in Emacs. Experiment with the menu or read the following sections explaining commands.

Image 9.2: Koutline Menu

9.2 Creating Outlines ¶

In addition to the Kotl/Create menu item, you can create and experiment with outline files simply by finding a file, {C-x C-f}, with a .kotl suffix. .kot will also work for users impaired by operating systems with 3-character suffix limitations.

When a new koutline is created, an invisible root cell is added. Its permanent and relative ids are both 0, and it is considered to be at level 0 in the outline. All visible cells in the outline are at level 1 or deeper, and thus are descendants of this root cell. Some koutliner commands prompt for cell numbers as arguments. An argument of 0 makes commands operate upon the entire outline.

An initial level 1 cell is also created to make it easy to start entering text in the outline. A koutline always has at least one visible cell in it.

See Autonumbering, which explains how cells are labeled according to their respective levels in the outline and how these labels are updated as the structure of the outline changes.

9.3 Autonumbering ¶

See Adding and Killing, for information on how to add new cells to or remove cells from a koutline. As you do this, or as you promote or demote cells within the outline, the labels preceding the contents of each cell automatically update to reflect the new structure. These labels are also known as autonumbers and as relative ids because they change as the structure changes.

The outline structure is shown by these labels and by the indentation of each outline level. Normally, each deeper level is indented another three characters, to reflect the nesting.

The default autonumbers are called alphanumeric labels because they alternate between using numbers and letters to distinguish each successive level. Each alphanumeric label uniquely identifies a cell’s position in an outline, so that there is no need to scan back to prior cells to see what the current section number of an outline is. This is similar to a legal numbering scheme but without all the period characters between level numbers. As an example, 1b3 is equivalent to a legal label of 1.2.3. Both refer to the 3rd cell at level 3, below the 2nd child of the first cell at level 1. Said another way, this is the 3rd child of the 1st cell’s 2nd child. In other words, it is easier to visualize hierarchies than to talk about them.

Alphanumeric labels are the default because they are shorter and easier to read aloud than equivalent legal ones. They also simplify distinguishing between even and odd level labels because of the alternating character set.

You can change the labeling scheme used in a particular outline with the command {C-c C-l}. A {?} will show all of the labeling options. The default, alpha labels, legal labels, and permanent idstamps (permanent cell ids) are all available.

A cell label is normally followed by a period and a space, called the label separator, prior to the start of the cell contents. You can change the separator for the current outline with {C-c M-l}. {C-u C-c M-l} will additionally change the default separator value used when new outlines are created (for the current session only). For example, use the value " " (two spaces) to get eliminate the trailing period after each cell label. The separator must be at least two characters long but may be longer.

If you find a separator that you prefer for all outlines, change the separator setting permanently by adding the following line to your Emacs initialization file, ~/.emacs, substituting for ‘your-separator’:

(setq kview:default-label-separator "your-separator")

9.4 Idstamps ¶

Idstamps (permanent ids) are associated with each cell. They maintain hyperlinks as cells are reordered within a koutline. See Klinks. Idstamps may be displayed in place of the outline level relative ids. Use {C-c C-l id RET}.

An idstamp counter for each outline starts at 0 and is incremented by one each time a cell is added to the outline. This idstamp stays with the cell no matter where it is moved within the outline. If the cell is deleted, its idstamp is not reused.

The 0 idstamp is always assigned to the root node of the entire outline. This node is never visible within the outline, but is used so that the outline may be treated as a single tree when needed. Idstamps always begin with a 0, as in 012, to distinguish them from relative ids.

9.5 Editing Outlines ¶

Text editing within the Koutliner works just as it does for other buffers, except when you need to deal with the structural components of an outline. Within the contents of a cell, all of your standard editing keys should work properly. You can just type in text and the left and right margins of the lines will be maintained for you. See Filling, for the times when you need to refill a paragraph or to control when filling occurs.

Don’t invoke editing commands with {M-x command-name RET} since the Koutliner uses differently named commands made to act like the regular editing commands. Koutliner commands, however, account for the structure and indentation in koutlines.

You may use the mouse to select parts of the contents of a single cell for editing. But don’t drag across cell boundaries and then edit the selected region, since that will destroy the outline structure.

• Adding and Killing
• Promoting and Demoting
• Relocating and Copying
• Moving Around
• Filling
• Transposing
• Splitting and Appending
• Inserting and Importing
• Exporting

|-----------------------------+----------------------------|
| Promotion Outside Org Table | Demotion Outside Org Table |
|-----------------------------+----------------------------|
| M-TAB or Shift-TAB          | TAB                        |
| M-<left>                    | M-<right>                  |
| M-Shift-<left>              | M-Shift-<right>            |
| C-c C-,                     | C-c C-.                    |
| C-c C-<                     | C-c C->                    |
|-----------------------------+----------------------------|

|----------------------------+-----------------------------|
| Promotion Inside Org Table | Demotion Inside Org Table   |
|----------------------------+-----------------------------|
| M-0 M-TAB                  | M-0 TAB                     |
| C-c C-,                    | C-c C-.                     |
| C-c C-<                    | C-c C->                     |
|----------------------------+-----------------------------|

9.6 Viewing Outlines ¶

The Koutliner has very flexible viewing facilities to allow you to effectively browse and study large amounts of material.

• Hiding and Showing
• View Specs

9.7 Klinks ¶

Cells may include hyperlinks that refer to other cells or to external sources of information. Explicit Hyperbole buttons may be created as usual with mouse drags (see Creation Via Action Key Drags). Implicit Hyperbole buttons may be added to Koutline text as well. A klink is a special implicit link button, delimited by <> separators, that jumps to a koutline cell and may also adjust the current outline viewspecs. This section discusses klinks.

There are three forms of klinks:

internal ¶

‘<#2b=06>’ is an internal klink, since it refers to the koutline in which it is embedded. When activated, it jumps to the cell within the current outline which has permanent id ‘06’ and relative id ‘2b’. ‘<#06>’ does the same thing, as does ‘<#2b>’, though this latter form will not maintain the link properly if the cell is moved elsewhere within the outline. The form, ‘<#2b=06|ben>’ additionally sets the view spec of the current outline back to the default value, with a blank line between each cell and the whole outline visible.

external ¶

The second klink format is an external link to another koutline, such as, ‘<EXAMPLE.kotl#3=012|c1e>’, which displays the named file, starting at the cell 3 (whose permanent identifier is 012), with the view specification of: blank lines turned off, cutoff after one line per cell, and showing ellipses for cells or trees which are collapsed.

view spec ¶

The third format sets a view spec for the current koutline. For example, ‘<|ben>’, when activated, sets the view in the current outline to display blank lines, to use ellipses after collapsed lines and to label cells with the alphanumeric style.

Press the Action Key over a klink to follow it. This will flash the klink as a button and then will display its referent in the other window. If the klink contains a view spec, it will be applied when the referent is displayed.

There are a number of easy ways to insert klinks into koutlines. If you have mouse support under Hyperbole, simply click the Action Key within the indentation to the left of a cell text. If you then double click on some cell, a link to that cell will be inserted where you started. From a keyboard, use {C-c l} when in a koutline or {C-h h k l} when not in a koutline to insert a klink. Since klinks are implicit buttons, you may instead type in the text of the klink just as you saw them in the examples above and they will work exactly as if they had been entered with the insert link command.

If you prefer the standard copy and yank model that Emacs provides, place point within a klink when there is no active region and use {M-w} to copy the klink. To instead copy a reference to the current Koutline cell, use {M-w} outside of a klink when no region is active or {M-x kotl-mode:copy-absolute-klink-to-kill-ring RET} anywhere within a cell. Then {C-y} will yank the last copied text into any buffer you desire. Of course, when a region is active, {M-w} will copy the region as it does normally in Emacs.

Similarly, you can copy to an Emacs register rather than to the kill ring. When no region is active/highlighted, {C-x r s} prompts for an Emacs register and saves to it either the current klink or, when outside of a klink, a reference to the current cell. {M-x kotl-mode:copy-absolute-klink-to-register RET} anywhere within a cell saves a reference to the current cell to a register.

{C-x r i} with the same register then inserts at point the Koutline reference previously saved. When a region is active, these operate on the region instead.

There are also commands without any builtin key bindings that always copy a klink reference to the current cell:

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

Because klinks use a very generic syntax, surrounded by <angle brackets>, in certain modes, mostly C-based programming modes, certain non-klink syntax can be mistakenly identified as klinks. Therefore, the Koutliner provides two customizable variables which disable klink recognition in selected major modes, klink:ignore-modes and klink:c-style-modes. Add a mode to one of these if you find any syntax that improperly registers as a klink.

klink:ignore-modes is for non-programming modes, as Hyperbole ensures that within all programming major modes, klinks are recognized only when point is within a comment.

klink:c-style-modes is rarely needed but is there if Hyperbole ever mistakenly recognizes a pattern within a comment as a klink when it isn’t.

9.8 Cell Attributes ¶

Attributes are named properties whose values are specific to an outline cell. Thus, each cell, including the invisible 0 root cell, has its own attribute list. Every cell has three standard attributes:

idstamp ¶

The permanent id of the cell, typically used in cross-file hyperlinks that reference the cell, this is a whole number that starts from 0, which is always the hidden root cell of the outline tree.

creator ¶

The e-mail address of the person who created this cell.

create-time ¶

The time at which the cell was created. This is stored in a form that allows for easy data comparisons but is displayed in a human readable format, such as ‘Jan 28 18:27:59 CST 2021’.

{C-c C-i} adds, modifies or removes an attribute from a cell. The prefix argument given to this command determines what it does.

{C-c C-i}

sets an attribute of the cell at point; setting an attribute’s value to ‘nil’ is the same as removing it.

{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

The ‘no-fill’ attribute is special. When set to ‘t’, it prevents movement, promotion, demotion, exchange, split or append commands from refilling the cell, even if the variable, kotl-mode:refill-flag, is set to ‘t’. It does not prevent you from invoking explicit commands that refill the cell. See Filling.

{C-c h} prompts for a cell label and displays the cell’s attributes. {C-u C-c h} prompts for a cell label 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.

9.9 Koutliner History ¶

Much of the Hyperbole outliner design is based upon concepts pioneered in the Augment/NLS system, [Eng84a]. Augment treated documents as a hierarchical set of nodes, called statements, rather than cells. Every Augment document utilized this intrinsic structure.

The system could rapidly change the view of a document by collapsing, expanding, generating, clipping, filtering, including or reordering these nodes. It could also map individual views to multiple workstation displays across a network to aid in distributed, collaborative work.

These facilities aided greatly in idea structuring, cross-referencing, and knowledge transfer. The Koutliner is a start at bringing these capabilities back into the mainstream of modern computing culture.

10.1 HyRolo Concepts ¶

HyRolo manages and searches a list of rolo files stored in the hyrolo-file-list custom option. A rolo file consists of an optional header that starts and ends with a line of equal signs (at least three equal signs starting at the beginning of a line), followed by zero or more rolo records which we call entries.

The first file in the list should be a user-specific hyrolo file, typically in the home directory and must have a suffix of either .org (Org mode) or .otl (Emacs Outline mode). Other files in the list may use suffixes of .org, .otl, .md (Markdown mode) or .kotl (Koutline mode).

HyRolo entries begin with a delimiter of one or more special characters followed by another space. Delimiters vary based on the type of file, for example level 3 entry delimiters look like this:

Emacs Outline Mode: ***
Koutline Mode:      1b3 or 1.2.3
Markdown Mode:      ###
Org Mode:           ***

Entries may be arranged in a hierarchy, where child entries start with at least one more delimiter characters than do their parents. Top-level entries use either a single delimiter character or a sequence of digits in the case of Koutlines.

Beyond this initial delimiter, entries are completely free-form text. It is best to use a "lastname, firstname" format, however, when adding contact entries into the first HyRolo file in your list. Then HyRolo will automatically keep your entries alphabetized as you add them; HyRolo can also sort the entries if you ever need. HyRolo will use this ordering if you accept the default entry with which it prompts you when adding a new entry.

Here is an example of a simple HyRolo file. The date at the end is automatically added by HyRolo whenever a new record is added, unless hyrolo-date-format is set to the empty string.

==================================================================
                          PERSONAL ROLO
<Last-Name>, <First>  <Email>        W<Work#>       F<Fax#>
==================================================================
*   Smith, John       <js@hiho.com> W708-555-2001  F708-321-1492
        Chief Ether Maintainer, HiHo Industries
        05/24/2020

Any search done on the rolo scans the full text of each entry. During a search, the rolo file header separator lines and anything in between are appended to the buffer of matched entries before any entries are retrieved from the file. Whenever an entry is matched, it and all of its descendant entries are retrieved. If your emacs version supports textual highlighting, each search match is highlighted for quick, visual location.

For example, a search on "Company" could retrieve the following:

==================================================================
                        COMPANY ROLO
==================================================================
*    Company
**     Manager
***      Staffer

Thus, searching for Company retrieves all listed employees. Searching for Manager turns up all Staffer entries.

10.2 Rolo Menu ¶

The Rolo submenu of the Hyperbole menu offers a full set of commands for searching and maintaining a personal address book. It looks like so.

Image 10.1: HyRolo Menu

The Rolo/ menu entry on the Hyperbole minibuffer menu provides the same set of commands as the menubar Rolo menu but with more concise labels.

The minibuffer Rolo/ menu offers the following commands (ConsultFind and HelmFind appear only when the Consult and Helm packages are installed prior to loading Hyperbole. They are especially noteworthy as they allow for fast line-level searching across many files with interactive search pattern narrowing):

Menu Item       Command                 Description
=====================================================================
Add             hyrolo-add              Adds a hyrolo entry
ConsultFind     hyrolo-consult-grep     Interactively narrow grep matches
Display         hyrolo-display-matches  Displays last matches again
Edit            hyrolo-edit             Edits an existing hyrolo entry
File            hyrolo-find-file        Edits a hyrolo-file-list file
HelmFind        hyrolo-helm-org-rifle   Interactively narrow entry matches
Info            id-info                 Displays a hyrolo manual entry
Kill            hyrolo-kill             Deletes a hyrolo entry
Mail            hyrolo-mail             Mails to an address at point
Order           hyrolo-sort             Sorts all hyrolo levels
RegexFind       hyrolo-grep             Finds all entries containing
                                          a regular expression
StringFind      hyrolo-fgrep            Finds all entries containing
                                          a string (or logical
                                          expression)
TagFind         hyrolo-tags-view        Finds HyWiki Org tags
WordFind        hyrolo-word             Finds all entries containing
                                          a string of whole words
Yank            hyrolo-yank             Inserts the first matching
                                          hyrolo entry at point
=====================================================================

The ’File’ menu item displays and edits the first file listed in hyrolo-file-list unless given a prefix argument, in which case it prompts with completion for the file to edit.

A prefix argument used with any of the above menu items that have ’Find’ in their names limits the search to a maximum number of matches given by the argument. The search is terminated whenever that number of matches is found.

With any of the above commands that prompt for a HyRolo name, such as Edit or Add (not the Find commands), you may use the form parent/child to locate a child entry below a specific parent. Hence, for a HyRolo which looks like so:

*    Company
**     Manager
***      Staffer

you can refer to the Staffer entry with the following hierarchical notation, Company/Manager/Staffer. This hierarchical notation is not used in search expressions since they search the entire HyRolo anyway. Thus, "Staffer" as a search pattern will find an entry containing "Staffer" at any level in a hierarchy, like so:

***      Staffer

10.3 HyRolo Searching ¶

See Rolo Menu, for the list of HyRolo search commands. In this section, the menu item names from the minibuffer menu are used to refer to each command.

The RegexFind menu item searches the rolo list for all entries which contain matches for a given regular expression. The regular expression syntax used is the same as the one used within Emacs and across the GNU set of tools. See Syntax of Regular Expressions in the GNU Emacs Manual, for full documentation on this format.

The TagFind menu item searches through HyRolo Org files and finds headlines with any matching tags. An Action Key press on any matching line displays the line in its source buffer.

The WordFind menu item locates full-word matches so that if you search for ‘product’, it won’t match to occurrences of ‘production’. It is also handy for more precise name matching.

The StringFind menu item has two uses. It can find all entry matches for a string or can execute logical queries for more precise matching. The format of logical queries is explained here; a simple parenthesis delimited prefix format is used with the following logical operators.

Operator Name   Num of Args   Description
=====================================================================
and             two or more   Match entries with all str args
or              two or more   Match entries with any str args
xor             two or more   Match entries with exactly 1 str arg
not             one           Match entries without the str arg

r-and           two or more   Match entries with all regexp args
r-or            two or more   Match entries with any regexp args
r-xor           two or more   Match entries with exactly 1 regexp arg
r-not           one           Match entries without the regexp arg
=====================================================================

For example:

(and Company (not Vice-President))

would match those entries for people associated with ‘Company’ who do not have ‘Vice-President’ titles.

The following example would provide a list of all people marked as clients whose area codes are outside of 408 and all non-clients within the 408 area code. This could be useful after all clients within the 408 area code have been contacted and you want to see who else you should contact.

(xor client 408- )

When using the regular expression operators, your operands are sent as regular expressions without the need to quote single words or special regular expression characters like ’*’ and ’?’. Use double quote marks to include a phrase or multi-word regular expression pattern to match. For example:

(r-and HyRolo "Red Buttons?")

would match entries that contain both "HyRolo" and either "Red Button" or "Red Buttons".

10.4 HyRolo Keys ¶

After a rolo search is performed, point is left in the rolo match buffer, *HyRolo*, which uses hyrolo-mode to simplify browsing many HyRolo matches. Press {?} when in the match buffer for a summary of available keys, all of which are documented in this section.

If your HyRolo search did not match what you want, use {r} to start a new regular expression query or {C-u r} for a string query. The rest of the match buffer keys work with the search results currently displayed.

If your emacs version supports textual highlighting, each search match is highlighted for quick, visual location. {TAB} moves point forward to successive spans of text which match the search expression. If the matching text is hidden/invisible, it is shown; the body of the entry with the match, as well as all of its sub-entries are shown. {M-TAB} or {SHIFT-TAB} move point backward to earlier matches. These keys allow you to quickly find the matching entry of most interest to you if your search expression failed to narrow the matches sufficiently.

To extend the match expression with some more characters to find a particular entry, use {M-s}. This performs an interactive search forward for the match expression. You may add to or delete characters from this expression to find different occurrences or move to the next match with {C-s}. {C-r} reverses the direction of the search.

To search for a specific entry name in the match buffer, use {l} to interactively locate the text immediately following the entry start delimiter, typically one or more asterisks. This lets you find entries by last name quickly, eliminating other matches. Standard string, {C-s}, and regular expression, {C-M-s}, interactive search commands are also available within the rolo match buffer.

Single key outlining commands are also available for browsing matches. If your search matches a large number of entries, use {t} to get a top-level summary of entries. Only the first line of each first-level match is shown. If you want to see an overview of all the levels, use {o} which shows the first line of every entry level. If you want an overview of just the first two levels, {C-u 2 o} will work.

Press {s} to show (expand) the entry at point if it is hidden (collapsed). If point is on a file header, this will expand the header and show the entire set of matched entries for the file. The {h} does the reverse and hides entries. Within file headers it hides the file from the end of the current line forward, so you can leave parts of the header displayed, if desired. Press {a} to expand all entries in the buffer across all matched files.

If an entry is collapsed/hidden, moving to any hidden part auto-expands it. Use {h}, the hide entry subtree to hide it again, if desired; this leaves point at the beginning of the entry (does not apply in file headers) to facilitate further use of movement by entry commands.

Other keys are defined to help you work with matching entries.

{b} ¶

Move to the previous entry at the same level as the current entry.

{f}

Move to the next entry at the same level as the current entry.

{n}

Move to the next entry at any level.

{p}

Move to the previous entry at any level.

{u}

Move to the previous higher entry one level up.

{,}

Move to the beginning of the entry. With a prefix argument, move to the beginning of highest ancestor level.

{.}

Move to the end of the entry. With a prefix argument, move to the end of the entire subtree.

{[}

Move to previous file/buffer location header beginning with @loc>.

{]}

Move to next file/buffer location header beginning with @loc>.

{<}

Move to the beginning of the buffer.

{>}

Move to the end of the buffer.

{DEL}

Scroll backward a windowful.

{SPC}

Scroll forward a windowful.

Use the {e} key to jump to and edit the current line in its original source file. If on a rolo entry and it contains a datestamp at its end, update the datestamp, unless this feature has been turned off via the Cust/Toggle-Rolo-Dates menu item. The variable, hyrolo-edit-hook, performs this update. This allows programmed modification of the way rolo edits work. The variable, hyrolo-add-hook, works the same way but is evaluated when a new entry is first added. The format of the datestamp is specified by hyrolo-date-format.

Once you have found an entry of interest and you want to remove the rolo match buffer, use {q} to quit. This will restore your current frame to its state prior to the rolo search.

10.5 HyRolo Settings ¶

The files used in any rolo search are given by the hyrolo-file-list variable, whose default value is typically "~/.rolo.otl", in which case, searches scan only your personal rolo file. But you can customize this to include files with variables in them, wildcard patterns and directories, as explained below. Any paths added to this list should be absolute.

If you include file wildcards in paths for this variable and find-file-wildcards is non-nil (the default), then any files matching the pattern (which can include [char-matches] or * wildcards and regular text) when the variable is set will be included in HyRolo searches. For more on wildcards, see Wildcards in the GNU Emacs Manual.

If you include an Environment variable or Emacs Lisp variable with the ${var} format in a path, they also are resolved when hyrolo-file-list is set. Variables with values that include multiple paths, e.g. PATH, are resolved to the first existing entry that matches.

If you include an existing directory (invalid ones are ignored) in your hyrolo-file-list, HyRolo will expand it recursively across all of its files that match hyrolo-file-suffix-regexp. By default, this is Org files (.org), Emacs outlines (.otl), Koutlines (.kotl), or Markdown files (.md). See hpath.el#hpath:expand-list.

Once expanded, if a file in the list does not exist or is not readable, it is dropped. Paths are searched in the order in which they appear in the list. You should leave your personal rolo file as the first entry in the list, since this is the only file to which the HyRolo menu Add command adds entries.

Hyperbole releases earlier than 4.17 used a different filename for the personal rolo. If such a file exists, you will be prompted to rename it whenever the HyRolo system is loaded.

If you want to have HyRolo search your directory of Org files, add the following to your Emacs initialization file:

(add-hook ’hyperbole-init-hook
	  (lambda ()
	    (require ’org)
	    (setq hyrolo-file-list (append (hyrolo-initialize-file-list)
                                           (list org-directory)))))

If you use the Big Brother DataBase (BBDB) Emacs package to capture email addresses and store contact information, the rolo automatically works with it. If the BBDB package is loaded before HyRolo, then your bbdb-file of contacts is added as the second entry in hyrolo-file-list and will be searched automatically for any matches by the rolo find commands. Presently there is no support for editing BBDB entries, just finding them.

For finding matches within only BBDB, there are the commands hyrolo-bbdb-fgrep (string finding) and hyrolo-bbdb-grep (regular expression finding). They may be bound to keys if desired.

If you use Google/Gmail Contacts, you can configure the HyRolo to query your Google Contacts for matches. First you must download and install the external google-contacts package using the Emacs Package Manager. Then you must install the non-Emacs GNU Privacy Guard (GPG) package from https://gnupg.org so that the gpg or gpg2 executable is in your command-line search path. Once these are in place, either restart Emacs or use {M-x hyrolo-initialize-file-list RET} to add Google Contacts to your searches.

When you next do a search, you will be prompted for your Google Contacts password and may also have to enter an authorization code that will be displayed on your screen. After authorization, your your information will be cached so that you are not prompted for it again within this Emacs session.

For finding matches within only Google Contacts, there are the commands hyrolo-google-contacts-fgrep (string finding) and hyrolo-google-contacts-grep (regular expression finding). They may be bound to keys if desired.

If you ever need to disable Google Contacts usage, there is a flag, hyrolo-google-contacts-flag, which when set to ‘nil’ disables searching of your Google Contacts.

Below are the rest of the settings available with HyRolo:

hyrolo-highlight-face ¶

If textual highlighting is available in your emacs on your current display type, the rolo uses the value of hyrolo-highlight-face as the face which highlights search matches.

hyrolo-kill-buffers-after-use ¶

HyRolo file buffers are left around after they are searched, on the assumption that another search is likely to follow within this emacs session. You may wish to change this behavior with the following setting: (setq hyrolo-kill-buffers-after-use t).

hyrolo-save-buffers-after-use ¶

After an entry is killed, the modified rolo file is automatically saved. If you would rather always save files yourself, use this setting: (setq hyrolo-save-buffers-after-use nil).

hyrolo-email-format ¶

When an entry is being added from within a mail reader buffer, the rolo extracts the sender’s name and e-mail address and prompts you with the name as a default. If you accept the default, it will enter the name and the email address using the format given by the hyrolo-email-format variable. See its documentation if you want to change its value.

hyrolo-hdr-regexp ¶

A rolo file may begin with an optional header section which is copied to the match display buffer whenever any matches are found during a search. The start and end lines of this header are controlled by the regular expression variable, hyrolo-hdr-regexp, whose default value is "^===". This allows lines of all equal signs to visually separate matching entries retrieved from multiple files during a single search.

hyrolo-hdr-and-entry-regexp ¶

The rolo entry start delimiter is given by the regular expression variable, hyrolo-hdr-and-entry-regexp, whose default value is "^\*+", i.e. one or more asterisks at the beginning of a line.

hyrolo-display-format-function ¶

When a rolo search is done, each matching entry is passed through the function given by the variable, hyrolo-display-format-function, before it is displayed. This should be a function of one argument, namely the matching rolo entry as a string. The string that this function returns is what is displayed in the rolo match buffer. The default function used is identity which passes the string through unchanged. If you use the rolo code to search other kinds of record-oriented data, this variable can be used to format each entry however you would like to see it displayed. With a little experience, you can quickly write functions that use local bindings of the rolo entry and file settings to search all kinds of record-oriented data. There is never a need to learn a complicated query language.

12.1 Hook Variables ¶

Hyperbole supplies a number of hook variables that allow you to adjust its basic operations to meet your own needs, without requiring you to change the code for those operations.

We find it best to always set the value of hook variables either to ‘nil’ or to a list of function names of no arguments, each of which will be called in sequence when the hook is triggered. If you use the add-hook function to adjust the value of hooks, it will do this automatically for you.

Given the name of a function, a Hyperbole hook variable triggered within that function has the same name as the function with a ‘-hook’ appended. Hyperbole includes the following hook variables:

hyperbole-init-hook ¶

For customization at Hyperbole initialization time. Use this to load any personal Hyperbole type definitions or key bindings you might have. It is run after Hyperbole support code is loaded but before Hyperbole is initialized, i.e. prior to keyboard and mouse bindings.

action-key-depress-hook ¶

assist-key-depress-hook ¶

Run after an Action or Assist Mouse Key depress is detected.

action-key-release-hook ¶

assist-key-release-hook ¶

Run after an Action or Assist Mouse Key release is detected, before any associated action is executed.

action-act-hook ¶

Run before each Hyperbole button activation. The variable hbut:current contains the button to be activated when this is run.

ebut-create-hook ¶

Adds to the Hyperbole explicit button creation process.

ebut-delete-hook ¶

Adds to the Hyperbole explicit button deletion process.

ebut-modify-hook ¶

Executed when an explicit button’s attributes are modified.

hibtypes-begin-load-hook ¶

Executed prior to loading of standard Hyperbole implicit button types. Used to load site-specific low priority implicit button types since lowest priority ibtypes are loaded first.

hibtypes-end-load-hook ¶

Executed after loading of standard Hyperbole implicit button types. Used to load site-specific high priority implicit button types since highest priority ibtypes are loaded last.

htype-create-hook ¶

Executed whenever a Hyperbole type (e.g. action type or implicit button type) is added to the environment.

htype-delete-hook ¶

Executed whenever a type is deleted from the environment.

kotl-mode-hook ¶

Executed whenever a koutline is created or read in or when kotl-mode is invoked.

hyrolo-add-hook ¶

Executed after the addition of a new rolo entry.

hyrolo-display-hook ¶

Executed when rolo matches are displayed.

hyrolo-edit-hook ¶

Executed after point is successfully moved to an entry to be edited.

hyrolo-mode-hook ¶

Executed when a rolo match buffer is created and put into hyrolo-mode.

hyrolo-yank-reformat-function ¶

A variable whose value may be set to a function of two arguments, START and END, which give the region of the rolo entry yanked into the current buffer by the hyrolo-yank command. The function may reformat this region to meet user-specific needs.

Hyperbole also makes use of a number of standard Emacs hook variables.

find-file-hook ¶

This is called whenever a file is read into a buffer. Hyperbole uses it to highlight any buttons within files.

write-file-hooks ¶

This is called whenever a buffer is written to a file. Hyperbole uses it to save modified button attributes associated with any file from the same directory as the current file.

Hyperbole mail and news facilities also utilize a number of Emacs hook variables. These hide button data and highlight buttons if possible. See the Hyperbole files with ‘mail’ and ‘gnus’ in their names for specific usage of such hooks.

12.2 Creating Types ¶

To define or redefine a single Hyperbole type, you may either:

• move your Emacs point to within the type definition and use {C-M-x} (eval-defun) (only works in Emacs Lisp mode);
• or move your point to the end of the last line of the type definition and use {C-x C-e} (eval-last-sexp) (works in most modes).

The functions from the ‘htype’ class may be applied to any Hyperbole types, if needed.

The following subsections explain the specifics of Hyperbole type definitions which are beyond standard practice for Emacs Lisp programming. See the definitions of the standard types in hactypes.el and hibtypes.el for examples.

• Creating Action Types
• Creating Implicit Button Types

12.3 Explicit Button Technicalities ¶

• Button Label Normalization
• Operational and Storage Formats
• Programmatic Button Creation

  <(fake button)>     <( fake      button)>

  Pam>  <(fake
  Pam>    button)>

  ;; <(fake
  ;;   button)>

  /* <( fake      */
  /*    button )> */

12.4 Encapsulating Systems ¶

A powerful use of implicit button types is to provide a Hyperbole-based interface to external systems. The basic idea is to interpret patterns output by the application as implicit buttons.

See the hsys-* files for examples of how to do this. Encapsulations are provided for the following systems (the systems themselves are not included with Hyperbole):

World-Wide Web

The world-wide web system originally developed at CERN, that now spans the Internet universe. This is automatically loaded by Hyperbole so that a press of the Action Key follows a URL.

12.5 Embedding Hyperbole ¶

The standard Hyperbole user interface has purposely been separated from the Hyperbole backend to support the development of alternative interfaces and the embedding of Hyperbole functionality within other system prototypes. The Hyperbole backend functionality that system developers can make use of is called its Application Programming Interface (API). The API may be used to make server-based calls to Hyperbole when Emacs is run as a non-interactive (batch) process, with its input/output streams attached to another process.

The public functions and variables from the following files may be considered the present Hyperbole API:

hact.el, hargs.el, hbmap.el, hbut.el, hhist.el, hmail.el, hmoccur.el, hpath.el, htz.el, hypb.el, hyrolo.el, hyrolo-logic.el, hywconfig.el and set.el.

Note when looking at these files, that they are divided into sections that separate one data abstraction (class) from another. A line of dashes within a class separates public parts of the class from the private parts that follow the line.

This API does not include the Hyperbole Koutliner, as it has been designed for interactive use, rather than programmatic extensibility. You are welcome, however, to study its code, below the hyperbole-${hyperb:version}/kotl/ directory.