-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathhyperbole.texi
12490 lines (10674 loc) · 467 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: 19-Jan-25 at 18:06:31 by Bob Weiner
@c %**start of header (This is for running Texinfo on a region.)
@setfilename hyperbole.info
@ifnothtml
@settitle GNU Hyperbole Manual
@end ifnothtml
@c %**end of header (This is for running Texinfo on a region.)
@set FONT-SIZE 16
@set WIDTH 100%
@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
@set UPDATED January, 2025
@set UPDATED-MONTH January 2025
@set EDITION 9.0.2pre
@set VERSION 9.0.2pre
@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
@c In PDF output, like Info output, display only the label of an @uref
@c or @url link when given.
@tex
\global\urefurlonlylinktrue
@end tex
@copying
This manual is for GNU Hyperbole
(Edition @value{EDITION}, Published @value{UPDATED}).
Copyright @copyright{} 1989-2025 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 @bkbd{C-h h d d} for a demonstration. GNU Hyperbole offers
context-sensitive mouse and keyboard keys that do the right
thing, an Org-based Wiki generator with auto-wikiword
highlighting, 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)
@top GNU Hyperbole
@c @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-2025 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 9.0.2pre
Printed January 19, 2025.
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-2025 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 9.0.2pre
January 19, 2025
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::
* HyWiki::
* HyNote::
* 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 Index::
* 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 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
HyWiki
* HyWikiWords::
* Publish HyWiki::
* HyWiki Menu::
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::
* Highlight Menu Key Toggle::
* 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 - ERT Results 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::
@end detailmenu
@end menu
@node Introduction, Usage, Top, Top
@chapter Introduction
This edition of the GNU Hyperbole Manual is for use with any version
9.0.2pre or greater of GNU Hyperbole. Hyperbole runs atop GNU Emacs 27.2
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 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;
@item
Activate many kinds of @emph{implicit buttons} recognized by context
within text buffers, e.g. URLs, pathnames with section anchors, grep
output lines, and git commits. A single key, @bkbd{M-@key{RET}}, 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 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;
@item
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;
@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
keyboard and mouse-based control of information display within multiple
windows. It also provides point-and-click access to Info manuals, ftp
archives, the World-Wide Web and much more.
@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 @file{../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
@file{../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 they recognize. @xref{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.
@xref{Buttons}, for an overview of Hyperbole buttons and how to use
them. Hyperbole's action-oriented button support is enabled via the
global minor mode, @code{hyperbole-mode}.
@xref{Menus}, for summaries of Hyperbole menu commands and how to use
the minibuffer-based menus that work on any display that Emacs supports.
@xref{HyWiki}, for Hyperbole's markup-free, personal Wiki system for
note-taking and automatic WikiWord highlighting and hyperlinking. It
extends Org mode. HyWikiWord hyperlink buttons are automatically
enabled for wiki pages below @code{hywiki-directory}. To enable them
in text buffers outside of this directory, enable the global minor
mode, @code{hywiki-mode}.
@xref{HyNote}, for a start on the very early stages of Hyperbole's
multi-format note taking system. HyNote supports Org, Markdown,
Koutline and Emacs Outline file formats. HyNote works in any buffer
where HyWiki support is active.
@xref{HyControl}, for how to quickly and interactively control what your
Emacs windows and frames display and where they appear.
@xref{Koutliner}, for concept and usage information on the
autonumbered, hypertextual outliner. It uses its own major mode.
@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, full-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 throughout a single session of editor
usage only.
@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 de`al 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.
@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 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, @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 in 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 and you use the Emacs Info reader to
read this manual, 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
There are three categories of buttons:
@table @dfn
@item 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 @bkbd{C-h h e l}.
@item 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 @bkbd{C-h h i l}. Use @bkbd{M-1
C-h h i l} instead to be prompted for a name for the implicit button.
@item 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 @bkbd{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 @bkbd{C-h h g l}. Use @bkbd{C-u C-h h g l} instead to
create a named global implicit button.
@end table
Buttons are activated by pressing @bkbd{M-@key{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; @pxref{Buttons}. Emacs Lisp
programmers can develop new button types and actions. @xref{Creating
Types}.
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. The
mouse versions of these keys additionally allow for drag actions. We
call these the Action Mouse and Action Assist keys or buttons. @xref{Smart
Keys}.
@item 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. @xref{HyRolo}.
@item 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. @xref{HyControl}.
@item 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. @xref{Koutliner}.
@item 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). @xref{Developing
with Hyperbole}.
@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