branch: externals/hyperbole
commit df7217fc7fbf362b0ad7851e7837190116f78dc4
Author: Bob Weiner <r...@gnu.org>
Commit: Bob Weiner <r...@gnu.org>
Add Org source for EmacsConf 2022 Hyperbole and Org Talk
---
HY-TALK/.hypb | 2 +-
HY-TALK/HYPB | 22 +-
HY-TALK/Hyperbole-and-Org-Mode.org | 529 +++++++++++++++++++++++++++++++++++++
HY-TALK/hbirds.gif | Bin 0 -> 75306 bytes
4 files changed, 549 insertions(+), 4 deletions(-)
diff --git a/HY-TALK/.hypb b/HY-TALK/.hypb
index cffaa3811f..044b0667ee 100644
--- a/HY-TALK/.hypb
+++ b/HY-TALK/.hypb
@@ -1,6 +1,6 @@
"Hyperbole-and-Org-Mode.org"
-("Make_Your_Text_Fly_with_Hyperbole_and_Org_Mode" nil nil exec-window-cmd
("mpv --loop hbirds.gif") "r...@gnu.org" "20221128:03:16:57" "rsw"
"20221128:03:18:33")
+("Bring_Your_Text_to_Life" nil nil life (1) "r...@gnu.org" "20221204:08:36:54"
nil nil)
"HY-TALK.org"
("Make_Your_Text_Come_Alive" nil nil kbd-key ("C-x 1 C-x 2 C-x o M-x hanoi
RET") "r...@gnu.org" "20200803:20:10:07" "rsw" "20200803:20:14:20")
diff --git a/HY-TALK/HYPB b/HY-TALK/HYPB
index 767e23f675..4e3b14bb1f 100644
--- a/HY-TALK/HYPB
+++ b/HY-TALK/HYPB
@@ -3,6 +3,24 @@
Install: <unless (featurep 'org-present) (package-install 'org-present)>
+(defun rsw-org-present-setup (buffer-name heading)
+ ;; Don't hide headline stars
+ (setq org-present-hide-stars-in-headings nil
+ ;; org-present-startup-folded nil
+ org-hide-emphasis-markers nil)
+
+ ;; Show only top-level headlines
+ (org-overview)
+
+ ;; Unfold the current entry
+ (org-show-entry)
+
+ ;; Show only direct subheadings of the slide but don't expand them
+ (org-show-children))
+
+(add-hook 'org-present-after-navigate-functions 'rsw-org-present-setup)
+
+
* Enable all Hyperbole keys including {M-RET} in Org mode
<setq hsys-org-enable-smart-keys t>
@@ -26,11 +44,9 @@ or interactively after loading Hyperbole:
Load,
Configure,
Activate: <hypb:activate-interaction-log-mode>
-
- Activate: <interaction-log-mode 1>
Deactivate: <interaction-log-mode 0>
-** Keypression - overlaying parts of buffer (shows trail of keys)
+** ALTERNATIVE: Keypression - overlaying parts of buffer (shows trail of keys)
Used for EmacsNYC talk
Install: <unless (package-installed-p 'keypression) (package-install
'keypression)>
diff --git a/HY-TALK/Hyperbole-and-Org-Mode.org
b/HY-TALK/Hyperbole-and-Org-Mode.org
new file mode 100644
index 0000000000..908ba667cc
--- /dev/null
+++ b/HY-TALK/Hyperbole-and-Org-Mode.org
@@ -0,0 +1,529 @@
+#+STARTUP: showall
+# Frame layout for presentation: <burly-open-bookmark "hyperorg">
+# {M-: (setq org-image-actual-width (list 500)) RET C-c C-x C-v}
+#+TODO: Bob-TODO: Bob-ACTV: | Bob-DONE:
+#+TODO: Mats-TODO: Mats-ACTV: | Mats-DONE:
+
+* Powerful Productivity with Hyperbole and Org Mode
+
+ Robert Weiner
+ <r...@gnu.org>
+
+ EmacsConf 2022
+
+
+ [[../hyperbole-banner.png]]
+ [[./org-mode-unicorn.png]]
+
+
+
+* About Me
+
+ - Author and co-maintainer of GNU Hyperbole
+
+ - Long-time application architect and developer
+
+ - Many years of Emacs use and development
+
+* Goal of this Talk
+
+Show how embedding simple Hyperbole text patterns into Org documents
+gives Org even more power and brings your documents to life with
+minimal additional cognitive overhead.
+
+* Table of Contents
+
+ - Why the Name, Hyperbole
+
+ - Hyperbole, the Package
+
+ - Context-sensitive Smart Keys
+
+ - Implicit Buttons
+
+ - Action Key on Org Constructs
+ + <hsys-org-enable-smart-keys> Shares M-RET between Hyperbole and Org
+ + Action Key Supports Org Links and Targets
+ + Simplify Inline Image Toggling
+ + Cycle Todos
+ + Cycle Image Link Buttons
+ + Code Block Support
+
+ - Search Org Notes with HyRolo
+
+ - Embed Org Tables in Hyperbole Koutlines
+
+ - Interactive Demonstrations with Action Buttons and Key Series
+
+ - Acknowledgements
+
+ - Conclusion
+
+* Why the Name, Hyperbole
+
+ - Pronounciation: hī-pûr′b-lē
+
+ - Definition: An extravagant statement or assertion not intended
+ to be understood literally.
+
+ - About: Hyperbole combines the world's simplest hyperbutton
+ markup with powerful automation capabilities across
+ all of Emacs, including Org mode.
+
+ For a full description of Hyperbole, see:
+
+ https://gnu.org/s/hyperbole
+
+
+ "We have too much information in our lives, and it's coming in
+ faster than we can organize it. Rather than manually specifying
+ relationships between bits of information, we need a system that
+ can see these connections simply by taking context and content
+ into account." -- John Wiegley, former Emacs Maintainer
+
+
+* Hyperbole, the Package
+
+** Setting Up Hyperbole
+
+ - It works in Emacs 27, 28 and 29, with the latest Org releases, on
+ any Emacs display device.
+
+ - Installation is Simple (GNU Elpa Stable Package):
+
+ (package-install 'hyperbole)
+
+ or for the latest in-development release (GNU Elpa-Devel Package):
+
+ (add-to-list 'package-archives '("elpa-devel" .
"https://elpa.gnu.org/devel/";))
+ (package-install 'hyperbole)
+
+ - Then activate it as a global minor mode:
+
+ (hyperbole-mode 1)
+
+ - You can also disable it quickly:
+
+ (hyperbole-mode 0)
+
+ - Or remove its package quickly:
+
+ {M-x package-delete RET hyperbole RET}
+
+ - Complete Details in:
+
+ https://gnu.org/s/hyperbole/man/hyperbole.html#Installation
+
+ - Join the low-traffic Hyperbole discussion list by sending any email to:
+
+ <hyperbole-users-j...@gnu.org>
+
+** Videos
+
+Hyperbole is extensively documented and there are videos too!
+
+
|-----------------------------------------------------+------------------------------|
+ | GNU Hyperbole Videos | Web Link
|
+
|-----------------------------------------------------+------------------------------|
+
|-----------------------------------------------------+------------------------------|
+ | Overview and Demo |
https://youtu.be/WKwZHSbHmPg |
+ | Covers all of Hyperbole |
|
+ | Hyperlink timestamps to watch each short section |
|
+
|-----------------------------------------------------+------------------------------|
+ | Quick Introduction |
https://youtu.be/K1MNUctggwI |
+
|-----------------------------------------------------+------------------------------|
+ | Introduction to Buttons |
https://youtu.be/zoEht66N2PI |
+
|-----------------------------------------------------+------------------------------|
+ | HyRolo, the fast contact/hierarchical record viewer |
https://youtu.be/xdJGFdgKPFY |
+
|-----------------------------------------------------+------------------------------|
+ | HyControl, the fast Emacs frame and window manager |
https://youtu.be/M3-aMh1ccJk |
+
|-----------------------------------------------------+------------------------------|
+ | Find/Web Search |
https://youtu.be/8lMlJed0-OM |
+
|-----------------------------------------------------+------------------------------|
+
+
+* Context-sensitive Smart Keys
+
+ - Hyperbole provides two context-sensitive keys, the Action Key,
+ {M-RETURN}/{M-RET}, and the Assist Key, {C-u M-RET} which provides
+ context-sensitive help or does the inverse of the Action Key.
+
+ - By default within Org mode, {M-RETURN}/{M-RET} activates Hyperbole
+ buttons and Org links; elsewhere in Org, it runs the standard Org
+ binding. {C-u M-RET}
+
+ - Outside of Org, press {M-RET} anywhere on a line that looks like a
+ hyperbutton/cross-reference to anything. Hyperbole computes the
+ context and applies its best guess action. Eliminate the need to
+ remember dozens of key bindings. Just press and go, keeping you
+ in the flow.
+
+ - {C-h A} show what the Action Key does in the current context
+ {C-u C-h A} show what the Assist Key does in the current context
+
+* Implicit Buttons
+
+ Simple Delimiters Instantly Create Implicit Hyperbuttons with Actions
Anywhere
+
+** Path Links
+
+Double-quoted path links can contain environment or Emacs Lisp
+variables, Markdown-like #section anchor references with spaces intact
+and relative line and column numbers. Here we jump to a specific
+place in a headline and display that at the top of the buffer.
+
+ "${hyperb:dir}/HY-NEWS#Org Mode:2:6"
+
+But the #section syntax works in many modes with sections or single
+line programming comments:
+
+ "HY-TALK.org#Action Types"
+
+ "~/.bashrc#List all parent directories of local Git repos"
+
+We can have buttons load Lisp libraries with a '-' prefix:
+
+ "-org-id"
+
+'!' prefix runs a terminal shell command:
+
+ "!date"
+
+ "!head ~/.emacs"
+
+'&' prefix asynchronously runs a GUI program:
+
+ "&open ../man/hyperbole.pdf"
+
+** <<<Hyperbole Key Series>>>
+
+Brace-delimited key series allow in-buffer activation of arbitrary
+strings of key sequences without the need to create keyboard macros or
+name them.
+
+ {C-x 4 b *scratch* RET M-< "Insert any text. That's cool!" RET RET M-<}
+
+Export this Org file as HTML and display:
+
+ {C-c C-e h o}
+
+ --
+
+ "It's cool to be able to turn arbitrary text into hyperlinks in
+ arbitrary modes, and have one keypress that does what I want on
+ all of them."
+
+** Info Node or Index Links
+
+Simply parenthesize the Info manual name and follow it with a node
+name or index entry to jump right there:
+
+ "(org)C-c C-l"
+
+You can also use short names in front of implicit links:
+
+ <[ib]> "(hyperbole)Implicit Buttons"
+ <[frm]> "(hyperbole)C-h h s f"
+
+Then better than Org links that jump to targets, {M-RET} on a link
+to a named implicit button (ilink) to activate the original button.
+
+ <ilink:ib>
+
+Similarly, you can these buttons to your Hyperbole personal button file
+accessed with {C-h h b p} and they become global buttons that can be referenced
+from any buffer with a global link:
+
+ <glink:frm>
+
+** Action Buttons
+
+Angle brackets followed by an Elisp command name and arguments, create
+an Action Button that is executed with a press of the Action Key.
+Variable name values can also be displayed.
+
+ <hypb:rgrep "Action Buttons"> Recursively find Elisp or text
matches
+
+ <fill-column> Display variable values in the
minibuffer
+
+ <hypb:activate-interaction-log-mode> Show key presses as in the rightmost
frame
+
+ # Hyperbole includes custom Youtube action types
+ # Play just segments of Youtube videos; snippet from Hyperbole Introduction
+ <yt-play "WKwZHSbHmPg" "50m34s" "50m58s">
+
+ # Search Youtube for related videos
+ <yt-search "hypertext hyperbole">
+
+** Windows Grids
+
+ # Use {C-h h h} to restore windows after windows grid commands
+ # Display a 2x3 grid of Dired buffers
+ {C-u 0 M-x hycontrol-windows-grid RET dired-mode RET 23 RET}
+
+ # Use an Action Button for a grid of matching files
+ <hycontrol-windows-grid-by-file-pattern 22
+ "~/Dropbox/emacs/ramin-org-notes/*emacs*.org">
+
+
+ "Because I’m trying to prevent my poor hands from turning into
+ gnarled, useless claws, I extensively use speech recognition
+ software. Hyperbole’s frame and window controls let me set up
+ workspaces and move stuff with a few vocal commands, without
+ having to type or use a mouse. It’s just great. I can’t say
+ enough nice things about it. I always know I’ve found a killer
+ piece of functionality when I find myself desperately wishing I
+ had it everywhere."
+
+
+* Action Key on Org Constructs
+
+** <hsys-org-enable-smart-keys> Shares M-RET between Hyperbole and Org
+This <<variable>> sets the Org mode contexts where Hyperbole's
+Action/Assist keys are active. By default, these 'Smart Keys'
+work only on hyperbuttons (Hyperbole's and Org's) when the variable
+is set to 'buttons.
+
+ <hsys-org-enable-smart-keys>
+
+ <setq hsys-org-enable-smart-keys 'buttons>
+
+Set this to 't to enable the Smart Keys in all Org contexts
+(nil to disable):
+
+ <setq hsys-org-enable-smart-keys t>
+
+See {C-h f smart-org RET} for details on all the Org contexts
+that Hyperbole supports, many of which we are demonstrating here.
+
+** Action Key Supports Org Links and Targets
+
+ Internal Target Link: [[variable]]
+
+ Radio Target Link: Hyperbole Key Series
+
+ Internal Heading Link: [[*Action Buttons]]
+
+ External File Link: [[file:HY-TALK.org][Link to another talk]]
+
+** Simplify Inline Image Toggling
+
+|--------------------------------------------------+----------------------------|
+| Toggle Inline Images - Org Markup | Hyperbole Markup
|
+|--------------------------------------------------+----------------------------|
+| [[elisp:(setq org-confirm-elisp-link-function nil)]] |
<org-toggle-inline-images> |
+| [[elisp:org-toggle-inline-images]] |
|
+|--------------------------------------------------+----------------------------|
+| Keystrokes Required to Execute - Org | Hyperbole
|
+|--------------------------------------------------+----------------------------|
+| {C-c C-o yes RET C-n C-c C-o} | {M-RET}
|
+|--------------------------------------------------+----------------------------|
+
+** Cycle Todos
+
+*** Bob-TODO: Demonstrate Action Key Cycling
+
+The Action Key moves a todo to its next state. The Assist Key shifts
+it to its next group of states.
+
+ # #+TODO: Bob-TODO: Bob-ACTV: | Bob-DONE:
+ # #+TODO: Mats-TODO: Mats-ACTV: | Mats-DONE:
+
+
+** Code Block Support
+
+#+BEGIN_SRC shell :results output
+ echo $PATH
+#+END_SRC
+
+#+RESULTS:
+:
/Users/bk/.nix-profile/bin:/Library/Frameworks/Python.framework/Versions/3.8/bin:/Applications:/Applications/Emacs26.app/Contents/MacOS/libexec:/Applications/Emacs26.app/Contents/MacOS/bin:/usr/local/opt/findutils/libexec/gnubin:/usr/local/sbin:/usr/local/Cellar/python3/libexec/bin:/usr/local/opt/libexec/gnubin:/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:/usr/local/bin:/usr/local/Cellar/python@3.9/3.9.2_2/Frameworks/Python.framework/Versions/3
[...]
+
+
+#+BEGIN_SRC python :dir ~/Dropbox/py/rsw_py_stack :results output
+ from stack import Stack
+
+ assert_expr = lambda expr: print(' ; '.join([f"{e:<30} => {eval(str(e))}"
for e in [expr]]))
+ s1 = Stack(0, 1, 2)
+ s2 = Stack()
+ assert_expr('s1')
+ assert_expr('s2')
+ assert_expr('s1.top() == 2')
+ assert_expr('s2.top() is None')
+ assert_expr('s1.is_empty() is False')
+ assert_expr('s2.is_empty() is True')
+ assert_expr('s1 and not s2 is True')
+ assert_expr('s2.push("a") == Stack("a")')
+ assert_expr('s1 + s2')
+ assert_expr('s1 == Stack(0, 1, 2, "a")')
+ assert_expr('s1.pop() == "a"')
+ assert_expr('s1 * 2')
+ assert_expr('s1 == Stack(0, 1, 2, 0, 1, 2)')
+
+#+END_SRC
+
+#+RESULTS:
+#+begin_example
+s1 => Stack(0, 1, 2)
+s2 => Stack()
+s1.top() == 2 => True
+s2.top() is None => True
+s1.is_empty() is False => True
+s2.is_empty() is True => True
+s1 and not s2 is True => True
+s2.push("a") == Stack("a") => True
+s1 + s2 => Stack(0, 1, 2, 'a')
+s1 == Stack(0, 1, 2, "a") => True
+s1.pop() == "a" => True
+s1 * 2 => Stack(0, 1, 2, 0, 1, 2)
+s1 == Stack(0, 1, 2, 0, 1, 2) => True
+#+end_example
+
+* Search Org Notes with HyRolo
+
+HyRolo is like grep (full-text search) but for hierarchical,
+multi-line records stored in files. It' interactive interface is for
+contacts but it has functions to search any record-based text files,
+like Org files, across any number of directories, recursively if
+needed.
+
+Let's see how easy it is to create an Action Button to search a subset
+of Org files for the term 'programming':
+
+ <hyrolo-fgrep-directories "*lessons*.org"
+ "~/Dropbox/emacs/ramin-org-notes/">
+
+
+* Embed Org Tables in Hyperbole Koutlines
+
+The Koutliner is Hyperbole's autonumbered outliner mode with an
+automatic, unique hyperlink anchor per cell/heading. It uses a
+compact numbering scheme that alternates letters and numbers per
+level, like '1a2b' but also support legal, 1.1.2.2 numbering.
+
+It has its own link format called 'klinks' that look like Action
+Buttons but start with a pathname rather than an Elisp symbol.
+These can link to a specific cell and set overall views of the
+outline:
+
+Here's a link to an Org Table:
+
+ <~/EXAMPLE.kotl, 3d2>
+
+
+* Interactive Demonstrations with Action Buttons and Key Series
+
+Let's show a Koutline with blank lines removed, switched to legal
+numbering and clipped to 3 lines per cell:
+
+ <~/EXAMPLE.kotl, |en.c3>
+
+Let's see this Org file in overview mode in another window:
+
+ {C-xnw C-x4c M-x org-overview RET M-<}
+
+Let's mark all the backup files in a directory for future deletion:
+
+ {C-x 4 d RET ~}
+
+
+n* Acknowledgements
+
+ The Org Team - for all the incredible things Org can do
+
+ Mats Lidell - long-time co-maintainer of Hyperbole
+ https://tinyurl.com/y2g5fvdu
+
+ Ramin Honary - for diving into Hyperbole and writing about it
+ http://tilde.town/~ramin_hal9001/index.html
+
+ John Wiegley (former Emacs maintainer) - Using Hyperbole: A Motivation
+ https://tinyurl.com/y3vnsuef
+
+ Adrien Brochard - Quick Hyperbole blog posting with animated gifs
+ https://blog.abrochard.com/hyperbole-intro.html
+
+ The FSF and GNU Project - providing a home for Hyperbole in GNU Elpa
+
+
+* Conclusion
+
+ - Hyperbole embeds well into Org mode
+
+ - Hyperbole offers easy markup and powerful hyperbuttons
+
+ - Hyperbole and Org together can automate complex tasks
+ without the much need to understand or utilize Elisp
+
+ - <(Bring Your Text to Life)> with Hyperbole and Org Mode
+
+ https://gnu.org/s/hyperbole
+
+ https://orgmode.org/
+
+-- Presentation End --
+
+
+* Appendices
+
+** Hyperbole Articles (Videos Listed in the Presentation)
+
+*** Potential Workflows
+
+ https://tinyurl.com/y57efmmr
+
+*** Summary of Hyperbole Uses
+
+ https://tinyurl.com/yxp3kv5s
+
+ Or after installing Hyperbole, try: {C-h h d w}
+
+*** Hyperbole Vision Quest Usage Articles
+
+ https://tinyurl.com/y5db5bpa
+
+
+** A Final Perspective on Hyperbole
+
+*** Reduce Cognitive Burden
+
+ From John Wiegley:
+
+ "Hyperbole lifts some of the cognitive burden from Emacs users by
+ defining an extensible, large set of "recognizers" for various
+ types of informational references, and "actions" for doing things
+ with that information, such as visiting referenced documents, or
+ web pages, or dictionary definitions. It's quite easy to add new,
+ contextually-sensitive recognizers, and actions, so that you can
+ teach Emacs to become more aware of how you use it to manage
+ information. -- John Wiegley
+
+
+*** Network Effects
+
+ "But what's more, with every new recognizer and action you add,
+ the more interactive all your information becomes. It's a
+ multiplying effect, turning inert, standalone documents into more
+ interactive, virtual semi-networks. And very few of these links
+ do you need to update and maintain, because most of the
+ information is inferred based on where you are when you hit the
+ 'action key'." -- John Wiegley
+
+
+*** Globally Accessible
+
+ "Since this functionality is transparently added everywhere, not
+ just special buffer types specific to Hyperbole, it's able to
+ make Org-mode outlines richer, Gnus article reading more
+ interactive, and source code more accessible to new readers --
+ provided they're using Emacs too." -- John Wiegley
+
+
+-- Document End --
+
+# Local Variables:
+# org-confirm-babel-evaluate: nil
+# truncate-lines: nil
+# hyrolo-file-list: '("~/.rolo.otl")
+# eval: (org-babel-do-load-languages 'org-babel-load-languages '((python . t)
(shell . t)))
+# End:
diff --git a/HY-TALK/hbirds.gif b/HY-TALK/hbirds.gif
new file mode 100644
index 0000000000..73516ea8f4
Binary files /dev/null and b/HY-TALK/hbirds.gif differ
