GNU Hyperbole Demonstration by Bob Weiner

      1. 
Table of Contents
      -----------------
      * Introduction
      * Smart Keys 
      * Koutliner
      * HyControl
      * HyRolo
      * History
      * Implicit Buttons
      * Explicit Buttons
      * Smart Mouse Keys
      * Epilog
      * References
      2. 
Introduction
      
      Welcome to GNU Hyperbole.  Hyperbole will super-charge your GNU Emacs
      experience, allowing you to work faster, utilize fewer key bindings, recall
      more information and link it all together by learning just a few concepts and
      keys.  Invest an hour learning Hyperbole now and speed your daily information
      management for years to come.
      
      If you simply want to know what Hyperbole is, see the file "HY-ABOUT".
      Hyperbole displays that file when you press {C-h h d a}.  Hyperbole assumes
      you know how to use Emacs.  Otherwise, run the Emacs tutorial by pressing
      {C-h t} first.
      
      You should be looking at this file within Emacs and Hyperbole should already
      be installed within your copy of Emacs.  To be sure, press {C-h h} and you
      should see the Hyperbole menu in your minibuffer window at the bottom of
      your current Emacs frame.  Press {q} to quit out of this menu and we can
      begin.  If Hyperbole is not installed, see the "INSTALL" file, in the
      same directory as this file, for instructions on installing it.
      
      This demo illustrates simple usage of the basic Hyperbole button-action types
      and shows how Hyperbole can support a style of self-documenting, interactive
      files.  See the glossary in the Hyperbole Manual, "(hyperbole)Glossary", if
      terms used here are unfamiliar to you.
      3. 
