3. Buttons

This chapter explains the user-level notion of Hyperbole buttons. 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.

3.1 Explicit Buttons

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.

3.2 Global Buttons

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.

3.3 Implicit Buttons

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, 3.4 Action Types, 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

Displays annotated bibliography entries referenced internally, delimeters = []. 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.

completion

Inserts completion at point into minibuffer or other window.

dir-summary

Detects filename buttons in files named "MANIFEST" or "DIR". Displays selected files. Each file name 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.

doc-id

Displays an index entry for a site-specific document 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'. This permits creation of catalogued online libraries. See `${hyperb:dir}/hib-doc-id.el' for more information.

elisp-compiler-msg

Jumps to source code for definition associated with byte-compiler error message. Works when activated anywhere within an error line.

debugger-source

Jumps to source line associated with debugger stack frame or breakpoint lines. This works with gdb, dbx, and xdb. Such lines are recognized in any buffer.

grep-msg

Jumps to line associated with grep or compilation error msgs. Messages are recognized in any buffer.

hyp-address

Turns a Hyperbole e-mail list address into an implicit button which inserts Hyperbole environment information. Useful when sending mail to a Hyperbole mail list. See also the documentation for actypes::hyp-config.

hyp-source

Turns source location entries in Hyperbole reports into buttons that jump to the associated location.

Info-node

Makes "(file)node" buttons display the associated Info node.

kbd-key

Executes a key sequence delimited by curly braces. Key sequences should be in human readable form, e.g. {C-b}. Forms such as {}, {}, and {^b} will not be recognized.

klink

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

mail-address

If on an e-mail address in a specific buffer type, mail to that address in another window. Applies to the rolodex match buffer, any buffer attached to a file in rolo-file-list, or any buffer with `mail' or `rolo' (case-insensitive) within its name.

man-apropos

UNIX manual

man pages

man apropos

Makes man apropos entries display associated man pages when selected.

patch-msg

Jumps to source code associated with output from the patch program. Patch applies diffs to source code.

pathname

Makes a delimited, valid pathname display the path entry. Also works for delimited and non-delimited ange-ftp and efs pathnames. See hpath:at-p function documentation for possible delimiters. See hpath:suffixes variable documentation for suffixes that are added to or removed from pathname when searching for a valid match. See hpath:find function documentation and hpath:display-alist and hpath:find-alist variable documentation for special file display options.

rfc

Retrieves and displays an Internet rfc referenced at point. Requires ange-ftp or efs when needed for remote retrievals. The following formats are recognized: RFC822, rfc-822, and RFC 822. The hpath:rfc variable specifies the location from which to retrieve RFCs."

rfc-toc

Summarizes contents of an Internet rfc from anywhere within rfc buffer. Each line in summary may be selected to jump to section.

text-toc

