;; -*- Mode: kotl -*- 
"Kotl-4.0" ;; file-format

   1. People often ask why so many different concepts and capabilities are part
      of Hyperbole and how they relate to one another.  This is a rapid-fire,
      technical summary of how each part of Hyperbole's design builds upon
      other parts to provide advanced, yet easy-to-use capabilities throughout
      Emacs.  This document does not explain how to use Hyperbole.  It is meant
      to be viewed with Hyperbole's Koutliner, mentioned later in this document.

     1a. The "FAST-DEMO" file on {C-h h d d} interactively introduces you to
         Hyperbole in a step-by-step fashion.  That is a quick way to get a
         feel for it.  For a much more extensive, interactive, introduction,
         see the "DEMO" file instead.

     1b. The "HY-WHY.kotl" file on {C-h h d w} summarizes Hyperbole use cases
         if you are not yet motivated to use it.

     1c. The "HY-ABOUT" file on {C-h h d a} is a gentler, less detailed
         introduction to what Hyperbole offers.

     1d. To see what is new in Hyperbole from the Doc/News item, you use the
         key series, {C-h h d n}.

   2. GNU Hyperbole is a turnkey Emacs package with no external package
      requirements that offers an extensive, extensible, hypertextual
      information management system. It works with all kinds of file formats,
      including Org mode.  The core of Hyperbole supplies a default
      set of hyperbutton types, each of which performs a specific action.

   3. Hyperbole's Action {M-RET} and Assist Keys {C-u M-RET}, collectively
      known as the Smart Keys, provide context-sensitive activation of
      hyperbuttons and many other actions.  Hyperbole hyperbuttons can span
      multiple lines but you must activate them with a press on the first
      line of each button.

   4. There are three broad categories of Hyperbole button types:

     4a. Implicit Buttons - recognized by context without heavyweight markup;
         no meta-data other than the button text and optional name; its
         button types are defined using `defib' with a form similar to
         `defun'; each type can have a different textual appearance.

     4b. Explicit Buttons - context-independent buttons that all look the
         same (like <(button)>); have meta-data defined by the parameters of
         its specified action type and no other typing information, so an
         explicit button's type is its action type; the values of the action
         type's parameters are prompted for when the button is created and
         the meta-data is stored in a ".hypb" file in the same directory as
         the button source file.

     4c. Global Buttons - implicit or global buttons with names stored in
         your personal button file; the file is edited with {C-h h b p}.
         Hyperbole then reads all the button names in this file and prompts
         with completion to activate any such button with {C-h h g a}.

   5. Hyperbole action types determine what Hyperbole's hyperbuttons do; they
      are defined with the `defact' macro, similar to `defun'.  Links are one
      set of actions that display referents, but an action type can implement
      any Lisp behavior and is similar to a regular Lisp function.  Any
      category of Hyperbole button can invoke any action type or regular Lisp
      function.

   6. Let's explore implicit buttons a bit more since they are the most
      widely used category of Hyperbole buttons.  Implicit buttons are
      recognized within a buffer context without the need to add any special
      markup as Org mode and Markdown do.  Implicit buttons are built from an
      implicit button type that runs an action type when activated with the
      Action Key.

   7. Implicit button types and Action Key contexts recognize all sorts of
      cross-references embedded in files, e.g. URLs, Org IDs or email
      addresses, without any additional markup, and trigger associated action
      types.

     7a. To see all of the builtin implicit button types, use {C-h h i t RET}.
         This shows them in decreasing priority order.  The first type matched
         at any point is the type used.

     7b. Optionally, you can add a delimited <[name]> in front of an implicit
         button so that it can be activated by name via {C-h h i a}, or you
         can press the Action Key on the button name or its text.  If you put
         named implicit buttons in your personal button file, edited with
         {C-h h b p}, they become global buttons as mentioned before,
         activated by name with {C-h h g a}.

     7c. Brace-delimited key series (any series of Emacs key sequences strung
         together in braces) is one type of implicit button, e.g. {C-u C-n
         C-e}.  You can embed such sequences in any file and activate them
         instantly with an Action Key press within the braces.  These let you
         tie Emacs and Hyperbole commands together by simply typing out the
         keys for reuse any time in the future.  No need to learn about Emacs'
         keyboard macros or how to save them to files.

     7d. Action Buttons are a generalized form of implicit buttons that are
         delimited by angle brackets.  Such buttons allow invocation of any
         action type or Emacs function by name, followed by any needed
         arguments, when the Action Key is pressed within the button:

       7d1. Count windows in the selected frame:
              <message "This frame has %d windows" (count-windows)>

       7d2. Display the early Internet standard mail specification:
              <link-to-rfc 822>

       7d3. See more examples here: "FAST-DEMO#Action Buttons".

   8. Much of Hyperbole's functionality is accessed with its keyboard-driven
      minibuffer menu.

     8a. {C-h h} displays the top-level minibuffer menu.  Any item can be
         selected by typing its first capitalized letter or you can press the
         Action Key on the item to activate it.  The Assist Key will display
         the item's action in a help buffer.  Press the Action Key on the
         action name to display its definition/source code; the Assist Key
         will display its full documentation.

     8b. The keystrokes to access any menu command may be added to any file
         surrounded by curly braces as a key series.  Then an Action Key
         press will run it; put it in your personal button file, give it a
         short name and then you can access it anywhere.

   9. <(Explicit buttons)> can be created and embedded in most any type of
      file or buffer; each sends a set of given parameters to an action
      type when activated with an Action Key press.  See also "DEMO#Explicit
      Buttons".

  10. "HYPB" files serve as convenient home pages for embedding Hyperbole
      buttons.  Each user has a personal button file accessed with {C-h h b
      p} and each directory can have a local button file accessed with {C-h
      h b d}.  See "DEMO#Button Files".

  11. Global buttons are either explicit or named implicit buttons that are
      activated by choosing from a list of names, without the need to have
      the button source buffer on screen, thus they are available globally.
      All global buttons are stored in a user's personal "HYPB" file.  See
      "DEMO#Global Buttons" for how to use these.

  12. Hyperbole lets you set and control which windows or frames you want
      all of your hyperlink referents displayed in.  Each time you activate
      a Hyperbole button, it stores your current frame configuration on a
      stack.  You can pop back to a prior one with {C-h h h}.  You can also
      store per-frame window configurations in a ring or store and retrieve
      them by name utilizing the Hyperbole Win/ menu on {C-h h w}.

  13. You access Hyperbole's HyControl subsystem from the Screen/ menu on {C-h
      h s}.  This lets you rapidly control the set of, location of and size of
      per-frame windows (choose 'w' for WindowsControl) or frames (choose 'f'
      for FramesControl) on your screen.  Use 't' to toggle between these two
      modes and 'Q' when you want to quit from this mode.  A persistent prefix
      argument for all of HyControl's commands lets you quickly adjust things
      at any scale you like, e.g. widen a window by 20 characters at a time.
      See "DEMO#HyControl".

  14. Hyperbole's Koutliner subsystem on {C-h h k} is a powerful,
      hierarchically auto-numbered outliner with automatic permanent hyperlink
      ids for each outline node (called cells).  Any type of Hyperbole button
      can be embedded within Koutlines and external links can be made to
      specific cells together with a specific view of the outline using an
      implicit link type call a klink.

    14a. {C-h h k e} creates a personal copy of an example Koutline file that
         you can edit as you like; the content of that file explains Koutliner
         concepts and commands.

    14b. Like magic, {C-h h k f d}, converts this Koutline to HTML and displays
         it in your web browser, with each tree fully collapsible and
         expandable with your mouse.

  15. Hyperbole's HyRolo subsystem on {C-h h r} can be used just as a contact
      manager but it really is a generalized, hierarchical record retrieval
      system for files.

    15a. Simply set hyrolo-file-list to any list of Emacs Outline, Koutline,
         Markdown or Org files, any of which can contain any type of
         Hyperbole button, and HyRolo will perform full-text searches and
         rapidly display string, word, regular expression or logical query
         matches within each hierarchical record of each file (showing the
         full-text of the record, not just the matching line).

    15b. You can also include directories in the list and HyRolo will
         recursively scan them for files of the supported types.

    15c. File wildcards with asterisk matches, e.g. myfiles*.org and
         character sets, [abc]*.org also work.

    15d. Try it here: "DEMO#HyRolo".

  16. Hyperbole's Find/ menu on {C-h h f} unifies finding and filtering through
      lists of files and lines within those files.  It simplifies access to
      Emacs and Posix utilities without the need to remember specific command
      names.

  17. Hyperbole's Find/Web menu on {C-h h f w} gives you ready access to many
      structured web searches without having to remember site URLs or query
      parameters.  It also offers access to Emacs' webjump package (type {j}
      for Jump) to quickly jump to specific websites, similar to what {C-x r b}
      does for Emacs Bookmarks.

  18. In summary, Hyperbole integrates many information management
      capabilities spread throughout Emacs and the web.  It augments them
      with a new set of hyperbutton types and control systems, all easily
      accessible from a unified, keyboard driven minibuffer menu.

    18a. Hyperbole lets you rapidly get to information whether local or remote,
         whether via search or filtering, and then interlink it with other
         information, display it where you need on your screen, and edit it
         rapidly using multiple views in the Koutliner or via its Org mode
         compatibility.

    18b. If you learn to use just the implicit button types in Hyperbole, those
         alone should greatly improve your Emacs productivity.  Then as you
         learn more of Hyperbole's concepts, you can accelerate your
         information management further across time.