Smart Keys 
      
      Hyperbole provides two context-sensitive keys, the Action Key and the Assist
      Key, jointly referred to as Smart Keys that each do dozens of things,
      essentially whatever is most helpful in any given textual context where they
      are pressed.  The Action Key is {M-RET} (ESC RETURN if you are unsure) on the
      keyboard and the shift-middle mouse button on a 3-button mouse or the
      shift-left button on a two button mouse.  The Assist Key is {C-u M-RET} and
      the shift-right mouse button.  Memorize these keys; you will use them a lot.
      To distinguish the mouse buttons from the keyboard keys, we will often refer
      to the Action Mouse Key or Assist Mouse Key.  (It is possible to rebind these
      keys to the unshifted middle and right mouse buttons, if desired.  See the
      Smart Key Bindings section of the Hyperbole Manual, "(hyperbole)Smart Key
      Bindings").
      
      The Action Key selects entities, creates links and activates buttons.  The
      Assist Key provides help, such as reporting on a button's attributes, or
      serves a complementary function to whatever the Action Key does within a
      context.  Press the Action Key within this <(button)> to see all of the
      contexts and operations of the Smart Keys.  SPACE scrolls forward and
      backwards DELETE scrolls backward within the Smart Key summary; {q} quits
      and returns here.
      
      See also the later section, <(Smart Mouse Keys)>.
      
      Now let's look at many of the things you can do with the Smart Keys.
      4. 
Koutliner
      
      A unique feature of Hyperbole is the Koutliner; it is for outlining thoughts,
      developing requirements or listing tasks and hyperlinking them to other
      documents.
      
      The Hyperbole Koutliner produces structured, autonumbered documents composed
      of hierarchies of cells.  Each cell has two identifiers, a relative
      autonumber indicating its present position within the outline and a permanent
      identifier suitable for use within hyperlink references to the cell.
      
      A demonstration of the Koutliner is found on the Hyperbole Kotl/Example menu
      entry.  {C-h h k e}, gives you an editable copy of Hyperbole's example
      Koutliner file.  This explains the Koutliner commands and lets you try them
      out as you learn.  Additional documentation can be found in
      "(hyperbole)Koutliner".  "(hyperbole)Koutliner Keys" summarizes in
      alphabetical order the Koutliner commands which are bound to keys.
      5. 
HyControl
      
      Hyperbole includes the fastest, easiest-to-use Emacs window and frame
      management system available, HyControl, found under the Hyperbole Screen
      menu, {C-h h s}.  If you use a lot of Emacs windows or frames (native window
      system windows), then this tool is for you.  A long video demonstrating most
      of HyControl's features is available at https://youtu.be/M3-aMh1ccJk.
        
      HyControl interactively adjusts the layout of your windows and frames down to
      the pixel-level, if desired.  You adjust the location, size and display
      elements of your windows and frames until they look as you like and then
      simply quit HyControl and go back to work.  It has smart features for laying
      out large grids of windows, avoiding having frames cover graphical toolbars
      anchored at the edges of your screen, and allows you to quickly set numeric
      arguments to apply to operations, like resizing a frame to a percentage of
      your screen size.
      
      There are two submodes of HyControl: one for controlling windows and one for
      controlling frames, although a number of commands are available in both modes
      where they are useful.
      
      Hyperbole binds {C-c } to invoke HyControl windows control; otherwise, the
      Hyperbole minibuffer menu item, Screen/WindowsControl {C-h h s w}, will do
      the same thing.
      
      Once in HyControl, your minibuffer window at the bottom of the selected frame
      will display a summary of keys you may use to adjust your windows until you
      press {q} to quit from HyControl.  If you don't see it, press {?}, to turn on
      this help display.  The key, {t}, will always switch you between controlling
      frames and windows, the minor modes of HyControl, with a modeline indicator
      of either "HyFrm" or HyWin" depending on which type of control is active.
      See "(hyperbole)HyControl" for full usage information.
      
      HyControl interactively adjusts the layout of your windows and frames down to
      the pixel-level, if desired.  You adjust the location, size and display
      elements of your windows and frames until they look as you like and then
      simply quit HyControl and go back to work.  It has smart features for laying
      out large grids of windows, avoiding having frames cover graphical toolbars
      anchored at the edges of your screen, and allows you to quickly set numeric
      arguments to apply to operations, like resizing a frame to a percentage of
      your screen size.
      
      There are two submodes of HyControl: one for controlling windows and one for
      controlling frames, although a number of commands are available in both modes
      where they are useful.
      
      Hyperbole binds {C-c \} to invoke HyControl windows control; otherwise, the
      Hyperbole minibuffer menu item, Screen/WindowsControl {C-h h s w}, will do
      the same thing.
      
      Once in HyControl, your minibuffer window at the bottom of the selected frame
      will display a summary of keys you may use to adjust your windows until you
      press {q} to quit from HyControl.  If you don't see it, press {?}, to turn on
      this help display.  The key, {t}, will always switch you between controlling
      frames and windows, the minor modes of HyControl, with a modeline indicator
      of either "HyFrm" or HyWin" depending on which type of control is active.
      See "(hyperbole)HyControl" for full usage information.
      6. 
HyRolo
      
      HyRolo is an advanced hierarchical, record-oriented retrieval system that
      uses text files for storing its records.  Most often this is used for contact
      management but it can quickly be adapted to most any record-oriented lookup
      task requiring fast retrieval.
      
      HyRolo manages and searches rolo files which consist of an optional header
      that starts and ends with a line of equal signs (at least three equal signs
      starting at the beginning of a line), followed by zero or more rolo records.
      You must manually add a header to any rolo file if you want it to have one.
      
      We call rolo records, entries.  Entries begin with a delimiter of one or more
      `*' characters at the beginning of a line.  Entries may be arranged in a
      hierarchy, where child entries start with one more `*' character than do
      their parents.  Top-level entries begin with a single `*'.
      
      Beyond this initial delimiter, entries are completely free-form text.  It is
      best to use a "lastname, firstname" format, however, when adding contact
      entries into a rolo.  Then HyRolo will automatically keep your entries
      alphabetized as you enter them.  Then you can sort the entries if you ever
      need.
      
      HyRolo commands are invoked from the Hyperbole Rolo menu.  See
      "(hyperbole)HyRolo" for a full reference on commands including adding
      entries, regular expression searches and manipulating the HyRolo search
      results buffer.
      
      For demonstration purposes, we discuss only the most common searches and use
      a global key binding for quick access to HyRolo searches of existing entries.
      Below is a sample rolo file that we will work with in this DEMO.  The date at
      the end of each record is automatically added by HyRolo whenever a new record
      is added.
      
      ==================================================================
      DEMO ROLO
      ==================================================================
      *    HiHo Industries
      **     Strong, Hugo            <hs@hiho.com>  W708-555-9821
                   Manager
                   04/12/2017
      ***      Smith, John           <js@hiho.com>  W708-555-2001
                   Chief Ether Maintainer
                   05/24/2017
      *    Work Industries
      **     Hansen, Dan             <dh@work.com>  W218-555-2311
                   Manager
                   02/18/2017
      ***      Dunn, John            <md@work.com>  W218-555-3233
                   Media Maker
                   11/2/2017
      7. 
History
      
      Hyperbole provides a history command that returns you to previous button
      locations in the reverse order of the way you traverse them.  It actually
      restores your complete frame and window configuration at the time of the
      button press.  You access it by selecting the Hist command from the top-level
      Hyperbole menu, {C-h h h}.  Remember this because you will want to use that
      command to return to this DEMO later.
      8. 
Implicit Buttons
      
      An incredibly powerful feature of Hyperbole is known as implicit buttons,
      i.e. a specific format of text within a buffer that Hyperbole recognizes as a
      button and lets you activate.  Hyperbole recognizes these by context and does
      not require any specialized markup.
      
      Note that you must press a Smart Key on the first line of an implicit button
      to utilize it if it spans multiple lines and always press on a regular
      character, not a delimiter like ( or ) since these are treated specially and
      used to select groups of text.
      
      Hyperbole has many built-in implicit button types, a number of which you will
      see here, and allows you to create your own.  Once a type is known, you can
      embed an infinite number of buttons of that type within your text simply by
      typing them.  Let's look at some of these button types and how you can use
      them.
      9. 
Explicit Buttons
      
      Beyond implicit buttons recognized in-context by Hyperbole, Hyperbole also
      offers `explicit buttons' that you create and embed within documents.  As you
      have seen, explicit buttons look like this `<(fake button)>'.  They are
      quickly recognizable, yet relatively non-distracting as one scans the text in
      which they are embedded.  Explicit buttons can link to local and remote files
      or to a section within a document; they can calculate things or query
      databases or show different views of bodies of information.  Unlike HTML
      hyperbuttons, there is no markup language to learn nor specific document
      format required.  You can create explicit buttons with simple keyboard
      presses or mouse drags from one window to another.
      
      This button prints the <(factorial)> of 5 in the minibuffer when activated
      with the Action Key.  If you instead press the Assist Key, you get help for
      the preceding button.  The help offered is a summary report of the button.
      You will see that it utilizes the `eval-elisp' action type.  You can also see
      who created it.  Try it.  {q} will quit the summary report display.
      
      Note that the create-time and mod-time are displayed using your own timezone
      but they are stored as universal times.  So if you work with people at other
      sites, you can mix their buttons with your own within the same document and
      see one unified view of the modification times on each button.
      
      Every explicit button utilizes an `action type', many of which are predefined
      by Hyperbole.  {C-h h e t RET} lists all action types available to you when
      creating explicit buttons and specifying their types.
      
      Hyperbole is pretty forgiving about the format of explicit buttons.  For
      example, all of the following represent the same button, as long as you press
      on the *first* line of the button, within the button delimiters:
      
      <(factorial button)>
      
      <( factorial      button)>
      
      Pam>  <(factorial
      Pam>    button)>
      
      ;; <(factorial
      ;;   button)>
      
      /* <( factorial      */
      /*    button )> */
      10. 
Smart Mouse Keys
      
      If you use Emacs with mouse support under the macOS window system, the X
      Window System or MS Windows, Hyperbole automatically configures your mouse
      keys for use as Smart Keys and provides additional display-oriented
      operations as demonstrated here.
      
      See the Hyperbole menu item, Doc/SmartKeys {C-h h d s}, for a summary of
      all Smart Key operations.  For extensive details on Smart Key operation,
      see the Hyperbole manual section, "(hyperbole)Smart Key Reference".
      
      If you ever want to restore the mouse bindings that existed before Hyperbole
      was loaded, use the `hmouse-toggle-bindings' command.  It switches between
      the Hyperbole mouse key bindings and those set prior to loading Hyperbole
      and then back again if invoked once more.  There is no default key binding
      for this command, so you must use `M-x hmouse-toggle-bindings RET'.
      Alternatively, you may select a key and bind it as part of any setting of
      `hyperbole-init-hook' within your personal .emacs file.
      
      For example:
        (add-hook 'hyperbole-init-hook
          (lambda () (global-set-key <YOUR-KEY-HERE> 'hmouse-toggle-bindings)))
      11. 
Switching to Another Buffer
      
      An Action Key click in the left edge of a modeline buries the current buffer,
      i.e. puts it on the bottom of the buffer list and removes it from view, if it
      is not the only available buffer.  An Assist Key click in the left edge of a
      modeline unburies the bottom buffer.  Repeated clicks of either key allow you
      to cycle through buffers to get to the one you want.  Try this out.  A
      similar thing can be accomplished by using the left mouse key and the Assist
      Mouse Key on the modeline buffer name if you need a wider space as a target.
      12. 
Running Dired on the Current Directory
      
      An Action Key click on the modeline buffer name runs dired on the current
      directory.  An Action key click on an item in the dired buffer, displays the
      item.  An Action Key click on part of the directory name in the first line of
      the dired buffer runs dired on the ancestor directory given by the text to
      the left of the click location.  A click at the end of the first line quits
      the dired session.
      13. 
Displaying Documentation
      
      An Action Key click in the right edge of a modeline displays the Info manual
      browsing system, see "(info)".  Once in Info, you can click with your Action
      Key to follow menu items, cross references, or to jump to Info nodes
      referenced within the top header line of a node.  Try browsing a bit and
      while in Info, display context-sensitive help for both the Action and Assist
      Keys to see all that they can do.
      
      If you click again with the Action Key on the right edge of the window
      displaying Info, it will hide the Info buffer.  Thus, it works as a toggle to
      display or to hide the Info buffer.  Isn't that easy?
      
      A click of the Assist Key at the right edge of a modeline toggles between
      display and removal of the Smart Key operation summary.  To remove the summary,
      you must click on the modeline of the window displaying the summary.
      14. 
Buffer Menu and Screen Control
      
      An Action Key click in the blank center portion of a modeline displays
      a buffer menu, a summary of available buffers.  An Action Key click on
      any buffer menu line then displays that buffer and closes the buffer
      menu.
      
      If you want to display several buffers, first create some new windows, then
      display the buffer menu and drag from each buffer name to the window in which
      you want it displayed.  This works across frames and also works in ibuffer
      and dired modes too!  Try it now.
      
      Alternatively, you may display the buffer menu, use its {m} command to mark
      buffers and then use the {@} command to display the marked buffers in a grid
      of popup windows whose number of rows and columns you specify at the prompt
      or via a prefix argument.  This also works in ibuffer-menu and dired modes.
      
      An Assist Key click in the blank center portion of a modeline pops up
      a menu of convenient screen commands that lets you select buffers
      grouped by major mode, use HyControl, or jump to specific windows,
      window configurations or frames.
      
      See "(hyperbole)action-key-modeline-function" for how to adjust this
      behavior.
      15. 
Epilog
      
      We hope you have enjoyed this introduction to Hyperbole. It can be your
      ever-ready sidekick in your daily knowledge work.  Explore the Hyperbole
      menus to learn more interactively.  For reference, the Hyperbole Manual, has
      extensive detail about the many things that Hyperbole does when you are ready
      to dive deeper.  Read it online with the GNU Info reader at "(hyperbole)Top".
      16. 
References
      
      [FSF 16] Free Software Foundation, Inc.  GNU Emacs Manual.  Free Software
      Foundation, Cambridge: MA, 2016.  "(emacs)Top"