Jumps to the text file section referenced by a table of contents entry at point. File name must contain `README' and there must be 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 file section name line must start with one or more asterisk characters at the very beginning of the line.

www-url

When not in a w3 browser buffer, follow any non-ftp url (link) at point. The variable, action-key-url-function, can be used to customize the url browser that is used.

The Hyperbole Smart Keys offer extensive additional context-sensitive point-and-click type behavior beyond these standard implicit button types. See section 4. Smart Keys.

3.4 Action Types

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 in alphabetical order include:

annot-bib

Follows internal ref KEY within an annotated bibliography, delimiters=[].

completion

Inserts completion at point into minibuffer or other window. Unless at end of buffer or if completion has already been inserted, then deletes completions window.

eval-elisp

Evaluates a Lisp expression LISP-EXPR.

exec-kbd-macro

Executes KBD-MACRO REPEAT-COUNT times. KBD-MACRO may be a string of editor command characters or a function symbol. Optional REPEAT-COUNT nil means execute once, zero means repeat until error.

exec-shell-cmd

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

exec-window-cmd

Executes an external window-based SHELL-CMD string asynchronously.

hyp-config

Inserts Hyperbole configuration info at end of optional OUT-BUF or current.

hyp-request

Inserts Hyperbole mail list request help into optional OUT-BUF or current.

hyp-source

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

kbd-key

Executes the function binding for KEY-SEQUENCE, delimited by {}. Returns t if a KEY-SEQUENCE has a binding, else nil.

link-to-buffer-tmp

Displays a BUFFER in another window. Link is generally only good for current Emacs session. Use 'link-to-file' instead for a permanent link.

link-to-directory

Displays a DIRECTORY in Dired mode in another window.

link-to-doc

Displays online version of a document given by DOC-ID, in other window. If the online version of a document is not found in doc-id-indices, an error is signalled.

link-to-ebut

Performs action given by another button, specified by KEY and KEY-FILE.

link-to-elisp-doc

Displays documentation for FUNC-SYMBOL.

link-to-file

Displays a PATH in another window scrolled to optional POINT. With POINT, buffer is displayed with POINT at the top of the window.

link-to-file-line

Displays a PATH in another window scrolled to LINE-NUM.

link-to-kcell

Displays FILE with kcell given by CELL-REF at the top of the window. CELL-REF may be a kcell's display label or its permanant idstamp. If FILE is nil, the current buffer is used. If CELL-REF is nil, the first cell in the view is shown.

link-to-kotl

Displays at the top of another window the referent pointed to by LINK. LINK may be of any of the following forms, with or without delimiters:

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

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

link-to-Info-node

Displays an Info NODE in another window. NODE must be a string of the form '(file)nodename'.

link-to-mail

Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window. See documentation for the variable hmail:init-function for information on how to specify a mail reader to use.

link-to-regexp-match

Finds REGEXP's Nth occurrence in FILE and displays location at window top. Returns t if found, signals an error if not.

link-to-rfc

Retrieves and displays an Internet rfc given by RFC-NUM. RFC-NUM may be a string or an integer. Requires ange-ftp or efs for remote retrievals.

link-to-string-match

Finds STRING's Nth occurrence in FILE and displays location at window top. Returns t if found, nil if not.

man-show

Displays man page on TOPIC, which may be of the form <command>(<section>).

rfc-toc

Computes and displays summary of an Internet rfc in BUF-NAME. Assumes point has already been moved to start of region to summarize. Optional OPOINT is point to return to in BUF-NAME after displaying summary.

text-toc

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

www-url

Follows a link given by URL. The variable, action-key-url-function, can be used to customize the url browser that is used.

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.

3.5 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 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 10.2 Creating Types, for information on how to develop or modify types.

3.6 Button Files

It is often convenient to create lists of buttons that can be used as menus to provide centralized access to distributed information pools or for other purposes. These files can serve as useful roadmaps to help efficiently guide a user through both unfamiliar and highly familiar information spaces. Files that are created specifically for this purpose, we call 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 standard button files. Its standard value is `HYPB'.)

A personal button file may serve as a user's own roadmap to frequently used resources. Selection of the ButFile/PersonalFile menu item 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 standard 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 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.

One might suggest that menu quick access be provided for group-specific and site-specific button files. Instead, link buttons to such things should be placed at the top of your personal button file. This provides a more flexible means of quick access.

3.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.

3.7.1 Creation

3.7.1.1 Creation Via Action Key Drags

The most efficient way to create an explicit button interactively is to use the mouse Action Key to drag from a button source window to a window showing its link referent. More specifically, you should split your current Emacs frame into two windows: one which contains the point at which you want a button to be inserted and another which shows the point to which you want to link. Depress the mouse Action Key at the point at which the button should be inserted, drag to the other window and release it at the point of the link referent. The process becomes quite simple with a little practice. (See section Creation Via Menus, for a more detailed explanation of the explicit button creation process.)

Hyperbole uses the link referent context to determine the type of link to make. If there are a few different types of links which are applicable from the context, you will be prompted with a list of the types. Simply use the Action Key or the first letter of the link type to select one of the type names and to finish the link creation. Hyperbole will then insert explicit button delimiters around the button label and will display a message in the minibuffer indicating both the button name and its action/link type.

If you run Emacs under a window system, you can emulate an Action Key drag from the keyboard by: hitting {M-o}, the hkey-operate command, at the button source location, moving to the link destination, e.g. with {C-x o}, and then hitting {M-o} again. This simulates a depress and then release of the Action Key. {C-u M-o} emulates drags of the Assist Key. This will not work when Hyperbole is run from a dumb terminal Emacs session since drag actions are not supported without a window system.

