This chapter explains the user-level notion of Hyperbole buttons. You should read it before reading section Using Hyperbole.
Hyperbole buttons that are stored in files persist across Emacs sessions, so they provide a convenient means of linking from one information source to another.
Hyperbole creates and manages explicit buttons which look like
this <(fake button)> to a Hyperbole user. They are quickly
recognizable, yet relatively non-distracting as one scans the text in
which they are embedded. The text between the <( and
)> delimiters is called the button label. Spacing between
words within a button label is irrelevant to Hyperbole, so button labels
may wrap across several lines without causing a problem.
Hyperbole stores the button data that gives an explicit button its behavior, separately from the button label, in a file named `.hypb' 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.
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; one simply copies the button label with its delimiters to a new location in such cases.
Each explicit button is assigned an action type which determines the actions that it performs. Link action types connect buttons to particular types of referents. Activation of such buttons then displays the referents.
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 of data to integrate it with a Hyperbole framework.
Access to explicit buttons depends upon the information on your screen since they are embedded within particular buffers. Sometimes it is useful to activate buttons without regard to the information with which you are presently working. In such instances, you use global buttons, which are simply explicit buttons which may be activated or otherwise operated upon by entering their labels when they are prompted for, rather than selecting the buttons within a buffer.
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 an exec-kbd-macro button
with an easy to type name and then you can easily activate it whenever
the need arises.
Implicit buttons are those defined by the natural structure of a document. They are identified by contextual patterns which limit the locations or states in which they can appear. Their behavior is determined by one or more actions which they trigger when activated. An action is derived from either a Hyperbole action type specification, see section Action Types and Actions, or an Emacs Lisp function. Implicit button types may use the same action types that explicit buttons do.
Implicit buttons never have any button data associated with them. They are recognized in context based on predicate matches defined within implicit button types. For example, Hyperbole recognizes file names enclosed in double quotes and can quickly display their associated files in response to simple mouse clicks.
See `hibtypes.el' for complete examples. Standard implicit button types include (in alphabetical order):
annot-bib
completion
dir-summary
doc-id
elisp-compiler-msg
debugger-source
grep-msg
hyp-address
actypes::hyp-config.
hyp-source
Info-node
kbd-key
klink
actypes::link-to-kotl for valid link
specifiers.
mail-address
man-apropos
UNIX manual
man pages
man apropos
patch-msg
patch
program. Patch applies diffs to source code.
pathname
hpath:at-p for possible delimiters.
See hpath:find for special file display options.
rfc
rfc-toc
The Hyperbole Smart Keys offer extensive additional context-sensitive point-and-click type behavior beyond these standard implicit button types. See section Smart Keys.
Action types provide action procedures that specify button behavior. The arguments needed by an action type are prompted for at button creation time. When a button is activated, the stored arguments are fed to the action type's action body to achieve the desired result. Hyperbole handles all of this transparently.
Standard action types include:
annot-bib
completion
eval-elisp
exec-kbd-macro
exec-shell-cmd
exec-window-cmd
hyp-config
hyp-request
hyp-source
kbd-key
link-to-buffer-tmp
link-to-directory
link-to-doc
link-to-ebut
link-to-elisp-doc
link-to-file
link-to-file-line
link-to-kcell
link-to-kotl
< pathname [, cell-ref] > < [-!&] pathname > < @cell-ref >
link-to-Info-node
link-to-mail
link-to-regexp-match
link-to-rfc
link-to-string-match
man-show
<command>(<section>).
rfc-toc
The use of action types provides 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 non-nil. 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 may be evaluated.
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 their match predicates as specific as possible, one can minimize any overlapping of implicit button type domains.
Once a type name is defined, its precedence relative to other types remains the same even if you redefine the body of the type, as long as you don't change its name. This allows incremental modifications to types without having to worry about shifts in type precedence. See section Creating Types, for information on how to develop or modify types.