"ben" ;; kvspec:current
67 ;; id-counter
alpha ;; label-type
4 ;; label-min-width
". " ;; label-separator
3 ;; level-indent

;; depth-first kcell attributes
[[0
  (creator "rsw@gnu.org" create-time "20230513:18:17:42" id-counter 67)]
 [1
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [25
  (creator "rsw@gnu.org" create-time "20230513:18:35:44")]
 [26
  (creator "rsw@gnu.org" create-time "20230513:18:35:46")]
 [27
  (creator "rsw@gnu.org" create-time "20230513:18:45:15")]
 [63
  (creator "rsw@gnu.org" create-time "20231119:12:33:28")]
 [23
  (creator "rsw@gnu.org" create-time "20230513:18:33:50")]
 [4
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [39
  (creator "rsw@gnu.org" create-time "20231119:11:25:23")]
 [41
  (creator "rsw@gnu.org" create-time "20231119:11:25:51")]
 [42
  (creator "rsw@gnu.org" create-time "20231119:11:25:58")]
 [43
  (creator "rsw@gnu.org" create-time "20231119:11:26:07")]
 [3
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [32
  (creator "rsw@gnu.org" create-time "20230513:19:22:15")]
 [5
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [47
  (creator "rsw@gnu.org" create-time "20231119:11:44:58")]
 [45
  (creator "rsw@gnu.org" create-time "20231119:11:44:54")]
 [18
  (creator "rsw@gnu.org" create-time "20230513:18:22:23")]
 [19
  (creator "rsw@gnu.org" create-time "20230513:18:22:27")]
 [21
  (creator "rsw@gnu.org" create-time "20230513:18:26:47")]
 [22
  (creator "rsw@gnu.org" create-time "20230513:18:27:02")]
 [38
  (creator "rsw@gnu.org" create-time "20230513:20:13:11")]
 [6
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [51
  (creator "rsw@gnu.org" create-time "20231119:11:56:10")]
 [49
  (creator "rsw@gnu.org" create-time "20231119:11:55:55")]
 [7
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [8
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [9
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [10
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [11
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [12
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [36
  (creator "rsw@gnu.org" create-time "20230513:19:50:06")]
 [37
  (creator "rsw@gnu.org" create-time "20230513:19:50:14")]
 [13
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [64
  (creator "rsw@gnu.org" create-time "20231119:12:40:08")]
 [66
  (creator "rsw@gnu.org" create-time "20231119:12:40:38")]
 [67
  (creator "rsw@gnu.org" create-time "20231119:12:41:14")]
 [65
  (creator "rsw@gnu.org" create-time "20231119:12:40:26")]
 [14
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [15
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [16
  (creator "rsw@gnu.org" create-time "20230513:18:17:42")]
 [31
  (creator "rsw@gnu.org" create-time "20230513:19:08:35")]
 [29
  (creator "rsw@gnu.org" create-time "20230513:19:06:51")]
 nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil]
