FAST-DEMO

* GNU Hyperbole Fast Demo by Bob Weiner

  Send an email or a testimonial if you like Hyperbole to <rsw@gnu.org>.

  This interactive demo is the fast way to get started with Hyperbole after
  installation.  The prior, lengthier Hyperbole demo/tutorial can be found
  in this file: "DEMO".  For a non-interactive introduction to Hyperbole
  concepts, see "HY-CONCEPTS.kotl".


* Introductory Videos

  If you prefer video introductions, visit the videos linked to in the tables below;
  otherwise, skip to the next section.  The first table, "#Hyperbole Overview Video",
  is an overview talk of Hyperbole broken into few minute sections that you can watch
  individually.  The second table has links to separate videos covering aspects of
  Hyperbole, including the full <ilink:Overview and Demo>.

** Hyperbole Overview Video

  Demos of Hyperbole features start in 'section 06 - Hyperbole Buttons' in this first
  table.  Press {M-RET} either in the first column <[button name]> or in the second
  column video link to watch each section.

  |--------------------------------------+-----------------------------------------|
  | Hyperbole Overview Video Sections    | Video Snippets                          |
  |--------------------------------------+-----------------------------------------|
  |--------------------------------------+-----------------------------------------|
  | 01. <[Introduction]>                 | <yt-play "WKwZHSbHmPg" "0:01" "1:38">   |
  | 02. <[Hyperbole Mission]>            | <yt-play "WKwZHSbHmPg" "1:39" "2:43">   |
  | 03. <[Why Use Hyperbole]>            | <yt-play "WKwZHSbHmPg" "2:44" "4:34">   |
  | 04. <[Components]>                   | <yt-play "WKwZHSbHmPg" "4:35" "7:30">   |
  | 05. <[Installation & Use]>           | <yt-play "WKwZHSbHmPg" "7:31" "8:35">   |
  | 06. <[Hyperbole Buttons]>            | <yt-play "WKwZHSbHmPg" "8:36" "10:03">  |
  | 07. <[Button Categories & Files]>    | <yt-play "WKwZHSbHmPg" "10:04" "12:25"> |
  | 08. <[Implicit Buttons]>             | <yt-play "WKwZHSbHmPg" "12:26" "20:03"> |
  | 09. <[Implicit Button Types]>        | <yt-play "WKwZHSbHmPg" "20:04" "21:47"> |
  | 10. <[Explicit Buttons]>             | <yt-play "WKwZHSbHmPg" "21:48" "33:28"> |
  | 11. <[Global Buttons]>               | <yt-play "WKwZHSbHmPg" "33:29" "36:08"> |
  | 12. <[Mouse Keys/Buttons]>           | <yt-play "WKwZHSbHmPg" "36:09" "36:55"> |
  | 13. <[Mouse Drags & Treemacs]>       | <yt-play "WKwZHSbHmPg" "36:56" "38:00"> |
  | 14. <[Window Grids & Throws]>        | <yt-play "WKwZHSbHmPg" "38:01" "39:45"> |
  | 15. <[The Find Menu]>                | <yt-play "WKwZHSbHmPg" "39:46" "41:14"> |
  | 16. <[The Koutliner]>                | <yt-play "WKwZHSbHmPg" "41:15" "47:09"> |
  | 17. <[HyRolo]>                       | <yt-play "WKwZHSbHmPg" "47:10" "49:04"> |
  | 18. <[HyControl & Org Mode]>         | <yt-play "WKwZHSbHmPg" "49:05" "50:33"> |
  | 19. <[Integrations]>                 | <yt-play "WKwZHSbHmPg" "50:34" "50:58"> |
  | 20. <[Hyperbole History]>            | <yt-play "WKwZHSbHmPg" "50:59" "53:28"> |
  | 21. <[Acknowledgements & Resources]> | <yt-play "WKwZHSbHmPg" "53:29" "54:24"> |
  | 22. <[The Big Picture]>              | <yt-play "WKwZHSbHmPg" "54:25" "56:44"> |
  |--------------------------------------+-----------------------------------------|

