Implicit Button Types

Below is a list of standard implicit button types in the order in which Hyperbole tries to match to the types when looking for an implicit button (decreasing priority order). {C-h h i t RET} provides similar information. See the Hyperbole file, ../hibtypes.el, for examples of how to define implicit button types (in the file, they are listed in reverse order, increasing in priority).

smart-org

smart-org is not an actual implicit button type, just an Elisp function, but it behaves similarly, so it is documented here.

Hyperbole recognizes Org mode constructs in any of these modes: org-mode, org-agenda-mode, outshine-mode or poporg-mode. (See the function hsys-org-mode-p).

Hyperbole does quite a few things for Org mode users. When the Action Key is pressed and hsys-org-enable-smart-keys is ‘t’:

1. On an Org tag, call hsys-org-agenda-tags-p and an appropriate view tags function based on current directory or buffer name, matching to the tag. If on a colon between tags, match to all tags on the line.

2. On an Org todo keyword, cycle through the keywords in that set or if final done keyword, remove it.

3. On an Org agenda view item, jump to the item for editing.

   When the Action Key is pressed and hsys-org-enable-smart-keys is either ‘t’ or ‘:buttons’:

4. Within a radio or internal target or a link to it, jump between the target and the first link to it, allowing two-way navigation.

5. On another internal link in an Org mode file, jump to its referent.

6. On an Org mode external link, jump to its referent.

7. On a Hyperbole button, activate the button.

8. With point on the :dir path of a code block definition, display the directory given by the path.

9. With point on any #+BEGIN_SRC, #+END_SRC, #+RESULTS, #+begin_example or #+end_example header, execute the code block via the Org mode standard binding of {C-c C-c}, org-ctrl-c-ctrl-c.

10. With point on an Org mode heading, cycle the view of the subtree at point.

11. In any other context besides the end of a line, invoke the Org mode standard binding of {M-RET}, org-meta-return.

When the Assist Key is pressed, it behaves just like the Action Key except in these contexts:

1. On an Org tag, call hsys-consult-org-grep-tags-p and an appropriate consult grep function based on current directory or buffer name, prompting with and matching to the tag. If on a colon between tags, prompt and match to all tags on the line.
2. On an Org todo keyword, move to the first todo keyword in the next set, if any.
3. On an Org mode link or agenda view item, display Hyperbole context-sensitive help.
4. On a Hyperbole button, performs the Assist Key function, generally showing help for the button.
5. With point on the :dir value of a code block definition, display a help summary of this implicit directory button.
6. With point on any #+BEGIN_SRC, #+END_SRC, #+RESULTS, #+begin_example or #+end_example header, remove any associated results.
7. Not on a Hyperbole button but on an Org mode heading, cycle through views of the whole buffer outline.

To disable Hyperbole support within Org major and minor modes, set the custom option hsys-org-enable-smart-keys to nil. Then in Org modes, the Action Key will simply invoke org-meta-return. {C-h h c o} (minibuffer menu Cust/Org-M-RET) will interactively customize this setting.

The following table summarizes the effect of this option setting.

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

doc-id

Display a document from a local document library given its id. Ids must be delimited by doc-id-start and doc-id-end and must match the function given by doc-id-p. (Note that this implicit button type is not installed by default. You must manually configure it and load it from the file, ${hyperb:dir}/hib-doc-id.el). See the commentary at the top of that file for more information.

smerge

Within a merge conflict buffer, with smerge-mode active, make the conflict marker lines into buttons that select what version to keep. The upper, center and lower conflict marker lines keep the upper conflict, both conflicts or the lower conflict, respectively.

See Smart Key - Magit Mode for similar buttons for conflict resolution from within the magit-status-mode.

completion

Insert the completion at point (from a completions buffer) into the minibuffer or the other window.

hywiki-existing-word

When on a HyWikiWord with an existing page, display its page and optional section.

action

The Action Button type. At point, activate any of: an Elisp variable, a Hyperbole action-type, or an Elisp function call surrounded by <> rather than (). If an Elisp variable, display a message showing its value.

hyp-source