3.7.1.2 Creation Via Menus

You can alternatively use the Hyperbole menus to create explicit buttons. First, mark a short region of text in any fashion allowed by GNU Emacs and then select the Hyperbole menu item sequence, Ebut/Create. You will be prompted for the button's label with the marked region as the default. If you accept the default and enter the rest of the information you are prompted for, the button will be created within the current buffer and Hyperbole will surround the marked region with explicit button delimiters to indicate success.

If you do not mark a region before invoking the button create command, you will be prompted for both a label and a target buffer for the button and the delimited label text will be inserted into the target buffer after a successful button creation.

After Hyperbole has the button label and its target buffer, it will prompt you for an action type for the button. Use the {?} completion help key to see the available types. The type selected determines any following values for which you will be prompted.

If a previous button with the same label exists in the same buffer, Hyperbole will add an instance number to the label when it adds the delimiters so that the name is unique. Thus, you don't have to worry about accidental button name conflicts. If you want the same button to appear in multiple places within the buffer, just enter the label again and delimit it yourself. Hyperbole will interpret all occurrences of the same delimited label within a buffer as the same button.

If you create link buttons using the Hyperbole menus, the best technique is to place on screen both the source buffer for the button and the buffer to which it will link. Mark the region of text to use for your button label, invoke the button create command from the menu, choose an action type which begins with link-to- and then use the direct selection techniques mentioned in 6. Entering Arguments, to select the link referent.

3.7.2 Renaming

Once an explicit button has been created, its label text must be treated specially. Any inter-word spacing within the label may be freely changed, as may happen when a paragraph is refilled. But a special command must be invoked to rename it.

The rename command operates in two different ways. If point is within a button label when it is invoked, it will tell you to edit the button label and then invoke the rename command again. The second invocation will actually rename the button. If instead the command is originally invoked outside of any explicit button, it will prompt for the button label to replace and the label to replace it with and then will perform the rename. All occurrences of the same button in the buffer will be renamed, so you need locate only one occurrence of the button.

The rename command may be invoked from the Hyperbole menu via Ebut/Rename. A faster method is to use a key bound to the hui:ebut-rename command. Your site installation may include such a key. {C-h w hui:ebut-rename RET} should show you any key it is on. If no key binding has been established or if you prefer one of your own, simply bind it within your `~/.emacs' file. We recommend the {C-c C-r} key, as in: (global-set-key "\C-c\C-r" 'hui:ebut-rename).

3.7.3 Deletion

Ebut/Delete works similarly to the Rename command but deletes the selected button. The button's delimiters are removed to confirm the delete. If the delete command is invoked with a prefix argument, then both the button label and the delimiters are removed as confirmation.

Presently there is no way to recover a deleted button; it must be recreated. Therefore, the hui:ebut-delete-confirm-p variable is true by default, causing Hyperbole to require confirmation before interactively deleting explicit buttons. Set it to nil if you prefer no confirmation.

3.7.4 Modification

Ebut/Modify prompts you with each of the elements from the button's data list and allows you to modify each in turn.

There is a quicker way to modify explicit link buttons. Simply drag with the mouse Action Key from within the button label to a link destination in a different window, just as you would when creating a new button with a mouse drag. Remember that drags may also be emulated from the keyboard. See section 3.7.1 Creation.

3.7.5 Location

The Ebut/Help menu can be used to summarize a single explicit button or all such buttons within a single buffer. The buttons summarized may then be activated directly from the summary.

Ebut/Help/BufferButs summarizes the explicit buttons in the order in which they appear in the buffer. Ebut/Help/CurrentBut summarizes only the button at point. Ebut/Help/OrderedButs summarizes the buttons in alphabetical order. All of these summary commands eliminate duplicate instances of buttons from their help displays.

Ebut/Search prompts for a search pattern and searches across all the locations in which you have previously created explicit buttons. It asks you whether to match to any part of a button label or only complete labels. It then displays a list of button matches with a single line of surrounding context from their sources. Any button in the match list may be activated as usual. An Action Key press on the surrounding context jumps to the associated source line or a press on the filename preceding the matches jumps to the file without selecting a particular line.

There are presently no user-level facilities for globally locating buttons created by others or for searching on particular button attributes.

3.7.6 Buttons in Mail

Hyperbole allows the embedding of buttons within electronic mail messages that are composed in Emacs with the standard (mail) command, normally bound to {C-x m} or with other Emacs-based mail composing functions. An enhanced mail reader can then be used to activate the buttons within messages just like any other buttons.

Hyperbole automatically supports the following mail readers: Rmail, section `Rmail' in the GNU Emacs Manual, VM, section `Introduction' in the VM Manual, and PIEmail, and MH-e. Button inclusion and activation within USENET news articles is also supported in the same fashion via the GNUS news reader, section `Introduction' in the GNUS Manual, if available at your site. (The `hmail.el' file provides a generalized interface that can be used to hook in other mail or news readers if the necessary interface functions are written.)

