2. Installation

Hyperbole must be installed at your site before you can use it. The following sections explain how to obtain, install and configure Hyperbole for use.

If you want to customize the basic Hyperbole initialization sequence for yourself rather than the users at your site, you should make a personal copy of the `hsite.el' file, modify it the way you want, and then load it. (If you are familiar with Emacs Lisp, 10.1 Hook Variables.)

2.1 Obtaining

Hyperbole can be obtained via anonymous ftp on the Internet from:

`ftp://ftp.gnu.org/gnu/hyperbole'.

Here are instructions for downloading and unpacking Hyperbole.

Move to a directory below which you want the `hyperbole' directory to be created. Unpacking the Hyperbole archive will create the `hyperbole' directory and will place all of the files below it.

  cd <LOCAL-EMACS-LISP-DIR>

Ftp to ftp.gnu.org.

   prompt> ftp ftp.gnu.org

Login as anonymous with your own <user-id>@<site-name> as a password.

   Name (ftp.gnu.org): anonymous
   331 Guest login ok, send EMAIL address (e.g. user@host.domain)
       as password.
   Password:
   230 Guest login ok, access restrictions apply.

Move to the Hyperbole directory:

   ftp> cd gnu/hyperbole

Set your transfer mode to binary:

   ftp> bin
   200 Type set to I.

Turn off prompting:

   ftp> prompt
   Interactive mode off.

Retrieve just the Hyperbole archive and any diff-based patches (there may not be any patches):

   ftp> mget hyperbole*
   ftp> mget hdiff*

Close the ftp connection:

   ftp> quit
   221 Goodbye.

Unpack the tar archive using the GNU version of the zcat program, sometimes called gzcat or the gunzip program:

   zcat hyperbole*tar.gz | tar xvf -
or
   gunzip hyperbole*tar.gz; tar xvf hyperbole*tar

Apply any patches you retrieved:

   cd hyperbole; patch < <patch-file>

2.2 Building

The following explains how to Use the Hyperbole `Makefile' to compile any needed code, to generate the `hsite.el' file used for site-specific Hyperbole customization, and to produce printable documentation.

Edit the line near the top of `Makefile' that represents the emacs version that you use, so that it corresponds to the emacs executable name used on your system. Then immediatly below there, set the EMACS variable to the variable name for the emacs that you will use to compile the Hyperbole Lisp files.

You may also have to set the SITE-PRELOADS variable defined further down in the file; follow the instructions that precede the SITE-PRELOADS = line. Make these changes now and save the `Makefile'.

The following instructions use the term `<HYPERBOLE-DIR>/' to refer to your `hyperbole/' directory, so substitute your own value.

To install Hyperbole for use with InfoDock, XEmacs, GNU Emacs or Epoch, from a shell:

   cd <HYPERBOLE-DIR>; make

All of the .elc compiled Lisp files are already built for XEmacs and V19, so this build will finish very quickly. If you really want to rebuild all of the .elc files, use:

   cd <HYPERBOLE-DIR>; make all-elc

To produce the Postscript version of the Hyperbole manual, you must have the TeX formatter on your system:

   cd <HYPERBOLE-DIR>; make ps

To install Hyperbole for use with GNU Emacs V18 or Epoch:

   cd <HYPERBOLE-DIR>; make all-elc-v18

This will produce a complete set of Emacs V18 .elc files.

2.3 Installing

You may want to explore the Hyperbole configuration options before installing it. See section 2.4 Configuring. If you just want to get up and running quickly, however, there is no need to configure anything, just follow these instructions to install Hyperbole.

Add the following lines to a site initialization file such as `site-start.el' to set up so that all users have Hyperbole loaded for them when they run Emacs. Otherwise, each user will have to add these lines to his own `~/.emacs' initialization file.

To autoload Hyperbole so that it loads only when needed:

(defvar hyperb:dir "<HYPERBOLE-DIR>/")
  "Directory where the Hyperbole executable code is kept.
It must end with a directory separator character.")

