# 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
#
# 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 package managers you can use to install Hyperbole once
you have GNU Emacs set up at your site.

** 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:

(require 'package)
(when (< emacs-major-version 27)
  (package-initialize))
(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.

**

===========================================================================
*		         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}/".