** Hyperbole Videos

  |-----------------------------------------------------+----------------------------------------|
  | GNU Hyperbole Videos                                | Web Links                              |
  |-----------------------------------------------------+----------------------------------------|
  |-----------------------------------------------------+----------------------------------------|
  | <[Overview and Demo]>                               | https://youtu.be/WKwZHSbHmPg           |
  | Sections broken out in the prior table              |                                        |
  |-----------------------------------------------------+----------------------------------------|
  | <[Unscripted Hyperbole Demo at EmacsATX]>           | <yt-play "iuwn8GpRj7w" "0:48" "32:42"> |
  |-----------------------------------------------------+----------------------------------------|
  | <[Quick Introduction]>                              | https://youtu.be/K1MNUctggwI           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Top 10 ways Hyperbole amps up Emacs]>             | https://youtu.be/BysjfL25Nlc           |
  |-----------------------------------------------------+----------------------------------------|
  | <[HyWiki: Zero Markup Hypertext]>                   | https://youtu.be/3zG3lRmi3Zg           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Introduction to Buttons]>                         | https://youtu.be/zoEht66N2PI           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Linking Personal Info with Implicit Buttons]>     | https://youtu.be/TQ_fG7b1iHI           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Powerful Productivity with Hyperbole and Org]>    | https://youtu.be/BrTpTNEXMyY           |
  |-----------------------------------------------------+----------------------------------------|
  | <[HyRolo, fast contact/hierarchical record viewer]> | https://youtu.be/xdJGFdgKPFY           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Using Koutline for stream of thought journaling]> | https://youtu.be/dO-gv898Vmg           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Build a Zettelkasten with HyRolo]>                | https://youtu.be/HdlCK9w-LyQ           |
  |-----------------------------------------------------+----------------------------------------|
  | <[HyControl, fast Emacs frame and window manager]>  | https://youtu.be/M3-aMh1ccJk           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Writing test cases for GNU Hyperbole]>            | https://youtu.be/maNQSKxXIzI           |
  |-----------------------------------------------------+----------------------------------------|
  | <[Find/Web Search]>                                 | https://youtu.be/8lMlJed0-OM           |
  |-----------------------------------------------------+----------------------------------------|


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

  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
  "README.md#Installation", in the same directory as this file, for
  instructions on installing it, though {M-x package-install RET hyperbole
  RET} is typically all you need.

  If you simply want to know what Hyperbole is, see the file "HY-ABOUT".
  Hyperbole displays that file when you press the minibuffer menu command,
  {C-h h d a}.  Any of Hyperbole's menu commands can be programmatically
  bound to another key, like so:

    (global-set-key "\C-cd" (kbd "C-h h d a"))