Turn source location entries following an ‘@loc>’ line in Hyperbole reports into buttons that jump to the associated location. For example, {C-u C-h h d d C-h h e h o} summarizes the properties of the explicit buttons in the ${hyperb:dir}/DEMO file and each button in that report buffer behaves the same as the corresponding button in the original ${hyperb:dir}/DEMO file.

hyp-address

Within a mail or Usenet news composer window, make a Hyperbole support/discussion e-mail address insert Hyperbole environment and version information. This is useful when sending mail to a Hyperbole discussion mail list. See also the documentation for actypes::hyp-config. For example, a click of an Action Mouse Key on <hyperbole-users@gnu.org> in a mail composer window would activate this implicit button type.

Info-node

Make a "(filename)nodename" button display the associated Info node. Also make a "(filename)itemname" button display the associated Info index item. Examples are "(hyperbole)Implicit Buttons" and “(hyperbole)C-c /”.

gnus-push-button

Activate GNUS-specific article push-buttons, e.g. for hiding signatures. GNUS is a news and mail reader.

texinfo-ref

Display Texinfo, Info node or help associated with Texinfo node, menu item, @xref, @pxref, @ref, @code, @findex, @var or @vindex at point. If point is within the braces of a cross-reference, the associated Info node is shown. If point is to the left of the braces but after the @ symbol and the reference is to a node within the current Texinfo file, then the Texinfo node is shown.

For @code, @findex, @var and @vindex references, the associated documentation string is displayed.

patch-msg

Jump to the source code associated with output from the ‘patch’ program. Patch applies diffs to source code.

elisp-compiler-msg

Jump to source code for definition associated with an Emacs Lisp byte-compiler error message or ERT test output line. Works when activated anywhere within such a line.

debugger-source

Jump to the source line associated with a debugger stack frame or breakpoint line. This works with gdb, dbx, and xdb. Such lines are recognized in any buffer. For example, in Python, this will test for and jump to a source line referenced in Python pdb, traceback, or pytype error.

grep-msg

Jump to the line associated with a grep or compilation error message. Messages are recognized in any buffer.

hyrolo-stuck-msg

Jump to the position where a HyRolo search has become stuck from the error. Such errors are recognized in any buffer.

ripgrep-msg

Jump to a line associated with a ripgrep (rg) line numbered msg. Ripgrep outputs each pathname once, followed by all matching lines in that pathname. Messages are recognized in any buffer (other than a helm completion buffer).

grep-single-file

Jump to the source line from a single file, line-numbered grep msg. Such grep msgs start with the line number followed by a colon. The buffer may contain the file searched prior to any such line or it may not, e.g. {M-!} in which case hpath:get-grep-filename will extract a best guess from the command-history.

ipython-stack-frame

Jump to the line associated with an ipython stack frame line numbered msg. ipython outputs each pathname once followed by all matching lines in that pathname. Messages are recognized in any buffer (other than a helm completion buffer).

pathname-line-and-column

