-
Notifications
You must be signed in to change notification settings - Fork 11
/
HY-CONCEPTS.kotl
311 lines (269 loc) · 14.3 KB
/
HY-CONCEPTS.kotl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
;; -*- 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 "[email protected]" create-time "20230513:18:17:42" id-counter 67)]
[1
(creator "[email protected]" create-time "20230513:18:17:42")]
[25
(creator "[email protected]" create-time "20230513:18:35:44")]
[26
(creator "[email protected]" create-time "20230513:18:35:46")]
[27
(creator "[email protected]" create-time "20230513:18:45:15")]
[63
(creator "[email protected]" create-time "20231119:12:33:28")]
[23
(creator "[email protected]" create-time "20230513:18:33:50")]
[4
(creator "[email protected]" create-time "20230513:18:17:42")]
[39
(creator "[email protected]" create-time "20231119:11:25:23")]
[41
(creator "[email protected]" create-time "20231119:11:25:51")]
[42
(creator "[email protected]" create-time "20231119:11:25:58")]
[43
(creator "[email protected]" create-time "20231119:11:26:07")]
[3
(creator "[email protected]" create-time "20230513:18:17:42")]
[32
(creator "[email protected]" create-time "20230513:19:22:15")]
[5
(creator "[email protected]" create-time "20230513:18:17:42")]
[47
(creator "[email protected]" create-time "20231119:11:44:58")]
[45
(creator "[email protected]" create-time "20231119:11:44:54")]
[18
(creator "[email protected]" create-time "20230513:18:22:23")]
[19
(creator "[email protected]" create-time "20230513:18:22:27")]
[21
(creator "[email protected]" create-time "20230513:18:26:47")]
[22
(creator "[email protected]" create-time "20230513:18:27:02")]
[38
(creator "[email protected]" create-time "20230513:20:13:11")]
[6
(creator "[email protected]" create-time "20230513:18:17:42")]
[51
(creator "[email protected]" create-time "20231119:11:56:10")]
[49
(creator "[email protected]" create-time "20231119:11:55:55")]
[7
(creator "[email protected]" create-time "20230513:18:17:42")]
[8
(creator "[email protected]" create-time "20230513:18:17:42")]
[9
(creator "[email protected]" create-time "20230513:18:17:42")]
[10
(creator "[email protected]" create-time "20230513:18:17:42")]
[11
(creator "[email protected]" create-time "20230513:18:17:42")]
[12
(creator "[email protected]" create-time "20230513:18:17:42")]
[36
(creator "[email protected]" create-time "20230513:19:50:06")]
[37
(creator "[email protected]" create-time "20230513:19:50:14")]
[13
(creator "[email protected]" create-time "20230513:18:17:42")]
[64
(creator "[email protected]" create-time "20231119:12:40:08")]
[66
(creator "[email protected]" create-time "20231119:12:40:38")]
[67
(creator "[email protected]" create-time "20231119:12:41:14")]
[65
(creator "[email protected]" create-time "20231119:12:40:26")]
[14
(creator "[email protected]" create-time "20230513:18:17:42")]
[15
(creator "[email protected]" create-time "20230513:18:17:42")]
[16
(creator "[email protected]" create-time "20230513:18:17:42")]
[31
(creator "[email protected]" create-time "20230513:19:08:35")]
[29
(creator "[email protected]" 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]