All explicit buttons to be mailed must be created within the outgoing message buffer. There is no present support for including text from other buffers or files which contain explicit buttons, except for the ability to yank the contents of a message being replied to, together with all of its buttons, via the (mail-yank-original) command bound to {C-c C-y}. From a user's perspective, buttons are created in precisely the same way as in any other buffer. They also appear just like any other buttons to both the message sender and the reader who uses the Hyperbole enhanced readers. Button operation may be tested any time before a message is sent. A person who does not use Hyperbole enhanced mail readers can still send messages with embedded buttons since mail composing is independent of any mail reader choice.

Hyperbole buttons embedded within received mail messages act just like any other buttons. The mail does not contain any of the action type definitions used by the buttons, so the receiver must have these or she will receive an error when she activates the buttons. Buttons which appear in message Subject lines are copied to summary buffers whenever such summaries are generated. Thus, they may be activated from either the message or summary buffers.

Nothing bad will happen if a mail message with explicit buttons is sent to a non-Hyperbole user. The user will simply see the text of the message followed by a series of lines of button data at its end. Hyperbole mail users never see this data in its raw form.

In order to alert readers of your mail messages that you can utilize Hyperbole mail buttons, the system automatically inserts a comment into each mail message that you compose to announce this fact. The variable, smail:comment controls this behavior. See its documentation for technical details. By default, it produces a message of the form:

Comments: Hyperbole mail buttons accepted, vX.XX.

where the X's indicate your Hyperbole version number. You can cut this out of particular messages before you send them. If you don't want any message at all, add the following to your `~/.emacs' file before the point at which you load Hyperbole.

(setq smail:comment nil)

A final mail-related facility provided by Hyperbole is the ability to save a pointer to a received mail message by creating an explicit button with a link-to-mail action type. When prompted for the mail message to link to, if you press the Action Key on an Rmail message, the appropriate parameter will be copied to the argument prompt, as described in 6. Entering Arguments.

3.7.7 Buttons in News

Explicit buttons may be embedded within outgoing USENET news articles and may be activated from news articles that are being read. This support is available for the GNUS news reader. It is enabled by default within `hsite.el' by autoloading the `hgnus.el' file.

All Hyperbole support should work just as it does when reading or sending mail. See section 3.7.6 Buttons in Mail. When reading news, buttons which appear in message Subject lines may be activated within the GNUS subject buffer as well as the article buffer. When posting news, the *post-news* buffer is used for outgoing news articles rather than the *mail* buffer.

Remember that the articles you post do not contain the action type definitions used by the buttons, so the receiver must have these or she will receive an error when he activates the buttons. You should also keep in mind that most USENET readers will not be using Hyperbole, so if they receive a news article containing explicit buttons, they will wonder what the button data at the end of the message is. You should therefore limit distribution of such messages. For example, if most people at your site read news with GNUS and use Hyperbole, it would be reasonable to embed buttons in postings to local newsgroups.

In order to alert readers of your postings that you can utilize Hyperbole mail buttons embedded within personal replies, the system automatically inserts the same comment that is included within mail messages to announce this fact. See section 3.7.6 Buttons in Mail, for details and an explanation of how to turn this feature off.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.