Make a valid pathname:line-num[:column-num] pattern display the path at line-num and optional column-num. Also works for remote pathnames. May also contain hash-style link references with the following format: <path>[#<link-anchor>]:<line-num>[:<column-num>]. Line and column can also include a leading and optional character, L for line and C for column.

link-to-ibut <ilink>

At point, activate a link to an implicit button within the current buffer. This executes the linked to implicit button’s action in the context of the current buffer.

Recognizes the format ’<ilink:’ button_label [’:’ button_file_path] ’>’, where button_file_path is given only when the link is to another file, e.g. <ilink: my series of keys: ${hyperb:dir}/HYPB>.

link-to-gbut <glink>

At point, activate a link to a global button. This executes the linked to global button’s action in the context of the current buffer.

Recognizes the format ’<glink:’ button_label ’>’, e.g. <glink: open todos>.

link-to-ebut <elink>

At point, activate a link to an explicit button within the current buffer. This executes the linked to explicit button’s action in the context of the current buffer.

Recognizes the format ’<elink:’ button_label [’:’ button_file_path] ’>’, where : button_file_path is given only when the link is to another file, e.g. <elink: project-list: ~/projs>."

klink

Follow a link delimited by <> to a koutline cell. See the documentation for actypes::link-to-kotl for valid link specifiers.

man-apropos

Make man apropos entries (from ‘man -k’) display associated man pages when selected.

rfc

Retrieve and display an Internet Request for Comments (RFC) standards document referenced at point. The following formats are recognized: RFC822, rfc-822, and RFC 822. The hpath:rfc variable specifies the location from which to retrieve RFCs via HTTP.

kbd-key

Execute a key series (series of key sequences) around point, delimited by curly braces, {}. Key series should be in human readable form, e.g. {C-x C-b}. Formats such as {^x^b} will not be recognized. The string within (kbd "string") also acts as a key series button.

Any key sequence 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.

debbugs-gnu-mode

Debbugs is a client-server issue tracker used by GNU free software projects, including Hyperbole, to manage issues and maintain threads of discussion around them. You issue queries to a Debbugs server and it returns a listing entry for each matching issue. When on a GNU Debbugs listing entry in debbugs-gnu-mode, an Action Key press displays the discussion of the selected issue; an Assist Key press pretty prints the status of the issue to a window below the listing window.

debbugs-gnu-query

Display the results of a Debbugs query based on a bug reference string around point. This works in most types of buffers. If the query includes a single id number, it displays the original message submission for that id and allows browsing of the followup discussion. The following buffer text formats are accepted (with point prior to any attribute):

bug#id-number, bug# id-number, bug #id-number or bug id-number
bug?attr1=val1&attr2=val2&attr3=val3
bug#id-number?attr1=val1&attr2=val2&attr3=val3

Note that issue or debbugs may also be used in place of bug. See the documentation at the top of the hib-debbugs.el file for detailed query format information.

dir-summary

Detect filename buttons in files named "MANIFEST" or "DIR". Display selected files. Each filename must be at the beginning of the line and must be followed by one or more spaces and then another non-space, non-parenthesis, non-brace character.

text-toc

Jump to the text file section referenced by a table of contents (toc) entry at point. This works in any text derived major mode buffer with a ‘Table of Contents’ or ‘Contents’ label on a line by itself (it may begin with an asterisk), preceding the table of contents. Each TOC entry must begin with some whitespace followed by one or more asterisk characters. Each section header linked to by the toc must start with one or more asterisk characters at the very beginning of the line. TOCs in Internet RFCs work as well. For example, display this RFC, <link-to-rfc 822>, and Action Key press on any TOC line to jump to the associated section. Or try it in the Hyperbole DEMO file.

cscope

Jump to a C/C++ source line associated with a Cscope C analyzer output line. The cscope.el Lisp library available from the Emacs package manager must be loaded and the open source cscope program available from http://cscope.sf.net must be installed for this button type to do anything.

etags

Jump to the source line associated with an etags file entry in a TAGS buffer. If on a tag entry line, jump to the source line for the tag. If on a pathname line or line preceding it, jump to the associated file.

ctags

Jump to the source line associated with a ctags file entry in any buffer. Ctags files are used by old editors like vi to lookup identifiers. Emacs uses the newer, more flexible Etags format.

id-cflow

Expand or collapse C call trees and jump to code definitions. Requires cross-reference tables built by the external cxref program.

rfc-toc

Summarize contents of an Internet rfc from anywhere within an rfc buffer. Each line of the summary may be selected to jump to the associated section.

markdown-internal-link

Display any in-file Markdown link referent. Pathnames and urls are handled elsewhere.

org-link-outside-org-mode

Activate an Org link outside of an Org buffer.

git-commit-reference

Display the changeset for a git commit reference, e.g. commit a55e21, typically produced by git log. Hyperbole also includes two commands, hypb:fgrep-git-log and hypb:grep-git-log to list git commit references whose changesets contain either the string (fgrep) or regular expression (grep) given. Then an Action Key press displays the associated changeset.

annot-bib

Display annotated bibliography entries defined within the same buffer as the reference. References must be delimited by square brackets, must begin with a word constituent character, and must not be in buffers whose names begin with a ‘ ’ or ‘*’ character.

hyp-manual

When on a Hyperbole manual file path, display it. For example, display hyperbole.html#Smart Keys in a web browser using the local html version of the Hyperbole manual. When on hyperbole.texi#Smart Keys, jump to the Smart Keys node in the local Texinfo manual. Without a node name, go to the initial, top node.

Info file links like hyperbole.info#Smart Keys are handled by the Info-node implicit button type and displayed in the Emacs Info browser.

www-url

When not in an Emacs web browser buffer, follow any non-ftp URL (link) at point. The variable, browse-url-browser-function, may be used to customize which URL browser is called. Terse URLs which lack a protocol prefix, like www.gnu.org, are also recognized.

pathname

Make a valid pathname display the path entry. Also works for delimited and non-delimited remote pathnames, Texinfo @file{} entries, and hash-style link references to HTML, XML, SGML, Markdown or Emacs outline headings, shell script comments, and MSWindows paths (see ${hyperb:dir}/DEMO#POSIX and MSWindows Paths for details). Emacs Lisp library files (filenames without any directory component that end in .el and .elc) are located using the load-path directory list.

The pathname may contain references to Emacs Lisp variables or shell environment variables using the syntax, \"${variable-name}\". See Link Variable Substitution, for how this handled. The constant, hpath:variable-regexp, matches to this pattern within pathnames.

See the function documentation for hpath:at-p for possible delimiters. See the variable documentation for hpath:suffixes for suffixes that are added to or removed from the pathname when searching for a valid match. See the function documentation for hpath:find for special file display options.

If instead is a PATH-style variable name, .e.g. MANPATH, will prompt with completion for one of the paths and will then display that. If it is the colon or semicolon-separated string of paths value from a PATH-style variable, the path at point is displayed; empty paths, e.g. :: represent the current directory, .. Must have at least four paths within the variable value for this to work.

mail-address

If on an e-mail address in a specific buffer type, compose mail to that address in another window. Applies to any major mode descended from those in hypb:mail-address-mode-list, the HyRolo match buffer, any buffer attached to a file included in hyrolo-file-list, or any buffer with mail or rolo (case-insensitive) within its name. If hypb:mail-address-mode-list is set to ‘nil’, this button type is active in all buffers.

org-id

With an Action Key press on an Org Roam or Org node ID at point, display the associated node. If on the :ID: definition line, display a message about how to copy the id.

hyperbole-run-test-definition

With an Action Key press on the name in the first line of an ert test def, evaluate and run the ERT test. With an Assist Key press instead, edebug the test and step through it.

social-reference

Display the web page associated with a social media hashtag or username reference at point.

Reference format is:

[facebook|instagram|twitter|x]?[#@]<hashtag-or-username> or
[fb|in|tw|x]?[#@]<hashtag-or-username>

For example, ‘fb@someuser’ displays the home page for facebook user ‘someuser’ and ‘in#hashtag’ displays photos with the hashtag ‘hashtag’. The first part of the label for a button of this type is the social media service name. The service name defaults to the value of hibtypes-social-default-service (default value of “x”) when not given, so #hashtag would be the same as x#hashtag.

hyperbole-run-tests

Recognize Action Buttons of the form <hyperbole-run-tests test-selector> which when activated run Hyperbole tests using the ERT framework. The test-selector argument is as described in ert-select-tests.

hyperbole-run-test

Recognize Action Buttons of the form <hyperbole-run-test test-name> which when activated run individual Hyperbole tests, each given by the <test-name> argument, an unquoted name.

python-tb-previous-line

Move to prior line with potential Python line ref. In Python, tracebacks may be on a line just below the source reference line so since not on a Hyperbole button, move back a line and check for a source reference line again.

hywiki-word

When on a HyWikiWord, display its page and optional section. If the associated HyWiki page does not exist, create it automatically.

hynote-file

When on a HyNote file name stem, display the file and its optional section. This type is active only in buffers where hywiki-active-in-current-buffer-p is true. This may require that the global minor mode hywiki-mode has been enabled.

ert-should

When on an Emacs Regression Test (ERT) result and not on the first line of a result (its name), on a button or at the end of line, search for a matching should clause in the source buffer where the associated test is defined. This speeds debugging when a single test name contains many subtests, each with their own unique should clauses.