* Implicit Buttons

  Hyperbole automatically recognizes many common and complex patterns within
  Emacs buffers and turns them into hyperbuttons that either link to other
  things or perform a set of actions.  No need for markup, simply press on a
  button in any kind of Emacs buffer to activate it.

  These patterns are called `implicit buttons' and are activated by pressing
  {M-RET} (ESC RETURN, ALT-RETURN, or CMD-RETURN) or SHIFT-MIDDLE-MOUSE
  anywhere within them (this is known as the Action Key).  Hyperbole
  recognizes these buttons using its many predefined implicit button types
  that specify how to recognize each type of button and what action it
  performs.  (For example, the web links in the table above are implicit
  buttons that display web pages.  So are the series of key presses
  surrounded by braces throughout this document).  You can also add your own
  button and action types.

  Try pressing {M-RET} or SHIFT-MIDDLE-MOUSE on some of the implicit buttons
  in double quotes below to activate them and see how they behave.  Press
  {C-h A} (the A must be capitalized) on any Hyperbole button or highlighted
  Emacs push-button to see exactly what it does prior to activating it.


** Implicit Link Buttons

  You can simply type implicit buttons into a buffer or you can use {C-h h i
  c} to create them and give them names.  When you have exactly two windows
  in an Emacs frame, you can instantly create an unnamed implicit link
  button from the selected window to point in the other window by using {C-h
  h i l}.  {M-1 C-h h i l} creates or renames a named implicit button that
  looks like <[name]>.

  You can create the same button by depressing the Action Mouse Key in the
  text of one window and dragging to the text of the other and releasing it.
  An implicit link button of an appropriate type for the release context
  will be inserted at the original depress point.

  With more than two windows, Hyperbole will prompt you to choose the
  referent window and its associated point to which to link.  If the Ace
  Window package is installed and active, this will be used to choose the
  window; otherwise, you will be prompted to select it by mouse.


** Pathname Implicit Buttons

    "HY-NEWS#ORG MODE:3:6"   - outline section anchor & relative line number

       Display the file, "HY-NEWS", go to the star-outline section 'ORG
       MODE', move 3 lines into that section and then move 6 characters
       forward.  "HY-NEWS#ORG MODE:L3:C6" with the line and column numbers
       labeled works as well.

       Existing files and pathnames without spaces are also recognized without
       double quotes.

       The variable, <hpath:display-where>, determines where Hyperbole
       displays all button referents, whether in another window or frame.

    "#Key Series Implicit Buttons"

       Display at the top of another window the named section from the
       current buffer.

    <[comp]>: "README.md#Hyperbole Components" - Markdown anchor with spaces intact

       Display the file, "README.md", scrolled to it outline section,
       "Hyperbole Components".  Name this button, 'comp'.  Then you can link
       to it elsewhere in the buffer with <ilink: comp>.  {M-RET} on the
       ilink to activates the button it links to.

    "${hyperb:dir}/HY-NEWS"          - Elisp or environment variables; $VAR
                                       shell vars work too


    "subr.el"                        - edit any Elisp library in load-path

       The variable, hpath:auto-variable-alist, determines which file
       suffixes are looked up using variables containing multiple search
       directories. By default, Org files, Python files and Elisp files are
       handled.

    "(hyperbole)action-key-modeline-function"

       Double quoted Info manual references are also implicit buttons.  You
       can link to both nodes/sections in GNU Info manuals as well as to
       specific lines referenced by an index entry, as shown above, providing
       fine-grained structured document linking.  Remember this as there will
       be more Info links below.


** Key Series Implicit Buttons

    A key series is an arbitrary length set of bound Emacs keystrokes
    surrounded by braces, like a visual keyboard macro.  RET, SPC and
    ESC are translated into their respective keys.  Activate them with
    {M-RET} or SHIFT-MIDDLE-MOUSE.

    {C-h A}

       Press {C-h A} when over any Hyperbole button for an explanation of
       what it does.

    {M-x dired-other-window RET ${hyperb:dir}/*.el M-RET}

       Hyperbole home directory Dired listing of Emacs Lisp files only

    {C-22 C-c @}

       Display a 2x2 windows grid in the current frame of the 4 most recently
       used buffers.  Before you try this, remember the binding {C-h h y} for
       History.  Use that to return to your current window configuration
       after pressing the Action Key on any windows grid button.

    {C--1 C-c @ kotl/kotl-*.el RET}

       Find the Hyperbole Koutliner source files that begin with 'kotl' and
       display them in an auto-sized grid of windows.

    {C-0 C-c @ emacs-lisp-mode RET 33 RET}

       Display the 9 mostly recently used Emacs Lisp buffers in a 3x3 grid.
       A BLANK buffer fills in the grid if there are not enough Emacs Lisp
       ones.

    {C-x 4 d ${hyperb:dir} RET}

       Dired the Hyperbole home directory based on its variable.  {M-RET}
       on the directory itself will display the directory's value in the
       minibuffer.

       Within this dired buffer, mark a few files with {m} and then press
       {@} to display a window grid of those files only.  That works in
       Buffer Menu and IBuffer modes as well.

    {C-x C-b C-x C-q M-x keep-lines RET .el$ RET C-x C-q}

       Display a buffer list of Emacs Lisp file buffers only

    {C-x C-b C-x C-q M-x keep-lines RET [\\/]$ RET C-x C-q}

       Buffer list of directory buffers only


** Posix/Linux Shell Command Implicit Buttons

    Some of the below commands require recursive use of the minibuffer, so let's
    ensure that is enabled:

    <setq enable-recursive-minibuffers t>

    The shell command part of the demo requires a shell that is compatible
    with bash.  If you are using another shell you can switch to bash for
    this part of the demo:

    { M-x set-variable RET shell-file-name RET C-u M-! /usr/bin/env SPC bash RET RET }

       Set the name of the inferior shell to /bin/bash. If you do this
       don't forget to reset it to your preferred shell when you are ready
       with the demo.

    { M-x shell RET M-> (cd ${hyperb:dir}) RET }

       Move to a directory in a shell based on a Lisp variable.  Sections
       within key series surrounded by parentheses maintain spaces between
       words without the need to use 'SPC'.

    {M-x shell RET M-> (export HYPERBOLE_DIR=${hyperb:dir} &&
     cd $HYPERBOLE_DIR && grep -n gbut:label-list *.el) RET}

       Use both a Hyperbole resolved variable, ${hyperb:dir}, and a
       shell-resolved environment variable, $HYPERBOLE_DIR, to grep through
       Lisp files.

    {M-x shell RET M-> (apropos grep) RET}

       Use Posix apropos command to list grep-related commands.  Then press
       {M-RET} on any lines output to display the man page for the associated
       command.


** Grep Messages, Stack Traces, Man Page Apropos Implicit Buttons

  These implicit buttons typically appear in shell buffers.  You issue a
  shell command and then use {M-RET} or SHIFT-MIDDLE-MOUSE on the output
  lines of the command to display the associated reference.

*** grep -n gbut:label-list *.el
hactypes.el:454:					      (mapcar #'list (gbut:label-list))
hbut.el:605:				       (mapcar #'list (gbut:label-list))

       An Action Key press anywhere on the text of the two above output lines
       from a grep -n or a ripgrep command jumps to the referenced line.

*** python topwin.py
Traceback (most recent call last):
  File "topwin.py", line 18, in <module>
    import Quartz

       An Action Key press anywhere on the above 2 non-blank lines jumps to
       the source of the error.  You can jump into any stack frame this way
       when debugging from pretty much any language, even in a regular shell.

*** man -k spell
aspell(1)                - interactive spell checker
aspell-import(1)         - import old personal dictionaries into GNU Aspell
pspell-config(1)         - prints information about a libpspell installation

       An Action Key press anywhere on the above 3 non-blank lines displays
       the associated man documentation page.


** Action Buttons

  These are a generalized form of implicit buttons.

  If you know your way around Emacs Lisp and want to quickly turn snippets of
  Lisp code or Lisp variables into Hyperbole buttons, just remove any outer
  parentheses and surround the remaining code with <angle-brackets>.

  Here are some examples.

    <shell>

       Jump to an existing shell buffer or create a new one.

    <fill-column>

       Display the variable value of 'fill-column' in the minibuffer

    <find-file-other-window (expand-file-name "DEMO" hyperb:dir)>
    <hpath:find "${hyperb:dir}/DEMO")>
    "${hyperb:dir}/DEMO"

       All three of the above do essentially the same thing, displaying the
       file.

    <kotl/EXAMPLE.kotl#3b10|c2en>

       Display a Hyperbole Koutline starting from cell 3b10 with lines per
       cell clipped to 2.

    <ert-deftest hbut-tests-ibut-program-link-to-directory ()
      "Test programmatically creating a link-to-directory implicit button."
      (with-temp-buffer
	(ibut:program nil 'link-to-directory "/tmp")
	(should (string= "\"/tmp\"" (buffer-string))))>

    <hbut-tests-ibut-program-link-to-directory>

       Tests defined with the Emacs Regression Test framework using
       `ert-deftest' can be run via action buttons as well.  Press {M-RET}
       on the first line of each of the two above action buttons, within
       the <> delimiters.  Start with the first one which defines an ERT
       test case; the second one runs it, displaying the result which should
       be successful.

    <hyperbole-run-tests hyrolo>

       The above will even run all Hyperbole regression tests for the HyRolo
       hierarchical full-text record retriever part of Hyperbole.


