Package Installation (Emacs Package Manager)

Once you have Emacs set up at your site, you can install GNU Hyperbole using the Emacs Package Manager. If you are not familiar with it, see Packages in the GNU Emacs Manual for usage instructions and see Package Installation in the GNU Emacs Manual for an introduction to package archive sites which host libraries of Emacs packages.

Hyperbole releases update the Hyperbole package version number and occur slowly. with major releases typically at least a year apart. In between, many significant feature updates are made, tested and promoted to package archives that track the Hyperbole master git development branch (elpa-devel and melpa-snapshots). Since Hyperbole is a mature package with regression testing, the latest snapshots are usually fine for everyday use. Most users should choose a package archive site that tracks these latest updates (elpa-devel and melpa-snapshots). If you need slow-moving stability, get the latest release from ELPA or MELPA.

Here are the installation and configuration steps:

• Choose one package archive source for Hyperbole by adding one of the following expressions to your Emacs init file, see see The Emacs Initialization File in the GNU Emacs Manual:

  elpa-devel (latest Hyperbole updates):

  (add-to-list 'package-archives '("elpa-devel". "https://elpa.gnu.org/devel/") t)

  melpa-snapshots (latest Hyperbole updates):

  (add-to-list 'package-archives '("melpa-snapshots" . "https://snapshots.melpa.org/packages/") t)

  elpa (updates only when Hyperbole version number changes):

  (add-to-list 'package-archives '("elpa". "https://elpa.gnu.org") t)

  melpa-releases (updates only when Hyperbole version number changes):

  (add-to-list 'package-archives '("melpa-releases" . "https://releases.melpa.org/packages/") t)

