-
Notifications
You must be signed in to change notification settings - Fork 10
/
hyperbole.info
12727 lines (10830 loc) · 615 KB
/
hyperbole.info
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
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is hyperbole.info, produced by makeinfo version 6.5 from
hyperbole.texi.
This manual is for GNU Hyperbole (Edition 9.0.1, Published March, 2024).
Copyright (C) 1989-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation.
GNU Hyperbole software is distributed under the terms of the GNU
General Public License version 3 or later, as published by the Free
Software Foundation, Inc.
GNU Hyperbole is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY, without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details in the file,
"COPYING", within the Hyperbole package directory.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Hyperbole: (hyperbole). The Everyday Hypertextual Information Manager.
Use {C-h h d d} for a demonstration. GNU Hyperbole
offers context-sensitive mouse and keyboard keys that do the
right thing, a powerful contact manager, an advanced, auto-
numbered outliner with hyperlink anchors for each outline
cell, and easily editable and extensible hyperlink buttons,
even embeddable within mail and news messages.
END-INFO-DIR-ENTRY
File: hyperbole.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
GNU Hyperbole
*************
GNU Hyperbole
The Everyday Hypertextual Information Manager
Send any thanks in email to: <rsw@gnu.org>.
Copyright (C) 1989-2023 Free Software Foundation, Inc.
GNU Hyperbole is available for use, modification, and distribution
under the terms of the GNU General Public License (GPL) Version 3 or
later, as published by the Free Software Foundation, Inc., with all
rights and responsibilities thereof.
GNU Hyperbole is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY, without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Edition 9.0.1
March 10, 2024
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
E-mail: <hyperbole-users@gnu.org> (This is a mail list).
Web: www.gnu.org/software/hyperbole
[image src="im/hyperbole-cv.png" alt="Sample Hyperbole Screenshot" ]
Image 1: Sample Hyperbole screenshot of the Koutliner, DEMO file and
HyRolo
-------------
GNU Hyperbole was designed and written by Bob Weiner. *Note Setup::,
for information on how to obtain and to install Hyperbole.
This manual explains user operation and summarizes basic developer
facilities of GNU Hyperbole. Hyperbole provides convenient access to
information, control over its display and easy linking of items across
documents and across the web. The Hyperbole Koutliner offers flexible
views and structure manipulation within bodies of information.
We hope you enjoy using Hyperbole and that it improves your
productivity. If it does, consider sending us a quote or short note
discussing how it helps you. We may use your submission to help promote
further use of Hyperbole; all submissions will be considered freely
reusable and will fall under the same license as Hyperbole. E-mail your
quote to <hyperbole-users@gnu.org>. We volunteer our time on Hyperbole
and love to hear user stories in addition to any problem reports.
Before we delve into Hyperbole, a number of acknowledgments are in
order. Many thanks to Mats Lidell, a long-time Hyperbole user and
developer, who maintains Hyperbole with me and with whom I enjoy
interacting. Peter Wegner and Morris Moore encouraged the growth of
this work. Douglas Engelbart showed us the bigger picture and will
forever be an inspiration. His life-long quest at augmenting individual
and team capabilities represents a model from which we continue to draw.
Chris Nuzum has used Hyperbole since its inception, often demonstrating
its power in creative ways. The Koutliner is dedicated to my lovely
wife, Kathy.
* Menu:
* Introduction::
* Usage::
* Smart Keys::
* Buttons::
* Menus::
* HyControl::
* Koutliner::
* HyRolo::
* Window Configurations::
* Developing with Hyperbole::
* Glossary::
* Setup::
* Hyperbole Key Bindings::
* Koutliner Keys::
* Smart Key Reference::
* Suggestion or Bug Reporting::
* Questions and Answers::
* Future Work::
* References::
* Key Index::
* Function::
* Concept Index::
-- The Detailed Node Listing --
Introduction
* Manual Overview::
* Motivation::
* Hyperbole Overview::
* Mail Lists::
Usage
* Invocation::
* Documentation::
* Hyperbole Hooks::
Smart Keys
* Smart Key Bindings::
* Smart Key Operations::
* Smart Key Argument Selection::
* Smart Key Debugging::
* Smart Key Thing Selection::
* Smart Mouse Key Modeline Clicks::
* Smart Mouse Key Drags::
Smart Mouse Key Drags
* Creating and Deleting Windows::
* Saving and Restoring Window Configurations::
* Resizing Windows::
* Moving Frames::
* Dragging Buffers::
Dragging Buffers, Windows and Items
* Swapping Buffers::
* Displaying Buffers::
* Cloning Windows::
* Displaying Items::
* Keyboard Drags::
Buttons
* Explicit Buttons::
* Global Buttons::
* Implicit Buttons::
* Button Files::
* Action Types::
* Button Type Precedence::
* Utilizing Explicit Buttons::
Implicit Buttons
* Implicit Button Types::
* Action Buttons::
Utilizing Explicit Buttons
* Creation::
* Renaming::
* Deletion::
* Editing::
* Searching and Summarizing::
* Buttons in Mail::
* Buttons in News::
Creation
* By Menu::
* By Link:: Creation Via Buffer Link
* By Dragging:: Creation Via Assist Key Drags
Koutliner
* Menu Commands::
* Creating Outlines::
* Autonumbering::
* Idstamps::
* Editing Outlines::
* Viewing Outlines::
* Klinks::
* Cell Attributes::
* Koutliner History::
Editing Outlines
* Adding and Killing::
* Promoting and Demoting::
* Relocating and Copying::
* Moving Around::
* Filling::
* Transposing::
* Splitting and Appending::
* Inserting and Importing::
* Exporting::
Viewing Outlines
* Hiding and Showing::
* View Specs::
HyRolo
* HyRolo Concepts::
* HyRolo Menu::
* HyRolo Searching::
* HyRolo Keys::
* HyRolo Settings::
Developing with Hyperbole
* Hook Variables::
* Creating Types::
* Explicit Button Technicalities::
* Encapsulating Systems::
* Embedding Hyperbole::
Creating Types
* Creating Action Types::
* Creating Implicit Button Types::
Creating Implicit Button Types
* Action Button Link Types::
* Implicit Button Link Types::
* Programmatic Implicit Button Types::
Explicit Button Technicalities
* Button Label Normalization::
* Operational and Storage Formats::
* Programmatic Button Creation::
Setup
* Installation::
* Customization::
Installation
* Elpa Stable Package Installation::
* Elpa In-Development Package Installation::
* Git In-Development Package Installation::
* Manual Tarball Archive Installation::
Customization
* Referent Display::
* Internal Viewers::
* External Viewers::
* Link Variable Substitution::
* Web Search Engines::
* Using URLs with Find-File::
* Invisible Text Searches::
* Button Colors::
Hyperbole Key Bindings
* Binding Minibuffer Menu Items::
* Default Hyperbole Bindings::
* Testing::
Smart Key Reference
* Smart Mouse Keys::
* Smart Keyboard Keys::
Smart Mouse Keys
* Minibuffer Menu Activation::
* Thing Selection::
* Side-by-Side Window Resizing::
* Modeline Clicks and Drags::
* Smart Mouse Drags between Windows::
* Smart Mouse Drags within a Window::
* Smart Mouse Drags outside a Window::
Smart Keyboard Keys
* Smart Key - Company Mode::
* Smart Key - Org Mode::
* Smart Key - Ivy::
* Smart Key - Treemacs::
* Smart Key - Dired Sidebar Mode::
* Smart Key - ERT Results Mode::
* Smart Key - Emacs Pushbuttons::
* Smart Key - Argument Completion::
* Smart Key - ID Edit Mode::
* Smart Key - Emacs Cross-references (Xrefs)::
* Smart Key - Smart Scrolling::
* Smart Key - Smart Menus::
* Smart Key - Dired Mode::
* Smart Key - Hyperbole Buttons::
* Smart Key - View Mode::
* Smart Key - Helm Mode::
* Smart Key - Delimited Things::
* Smart Key - Occurrence Matches::
* Smart Key - The Koutliner::
* Smart Key - Flymake Mode::
* Smart Key - RDB Mode::
* Smart Key - Help Buffers::
* Smart Key - Custom Mode::
* Smart Key - Bookmark Mode::
* Smart Key - Pages Directory Mode::
* Smart Key - Python Source Code::
* Smart Key - C Source Code::
* Smart Key - C++ Source Code::
* Smart Key - Assembly Source Code::
* Smart Key - Lisp Source Code::
* Smart Key - Java Source Code::
* Smart Key - JavaScript Source Code::
* Smart Key - Objective-C Source Code::
* Smart Key - Fortran Source Code::
* Smart Key - Identifier Menu Mode ::
* Smart Key - Calendar Mode::
* Smart Key - Man Page Apropos::
* Smart Key - Emacs Outline Mode::
* Smart Key - Info Manuals::
* Smart Key - Email Readers::
* Smart Key - GNUS Newsreader::
* Smart Key - Buffer Menus::
* Smart Key - Tar File Mode::
* Smart Key - Man Pages::
* Smart Key - WWW URLs::
* Smart Key - HyRolo Match Buffers::
* Smart Key - Image Thumbnails::
* Smart Key - Gomoku Game::
* Smart Key - Magit Mode::
* Smart Key - The OO-Browser::
* Smart Key - Todotxt Mode::
* Smart Key - Default Context::
File: hyperbole.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
1 Introduction
**************
This edition of the GNU Hyperbole Manual is for use with any version
8.0.2pre or greater of GNU Hyperbole. Hyperbole runs atop GNU Emacs
27.1 or higher. It will trigger an error if your Emacs is older.
This chapter summarizes the structure of the rest of the manual,
describes Hyperbole, lists some of its potential applications, and
explains how to subscribe to its mail lists.
Throughout this manual, sequences of keystrokes are delimited by
curly braces '{ }'; function and variable names use this 'typeface'.
In brief, Hyperbole lets you:
* Quickly create typed hyperlink buttons either from the keyboard or
by dragging between a source and destination window with a mouse
button depressed. Activate Hyperbole buttons by pressing/clicking
on them or by name;
* Activate many kinds of _implicit buttons_ recognized by context
within text buffers, e.g. URLs, pathnames with section anchors,
grep output lines, and git commits. A single key, {M-<RET>}, or
mouse button automatically does the right thing in dozens of
contexts; just press and go;
* Build outlines with multi-level, numbered outline nodes, e.g.
1.4.8.6, that all renumber automatically when any cell (node) or
tree is moved in the outline. Each cell also has a permanent
hyperlink anchor that you can reference from any other cell;
* Manage all your contacts or record-based, unstructured texts
quickly with hierarchical categories; each entry can have embedded
hyperbuttons of any type. Or create an archive of documents with
hierarchical entries and use the same search mechanism to quickly
find any matching entry;
* Use single keys to easily manage your Emacs windows or frames and
quickly retrieve saved window and frame configurations;
* Search for things in your current buffers, in a directory tree or
across major web search engines with the touch of a few keys.
* Menu:
* Manual Overview::
* Motivation::
* Hyperbole Overview::
* Mail Lists::
File: hyperbole.info, Node: Manual Overview, Next: Motivation, Prev: Introduction, Up: Introduction
1.1 Manual Overview
===================
Hyperbole is an efficient, programmable hypertextual information
management system. It is intended for everyday work on any GNU Emacs
platform. Hyperbole allows hypertext buttons to be embedded within
unstructured and structured files, mail messages and news articles. It
offers intuitive keyboard and mouse-based control of information display
within multiple windows. It also provides point-and-click access to
Info manuals, ftp archives, and the World-Wide Web.
This is a reference manual with extensive details about Hyperbole
use. If you prefer a simpler, more interactive introduction to
Hyperbole, the 'FAST-DEMO' file included in the Hyperbole distribution
demonstrates many of Hyperbole's standard facilities without the need to
read through this reference manual. The 'FAST-DEMO' is a good way to
rapidly understand some of what Hyperbole can do for you. Once
Hyperbole is installed, (*note Setup::), you can access the 'FAST-DEMO'
with the key sequence {C-h h d d}.
*Note Glossary::, for definitions of Hyperbole terms. In some cases,
terms are not precisely defined within the body of this manual since
they are defined within the glossary. Be sure to reference the glossary
if a term is unclear to you. Although you need not have a keen
understanding of all of these terms, a quick scan of the glossary helps
throughout Hyperbole use.
*Note Setup::, for explanations of how to obtain, install, configure
and load Hyperbole for use. This appendix includes information on
user-level settings that you may want to modify after you understand
Hyperbole's basic operation.
*Note Suggestion or Bug Reporting::, for instructions on how to ask a
question, suggest a feature or report a bug in Hyperbole. A few
commonly asked questions are answered in this manual, *note Questions
and Answers::. If you are interested in classic articles on hypertext,
*note References::.
*Note Smart Keys::, for an explanation of the innovative,
context-sensitive mouse and keyboard Action and Assist Keys offered by
Hyperbole. *Note Smart Key Reference::, for a complete reference on
what the Action and Assist Keys do in each particular context they
recognize. *Note Smart Key Argument Selection::, for how Hyperbole
speeds selection of values when prompting for arguments.
Keep in mind as you read about using Hyperbole that in many cases, it
provides a number of overlapping interaction methods that support
differing work styles. In such instances, you need learn only one
technique that suits you.
*Note Buttons::, for an overview of Hyperbole buttons and how to use
them.
*Note Menus::, for summaries of Hyperbole menu commands and how to
use the minibuffer-based menus that work on any display that Emacs
supports.
*Note HyControl::, for how to quickly and interactively control what
your Emacs windows and frames display and where they appear.
*Note Koutliner::, for concept and usage information on the
autonumbered, hypertextual outliner. *Note Koutliner Keys::, for a full
summary of the outliner commands that are bound to keys.
*Note HyRolo::, for concept and usage information on the rapid
lookup, hierarchical, full-text record management system included with
Hyperbole.
*Note Window Configurations::, for instructions on how to save and
restore the set of buffers and windows that appear within a frame. This
feature lets you switch among working contexts easily, even on a dumb
terminal. Such configurations last throughout a single session of
editor usage only.
*Note Developing with Hyperbole::, if you are a developer who is
comfortable with Lisp.
*Note Future Work::, for future directions in Hyperbole's evolution.
File: hyperbole.info, Node: Motivation, Next: Hyperbole Overview, Prev: Manual Overview, Up: Introduction
1.2 Motivation
==============
Database vendors apply tremendous resources to help solve corporate
information management problems. But the information that people deal
with in their everyday worklife is seldom stored away in neatly defined
database schemas. Instead it is scattered among local and remote files,
e-mail messages, faxes, voice mail and web pages.
The rise of the web has demonstrated how hypertext technologies can
be used to build massive organized repositories of scattered
information. But assembling information for the web still remains a
great challenge and the data formats of the web are too structured to
deal with the wide variety of information that people process. Modern
web development requires the use of many languages: HTML, JavaScript,
and CSS. This in itself prevents its use as the prime means of
organizing and interlinking the constant flows of daily information.
GNU Hyperbole takes a distinctly different approach. It has its own
hypertext technology that can interface perfectly with web links but
which are much easier to create (simply drag from the source to the
destination of a link to create a new hyperlink). Hyperbole
hyperbuttons can link not only to static information but can perform
arbitrary actions (through the use of button types written in a single,
highly interactive language, Emacs Lisp). Hyperbole adds all of this
power to your written documents, e-mail, news articles, contact
management, outlines, directory listings, and much more. Hyperbole
works well with the very latest versions of GNU Emacs across every
editing and viewing mode in Emacs. It's core hypertext capabilities
operate as a global minor mode available across most file types, unlike
Org mode which is its own structured file format.
Unlock the power of GNU Hyperbole to make your information work for
you. One system. One language. One manual. One solution. Learn
Hyperbole and start moving further, faster.
File: hyperbole.info, Node: Hyperbole Overview, Next: Mail Lists, Prev: Motivation, Up: Introduction
1.3 Hyperbole Overview
======================
GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee), or just Hyperbole, is
like Markdown for hypertext. Hyperbole automatically recognizes dozens
of common, pre-existing patterns in any buffer regardless of mode and
can instantly activate them as hyperbuttons with a single key: email
addresses, URLs, grep -n outputs, programming backtraces, sequences of
Emacs keys, programming identifiers, Texinfo and Info cross-references,
Org links, Markdown links and on and on. All you do is load Hyperbole
and then your text comes to life with no extra effort or complex
formatting.
Hyperbole includes easy-to-use, powerful hypertextual button types
without the need to learn a markup language. Hyperbole's button types
are written in Lisp and can be wholly independent of the web, i.e. web
links are one type of Hyperbole link, not fundamental to its link
architecture. However, Hyperbole is a great assistant when editing HTML
or Javascript or when browsing web pages and links.
Hyperbole comes pre-built with most of the implicit button types you
will need but with a little extra effort and a few lines of code (or
even just a few words), you can define your own implicit button types to
recognize your specific buttons and then activate them anywhere in
Emacs. You press a single key, {M-<RET>} by default, on any kind of
Hyperbole button to activate it, so you can rely on your muscle memory
and let the computer do the hard work of figuring out what to do. {C-u
M-<RET>} shows you what any button will do in any context before you
activate it, so you can always be sure of what you are doing when needed
or if someone emails you a button (Hyperbole allows embedding buttons in
email messages too).
Hyperbole is something to be experienced and interacted with, not
understood from reading alone. It installs normally as a single Emacs
package with no dependencies outside of built-in Emacs libraries, *note
Installation::. Most of Hyperbole is a single global minor mode that
you can activate and deactivate at will. And it can be uninstalled
quickly as well if need be, so there is no risk in giving it a spin.
Once you have it installed, try the interactive demo with {C-h h d
d}. In fact, if you have Hyperbole loaded and you use the Emacs Info
reader to read this manual, you can press {M-<RET>} inside any of the
brace delimited series of keys you see in this document and Hyperbole
will execute them on-the-fly (easy keyboard-macro style buttons in any
text).
Hyperbole can dramatically increase your productivity and greatly
reduce the number of keyboard/mouse keys you'll need to work
efficiently.
Hyperbole consists of five parts.
_Buttons and Smart Keys_
There are three categories of buttons:
"explicit buttons"
may be added to documents with a simple drag between windows,
no markup language needed. With two windows on screen, an
explicit link button can be created at point in the current
buffer linking to the position in the other window's buffer by
pressing {C-h h e l}.
"Implicit buttons"
are patterns automatically recognized within existing text
that perform actions, e.g. bug#24568 displays the bug status
information for that Emacs bug number, without the need for
any additional markup. Implicit link buttons can be added to
documents with a simple drag between windows too.
Or from the keyboard, With two windows on screen, an implicit
link button can be created at point in the current buffer
linking to the position in the other window's buffer by
pressing {C-h h i l}. Use {M-1 C-h h i l} instead to be
prompted for a name for the implicit button.
"Global buttons"
are buttons that are activated by name from anywhere within
Emacs. They may be either explicit or named implicit buttons.
They are the named buttons stored in the a user's personal
button file, directly editable from the minibuffer menu with
{C-h h b p}.
With two windows on screen, a global explicit link button can
be created at point in the current buffer linking to the
position in the other window's buffer by pressing {C-h h g l}.
Use {C-u C-h h g l} instead to create a named global implicit
button.
Buttons are activated by pressing {M-<RET>} on them, clicking them
with a dedicated mouse button, or by referencing them by name
(global buttons that can be activated regardless of what is on
screen). Users create and activate Hyperbole buttons; *note
Buttons::. Emacs Lisp programmers can develop new button types and
actions. *Note Creating Types::.
Hyperbole includes two special "Smart Keys", the Action Key and the
Assist Key, that perform an extensive array of context-sensitive
operations across emacs usage, including activating and showing
help for Hyperbole buttons. In many popular Emacs modes, they
allow you to perform common, sometimes complex operations without
having to use a different key for each operation. Just press a
Smart Key and the right thing happens. The mouse versions of these
keys additionally allow for drag actions. We call these the Action
Mouse and Action Assist keys or buttons. *Note Smart Keys::.
_HyRolo_
a powerful, hierarchical contact manager which anyone can use, is
also included. It is easy to learn since it introduces only a few
new mechanisms and has a menu interface, which may be operated from
the keyboard or the mouse. It may also be used for full-text
searching over any record-based information in any number of Org,
Markdown, Koutline or Emacs Outline files. Hyperbole buttons may
be embedded in any records. *Note HyRolo::.
_HyControl_
the fastest, easiest-to-use window and frame control available for
GNU Emacs. With just a few keystrokes, you can shift from
increasing a window's height by 5 lines to moving a frame by 220
pixels or immediately moving it to a screen corner. Text in each
window or frame may be enlarged or shrunk (zoomed) for easy
viewing, plus many other features; this allows Hyperbole to quickly
control the way information is presented on-screen. *Note
HyControl::.
_Koutliner_
an advanced outliner with multi-level autonumbering and permanent
identifiers attached to each outline node for use as hypertext link
anchors, per node properties and flexible view specifications that
can be included in links or used interactively. *Note Koutliner::.
_Hyperbole API_
a set of programming libraries for system developers who want to
integrate Hyperbole with another user interface or as a back-end to
a distinct system. (All of Hyperbole is written in Emacs Lisp for
ease of modification. It has been engineered for real-world usage
and is well structured). *Note Developing with Hyperbole::.
Hyperbole may be used simply for browsing through documents
pre-configured with Hyperbole buttons, in which case, you can safely
ignore most of the information in this manual. Jump right into the
Hyperbole fast demonstration by typing {C-h h d d}, assuming Hyperbole
has been installed at your site. If you need to install Hyperbole,
*note Setup::, for Hyperbole installation and configuration information.
The demo offers a much less technical introduction to Hyperbole by
supplying good examples of use.
[image src="im/demo.png" alt="Hyperbole Minibuffer Menu and Demonstration Screenshot" ]
Image 1.1: Hyperbole Minibuffer Menu and Demonstration Screenshot
You likely will want to do more than browse with Hyperbole, e.g.
create your own buttons. The standard Hyperbole button editing user
interface is Emacs-based, so a basic familiarity with the Emacs editing
model is useful. The material covered in the Emacs tutorial, normally
bound to {C-h t}, is more than sufficient as background. *Note
(emacs)Glossary::, if some emacs-related terms are unfamiliar to you.
A Hyperbole user works with chunks of information that need to be
organized, interlinked, and processed. Such chunks can be hyperbuttons,
address book contacts, items in an outline, or even database query
results. Hyperbole does not enforce any particular hypertext or
information management model, but instead allows you to organize your
information in large or small chunks as you see fit. The Hyperbole
outliner organizes information into hierarchies which may also contain
links to external information sources. *Note Koutliner::.
Some of Hyperbole's most significant features are:
* Buttons may link to information or may execute functions, such as
starting or communicating with external programs;
* A simple mouse drag from a button source location to its link
destination is often all that is needed to create a new link. The
keyboard can also be used to emulate such drags;
* Buttons may be embedded within electronic mail messages;
* Outlines allow rapid browsing, editing and movement of chunks of
information organized into trees (hierarchies);
* Other hypertext and information retrieval systems may be
encapsulated under a Hyperbole user interface (a number of samples
are provided).
Typical Hyperbole applications include:
_personal information management_
Hyperlinks provide a variety of views into an information space. A
search facility locates hyperbuttons in context and permits quick
selection.
_documentation and code browsing_
Cross-references may be embedded within documentation and code.
Existing documentation may be augmented with point-and-click
interfaces to link code with associated design documents, or to
permit direct access to the definition of identifiers by selecting
their names within code or other documents.
_brainstorming_
The Hyperbole outliner (*note Koutliner::) is an effective tool for
capturing ideas and then quickly reorganizing them in a meaningful
way. Links to related ideas are easy to create so the need to copy
and paste information is greatly reduced.
_help/training systems_
Tutorials with buttons can show students how things work while
explaining the concepts, e.g. an introduction to the commands
available on a computer system. This technique can be much more
effective than written documentation alone.
_archive managers_
Programs that manage archives from incoming information streams may
be supplemented by having them add topic-based buttons that link to
the archive holdings. Users can then search and create their own
links to archive entries.
File: hyperbole.info, Node: Mail Lists, Prev: Hyperbole Overview, Up: Introduction
1.4 Mail Lists
==============
If you use Hyperbole, you may join the mailing list
<hyperbole-users@gnu.org> to discuss Hyperbole with users and
maintainers. There is a separate mail list to report problems or bugs
with Hyperbole, <bug-hyperbole@gnu.org>. For more details, *note
Suggestion or Bug Reporting::.
File: hyperbole.info, Node: Usage, Next: Smart Keys, Prev: Introduction, Up: Top
2 Usage
*******
Once Hyperbole has been installed for use at your site, loaded into your
Emacs session and activated with '(hyperbole-mode 1)', it is ready for
use. You will see a Hyperbole menu on your menubar and 'Hypb' in your
modeline.
* Menu:
* Invocation::
* Documentation::
* Hyperbole Hooks::
File: hyperbole.info, Node: Invocation, Next: Documentation, Prev: Usage, Up: Usage
2.1 Invocation
==============
You can invoke Hyperbole's commands in one of three ways:
* use the Hyperbole entry on your menubar;
* type {C-h h} or {M-x hyperbole <RET>} to display the Hyperbole
minibuffer menu;
* use a specific Hyperbole command, for example, a press of {M-<RET>}
on a pathname to display the associated file or directory.
{C-h h} enables Hyperbole if it has been disabled and displays a
Hyperbole menu in the minibuffer for quick keyboard or mouse-based
selection. Select an item from this menu by typing the item's first
capital letter. Use {Q} (note this is capitalized) to quit from the
minibuffer menu while leaving Hyperbole enabled. Use {X} (note this is
capitalized) to quit from the minibuffer menu and disable Hyperbole's
minor mode.
Use {C-h h d d} for an interactive demonstration of standard
Hyperbole button capabilities.
Type {C-h h k e} for an interactive demonstration of the Koutliner,
Hyperbole's multi-level autonumbered hypertextual outliner.
To try out HyControl, Hyperbole's interactive frame and window
control system, use {C-h h s w} for window control or {C-h h s f} for
frame control. Pressing {t} switches between window and frame control
once in HyControl. Hyperbole also binds {C-c \} for quick access to
HyControl's window control menu if it was not already bound prior to
Hyperbole's initialization.
Videos demonstrating Hyperbole's features are listed at
<https://gnu.org/s/hyperbole>.
The above are the best interactive ways to learn about Hyperbole.
File: hyperbole.info, Node: Documentation, Next: Hyperbole Hooks, Prev: Invocation, Up: Usage
2.2 Documentation
=================
The Hyperbole Manual is a reference manual, not a simple introduction.
It is included in the 'man/' subdirectory of the Hyperbole package
directory in four forms:
man/hyperbole.info - online Info browser version
man/hyperbole.html - web HTML version
man/hyperbole.pdf - printable version
man/hyperbole.texi - source form
The Hyperbole package installation places the Info version of this
manual where needed and adds an entry for Hyperbole into the Info
directory under the Emacs category. {C-h h d i} will let you browse the
manual. Then use {s} to search for anything throughout the manual. For
web browsing, point your browser to '${hyperb:dir}/man/hyperbole.html',
wherever the Hyperbole package directory is on your system; often this
is: '~/.emacs.d/elpa/hyperbole-${hyperb:version}/'.
File: hyperbole.info, Node: Hyperbole Hooks, Prev: Documentation, Up: Usage
2.3 Hyperbole Hooks
===================
When Hyperbole's code is first loaded and initialized,
'hyperbole-init-hook' is run. When 'hyperbole-mode' is enabled,
'hyperbole-mode-hook' and 'hyperbole-mode-on-hook' are run. When
'hyperbole-mode' is disabled, 'hyperbole-mode-hook' and
hyperbole-mode-off-hook are run.
If you prefer a different key to activate Hyperbole, you can 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 "\C-ch" 'hyperbole--enable-mode) (global-set-key
"\C-hh" 'view-hello-file)))'; then restart Emacs.
File: hyperbole.info, Node: Smart Keys, Next: Buttons, Prev: Usage, Up: Top
3 Smart Keys
************
When active, Hyperbole offers two special "Smart Keys", the Action Key
and the Assist Key, that perform an extensive array of context-sensitive
operations across emacs usage. In many Emacs modes, they allow you to
perform common, sometimes complex operations without having to use a
different key for each operation. Just press a Smart Key and the right
thing happens. This chapter explains typical uses of the Smart Keys.
*Note Smart Key Reference::, for complete descriptions of their behavior
in all contexts.
* Menu:
* Smart Key Bindings::
* Smart Key Operations::
* Smart Key Argument Selection::
* Smart Key Debugging::
* Smart Key Thing Selection::
* Smart Mouse Key Modeline Clicks::
* Smart Mouse Key Drags::
File: hyperbole.info, Node: Smart Key Bindings, Next: Smart Key Operations, Prev: Smart Keys, Up: Smart Keys
3.1 Smart Key Bindings
======================
With 'hyperbole-mode' enabled, {M-<RET>} is the Action Key and {C-u
M-<RET>} is the Assist Key. These keys allow context-sensitive
operation from any keyboard.
Mouse configuration of the Smart Keys is automatic for GNU Emacs
under Mac OS X, the X Window System and MS Windows, assuming your emacs
program has been built with support for any of these window systems.
The "Action Mouse Key" is bound to your shift-middle mouse key (or
shift-left on a 2-button mouse). The "Assist Mouse Key" is bound to
your shift-right mouse key, assuming Hyperbole is run under an external
window system. These keys support "Drag Actions", *note Smart Mouse
Keys::, as well as the standard Smart Key presses.
If you set the variable, 'hmouse-middle-flag', to 't' before loading
Hyperbole, then you may also use the middle mouse key as the Action Key.
If you want both the middle mouse key as the Action Key and the right
mouse key as the Assist Key for ease of use, then within your personal
'~/.emacs' file, add: '(add-hook 'hyperbole-init-hook
'hmouse-add-unshifted-smart-keys)' and then restart Emacs.
If you prefer other Smart Key bindings, simply bind the commands
'action-key' and 'assist-key' to keyboard keys. Hyperbole binds
{M-<RET>} to the command 'hkey-either'; this provides a single key
binding for both Smart Key commands; a prefix argument, such as {C-u},
then invokes 'assist-key' actions.
You may also bind 'action-mouse-key' and 'assist-mouse-key' to other
mouse keys, though you won't be able to execute mouse drag actions with
such key bindings. *Note Smart Mouse Key Drags::, and *note Keyboard
Drags::.
To permanently change any of these key bindings, use: '(add-hook
'hyperbole-init-hook (lambda () (hkey-set-key <KEY> '<CMD>)', for
example, '(hkey-set-key "\M-'" 'hkey-either)'.
File: hyperbole.info, Node: Smart Key Operations, Next: Smart Key Argument Selection, Prev: Smart Key Bindings, Up: Smart Keys
3.2 Smart Key Operations
========================
The Action Key generally selects entities, creates links and activates
buttons. The Assist Key generally provides help, such as reporting on a
button's attributes, or serves a complementary function to whatever the
Action Key does within a context.
The Hyperbole Doc/SmartKeys menu entry, {C-h h d s}, displays a
summary of what the Smart Keys do in all of their different contexts.
Alternatively, a click of the Assist Mouse Key in the right corner of a
window modeline (within the rightmost 3 characters) toggles between
displaying this summary and hiding it. Reference this summary whenever
you need it.
The following table is the same summary. Much of the browsing power
of Hyperbole comes from the use of the Smart Keys, so spend some time
practicing how to use them. Study what modeline clicks and window drag
actions do as these will give you a lot of power without much effort.
This table may appear daunting at first, but as you practice and notice
that the Smart Keys do just a few context-sensitive things per editor
mode, you will find it easy to just press or point and click and let
Hyperbole do the right thing in each context.
========================================================================================
Smart Keys
Context Action Key Assist Key
========================================================================================
Hyperbole
On a minibuffer menu item Activates item Item help
On an explicit button Activates button Button help
Reading argument
1st press at an arg value Copies value to minibuffer <- same
2nd press at an arg value Uses value as argument <- same
In minibuffer at eol Accepts minibuffer arg List completions
In minibuffer before eol Deletes rest of arg Deletes rest of arg
On an implicit button/path Activates button Button help
Within a koutline cell Collapses and expands Shows tree props
Left of a koutline cell Creates a klink Moves a tree
HyRolo Match Buffer Edits entries and mails to e-mail addresses
Mouse or Keyboard Display Control
Line end, not end of buffer
smart-scroll-proportional
= t (default) Makes curr line top line Bottom line
= nil Scrolls up a windowful Scrolls down
End of Any Help buffer Restores screen to the previous state
Read-only View Mode Scrolls up a windowful Scrolls wind down
Mouse-only Control
Drag from thing start or end Yanks thing at release Kills thing and yanks
A thing is a delimited at release
expression, such as a
string, list or markup
language tag pair
Drag from bottom Modeline Repositions frame as <- same
in frame with non-nil drag happens
drag-with-mode-line param
Drag from shared window side
or from left of scroll bar Resizes window width <- same