** Many More Implicit Button Types to Learn Across Time

  Activate this button, <emacs-lisp-mode>, to set this buffer into Emacs Lisp
  mode.  Then an Action Key press on each of the implicit button types below
  will jump to its Lisp definition.  Use this if you want to see what each
  type can do.  <normal-mode> reverts to the standard mode.

|------------------------+---------------------------+-----------------------|
|                          Implicit Button Types                             |
|------------------------+---------------------------+-----------------------|
| action                 | annot-bib                 | completion            |
| cscope                 | ctags                     | debbugs-gnu-mode      |
| debbugs-gnu-query      | debugger-source           | dir-summary           |
| doc-id                 | elink                     | elisp-compiler-msg    |
| etags                  | git-commit-reference      | glink                 |
| gnus-push-button       | grep-msg                  | hyp-address           |
| hyp-source             | id-cflow                  | ilink                 |
| Info-node              | ipython-stack-frame       | kbd-key               |
| klink                  | mail-address              | man-apropos           |
| markdown-internal-link | org-link-outside-org-mode | patch-msg             |
| pathname               | pathname-line-and-column  | rfc                   |
| rfc-toc                | ripgrep-msg               | social-reference      |
| texinfo-ref            | text-toc                  | www-url               |
|----------------------------------------------------------------------------|

Implicit button types are stored in their own namespace, 'ibtypes::', so to
see the doc on the 'pathname' ibtype, use {C-h f ibtypes::pathname RET}.

See "DEMO#Implicit Buttons" or "(hyperbole)Implicit Buttons" for more detail.
To learn how to create new kinds of implicit button and action types, see
"(hyperbole)Creating Types".


