forked from rswgnu/hyperbole
-
Notifications
You must be signed in to change notification settings - Fork 0
/
hyperbole.texi
11202 lines (9564 loc) · 419 KB
/
hyperbole.texi
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
\input texinfo @c -*- coding: utf-8 -*-
@c $Id$
@c hyperbole.texi --- The GNU Hyperbole Manual
@c Usage: Hardcopy man from TeX; Info man from `texinfo-format-buffer'.
@c
@c Author: Bob Weiner
@c
@c Orig-Date: 6-Nov-91 at 11:18:03
@c Last-Mod: 3-Dec-22 at 02:35:10 by Bob Weiner
@c %**start of header (This is for running Texinfo on a region.)
@setfilename hyperbole.info
@settitle GNU Hyperbole Manual
@c %**end of header (This is for running Texinfo on a region.)
@c Emacs documentation style settings
@c @documentencoding UTF-8
@c These two require Texinfo 5.0 or later, so we use the older
@c equivalent @set variables supported in 4.11 and hence.
@ignore
@codequotebacktick on
@codequoteundirected on
@end ignore
@set txicodequoteundirected
@set txicodequotebacktick
@include version.texi
@ifnotinfo
@macro bkbd {arg}
@kbd{@{\arg\@}}
@end macro
@end ifnotinfo
@ifinfo
@macro bkbd {arg}
@t{@{\arg\@}}
@end macro
@end ifinfo
@macro kitem {key}
@kindex \key\
@item @bkbd{\key\}
@end macro
@macro kitemx {key}
@kindex \key\
@itemx @bkbd{\key\}
@end macro
@copying
This manual is for GNU Hyperbole
(Edition @value{EDITION}, Published @value{UPDATED}).
Copyright @copyright{} 1989-2022 Free Software Foundation, Inc.
@quotation
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.
@sp 1
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.
@sp 1
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.
@sp 1
See the GNU General Public License for more details in the file,
``COPYING'', within the Hyperbole package directory.
@end quotation
@end copying
@dircategory Emacs
@direntry
* 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 direntry
@c
@c Comment the @set smallbook line out if you want to print on letter sized paper.
@c Smallbook formats for 7x9.25 inch book-sized printing.
@c @set smallbook
@ifset smallbook
@smallbook
@end ifset
@synindex vr fn
@iftex
@kbdinputstyle code
@end iftex
@titlepage
@sp 6
@title GNU Hyperbole Manual
@sp 1
@subtitle The Everyday Hypertextual Information Manager
@sp 1
@center @image{im/hyperbole-cv,4in,,Sample Hyperbole Screenshot}
@author Bob Weiner
@page
@vskip 0pt plus 1filll
@insertcopying
@sp 2
@example
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
@end example
@sp 2
The body of the manual was written in Emacs and laid out using the GNU
Texinfo markup language.
@end titlepage
@summarycontents
@contents
@c @setchapternewpage odd
@node Top, Introduction, (dir), (dir)
@unnumbered GNU Hyperbole
@ifhtml
@html
<CENTER><H1>GNU Hyperbole</H1></CENTER>
<CENTER><H2>The Everyday Hypertextual Information Manager</H2></CENTER>
<CENTER><H3><A HREF="mailto:rsw@@gnu.org">Say thanks or send a testimonial if you like Hyperbole.</A></H3></CENTER>
<P>Copyright © 1989-2022 Free Software Foundation, Inc.</P>
<P>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, with all rights and
responsibilities thereof.</P>
<P>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.</P>
<PRE>
Edition 8.0.1pre
Printed December 3, 2022.
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
</PRE>
<CENTER>
<DT><B>Screenshot of the Hyperbole Koutliner, Demonstration and HyRolo</B></DT><BR><BR>
<IMG NAME="Hyperbole Screenshot" SRC="im/hyperbole-cv.png"><BR>
</CENTER>
@end html
@sp 1
@center --------------------
@sp 1
@end ifhtml
@ifinfo
@center GNU Hyperbole
@center The Everyday Hypertextual Information Manager
@center Send any thanks in email to: <rsw@@gnu.org>.
@sp 2
@noindent
Copyright @copyright{} 1989-2022 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.
@sp 2
@example
Edition 8.0.1pre
December 3, 2022
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
@end example
@float Image,image:Sample
@caption{Sample Hyperbole screenshot of the Koutliner, DEMO file and HyRolo}
@image{im/hyperbole-cv,6in,,Sample Hyperbole Screenshot}
@end float
@sp 1
@center --------------------
@sp 1
@end ifinfo
@cindex credits
@cindex Hyperbole, obtaining
@cindex anonymous ftp
GNU Hyperbole was designed and written by Bob Weiner.
@xref{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::
@detailmenu
--- 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 File and Buffer 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 Dragging:: Creation Via Action Key Drags
* By Menu:: Creation Via Menus
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 - 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 - The Koutliner::
* 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 - Identifier Menu Mode ::
* 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 - Occurrence Matches::
* 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::
@end detailmenu
@end menu
@node Introduction, Usage, Top, Top
@chapter Introduction
This edition of the GNU Hyperbole Manual is for use with any version
8.0.1pre 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 @kbd{@{ @}}, function and variable names use this @code{typeface}.
@noindent
In brief, Hyperbole lets you:
@itemize @bullet
@item
Quickly create hyperlink buttons either from the keyboard or by dragging
between a source and destination window with a mouse button depressed.
Later, activate buttons by pressing/clicking on them or by giving the name
of the button.
@item
Activate many kinds of @emph{implicit buttons} recognized by context within
text buffers, e.g. URLs, grep output lines, and git commits. A single key
or mouse button automatically does the right thing in dozens of contexts;
just press and go.
@item
Build outlines with multi-level numbered outline nodes, e.g. 1.4.8.6, that
all renumber automatically as any node or tree is moved in the outline.
Each node also has a permanent hyperlink anchor that you can reference
from any other node;
@item
Manage all your contacts or record-based, unstructured nodes 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;
@item
Use single keys to easily manage your Emacs windows or frames and quickly
retrieve saved window and frame configurations;
@item
Search for things in your current buffers, in a directory tree or across
major web search engines with the touch of a few keys.
@end itemize
@menu
* Manual Overview::
* Motivation::
* Hyperbole Overview::
* Mail Lists::
@end menu
@node Manual Overview, Motivation, Introduction, Introduction
@section 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 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 (WWW).
@cindex file, FAST-DEMO
@cindex Hyperbole demo
@cindex demo file
@cindex tutorial
This is a reference manual with extensive details about Hyperbole use. If
you prefer a simpler, more interactive introduction to Hyperbole,
the @file{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,
(@pxref{Setup}), you can access the FAST-DEMO with the key sequence @bkbd{C-h h
d d}.
@xref{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.
@xref{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.
@xref{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, @pxref{Questions
and Answers}. If you are interested in classic
articles on hypertext, @pxref{References}.
@xref{Smart Keys}, for an explanation of the innovative, context-sensitive
mouse and keyboard Action and Assist Keys offered by Hyperbole.
@xref{Smart Key Reference}, for a complete reference on what the Action
and Assist Keys do in each particular context that they recognize.
@xref{Smart Key Argument Selection}, for how Hyperbole speeds selection of
prompted 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 and hardware limitations. In such instances, you need learn
only one technique that suits you.
@xref{Buttons}, for an overview of Hyperbole buttons and how to use them.
@xref{Menus}, for summaries of Hyperbole menu commands and how to use
the minibuffer-based menus that work on dumb terminals, PCs or workstations.
@xref{HyControl}, for how to quickly and interactively control your Emacs
windows and frames and what they display.
@xref{Koutliner}, for concept and usage information on the
autonumbered, hypertextual outliner. @xref{Koutliner Keys}, for a full
summary of the outliner commands that are bound to keys.
@xref{HyRolo}, for concept and usage information on the
rapid lookup, hierarchical, free text record management system included
with Hyperbole.
@xref{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 only throughout a single session of editor
usage.
@xref{Developing with Hyperbole}, if you are a developer who is
comfortable with Lisp.
@xref{Future Work}, for future directions in Hyperbole's evolution.
@node Motivation, Hyperbole Overview, Manual Overview, Introduction
@section 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 great 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.
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.
@node Hyperbole Overview, Mail Lists, Motivation, Introduction
@section Hyperbole Overview
@cindex GNU Hyperbole
@cindex Hyperbole
@cindex hypertext
@cindex Emacs Lisp
@cindex Emacs
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, @bkbd{M-@key{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. @bkbd{C-u
M-@key{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 some emails you a button (you can do that 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 standard Emacs libraries, @pxref{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 to giving it a spin.
Once you have it installed, try the interactive demo with @bkbd{C-h h d d}.
In fact, if you have Hyperbole loaded, you can press @bkbd{M-@key{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.
@page
@noindent
Hyperbole consists of five parts:
@table @emph
@item Buttons and Smart Keys
Hyperbole hyperlink and other kinds of buttons @dfn{explicit buttons} may
be added to documents with a simple drag between windows, no markup
language needed. @dfn{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. @dfn{Global buttons} are buttons that are
activated by name from anywhere within Emacs. @xref{Buttons}.
Buttons are accessed by clicking on them or referenced by name (global
buttons), so they can be activated regardless of what is on screen.
Users create and activate Hyperbole buttons; Emacs Lisp programmers
easily can develop new button types and actions.
Hyperbole includes two special @dfn{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. @xref{Smart Keys}.
@item Contact and Text Finder
an interactive, textual information management interface, including
fast, flexible file and text finding commands. A powerful, hierarchical
contact manager, @pxref{HyRolo}, 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 to look up any record-based information and
Hyperbole buttons may be embedded in any records;
@item Screen Control
the fastest, easiest-to-use window and frame control available for GNU
Emacs, @pxref{HyControl}. 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;
@item Hypertextual Outliner
an advanced outliner, @pxref{Koutliner}, 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;
@item Programming Library
a set of programming libraries, @pxref{Developing with Hyperbole}, 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).
@end table
@kindex C-h h d d
@vindex file, FAST-DEMO
@cindex demonstration
@cindex button demo
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 @bkbd{C-h h d d}, assuming Hyperbole
has been installed at your site. If you need to install
Hyperbole, @pxref{Setup}, for Hyperbole installation and configuration
information. The demo offers a much less technical introduction to
Hyperbole by supplying good examples of use.
@float Image,image:Demo
@caption{Hyperbole Minibuffer Menu and Demonstration Screenshot}
@image{im/demo,6in,,Hyperbole Minibuffer Menu and Demonstration Screenshot}
@end float
@sp 1
@cindex GNU Emacs
@kindex C-h t
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 @bkbd{C-h t}, is more than
sufficient as background. @xref{Glossary,,,emacs,the GNU Emacs Manual},
if some emacs-related terms are unfamiliar to you.
@cindex Hyperbole features
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. @xref{Koutliner}.
@noindent
Some of Hyperbole's most significant features are:
@itemize @bullet
@item
Buttons may link to information or may execute functions, such as
starting or communicating with external programs;
@item
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;
@item
Buttons may be embedded within electronic mail messages;
@item
Outlines allow rapid browsing, editing and movement of chunks of
information organized into trees (hierarchies);
@item
Other hypertext and information retrieval systems may be encapsulated
under a Hyperbole user interface (a number of samples are provided).
@end itemize
@cindex Hyperbole applications
@noindent
Typical Hyperbole applications include:
@table @emph
@item personal information management
Hyperlinks provide a variety of views into an information space. A
search facility locates hyperbuttons in context and permits quick
selection.
@item 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.
@item brainstorming
The Hyperbole outliner (@pxref{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.
@item 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.
@item 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.
@end table
@node Mail Lists, , Hyperbole Overview, Introduction
@section 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,
@pxref{Suggestion or Bug Reporting}.
@node Usage, Smart Keys, Introduction, Top
@chapter Usage
Once Hyperbole has been installed for use at your site, loaded into your
Emacs session and activated with @code{(hyperbole-mode 1)}, it is ready
for use. You will see a Hyperbole menu on your menubar and @code{Hypb} in
your modeline.
@menu
* Invocation::
* Documentation::
* Hyperbole Hooks::
@end menu
@node Invocation, Documentation, Usage, Usage
@section Invocation
@noindent
You can invoke Hyperbole's commands in one of three ways:
@itemize @bullet
@item use the Hyperbole entry on your menubar;
@findex hyperbole
@item type @bkbd{C-h h} or @bkbd{M-x hyperbole @key{RET}} to display the Hyperbole minibuffer menu;
@item use a specific Hyperbole command, for example, a press of @bkbd{M-@key{RET}}
on a pathname to display the associated file or directory.
@end itemize
@vindex file, .emacs
@cindex hyperbole-mode
@cindex minor mode, hyperbole
@cindex change key bindings
@cindex toggle key bindings
@cindex key bindings, toggle
@cindex enable Hyperbole
@cindex disable Hyperbole
@cindex Hyperbole minibuffer menu
@kindex C-h h
@kindex C-h h X
@kindex C-h h q
@bkbd{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 @bkbd{q} to quit from the minibuffer menu while leaving Hyperbole enabled.
Use@bkbd{X} (note this is capitalized) to quit from the minibuffer menu
and disable Hyperbole minor mode.
Use @bkbd{C-h h d d} for an interactive demonstration of standard Hyperbole
button capabilities.
Type @bkbd{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 @bkbd{C-h h s w} for window control or @bkbd{C-h h s f} for
frame control. Pressing @bkbd{t} switches between window and frame
control once in HyControl. Hyperbole also binds @bkbd{C-c \\} for quick
access to HyControl's window control menu if it was not already bound
prior to Hyperbole's initialization.
A long video demonstrating most of HyControl's features is available at
@url{https://youtu.be/M3-aMh1ccJk}.
The above are the best interactive ways to learn about Hyperbole.
@node Documentation, Hyperbole Hooks, Invocation, Usage
@section Documentation
@vindex Info-directory-list
@vindex hyperb:dir
@cindex Hyperbole manual
@noindent
The Hyperbole Manual is a reference manual, not a simple introduction.
It is included in the @file{man/} subdirectory of the Hyperbole package
directory in four forms:
@cindex Info manual
@cindex Texinfo manual
@vindex file, man/hyperbole.info
@vindex file, man/hyperbole.html
@vindex file, man/hyperbole.pdf
@vindex file, man/hyperbole.texi
@example
@file{man/hyperbole.info} - online Info browser version
@file{man/hyperbole.html} - web HTML version
@file{man/hyperbole.pdf} - printable version
@file{man/hyperbole.texi} - source form
@end example
@kindex C-h h d i
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. @bkbd{C-h h d i} will let you
browse the manual. Then use @bkbd{s} to search for anything
throughout the manual. For web browsing, point your browser
to @file{@code{$@{hyperb:dir@}}/man/hyperbole.html}, wherever the
Hyperbole package directory is on your system; often this