• Then copy Hyperbole’s ${hyperb:dir}/man/use-package file to your Emacs init file and customize it to your taste based on the comments therein, though everything will work fine without any modifications to the use-package file.

  ;;; use-package --- Reference configuration   -*- mode: emacs-lisp; lexical-binding: t; -*-
  
  ;; NOTE: If you use Emacs 28 or earlier, you'll need to install the
  ;; `use-package' Emacs package before using this configuration file
  ;; since it is not built-in to your Emacs.
  
  ;; -----------------------------------------------------------------
  
  ;; Default values herein represent the settings Hyperbole will default
  ;; to if not set within this `use-package' configuration.
  (use-package hyperbole
  
    ;; Install the package from a package archive if not already installed
    :ensure t
  
    ;; Hyperbole binds {C-h h} in the `global-map' to display its
    ;; minibuffer command menus. If you prefer a different binding,
    ;; you can restore the standard Emacs binding of {C-h h} and set
    ;; your preferred Hyperbole menu binding: example {C-c h} by
    ;; uncommenting the next three lines:
    ;; :config
    ;;   (global-set-key (kbd "C-h h") #'view-hello-file)
    ;;   (global-set-key (kbd "C-c h") #'hyperbole)
  
    :init
    ;; Enable or disable the global Hyperbole minor mode on startup:
    ;;   1 - enabled after Hyperbole is loaded so the Action and
    ;;       Assist Smart Keys are active
    ;;
    ;;   0 - off (default)
    (hyperbole-mode 1)
  
    ;; Initialize the global HyWiki minor mode to one of these values:
    ;; - :all   - highlight HyWikiWords in all editable buffers except
    ;;            those with a major mode in ‘hypb:exclude-major-modes’;
    ;;            also enable ‘hyperbole-mode’ minor mode if off.
    ;;
    ;; - :pages - highlight HyWikiWords in HyWiki pages only (Org files in
    ;;            ‘hywiki-directory’); also enable ‘hyperbole-mode’ minor
    ;;            mode if off. (default)
    ;;
    ;; - nil    - no highlighting, the ‘hywiki-mode’ is disabled.
    (hywiki-mode :all)
  
    ;; If you want to treat your Hyperbole link buttons like Org links,
    ;; uncomment this next Lisp sexpression and then you can surround
    ;; your Hyperbole buttons with double square brackets and get Org
    ;; link highlighting, e.g. [[bug#8291]].
    ;;
    ;; (push #'hyperbole-activate-button org-open-link-functions)
  
    :bind
    (:map hyperbole-mode-map
  	;; Bind Smart Keys: {M-RET} executes `action-key' and {C-u M-RET}
  	;; executes `assist-key' via this next binding
  	("M-RET" . hkey-either))
  
    :custom
    ;; Action and Assist Key Customizations
  
    ;; Customize how Hyperbole and Org mode share the M-RET key:
    ;;   t        - With `hyperbole-mode' enabled, Hyperbole controls the
    ;;              key.
    ;;
    ;;   'buttons - With `hyperbole-mode enabled', Hyperbole controls the
    ;;              key only when on a button or link; otherwise, Org
    ;;              controls it. (default)
    ;;
    ;;   nil      - In Org mode, Org controls the key.
    (hsys-org-enable-smart-keys t)
  
    ;; HyRolo Customizations
  
    ;; Uncomment and set `hyrolo-file-list' to a list of files,
    ;; directories and file wildcard expressions you want to find notes,
    ;; contacts or any hierarchical records in.  Directories are
    ;; searched recursively and filtered to only Org, Markdown, Koutline
    ;; and Emacs outline files.  The first entry is where HyRolo adds
    ;; new records.  (default = '("~/.rolo.org"))
    ;;
    ;; (hyrolo-file-list '("~/.rolo.org" "~/org/" "~/org-roam/" "~/Documents/notes/"))
  
    ;; HyWiki Customizations
  
    ;; Uncomment and set `hywiki-directory' to the directory to store
    ;; all HyWiki pages in (default = "~/hywiki/").
    ;;
    ;; (hywiki-directory "~/hywiki/")
  
    ;; If using these settings:
    ;;   (hywiki-mode :all)
    ;;   (hsys-org-enable-smart-keys t)
    ;;
    ;; then when Hyperbole's Action Key, {M-RET}, is pressed on any
    ;; potential WikiWord, e.g. any capitalized word, in any text or
    ;; programming buffer comment, it will display a page file of notes
    ;; associated with that WikiWord, creating it if it doesn't exist.
    ;;
    ;; If there are major-modes where you want to disable this
    ;; capability, uncomment the following line and add the mode names
    ;; inside the empty list:
    ;; (hywiki-word-create-exclude-action-key-modes '())
  
    ;; Koutliner Customizations
  
    ;; Inline image display can be toggled on/off with {C-c C-x C-v} but
    ;; if you want inline images to display all the time in Koutline
    ;; buffers, uncomment the next sexpression:
    ;;   (add-hook 'kotl-mode-hook 'iimage-mode)
  
    ;; NOTE: As of Hyperbole version 9.3.0, the Koutliner uses `C-c ;'
    ;; as the prefix for mode-specific <letter> key bindings (prior
    ;; prefix was `C-c'); this avoids overriding global user settings of
    ;; `C-c <letter>'.
    ;;
    ;;   If you want the prior Koutline {C-c <letter>} key bindings
    ;;   in addition to the current ones on {C-c ; <letter>), uncomment the
    ;;   following line:
    ;;     (kotl-mode:set-letter-prefix-control-c)
  
    ;;   If you want to use your own prefix for these letter
    ;;   keys, uncomment the following line and substitute your prefix:
    ;;     (kotl-mode:set-letter-prefix-standard "your-prefix-string")
  
    ;; Customize the behavior of the <tab> and S-<tab> keys in a Koutline.
    ;; One of three possible values:
    ;;   nil      - {TAB} demotes the current tree and {Shift-TAB}
    ;;              promotes the tree. (default)
    ;;
    ;;   'cycle  -  enables Org-like outline view cycling when point is in
    ;;              a context other than that specified by
    ;;              ‘org-cycle-emulate-tab’.  See {C-h f
    ;;              kotl-mode:tab-command RET} for details.
    ;;
    ;;   t       -  makes {TAB} indent lines and insert literal <tab>
    ;;              characters according to the context setting of
    ;;              ‘kotl-mode:emulate-tab’, which also determines where
    ;;              {Shift-TAB} deletes backward.
    (kotl-mode:tab-flag nil)
  
    ;; Setup contexts where ‘kotl-mode:tab-command’ should override
    ;; `kotl-mode:tab-flag' and run ‘kotl-mode:indent-line’, often
    ;; inserting a <tab> character.
    ;; Potential values are:
    ;;   nil         - Never
    ;;
    ;;   white       - Only in completely white lines
    ;;
    ;;   whitestart  - Only at the beginning of lines, before the first
    ;;                 non-white char
    ;;
    ;;   t           - Everywhere except in headlines
    ;;
    ;;   exc-hl-bol  - Everywhere except at the start of a headline
    (kotl-mode:emulate-tab nil)
  
    ;; Configure whether `kotl-mode:indent-line' uses tabs and spaces or
    ;; spaces only.
    ;; Potential values are:
    ;;   t   - may insert literal <tab> characters. (default)
    ;;
    ;;   nil - may insert <spc> characters only.
    (kotl-mode:indent-tabs-mode t)
  
    ;; Prior to the addition of Org-style visibility cycling to the
    ;; Koutliner on the TAB key, a press of the Action Key on a Koutline
    ;; cell line used to toggle showing/hiding the tree rooted at point.
    ;; Today, this does nothing.
    ;;
    ;; Uncomment the next expression if you prefer the prior behavior
    ;; but note that if `hywiki-mode' is set to `:all' when point is on
    ;; a capitalized word, an Action Key press will create a new HyWiki
    ;; page, as that has higher priority than this setting.
    ;;
    ;; (kotl-mode:action-key-default-function 'kotl-mode:show-or-hide-tree)
    )

• Restart Emacs to Install, Configure and Activate Hyperbole

  With Hyperbole now installed and configured you should see the Hypb hyperbole minor mode indicator in your modeline after Emacs startup and initializaton.

  The use-package expression will download and install Hyperbole, if need be, and then configure it as you have specified there. If you want to do any further interactive customization, see the section, see Customization.