* Hyperbole Explicit and Global Buttons

  You have learned the basics of Hyperbole implicit button types.  Hyperbole
  has two other categories of buttons:

  `Explicit buttons' are manually created and embedded within buffers and
  explicitly assigned any of the many action types that Hyperbole includes.
  These contrast with implicit buttons which Hyperbole generates
  automatically by recognizing text patterns in buffers.  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 (when
  not on a draggable item).  See the {C-h h e} menu for explicit button
  commands.  {C-h h e c} creates an explicit button and {C-h h e l} creates
  an explicit link button between two windows, just like their counterparts
  for implicit buttons.  See "DEMO#Explicit Buttons" or "(hyperbole)Explicit
  Buttons" for more detail.

  `Global buttons' are explicit or named implicit Hyperbole buttons that are
  stored in your personal button file edited with {C-h h b p}.  Any such
  button in there becomes global and is accessible by name without the need
  to have the that file on screen.  Simply press {C-h h g a} to activate a
  global button and you will be prompted with completion for the button
  name.  See the {C-h h g} menu for the rest of the global button commands.
  See "DEMO#Global Buttons" or "(hyperbole)Global Buttons" for more detail.


* Hyperbole Subsystems

  Hyperbole includes a number of subsystems that can raise your productivity
  when looking up any kind of hierarchical records (including those from Org
  mode or Outline mode), managing the precise location of windows and frames,
  and one of the most advanced legal outliners available anywhere.

** HyWiki

  HyWiki is Hyperbole's markup-free personal wiki system for note-taking and
  automatic wiki-word highlighting and hyperlinking.  It uses Org mode for
  note taking and adds automatic hyperlinking of HyWikiWords within Org files
  directly below the directory given by the variable, `hywiki-directory'
  (default = "~/hywiki").  A HyWikiWord is a capitalized word that contains
  upper and lowercase letters only and has a corresponding HyWikiWord.org
  wiki page file below `hywiki-directory'.  HyWikiWords require no
  delimiters.

  To create a new HyWikiWord simply type it in an Org file in
  `hywiki-directory' and then press {M-RET} with point on the word.  This
  will create an empty wiki page for that word.  Add any text to this file
  and save it to create the new HyWikiWord.

  Use {M-RET} on the first line of the expression below to set a demo
  HyWiki directory and turn on hywiki-mode so HyWikiWords are
  highlighted outside of the HyWiki directory.

    <progn (setq hywiki-directory (hpath:expand "${hyperb:dir}/hywiki/"))
           (hywiki-mode :all)>

  Now all these wiki-words should be highlighted and can appear in any
  text buffer and will be treated as hyperlinks.  Simply press {M-RET}
  on each to display the associated wiki page:

    HyWiki
    HyWikiMenus
    Publishing

  Let's create a new page.  Press {M-RET} on the HyWikiWord below:

  TestWord

  Finally, let's restore the standard HyWiki directory so you can add
  your own HyWiki pages.  Press {M-RET} on the following expression.

    <setq hywiki-directory "~/hywiki/">

  See "(hyperbole)HyWiki" for full details on HyWiki.

** 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.  Press {M-RET} on
  "(hyperbole)HyRolo".

** 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.  Press {M-RET} on
  "(hyperbole)HyControl".

** Koutliner

  The Hyperbole Koutliner produces multi-level, autonumbered 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.  It has
  extensive Org mode key binding compatibility including for visibility
  cycling, tree moving and table editing.

  A demonstration of the Koutliner is found on the Hyperbole Kotl/Example
  menu entry, {C-h h k e}.  This gives you an editable copy of Hyperbole's
  example Koutliner file.  This file 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.


* Reference Documentation

  As noted at the start, "DEMO" provides a more extensive, interactive look
  into Hyperbole, {C-h h d d}, if you have more time.

  For a quick, non-interactive introduction to Hyperbole concepts, use
  "HY-CONCEPTS.kotl" available with {C-h h d c}.

  For those who want the deepest knowledge of Hyperbole, there is the long
  Hyperbole reference manual that you can read in sections.  This covers in
  detail how each button and action type works, how to create your own button
  and action types and much more.  See "(hyperbole)" or use {C-h h d i}.

  It is included in the "${hyperb:dir}/man/" subdirectory of Hyperbole in
  four forms, accessible as the links below:

    "man/hyperbole.info"   - online Info browser version
    "man/hyperbole.html"   - web HTML version
    "man/hyperbole.pdf"    - printable version
    "man/hyperbole.texi"   - source form

-- The End --