INSTALL

# INSTALL --- GNU Hyperbole installation and invocation instructions
#
# See the "HY-ABOUT" file for a description of GNU Hyperbole.
#
# Author:       Bob Weiner
#
# Orig-Date:    25-Oct-16 at 09:10:12
# Last-Mod:     24-Jan-22 at 00:19:12 by Bob Weiner
#
# Copyright (C) 2016-2021  Free Software Foundation, Inc.
# See the "HY-COPY" file for license information.
#
# This file is part of GNU Hyperbole.

===========================================================================
*		           Installation
===========================================================================

There are multiple ways to obtain and install Hyperbole once
you have GNU Emacs set up at your site.

** The Stable Release (from GNU Elpa using the built-in Emacs Package Manager)

The Emacs Package Manager installs the latest stable version release
of GNU Hyperbole.  If you are not familiar with it, see the Packages
section of the GNU Emacs Manual, "(emacs)Packages", or
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html".

If you have Hyperbole 5.10 or higher already installed and simply want to
upgrade it, invoke the Emacs Package Manager with {M-x list-packages RET},
then use the {U} key followed by the {x} key to upgrade all out-of-date
packages, Hyperbole among them.  Then skip the text below and move on to
the section, Invocation.

Otherwise, to download and install the Hyperbole package, you should add
several lines to your personal Emacs initialization file, typically "~/.emacs".
(For further details, see "(emacs)Init File", or
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html").

Below are the lines to add:

(when (< emacs-major-version 27)
  (error "Hyperbole requires Emacs 27 or above; you are running version %d" emacs-major-version))
(require 'package)
(unless (package-installed-p 'hyperbole)
  (package-refresh-contents)	
  (package-install 'hyperbole))
(hyperbole-mode 1)

Now save the file and then restart Emacs.  Hyperbole will then be
downloaded and compiled for use with your version of Emacs; give it a
minute or two.  You may see a bunch of compilation warnings but these
can be safely ignored.


** The Latest Development Snapshot (from GNU Elpa-Devel using the built-in Emacs Package Manager)

The Elpa In-Development package pulls from the latest Hyperbole
development branch tip and does not require installation of any new
package manager software.  Since Hyperbole is a mature package, this is
usually fine to use and update on a day-to-day basis.  But new features
are tested on this branch and once in awhile it may break for a short
time before a fix is pushed.  With this branch you'll be able to submit
bug reports and feature requests but will not be able to submit pull
requests for changes to the developers; use the Git In-Development
Package instead for that.

If you have Hyperbole 5.10 or higher already installed and simply want to
upgrade it, invoke the Emacs Package Manager with {M-x list-packages RET},
then use the {U} key followed by the {x} key to upgrade all out-of-date
packages, Hyperbole among them.  Then skip the text below and move on to
the section, Invocation.

Otherwise, to download and install the Hyperbole package, you should add
several lines to your personal Emacs initialization file, typically "~/.emacs".
(For further details, see "(emacs)Init File", or
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html").

Below are the lines to add:

(when (< emacs-major-version 27)
  (error "Hyperbole requires Emacs 27 or above; you are running version %d" emacs-major-version))
(require 'package)
(add-to-list 'package-archives '("gnu-devel" . "https://elpa.gnu.org/devel/"))
(unless (package-installed-p 'hyperbole)
  (package-refresh-contents)
  (package-install 'hyperbole))
(hyperbole-mode 1)

Now save the file and restart Emacs.  Hyperbole will then be downloaded
and compiled for use with your version of Emacs; give it a minute or two.
You may see a bunch of compilation warnings but these can be safely
ignored.


** The Git Master Branch (from git source using the Straight Package Manager)

If you prefer to track Hyperbole development between releases and like
to try out new features still in testing, then use the Straight
package manager instead of the above, which pulls the latest Hyperbole
source code from its git repository.  This also gives you a cleaner
installation process without showing you any byte compilation
warnings.

If you have Hyperbole 5.10 or higher already installed and simply want to
upgrade it, invoke the Emacs Package Manager with {M-x list-packages RET},
then use the {U} key followed by the {x} key to upgrade all out-of-date
packages, Hyperbole among them.  Then skip the text below and move on to
the section, Invocation.

Otherwise, to download and install the Hyperbole package, you should add
several lines to your personal Emacs initialization file, typically "~/.emacs".
(For further details, see "(emacs)Init File", or
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html").

Below are the lines to add:

;; Use this in your Emacs init file to install Straight
(progn
  (when (< emacs-major-version 27)
    (error "Hyperbole requires Emacs 27 or above; you are running version %d" emacs-major-version))
  (defvar bootstrap-version)
  (setq package-enable-at-startup nil)
  (let ((bootstrap-file
         (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
        (bootstrap-version 5))
    (unless (file-exists-p bootstrap-file)
      (with-current-buffer
          (url-retrieve-synchronously
           "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
           'silent 'inhibit-cookies)
        (goto-char (point-max))
        (eval-print-last-sexp)))
    (load bootstrap-file nil 'nomessage)))

;; Then use this to install Hyperbole
(straight-use-package
 '(hyperbole
   :host nil
   :repo "https://git.savannah.gnu.org/git/hyperbole.git"
   :config (hyperbole-mode 1)))

Now save the file and restart Emacs.  Hyperbole will then be downloaded
and compiled for use with your version of Emacs; give it a minute or two.


** The Stable or Pre-Release Tarball Archive (manually installed)

If you are old-school, don't like package managers, and prefer doing
everything by hand, then you can obtain Hyperbole from a tarball:
Download either:

1. a stable release tar.gz source archive from either:
ftp://ftp.gnu.org/gnu/hyperbole/ or
http://ftpmirror.gnu.org/hyperbole/, which will find the closest
mirror of the GNU ftp site and show it to you;

or

2. the latest in-development pre-release tar.gz source archive linked
to at the top of this web page:
https://elpa.gnu.org/devel/hyperbole.html.

Then decompress and unpack the archive to a directory of your
choosing.  Move into the "hyperbole/" directory and execute
the following Posix shell command, "make bin", to
byte-compile the Hyperbole lisp files.  Then add the following
lines to your personal Emacs initialization file,
"~/.emacs":

(unless (and (featurep 'hyperbole) hyperbole-mode)
  (when (< emacs-major-version 27)
    (error "Hyperbole requires Emacs 27 or above; you are running version %d" emacs-major-version))
  (push "<directory-ending-with-hyperbole-where-you-unpacked>" load-path)
  (require 'hyperbole)
  (hyperbole-mode 1))

Restart Emacs and you should see the "Hypb" hyperbole minor mode
indicator in your modeline after startup.

===========================================================================
*		         Browsing the Source
===========================================================================

To explore the Hyperbole source code online rather than installing it
for use (which will also give you the source code), open a web page
to:

  https://git.savannah.gnu.org/cgit/hyperbole.git/tree/

Alternatively, you may download a tar.gz source archive from either:

  ftp://ftp.gnu.org/gnu/hyperbole/

or

  http://ftpmirror.gnu.org/hyperbole/

which will find the closest mirror of the GNU ftp site and show it to you.

===========================================================================
*			    Invocation
===========================================================================

Once Hyperbole has been installed for use at your site and loaded into your
Emacs session, it is ready for use.  You will see a Hyperbole menu on your
menubar and {C-h h} will display a Hyperbole menu in the minibuffer for
quick keyboard-based selection.

You can invoke Hyperbole commands in one of three ways:

   use the Hyperbole menu on your menubar;

   type {C-h h} or {M-x hyperbole RET} to bring up the Hyperbole main menu
   in the minibuffer window, for fast keyboard or mouse-based selection;
   select an item from this menu by typing the item's first letter; use {q}
   to quit from the menu.

   use a specific Hyperbole command such as an Action Key click {M-RET} on
   a pathname to display the associated file or directory.

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

{C-h h k e} offers 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.  {t} switches between window and frame control once in one of
them.  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.  A long video demonstrating most of HyControl's
features is available at https://youtu.be/M3-aMh1ccJk.

The above are the best interactive ways to learn about Hyperbole.  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.  For web
browsing, point your browser at "${hyperb:dir}/man/hyperbole.html",
wherever the Hyperbole package directory is on your system; often this is:
"~/.emacs.d/elpa/hyperbole-${hyperb:version}/".