(load (expand-file-name "hversion" hyperb:dir))
(load (expand-file-name "hyperbole" hyperb:dir))

This establishes a few key bindings and sets up Hyperbole to automatically load whenever you activate its menu. If you would rather have the whole Hyperbole system loaded when you start up so that you can always use the Smart Keys and other facilities, add the additional line:

(require 'hsite)

If you use mouse keys, be sure to add the above lines after any setup of mouse key bindings, to ensure that Hyperbole's mouse keys are properly initialized. See section 4. Smart Keys, for further details. If you use any Hyperbole mail or news support, 3.7.6 Buttons in Mail, be certain to perform all of your personal mail/news initializations before the point at which you load Hyperbole. Otherwise, the mail/news support may not be configured properly. For example, if you use the Emacs add-on Supercite package, its setup should come before Hyperbole initialization.

The Hyperbole Manual is included in the distribution in two forms:

`man/hyperbole.info'   - online version
`man/hyperbole.texi'   - source form

To add pointers to the Info version of the Hyperbole manual within your Info directory, follow these instructions. If Info-directory-list is bound as a variable within your Emacs (all versions except V18 and Epoch), then you can simply set it so that <HYPERBOLE-DIR> is an element in the list:

(setq Info-directory-list (cons "<HYPERBOLE-DIR>" Info-directory-list))

Otherwise, from a shell:

   cd to the directory given by your Info-directory variable
   rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .

For all versions of Emacs, add an Info menu entry for the Hyperbole manual in your Info `dir' file (the `*' should be placed in the first column of the file):

* Hyperbole::  GNU Emacs-based everyday information management system.
    Use {C-h h d d} for a demonstration.  Includes context-sensitive
    mouse and keyboard support, a powerful rolodex, an autonumbered
    outliner with hyperlink anchors for each outline cell, and extensible
    hypertext facilities including hyper-links in mail and news messages.

That's all there is to the installation. Once Hyperbole has been installed for use at your site, you can invoke it with {C-h h} or {M-x hyperbole RET} to bring up the Hyperbole main menu in the minibuffer window.

2.4 Configuring

There are many Hyperbole configuration options that may be changed by editing the `hyperbole.el' and `hsite.el' files in the `hyperbole/' directory. The following sections discuss the configuration options most likely to be of interest to users.

2.4.1 Internal Viewers

Configure the hpath:display-alist variable in `hsite.el'. Its value is an association list whose elements are (<file-name-regular-expression> . <function-of-one-arg>) pairs. Any path whose name matches a <file-name-regular-expression> will be displayed by calling the associated <function-of-one-arg> with the file name as the argument.

See section 2.4.2 External Viewers, for instructions on associating file names with external, window-system specific viewers.

2.4.2 External Viewers

The value of hpath:find-alist is determined when Hyperbole is initialized based upon the current window system and the version of Emacs in use. The value is an association list whose elements are (<file-name-regular-expression> . <viewer-program>) pairs. Any path whose name matches a <file-name-regular-expression> will be displayed using the corresponding viewer-program. If a <viewer-program> entry contains a %s string, the filename to display will be substituted at that point within the string. Otherwise, the filename will be appended to the <viewer-program> entry. See the "x-suffixes" and "nextstep-suffixes" settings within the definition of hpath:find-alist as examples.

2.4.3 Link Variable Substitution

This permits sharing of links over wide areas, where the variable values may differ between link creator and link activator. The entire process is wholly transparent to the user; it is explained here simply to help you in deciding whether or not to modify the value of hpath:variables.

2.4.4 Configuring Button Colors

Additionally, under XEmacs and Emacs 19, if hproperty:but-emphasize-p is set to t in `hsite.el', then whenever the mouse pointer moves over an explicit button, it will be emphasized in a different color or style. This emphasis is in addition to any non-mouse-sensitive button highlighting.

If you read in a file with explicit buttons before you load Hyperbole, these buttons won't be highlighted. Load Hyperbole and then use M-x hproperty:but-create RET to highlight the buttons in the current buffer.

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