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