1 \input texinfo @c -*-texinfo-*-
4 @comment %**start of header (This is for running Texinfo on a region.)
5 @setfilename hyperbole.info
6 @settitle Hyperbole User Manual
7 @comment %**end of header (This is for running Texinfo on a region.)
12 This manual is for GNU Hyperbole
13 (version @value{VERSION}, @value{UPDATED}).
15 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 2004, 2005, 2006 Free Software Foundation, Inc.
17 All trademarks referenced herein are trademarks of their respective
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.1 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
25 and with the Back-Cover Texts as in (a) below. A copy of the
26 license is included in the section entitled ``GNU Free Documentation
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software. Copies published by the Free
31 Software Foundation raise funds for GNU development.''
43 @center @titlefont{Hyperbole Manual}
45 @center Everyday Information Management
47 @center E-mail: <hyperbole-users@@gnu.org> (This is a mail list.)
54 @vskip 0pt plus 1filll
56 @setchapternewpage odd
60 @node Top, Introduction, (dir), (dir)
61 @c node-name, next, previous, up
67 @cindex InfoDock, obtaining
68 @cindex Hyperbole, obtaining
70 Hyperbole was designed and written by Bob Weiner. Motorola,
71 Inc@. funded and donated this work for free redistribution as part of
72 the InfoDock integrated software engineering and productivity toolset.
73 For information on how to obtain Hyperbole, @ref{Obtaining}.
75 This manual explains user operation and summarizes basic developer
76 facilities of Hyperbole. This major release of Hyperbole concentrates
77 on providing convenient access to information and control over its
78 display. The Hyperbole outliner emphasizes flexible views and structure
79 manipulation within bodies of information.
88 Hyperbole (pronounced Hi-purr-boe-lee) is an open, efficient,
89 programmable information management and hypertext system. It is
90 intended for everyday work on any UNIX platform supported by GNU Emacs.
91 It works well with the versions of Emacs that support multiple X or
92 NEXTSTEP windows: Emacs 19, XEmacs (formerly called Lucid Emacs) and
93 Epoch. Hyperbole allows hypertext buttons to be embedded within
94 unstructured and structured files, mail messages and news articles. It
95 offers intuitive mouse-based control of information display within
96 multiple windows. It also provides point-and-click access to Info
97 manuals, ftp archives, Wide-Area Information Servers (WAIS), and the
98 World-Wide Web (WWW) hypertext system through encapsulations of software
99 that support these protocols.
102 Hyperbole consists of four parts:
105 @item Info Management
106 an interactive information management interface, including a powerful
107 rolodex, which anyone can use. It is easy to pick up and use since it
108 introduces only a few new mechanisms and provides user-level facilities
109 through a menu interface, which you control from the keyboard or the
112 @item Hypertext Outliner
113 an outliner with multi-level autonumbering and permanent ids attached to
114 each outline node for use as hypertext link anchors, plus flexible view
115 specifications that can be embedded within links or used interactively;
118 a set of hyper-button types that provides core hypertext and other
119 behaviors. Users can make simple changes to button types and those
120 familiar with Emacs Lisp can quickly prototype and deliver new types;
122 @item Programming Library
123 a set of programming library classes for system developers who want to
124 integrate Hyperbole with another user interface or as a back-end to a
125 distinct system. (All of Hyperbole is written in Emacs Lisp for ease of
126 modification. Although Hyperbole was initially designed as a prototype,
127 it has been engineered for real-world usage and is well structured.)
133 @cindex demonstration
135 Hyperbole may be used simply for browsing through documents
136 pre-configured with Hyperbole buttons, in which case, one can safely
137 ignore most of the information in this manual. The @file{DEMO} file
138 included in the Hyperbole distribution demonstrates many of Hyperbole's
139 standard facilities. It offers a much less technical introduction for
140 Hyperbole users by providing good examples of how buttons may be
141 used and an introduction to the outliner.
143 So if this manual is too detailed for your taste, you can skip it
144 entirely and just jump right into the demonstration, normally by typing
145 @{@kbd{C-h h d d}@}, assuming Hyperbole has already been installed at
146 your site. Otherwise, @ref{Installation}, for Hyperbole installation
147 and configuration information.
149 Many users, however, will want to do more than browse with Hyperbole,
150 e.g@. create their own buttons. The standard Hyperbole button editing
151 user interface is GNU Emacs-based, so a basic familiarity with the Emacs
152 editing model is useful. The material covered in the GNU Emacs
153 tutorial, normally bound to @{@kbd{C-h t}@} within Emacs, is more than
154 sufficient as background. If some GNU Emacs terms are unfamiliar to
155 you, @ref{Glossary, Emacs Glossary,, emacs, the GNU Emacs Manual}.
157 Before we delve into Hyperbole, a number of acknowledgments are in
158 order. Peter Wegner has encouraged the growth in this work. Morris
159 Moore has helped me pursue my own research visions and kept me striving
160 for excellence. Doug Engelbart has shown me the bigger picture and
161 continues to be an inspiration. His work provides a model from which I
162 am beginning to draw. Kellie Clark and I jointly designed the Hyperbole
163 outliner while sharing a life together. Chris Nuzum, as a user of
164 Hyperbole, has helped demonstrate its power since its inception; he
165 knows how to work with Hyperbole far better than I.
173 * Entering Arguments::
176 * Window Configurations::
177 * Developing with Hyperbole::
179 * Smart Key Reference::
181 * Suggestion or Bug Reporting::
182 * Questions and Answers::
185 * Key Binding Index::
186 * Code and File Index::
189 --- The Detailed Node Listing ---
193 * Hyperbole Overview::
208 * Link Variable Substitution::
217 * Button Type Precedence::
219 * Utilizing Explicit Buttons::
221 Utilizing Explicit Buttons
233 * By Dragging:: Creation Via Action Key Drags
234 * By Menu:: Creation Via Menus
239 * Creating Outlines::
250 * Adding and Killing::
252 * Relocating and Copying::
255 * Splitting and Appending::
256 * Inserting and Importing::
260 * Hiding and Showing::
270 Developing with Hyperbole
274 * Explicit Button Technicalities::
275 * Encapsulating Systems::
276 * Embedding Hyperbole::
280 * Action Type Creation::
281 * Implicit Button Types::
283 Explicit Button Technicalities
285 * Button Label Normalization::
286 * Operational and Storage Formats::
287 * Programmatic Button Creation::
292 * Smart Keyboard Keys::
295 @node Introduction, Installation, Top, Top
296 @chapter Introduction
298 This chapter describes what Hyperbole is, lists some of its potential
299 applications, explains how to subscribe to its mail lists, and then
300 summarizes the structure of the rest of the manual.
303 * Hyperbole Overview::
308 @node Hyperbole Overview, Mail Lists, Introduction, Introduction
309 @section Hyperbole Overview
311 A Hyperbole user works with @emph{buttons} embedded within textual
312 documents; he may create, modify, move or delete buttons. Each button
313 performs a specific action, such as linking to a file or executing a
316 @cindex button, explicit
317 @cindex button, global
318 @cindex button, implicit
319 @cindex button category
320 @cindex explicit button
321 @cindex global button
322 @cindex implicit button
323 There are three categories of Hyperbole buttons:
325 @item explicit buttons
326 created by Hyperbole, accessible from within a single document;
329 created by Hyperbole, accessible anywhere within a user's network of
332 @item implicit buttons
333 created and managed by other programs or embedded within the structure
334 of a document, accessible from within a single document. Hyperbole
335 recognizes implicit buttons by contextual patterns given in their type
336 specifications (explained later).
339 Explicit Hyperbole buttons may be embedded within any type of text file.
340 Implicit buttons may be recognized anywhere within a text file,
341 depending on the implicit button types that are available. All global
342 buttons are stored in a single location and activated by entering their
343 names, rather than by direct selection, the means used to activate
344 explicit and implicit buttons.
350 Button Category Active Within Activation Means Managed By
351 ========================================================================
352 Explicit a single document direct selection Hyperbole
353 Global any document specifying its name Hyperbole
354 Implicit a matching context direct selection other tools
355 ========================================================================
359 Hyperbole buttons may be clicked upon with a mouse to activate them or
360 to describe their actions. Thus, a user can always check how a button
361 will act before activating it. Buttons may also be activated from a
362 keyboard. (In fact, virtually all Hyperbole operations, including menu
363 usage, may be performed from any standard character terminal interface,
364 so one need not be anchored to a workstation all day). @xref{Smart
367 @cindex Hyperbole features
368 Hyperbole does not enforce any particular hypertext or information
369 management model, but instead allows you to organize your information in
370 large or small chunks as you see fit. The Hyperbole outliner organizes
371 information hierarchies which may also contain links to external
375 Some of Hyperbole's most important features include:
379 Buttons may link to information or may execute procedures, such as
380 starting or communicating with external programs;
383 One simply drags between a button source location and a link destination
384 to create or to modify a link button. The same result can be achieved
388 Buttons may be embedded within electronic mail messages;
391 Outlines allow rapid browsing, editing and movement of chunks of
392 information organized into trees (hierarchies);
395 Other hypertext and information retrieval systems may be encapsulated
396 under a Hyperbole user interface (a number of samples are provided).
399 @cindex Hyperbole applications
401 Typical Hyperbole applications include:
404 @item personal information management
405 Overlapping link paths provide a variety of views into an information space.
406 A search facility locates buttons in context and permits quick selection.
408 @item documentation and code browsing
409 Cross-references may be embedded within documentation. One can add a
410 point-and-click interface to existing documentation, link code with
411 associated design documents, or jump to the definition of an identifier
412 by selecting its name within code or documentation.
415 The Hyperbole outliner, @xref{Outliner}, is an
416 effective tool for capturing ideas and then quickly reorganizing them in
417 a meaningful way. Links to related ideas are easy to create,
418 eliminating the need to copy and paste information into a single place.
420 @item help/training systems
421 Tutorials containing buttons can show students how things work while
422 explaining the concepts, e.g@. an introduction to local commands. This
423 technique can be much more effective than written documentation alone.
425 @item archive managers
426 Programs that manage archives from incoming information streams may be
427 supplemented by having them add topic-based buttons that link to the
428 archive holdings. Users can then search and create their own links to
432 @node Mail Lists, Manual Overview, Hyperbole Overview, Introduction
435 If you use Hyperbole, you should consider joining one of the two
436 Hyperbole interest mailing lists. @xref{Menus}, and the description
437 of the the Msg/ menu item, for a convenient means of joining and
438 mailing to these lists.
442 There are two Hyperbole-related mail lists.
443 One for discussing using hyperbole, @emph{hyperbole-users}, and the
444 other for reporting bugs, @emph{bug-hyperbole}.
446 To subscribe to the mail lists use the links below with your web
447 browser (or if your using hyperbole just click on them)
449 @cindex mail list requests
450 @cindex joining a mail list
451 @cindex subscribing to a mail list
452 @cindex unsubscribing from a mail list
454 http://lists.gnu.org/mailman/listinfo/hyperbole-users
456 http://lists.gnu.org/mailman/listinfo/bug-hyperbole
460 @strong{All} administration of the Hyperbole mailing lists should be
461 dealth with one of these web addresses. That includes addition,
464 Don't send administrative requests to the mail lists or people will
465 wonder why you don't know that the list administration is handled on
466 the web interfaces.@refill
470 So there are two Hyperbole-related mail lists:
472 @cindex hyperbole mail list
474 <hyperbole-users@@gnu.org>
478 Mail list for discussion of all issues regarding using
481 @cindex e-mail, effective communication
482 @cindex effective communication
483 Always use your Subject and/or Summary: lines to state the position that
484 your message takes on the topic that it addresses.
486 Statements end with periods, questions with question marks (typically),
487 and high energy, high impact declarations with exclamation points. This
488 simple rule makes all e-mail communication much easier for recipients to
489 handle appropriately.@refill
491 @cindex Hyperbole version
492 @cindex Emacs version
493 @vindex emacs-version
494 If you ask a question, your subject line should end with a ?,
495 e.g@. "Subject: How can man page SEE ALSOs be made implicit buttons?" A
496 "Subject: Re: How can ..." then indicates an answer to the question.
497 Question messages should normally include your Hyperbole and Emacs
498 version numbers and clearly explain your problem and surrounding issues.
499 Otherwise, you will simply waste the time of those who may want to help
500 you. (Your top-level Hyperbole menu shows its version number and @{@kbd{M-x
501 emacs-version @key{RET}}@} gives the other.)@refill
503 If you ask questions, you should consider adding to the discussion by
504 telling people the kinds of work you are doing or contemplating doing
505 with Hyperbole. In this way, the list will not be overwhelmed by
506 messages that ask for, but provide no information.@refill
509 @cindex bug-hyperbole mail list
511 <bug-hyperbole@@gnu.org>
515 Bug reports and suggestions should go here. It is important here that
516 you include as much info about your environment and program versions
520 @node Manual Overview, , Mail Lists, Introduction
521 @section Manual Overview
523 Remember that the @file{DEMO} file included in the Hyperbole
524 distribution demonstrates many of Hyperbole's standard facilities,
525 (@pxref{Top, Preface}) for more details.
527 @xref{Glossary}, for definitions of Hyperbole terms for quick
528 reference, so in some cases terms are not precisely defined within the
529 text. Be sure to reference the glossary if a term is unclear to you.
530 Although you need not have a keen understanding of all of these terms, a
531 quick scan of the Glossary should help throughout Hyperbole use.
533 If you have a question, feature suggestion or bug report on Hyperbole,
534 follow the instructions given in @ref{Suggestion or Bug Reporting}. A few
535 commonly asked questions are answered in the manual, @ref{Questions and
536 Answers}. If you are interested in classic articles on hypertext,
539 @xref{Installation}, for explanations of how to obtain, install, configure
540 and load Hyperbole for use.
542 @xref{Buttons}, for an overview of Hyperbole buttons and how to use them.
544 @xref{Smart Keys}, for an explanation of the innovative,
545 context-sensitive mouse and keyboard Action and Assist Keys offered by
546 Hyperbole. @xref{Smart Key Reference}, for a complete reference on what
547 the Action and Assist Keys do in each particular context that they
550 (Keep in mind as you read about how to use Hyperbole that in many cases,
551 it provides a number of overlapping interaction methods are provided to
552 support different work styles and hardware limitations. You need learn
553 only one with which you can become comfortable, in such instances.)
555 @xref{Menus}, for summaries of Hyperbole menu commands and how to use
556 the minibuffer-based menus that work on dumb terminals.
558 @xref{Entering Arguments}, for special support that Hyperbole provides for
559 entering arguments when prompted for them.
561 @xref{Outliner}, for concept and usage information on the
562 autonumbered, hypertextual outliner. A full summary of the outliner
563 commands that are bound to keys may be found in @ref{Outliner Keys}.
565 @xref{Rolodex}, for concept and usage information on the
566 rapid lookup, hierarchical, free text record management system included
569 @xref{Window Configurations}, for instructions on how to save and restore
570 the set of buffers and windows that appear with a frame. This feature
571 lets you switch among working contexts easily, even on a dumb terminal.
572 Such configurations only last throughout your current editor session.
574 Developers comfortable with Emacs Lisp will want to continue on through
575 to, @ref{Developing with Hyperbole}.
577 @xref{Future Work}, for future directions in Hyperbole's evolution.
580 @node Installation, Buttons, Introduction, Top
581 @chapter Installation
584 Hyperbole must be installed at your site before you can use it. The
585 following sections explain how to obtain, install and configure
588 @vindex file, hsite.el
589 @cindex customization, init
590 If you want to customize the basic Hyperbole initialization sequence for
591 yourself rather than the users at your site, you should make a personal
592 copy of the @file{hsite.el} file, modify it the way you want, and then
593 load it. (If you are familiar with Emacs Lisp, @ref{Hook Variables}.)
602 @node Obtaining, Building, Installation, Installation
607 @cindex anonymous ftp
608 Hyperbole can be obtained via anonymous ftp on the Internet from:
610 @file{ftp://ftp.gnu.org/gnu/hyperbole}.
612 @cindex downloading Hyperbole
613 @cindex obtaining Hyperbole
614 @cindex Hyperbole, obtaining
616 Here are instructions for downloading and unpacking Hyperbole.
618 Move to a directory below which you want the @file{hyperbole} directory to
619 be created. Unpacking the Hyperbole archive will create the
620 @file{hyperbole} directory and will place all of the files below it.
623 cd <LOCAL-EMACS-LISP-DIR>
630 prompt> ftp ftp.gnu.org
634 Login as @emph{anonymous} with your own @emph{<user-id>@@<site-name>} as
638 Name (ftp.gnu.org): anonymous
639 331 Guest login ok, send EMAIL address (e.g@. user@@host.domain)
642 230 Guest login ok, access restrictions apply.
646 Move to the Hyperbole directory:
649 ftp> cd gnu/hyperbole
653 Set your transfer mode to binary:
665 Interactive mode off.
669 Retrieve just the Hyperbole archive and any diff-based patches (there may not
678 Close the ftp connection:
689 @cindex uncompressing archives
690 @cindex unpacking archives
692 Unpack the tar archive using the GNU version of the @code{zcat} program,
693 sometimes called @code{gzcat} or the @code{gunzip} program:
696 zcat hyperbole*tar.gz | tar xvf -
698 gunzip hyperbole*tar.gz; tar xvf hyperbole*tar
702 Apply any patches you retrieved:
705 cd hyperbole; patch < <patch-file>
709 @node Building, Installing, Obtaining, Installation
712 @vindex file, Makefile
713 @vindex file, hsite.el
714 @cindex Hyperbole, building
715 @cindex building Hyperbole
716 The following explains how to Use the Hyperbole @file{Makefile} to
717 compile any needed code, to generate the @file{hsite.el} file used for
718 site-specific Hyperbole customization, and to produce printable
721 @vindex EMACS, environment variable
722 @cindex compiling Lisp
723 @cindex Lisp compilation
724 Edit the line near the top of @file{Makefile} that represents the emacs
725 version that you use, so that it corresponds to the emacs executable
726 name used on your system. Then immediatly below there, set the
727 @var{EMACS} variable to the variable name for the emacs that you will
728 use to compile the Hyperbole Lisp files.
730 @vindex SITE-PRELOADS, environment variable
731 You may also have to set the @var{SITE-PRELOADS} variable defined further down
732 in the file; follow the instructions that precede the @var{SITE-PRELOADS =}
733 line. Make these changes now and save the @file{Makefile}.
735 @cindex HYPERBOLE-DIR
736 The following instructions use the term @file{<HYPERBOLE-DIR>/} to refer
737 to your @file{hyperbole/} directory, so substitute your own value.
740 To install Hyperbole for use with InfoDock, XEmacs, GNU Emacs or Epoch, from
744 cd <HYPERBOLE-DIR>; make
748 All of the .elc compiled Lisp files are already built for XEmacs and V19, so
749 this build will finish very quickly. If you really want to rebuild all of
753 cd <HYPERBOLE-DIR>; make all-elc
757 @cindex manual, generating Postscript
758 @vindex file, man/hyperbole.ps
760 To produce the Postscript version of the Hyperbole manual, you must have
761 the TeX formatter on your system:
764 cd <HYPERBOLE-DIR>; make ps
768 To install Hyperbole for use with GNU Emacs V18 or Epoch:
771 cd <HYPERBOLE-DIR>; make all-elc-v18
775 This will produce a complete set of Emacs V18 .elc files.
778 @node Installing, Configuring, Building, Installation
781 @cindex configuration
782 You may want to explore the Hyperbole configuration options before
783 installing it. @xref{Configuring}. If you just want to get up and
784 running quickly, however, there is no need to configure anything, just
785 follow these instructions to install Hyperbole.
787 @cindex Hyperbole, initializing
788 @cindex initializing Hyperbole
790 @cindex site initialization
791 @vindex file, hsite.el
792 @vindex file, ~/.emacs
793 Add the following lines to a site initialization file such as
794 @file{site-start.el} to set up so that all users have Hyperbole
795 loaded for them when they run Emacs. Otherwise, each user will have to
796 add these lines to his own @file{~/.emacs} initialization file.
798 @cindex autoloading Hyperbole
799 @cindex Hyperbole, autoloading
801 To autoload Hyperbole so that it loads only when needed:
804 @vindex file, hversion.el
805 @vindex file, hyperbole.el
807 (defvar hyperb:dir "<HYPERBOLE-DIR>/")
808 "Directory where the Hyperbole executable code is kept.
809 It must end with a directory separator character.")
811 (load (expand-file-name "hversion" hyperb:dir))
812 (load (expand-file-name "hyperbole" hyperb:dir))
815 @cindex loading Hyperbole
816 @cindex Hyperbole, loading
817 This establishes a few key bindings and sets up Hyperbole to
818 automatically load whenever you activate its menu. If you would rather
819 have the whole Hyperbole system loaded when you start up so that you can
820 always use the Smart Keys and other facilities, add the additional line:
826 If you use mouse keys, be sure to add the above lines after any setup of
827 mouse key bindings, to ensure that Hyperbole's mouse keys are properly
828 initialized. @xref{Smart Keys}, for further details. If you use any
829 Hyperbole mail or news support, @ref{Buttons in Mail}, be certain to
830 perform all of your personal mail/news initializations before the point
831 at which you load Hyperbole. Otherwise, the mail/news support may not
832 be configured properly. For example, if you use the Emacs add-on
833 Supercite package, its setup should come before Hyperbole initialization.
835 @cindex Hyperbole manual
837 The Hyperbole Manual is included in the distribution in two forms:
840 @cindex Texinfo manual
841 @vindex file, man/hyperbole.info
842 @vindex file, man/hyperbole.texi
844 @file{man/hyperbole.info} - online version
845 @file{man/hyperbole.texi} - source form
848 @vindex Info-directory-list
850 To add pointers to the Info version of the Hyperbole manual within your
851 Info directory, follow these instructions. If @var{Info-directory-list}
852 is bound as a variable within your Emacs (all versions except V18 and
853 Epoch), then you can simply set it so that <HYPERBOLE-DIR> is an element
857 (setq Info-directory-list (cons "<HYPERBOLE-DIR>" Info-directory-list))
861 Otherwise, from a shell:
863 @vindex Info-directory
865 cd to the directory given by your @var{Info-directory} variable
866 rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .
870 For all versions of Emacs, add an Info menu entry for the Hyperbole
871 manual in your Info @file{dir} file (the `*' should be placed in the
872 first column of the file):
875 * Hyperbole:: GNU Emacs-based everyday information management system.
876 Use @{C-h h d d@} for a demonstration. Includes context-sensitive
877 mouse and keyboard support, a powerful rolodex, an autonumbered
878 outliner with hyperlink anchors for each outline cell, and extensible
879 hypertext facilities including hyper-links in mail and news messages.
882 @cindex invoking Hyperbole
883 @cindex starting Hyperbole
884 @cindex Hyperbole, starting
885 @cindex Hyperbole main menu
888 That's all there is to the installation. Once Hyperbole has been
889 installed for use at your site, you can invoke it with @{@kbd{C-h h}@}
890 or @{@kbd{M-x hyperbole @key{RET}}@} to bring up the Hyperbole main menu
891 in the minibuffer window.
894 @node Configuring, , Installing, Installation
897 @cindex configuration
898 @vindex file, hyperbole.el
899 @vindex file, hsite.el
900 There are many Hyperbole configuration options that may be changed by
901 editing the @file{hyperbole.el} and @file{hsite.el} files in the
902 @file{hyperbole/} directory. The following sections discuss the
903 configuration options most likely to be of interest to users.
908 * Link Variable Substitution::
913 @node Internal Viewers, External Viewers, Configuring, Configuring
914 @subsection Internal Viewers
915 @vindex hpath:display-alist
916 @vindex file, hsite.el
917 @cindex file display function
918 @cindex display function
919 @cindex internal viewer
920 @cindex link, display function
921 When given a file name, Hyperbole will by default display the file for
922 editing within an Emacs buffer. The @var{hpath:display-alist} variable
923 can be used to specify file name patterns, such as matching suffixes,
924 which will invoke a special Emacs Lisp function to display any matching
925 files within Emacs. This can be used to format raw data files for
928 Configure the @var{hpath:display-alist} variable in @file{hsite.el}.
929 Its value is an association list whose elements are
930 (<file-name-regular-expression> . <function-of-one-arg>) pairs. Any
931 path whose name matches a <file-name-regular-expression> will be
932 displayed by calling the associated <function-of-one-arg> with the file
933 name as the argument.@refill
935 @xref{External Viewers}, for instructions on associating file names with
936 external, window-system specific viewers.
938 @node External Viewers, Link Variable Substitution, Internal Viewers, Configuring
939 @subsection External Viewers
940 @vindex hpath:find-alist
941 @vindex file, hsite.el
942 @cindex window system
943 @cindex external program
944 @cindex external viewer
945 @cindex link, viewer program
946 If you will be using Hyperbole under a window system, you may want to
947 configure the @var{hpath:find-alist} variable in @file{hsite.el} to
948 support hyperlinks which open files using non-Emacs tools, e.g@. a
949 fax reader or a bitmap viewer.
951 The value of @var{hpath:find-alist} is determined when Hyperbole is
952 initialized based upon the current window system and the version of
953 Emacs in use. The value is an association list whose elements are
954 (<file-name-regular-expression> . <viewer-program>) pairs. Any path
955 whose name matches a <file-name-regular-expression> will be
956 displayed using the corresponding viewer-program. If a <viewer-program>
957 entry contains a @code{%s} string, the filename to display will be
958 substituted at that point within the string. Otherwise, the filename
959 will be appended to the <viewer-program> entry. See the "x-suffixes"
960 and "nextstep-suffixes" settings within the definition of
961 @var{hpath:find-alist} as examples.@refill
963 @node Link Variable Substitution, Button Colors, External Viewers, Configuring
964 @subsection Link Variable Substitution
965 @vindex hpath:variables
966 @cindex environment variables
967 @cindex Emacs Lisp variables
968 @cindex Lisp variables
969 Another variable to consider modifying in the @file{hsite.el} file is
970 @var{hpath:variables}. This variable consists of a list of Emacs Lisp
971 variable names, each of which may have a pathname or a list of pathnames
972 as a value. Whenever a Hyperbole file or directory link button is
973 created, its pathname is compared against the values in
974 @var{hpath:variables}. The first match found, if any, is selected and
975 its associated variable name is substituted into the link pathname, in
976 place of its literal value. When the link is resolved (the button is
977 activated), Hyperbole replaces each variable with the first matching
978 value from this list. (Environment variables are also replaced whenever
979 link paths are resolved.
981 This permits sharing of links over wide areas, where the variable values
982 may differ between link creator and link activator. The entire process
983 is wholly transparent to the user; it is explained here simply to help
984 you in deciding whether or not to modify the value of
985 @var{hpath:variables}.
987 @node Button Colors, , Link Variable Substitution, Configuring
988 @subsection Configuring Button Colors
989 @cindex XEmacs support
990 @cindex Emacs 19 support
991 @cindex Epoch support
992 @cindex button highlighting
993 @cindex button flashing
994 @vindex file, hui-ep*.el
995 @findex hproperty:cycle-but-color
996 When Hyperbole is run under a window system together with Emacs 19,
997 XEmacs or Epoch, it automatically highlights any explicit buttons in
998 a buffer and makes them flash when selected. The main setting
999 you may want change is the selection of a color (or style) for button
1000 highlighting and button flashing. See the @file{hui-*-b*.el} files for
1001 lists of potential colors and the code which supports this behavior. A
1002 call to @code{(hproperty:cycle-but-color)} within a Hyperbole
1003 initialization sequence in the @file{hsite.el} file changes the color
1004 used to highlight and flash explicit buttons.
1006 @cindex button emphasis
1007 @vindex hproperty:but-emphasize-p
1008 @vindex file, hsite.el
1009 Additionally, under XEmacs and Emacs 19, if @var{hproperty:but-emphasize-p}
1010 is set to @code{t} in @file{hsite.el}, then whenever the mouse pointer
1011 moves over an explicit button, it will be emphasized in a different
1012 color or style. This emphasis is in addition to any non-mouse-sensitive
1013 button highlighting.
1015 @cindex button highlighting, forcing
1016 @findex hproperty:but-create
1017 If you read in a file with explicit buttons before you load Hyperbole,
1018 these buttons won't be highlighted. Load Hyperbole and then use
1019 @code{M-x hproperty:but-create @key{RET}} to highlight the buttons in
1023 @node Buttons, Smart Keys, Installation, Top
1026 This chapter explains the user-level notion of Hyperbole buttons.
1027 Hyperbole buttons that are stored in files persist across Emacs
1028 sessions, so they provide a convenient means of linking from one
1029 information source to another.
1032 * Explicit Buttons::
1034 * Implicit Buttons::
1036 * Button Type Precedence::
1038 * Utilizing Explicit Buttons::
1041 @node Explicit Buttons, Global Buttons, Buttons, Buttons
1042 @section Explicit Buttons
1044 @cindex explicit button
1045 @cindex button, explicit
1046 @cindex button label
1047 Hyperbole creates and manages @emph{explicit buttons} which look like
1048 this @code{<(fake button)>} to a Hyperbole user. They are quickly
1049 recognizable, yet relatively non-distracting as one scans the text in
1050 which they are embedded. The text between the @code{<(} and
1051 @code{)>} delimiters is called the @dfn{button label}. Spacing between
1052 words within a button label is irrelevant to Hyperbole, so button labels
1053 may wrap across several lines without causing a problem.
1056 @cindex button attribute
1058 Hyperbole stores the @dfn{button data} that gives an explicit button its
1059 behavior, separately from the button label, in a file named @file{.hypb}
1060 within the same directory as the file in which the button is created.
1061 Thus, all files in the same directory share a common button data file.
1062 Button data is comprised of individual @dfn{button attribute} values. A
1063 user never sees this data in its raw form but may see a formatted
1064 version by asking for help on a button.
1066 @cindex button, moving
1067 @cindex moving buttons
1068 Explicit buttons may be freely moved about within the buffer in which
1069 they are created. (No present support exists for moving buttons between
1070 buffers). A single button may also appear multiple times within the
1071 same buffer; one simply copies the button label with its delimiters
1072 to a new location in such cases.
1074 Each explicit button is assigned an action type which determines the
1075 actions that it performs. @dfn{Link action types} connect buttons to
1076 particular types of referents. @dfn{Activation} of such buttons then
1077 displays the referents.
1079 @cindex linking, in-place
1080 @cindex Hyperbole data model
1081 Hyperbole does not manage referent data; this is left to the
1082 applications that generate the data. This means that Hyperbole
1083 provides in-place linking and does not require reformatting of data to
1084 integrate it with a Hyperbole framework.
1086 @node Global Buttons, Implicit Buttons, Explicit Buttons, Buttons
1087 @section Global Buttons
1089 @cindex global button
1090 @cindex button, global
1091 @cindex button label
1092 Access to explicit buttons depends upon the information on your screen
1093 since they are embedded within particular buffers. Sometimes it is
1094 useful to activate buttons without regard to the information with which
1095 you are presently working. In such instances, you use @dfn{global
1096 buttons}, which are simply explicit buttons which may be activated or
1097 otherwise operated upon by entering their labels when they are prompted
1098 for, rather than selecting the buttons within a buffer.
1100 If you want a permanent link to a file section that you can follow at
1101 any time, you can use a global button. Or what about an Emacs keyboard
1102 macro that you use frequently? Create an @code{exec-kbd-macro} button
1103 with an easy to type name and then you can easily activate it whenever
1106 @node Implicit Buttons, Action Types, Global Buttons, Buttons
1107 @section Implicit Buttons
1109 @cindex button, implicit
1110 @cindex implicit button
1111 Implicit buttons are those defined by the natural structure of a
1112 document. They are identified by contextual patterns which limit the
1113 locations or states in which they can appear. Their behavior is
1114 determined by one or more actions which they trigger when activated. An
1115 action is derived from either a Hyperbole action type specification,
1116 @ref{Action Types}, or an Emacs Lisp function. Implicit
1117 button types may use the same action types that explicit buttons do.
1119 @vindex file, hibtypes.el
1121 Implicit buttons never have any button data associated with them. They
1122 are recognized in context based on predicate matches defined within
1123 implicit button types. For example, Hyperbole recognizes file names
1124 enclosed in double quotes and can quickly display their associated files
1125 in response to simple mouse clicks.
1127 @cindex ibtypes, list of
1129 See @file{hibtypes.el} for complete examples. Standard implicit button
1130 types include (in alphabetical order):
1135 @findex ibtypes::annot-bib
1136 @cindex bibliography
1138 Displays annotated bibliography entries referenced internally, delimeters = [].
1139 References must be delimited by square brackets, must begin with a
1140 word constituent character, and must not be in buffers whose
1141 names begin with a ' ' or '*' character.
1144 @findex ibtypes::completion
1146 Inserts completion at point into minibuffer or other window.
1149 @findex ibtypes::dir-summary
1150 @vindex file, MANIFEST
1152 Detects filename buttons in files named "MANIFEST" or "DIR".
1153 Displays selected files.
1154 Each file name must be at the beginning of the line and must be followed
1155 by one or more spaces and then another non-space, non-parenthesis, non-brace
1159 @findex ibtypes::doc-id
1160 @cindex online library
1161 @cindex document identifier
1162 Displays an index entry for a site-specific document given its id. Ids
1163 must be delimited by 'doc-id-start' and 'doc-id-end' and must match the
1164 function given by 'doc-id-p'. This permits creation of catalogued
1165 online libraries. See @file{$@{hyperb:dir@}/hib-doc-id.el} for more
1168 @item elisp-compiler-msg
1169 @findex ibtypes::elisp-compiler-msg
1170 @cindex byte compiler error
1171 @cindex Emacs Lisp compiler error
1172 @cindex compiler error
1173 Jumps to source code for definition associated with byte-compiler error
1174 message. Works when activated anywhere within an error line.
1176 @item debugger-source
1177 @findex ibtypes::debugger-source
1184 Jumps to source line associated with debugger stack frame or breakpoint lines.
1185 This works with gdb, dbx, and xdb. Such lines are recognized in any buffer.
1188 @findex ibtypes::grep-msg
1190 @cindex compiler error
1191 Jumps to line associated with grep or compilation error msgs.
1192 Messages are recognized in any buffer.
1195 @findex ibtypes::hyp-address
1196 @cindex Hyperbole mail list
1197 Turns a Hyperbole e-mail list address into an implicit button which
1198 inserts Hyperbole environment information.
1199 Useful when sending mail to a Hyperbole mail list. See also the
1200 documentation for @code{actypes::hyp-config}.
1203 @findex ibtypes::hyp-source
1204 @cindex Hyperbole report
1205 Turns source location entries in Hyperbole reports into buttons that jump to the associated location.
1208 @findex ibtypes::Info-node
1210 Makes "(file)node" buttons display the associated Info node.
1213 @findex ibtypes::kbd-key
1214 @cindex key sequence
1215 Executes a key sequence delimited by curly braces.
1216 Key sequences should be in human readable form, e.g@. @{@kbd{C-b}@}.
1217 Forms such as @{
\ 2@}, @{
\ 2@}, and @{^b@} will not be recognized.
1220 @findex ibtypes::klink
1222 @cindex koutline link
1224 Follows a link delimited by <> to a koutline cell.
1225 See documentation for @code{actypes::link-to-kotl} for valid link
1229 @findex ibtypes::mail-address
1230 @cindex e-mail address
1231 @cindex rolodex address
1233 If on an e-mail address in a specific buffer type, mail to that address
1234 in another window. Applies to the rolodex match buffer, any buffer
1235 attached to a file in @var{rolo-file-list}, or any buffer with @file{mail}
1236 or @file{rolo} (case-insensitive) within its name.
1239 @findex ibtypes::man-apropos
1243 Makes man apropos entries display associated man pages when selected.
1246 @findex ibtypes::patch-msg
1247 @cindex patch output
1248 Jumps to source code associated with output from the @code{patch}
1249 program. Patch applies diffs to source code.
1252 @findex ibtypes::pathname
1255 @vindex hpath:suffixes
1261 @cindex link, pathname
1262 Makes a delimited, valid pathname display the path entry.
1263 Also works for delimited and non-delimited ange-ftp and efs pathnames.
1264 See @code{hpath:at-p} function documentation for possible delimiters.
1265 See @var{hpath:suffixes} variable documentation for suffixes that are
1266 added to or removed from pathname when searching for a valid match.
1267 See @code{hpath:find} function documentation and
1268 @var{hpath:display-alist} and @var{hpath:find-alist} variable
1269 documentation for special file display options.
1272 @findex ibtypes::rfc
1273 @cindex Internet RFC
1274 @cindex Request For Comment
1278 Retrieves and displays an Internet rfc referenced at point.
1279 Requires ange-ftp or efs when needed for remote retrievals. The
1280 following formats are recognized: RFC822, rfc-822, and RFC 822. The
1281 @var{hpath:rfc} variable specifies the location from which to retrieve
1285 @findex ibtypes::rfc-toc
1286 @cindex Internet RFC
1287 @cindex Request For Comment
1289 @cindex table of contents
1290 Summarizes contents of an Internet rfc from anywhere within rfc buffer.
1291 Each line in summary may be selected to jump to section.
1294 @findex ibtypes::text-toc
1295 @cindex table of contents
1296 @cindex toc implicit button type
1297 Jumps to the text file section referenced by a table of contents entry
1298 at point. File name must contain @file{README} and there must be a
1299 `Table of Contents' or `Contents' label on a line by itself (it may
1300 begin with an asterisk), preceding the table of contents. Each toc
1301 entry must begin with some whitespace followed by one or more asterisk
1302 characters. Each file section name line must start with one or more
1303 asterisk characters at the very beginning of the line.
1306 @findex ibtypes::www-url
1308 @cindex World-wide Web
1310 @cindex Action Key, web browsing
1311 @kindex Action Key, web browsing
1312 @vindex action-key-url-function
1313 When not in a w3 browser buffer, follow any non-ftp url (link) at point.
1314 The variable, @var{action-key-url-function}, can be used to customize
1315 the url browser that is used.
1318 The Hyperbole Smart Keys offer extensive additional context-sensitive
1319 point-and-click type behavior beyond these standard implicit button
1320 types. @xref{Smart Keys}.
1323 @node Action Types, Button Type Precedence, Implicit Buttons, Buttons
1324 @section Action Types
1327 @cindex argument, use
1329 @dfn{Action types} provide action procedures that specify button behavior.
1330 The arguments needed by an action type are prompted for at button creation
1331 time. When a button is activated, the stored arguments are fed to the
1332 action type's @dfn{action} body to achieve the desired result. Hyperbole
1333 handles all of this transparently.
1335 @cindex actypes, list of
1337 Standard action types in alphabetical order include:
1341 @findex actypes::annot-bib
1342 Follows internal ref KEY within an annotated bibliography, delimiters=[].
1345 @findex actypes::completion
1346 Inserts completion at point into minibuffer or other window.
1347 Unless at end of buffer or if completion has already been inserted, then
1348 deletes completions window.
1351 @findex actypes::eval-elisp
1352 Evaluates a Lisp expression LISP-EXPR.
1354 @item exec-kbd-macro
1355 @findex actypes::exec-kbd-macro
1356 Executes KBD-MACRO REPEAT-COUNT times.
1357 KBD-MACRO may be a string of editor command characters or a function symbol.
1358 Optional REPEAT-COUNT nil means execute once, zero means repeat until
1361 @item exec-shell-cmd
1362 @findex actypes::exec-shell-cmd
1363 Executes a SHELL-CMD string asynchronously.
1364 Optional non-nil second argument INTERNAL-CMD means do not display the shell
1365 command line executed. Optional non-nil third argument KILL-PREV means
1366 kill last output to shell buffer before executing SHELL-CMD.
1368 @item exec-window-cmd
1369 @findex actypes::exec-window-cmd
1370 Executes an external window-based SHELL-CMD string asynchronously.
1373 @findex actypes::hyp-config
1374 Inserts Hyperbole configuration info at end of optional OUT-BUF or current.
1377 @findex actypes::hyp-request
1378 Inserts Hyperbole mail list request help into optional OUT-BUF or current.
1381 @findex actypes::hyp-source
1382 Displays a buffer or file from a line beginning with 'hbut:source-prefix'.
1385 @findex actypes::kbd-key
1386 Executes the function binding for KEY-SEQUENCE, delimited by @{@}.
1387 Returns t if a KEY-SEQUENCE has a binding, else nil.
1389 @item link-to-buffer-tmp
1390 @findex actypes::link-to-buffer-tmp
1391 Displays a BUFFER in another window.
1392 Link is generally only good for current Emacs session.
1393 Use 'link-to-file' instead for a permanent link.
1395 @item link-to-directory
1396 @findex actypes::link-to-directory
1397 Displays a DIRECTORY in Dired mode in another window.
1400 @findex actypes::link-to-doc
1401 Displays online version of a document given by DOC-ID, in other window.
1402 If the online version of a document is not found in
1403 @var{doc-id-indices}, an error is signalled.
1406 @findex actypes::link-to-ebut
1407 Performs action given by another button, specified by KEY and KEY-FILE.
1409 @item link-to-elisp-doc
1410 @findex actypes::link-to-elisp-doc
1411 Displays documentation for FUNC-SYMBOL.
1414 @findex actypes::link-to-file
1415 Displays a PATH in another window scrolled to optional POINT.
1416 With POINT, buffer is displayed with POINT at the top of the window.
1418 @item link-to-file-line
1419 @findex actypes::link-to-file-line
1420 Displays a PATH in another window scrolled to LINE-NUM.
1423 @findex actypes::link-to-kcell
1424 Displays FILE with kcell given by CELL-REF at the top of the window.
1425 CELL-REF may be a kcell's display label or its permanant idstamp.
1426 If FILE is nil, the current buffer is used.
1427 If CELL-REF is nil, the first cell in the view is shown.
1430 @findex actypes::link-to-kotl
1431 Displays at the top of another window the referent pointed to by LINK.
1432 LINK may be of any of the following forms, with or without delimiters:
1434 < pathname [, cell-ref] >
1440 See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
1443 @item link-to-Info-node
1444 @findex actypes::link-to-Info-node
1445 Displays an Info NODE in another window.
1446 NODE must be a string of the form '(file)nodename'.
1449 @findex actypes::link-to-mail
1450 Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window.
1451 See documentation for the variable @var{hmail:init-function} for
1452 information on how to specify a mail reader to use.
1454 @item link-to-regexp-match
1455 @findex actypes::link-to-regexp-match
1456 Finds REGEXP's Nth occurrence in FILE and displays location at window top.
1457 Returns t if found, signals an error if not.
1460 @findex actypes::link-to-rfc
1461 Retrieves and displays an Internet rfc given by RFC-NUM.
1462 RFC-NUM may be a string or an integer. Requires ange-ftp or efs for
1465 @item link-to-string-match
1466 @findex actypes::link-to-string-match
1467 Finds STRING's Nth occurrence in FILE and displays location at window top.
1468 Returns t if found, nil if not.
1471 @findex actypes::man-show
1472 Displays man page on TOPIC, which may be of the form @code{<command>(<section>}).
1475 @findex actypes::rfc-toc
1476 Computes and displays summary of an Internet rfc in BUF-NAME.
1477 Assumes point has already been moved to start of region to summarize.
1478 Optional OPOINT is point to return to in BUF-NAME after displaying summary.
1481 @findex actypes::text-toc
1482 @cindex table of contents
1483 @cindex toc action type
1484 Jumps to the text file SECTION referenced by a table of contents entry
1488 @findex actypes::www-url
1490 @cindex World-wide Web
1492 @vindex action-key-url-function
1493 Follows a link given by URL.
1494 The variable, @var{action-key-url-function}, can be used to customize
1495 the url browser that is used.
1499 @vindex hui:ebut-prompt-for-action
1500 The use of action types provides a convenient way of specifying button
1501 behavior without the need to know how to program. Expert users who are
1502 familiar with Emacs Lisp, however, may find that they often want to
1503 tailor button actions in a variety of ways not easily captured within a
1504 type system. In such cases, @var{hui:ebut-prompt-for-action} should be
1505 set non-nil. This will cause Hyperbole to prompt for an action to
1506 override the button's action type at each explicit button creation. For
1507 those cases where the action type is sufficient, a nil value should be
1508 entered for the action. An action may be any Lisp form that may be
1511 @node Button Type Precedence, Button Files, Action Types, Buttons
1512 @section Button Type Precedence
1514 @cindex button precedence
1515 @cindex button label overlap
1516 Explicit buttons always take precedence over implicit buttons. Thus, if
1517 a button selection is made which falls within both an explicit and
1518 implicit button, only the explicit button will be selected. Explicit
1519 button labels are not allowed to overlap; Hyperbole's behavior in such
1522 @cindex ibtype, evaluation order
1523 If there is no explicit button at point during a selection request, then
1524 each implicit button type predicate is tested in turn until one returns
1525 non-nil or all are exhausted. Since two implicit button types may have
1526 overlapping domains (those contexts in which their predicates are true),
1527 only the first matching type is used. The type predicates are tested
1528 in @strong{reverse} order of definition, i.e@. most recently entered
1529 types are tested first, so that personal types defined after standard
1530 system types take precedence. It is important to keep this order in
1531 mind when defining new implicit button types. By making their match
1532 predicates as specific as possible, one can minimize any overlapping of
1533 implicit button type domains.
1535 @cindex type redefinition
1536 Once a type name is defined, its precedence relative to other types
1537 remains the same even if you redefine the body of the type, as long as
1538 you don't change its name. This allows incremental modifications to
1539 types without having to worry about shifts in type precedence.
1540 @xref{Creating Types}, for information on how to develop
1543 @node Button Files, Utilizing Explicit Buttons, Button Type Precedence, Buttons
1544 @section Button Files
1546 @cindex button files
1547 It is often convenient to create lists of buttons that can be used as
1548 menus to provide centralized access to distributed information pools or
1549 for other purposes. These files can serve as useful roadmaps to help
1550 efficiently guide a user through both unfamiliar and highly familiar
1551 information spaces. Files that are created specifically for this
1552 purpose, we call @dfn{button files}.
1554 @vindex hbmap:filename
1555 @cindex button file, personal
1556 @cindex button file, directory
1557 The Hyperbole menu system provides quick access to two types of these
1558 button files: personal and directory-specific, through the ButFile menu.
1559 (The variable, @var{hbmap:filename}, contains the base name of these
1560 standard button files. Its standard value is @file{HYPB}.)
1562 @vindex dir, ~/.hyperb
1563 @vindex hbmap:dir-user
1564 @cindex global button
1565 A personal button file may serve as a user's own roadmap to frequently
1566 used resources. Selection of the ButFile/PersonalFile menu item
1567 displays this file for editing. The default personal button file is
1568 stored within the directory given by the @var{hbmap:dir-user} variable
1569 whose standard value is @file{~/.hyperb}. The standard Hyperbole
1570 configuration also appends all global buttons to the end of this file,
1571 one per line, as they are created. So you can edit or annotate them
1574 A directory-specific button file may exist for each file system
1575 directory. Such files are useful for explaining the contents of
1576 directories and pointing readers to particular highlights within the
1577 directories. Selection of the ButFile/DirFile menu item displays the
1578 button file for the current directory; this provides an easy means of
1579 updating this file when working on a file within the same directory.
1580 If you want to view some other directory-specific button file, simply
1581 use the normal Emacs file finding commands.
1583 One might suggest that menu quick access be provided for group-specific
1584 and site-specific button files. Instead, link buttons to such things
1585 should be placed at the top of your personal button file. This provides
1586 a more flexible means of quick access.
1588 @node Utilizing Explicit Buttons, , Button Files, Buttons
1589 @section Utilizing Explicit Buttons
1591 Explicit buttons are a fundamental building block for creating personal
1592 or organizational hypertext networks with Hyperbole. This section
1593 summarizes the user-level operations available for managing these
1606 @node Creation, Renaming, Utilizing Explicit Buttons, Utilizing Explicit Buttons
1607 @subsection Creation
1610 * By Dragging:: Creation Via Action Key Drags
1611 * By Menu:: Creation Via Menus
1614 @node By Dragging, By Menu, Creation, Creation
1615 @subsubsection Creation Via Action Key Drags
1617 @cindex explicit button, creation
1618 @cindex button, creation
1619 @cindex link, creation
1621 @cindex Action Key drag
1622 The most efficient way to create an explicit button interactively is to
1623 use the mouse Action Key to drag from a button source window to a window
1624 showing its link referent. More specifically, you should split your
1625 current Emacs frame into two windows: one which contains the point at
1626 which you want a button to be inserted and another which shows the point
1627 to which you want to link. Depress the mouse Action Key at the point at
1628 which the button should be inserted, drag to the other window and
1629 release it at the point of the link referent. The process becomes quite
1630 simple with a little practice. (@xref{By Menu, Creation Via Menus}, for a
1631 more detailed explanation of the explicit button creation process.)
1633 Hyperbole uses the link referent context to determine the type of link
1634 to make. If there are a few different types of links which are
1635 applicable from the context, you will be prompted with a list of the
1636 types. Simply use the Action Key or the first letter of the link
1637 type to select one of the type names and to finish the link creation.
1638 Hyperbole will then insert explicit button delimiters around the button
1639 label and will display a message in the minibuffer indicating both the
1640 button name and its action/link type.
1645 @findex hkey-operate
1646 If you run Emacs under a window system, you can emulate an Action Key
1647 drag from the keyboard by: hitting @{@kbd{M-o}@}, the
1648 @code{hkey-operate} command, at the button source location, moving
1649 to the link destination, e.g@. with @{@kbd{C-x o}@}, and then hitting
1650 @{@kbd{M-o}@} again. This simulates a depress and then release of the
1651 Action Key. @{@kbd{C-u M-o}@} emulates drags of the Assist Key.
1652 This will not work when Hyperbole is run from a dumb terminal Emacs
1653 session since drag actions are not supported without a window system.
1656 @node By Menu, , By Dragging, Creation
1657 @subsubsection Creation Via Menus
1659 You can alternatively use the Hyperbole menus to create explicit
1660 buttons. First, mark a short region of text in any fashion allowed by
1661 GNU Emacs and then select the Hyperbole menu item sequence, Ebut/Create.
1662 You will be prompted for the button's label with the marked region as
1663 the default. If you accept the default and enter the rest of the
1664 information you are prompted for, the button will be created within the
1665 current buffer and Hyperbole will surround the marked region with
1666 explicit button delimiters to indicate success.
1668 If you do not mark a region before invoking the button create command,
1669 you will be prompted for both a label and a target buffer for the button
1670 and the delimited label text will be inserted into the target buffer
1671 after a successful button creation.
1673 After Hyperbole has the button label and its target buffer, it will
1674 prompt you for an action type for the button. Use the @{@kbd{?}@}
1675 completion help key to see the available types. The type selected
1676 determines any following values for which you will be prompted.
1678 @cindex button instance
1679 @cindex instance number
1680 If a previous button with the same label exists in the same buffer,
1681 Hyperbole will add an @dfn{instance number} to the label when it adds
1682 the delimiters so that the name is unique. Thus, you don't have to
1683 worry about accidental button name conflicts. If you want the same
1684 button to appear in multiple places within the buffer, just enter the
1685 label again and delimit it yourself. Hyperbole will interpret all
1686 occurrences of the same delimited label within a buffer as the same
1689 @cindex link, creation
1690 If you create link buttons using the Hyperbole menus, the best technique
1691 is to place on screen both the source buffer for the button and the
1692 buffer to which it will link. Mark the region of text to use for your
1693 button label, invoke the button create command from the menu, choose an
1694 action type which begins with @code{link-to-} and then use the direct
1695 selection techniques mentioned in @ref{Entering Arguments}, to select
1699 @node Renaming, Deletion, Creation, Utilizing Explicit Buttons
1700 @subsection Renaming
1702 @cindex explicit button, renaming
1703 @cindex button, renaming
1704 Once an explicit button has been created, its label text must be
1705 treated specially. Any inter-word spacing within the label may be
1706 freely changed, as may happen when a paragraph is refilled. But a
1707 special command must be invoked to rename it.
1709 The rename command operates in two different ways. If point is within a
1710 button label when it is invoked, it will tell you to edit the button
1711 label and then invoke the rename command again. The second invocation
1712 will actually rename the button. If instead the command is originally
1713 invoked outside of any explicit button, it will prompt for the button
1714 label to replace and the label to replace it with and then will perform
1715 the rename. All occurrences of the same button in the buffer will be
1716 renamed, so you need locate only one occurrence of the button.
1718 @vindex file, .~/.emacs
1719 @vindex file, hsite.el
1721 The rename command may be invoked from the Hyperbole menu via
1722 Ebut/Rename. A faster method is to use a key bound to the
1723 @code{hui:ebut-rename} command. Your site installation may include such
1724 a key. @{@kbd{C-h w hui:ebut-rename @key{RET}}@} should show you any
1725 key it is on. If no key binding has been established or if you prefer
1726 one of your own, simply bind it within your @file{~/.emacs} file. We
1727 recommend the @{@kbd{C-c C-r}@} key, as in: @code{(global-set-key
1728 "\C-c\C-r" 'hui:ebut-rename)}.
1731 @node Deletion, Modification, Renaming, Utilizing Explicit Buttons
1732 @subsection Deletion
1734 @cindex explicit button, deleting
1735 @cindex button, deleting
1736 Ebut/Delete works similarly to the Rename command but deletes the
1737 selected button. The button's delimiters are removed to confirm the
1738 delete. If the delete command is invoked with a prefix argument, then
1739 both the button label and the delimiters are removed as confirmation.
1741 @vindex hui:ebut-delete-confirm-p
1742 Presently there is no way to recover a deleted button; it must
1743 be recreated. Therefore, the @var{hui:ebut-delete-confirm-p} variable
1744 is true by default, causing Hyperbole to require confirmation before
1745 interactively deleting explicit buttons. Set it to nil if you prefer no
1748 @node Modification, Location, Deletion, Utilizing Explicit Buttons
1749 @subsection Modification
1751 @cindex explicit button, modifying
1752 @cindex button, modifying
1753 @cindex Smart Mouse Key drag
1754 Ebut/Modify prompts you with each of the elements from the button's
1755 data list and allows you to modify each in turn.
1757 There is a quicker way to modify explicit link buttons. Simply drag with the
1758 mouse Action Key from within the button label to a link destination in a
1759 different window, just as you would when creating a new button with a mouse
1760 drag. Remember that drags may also be emulated from the keyboard.
1763 @node Location, Buttons in Mail, Modification, Utilizing Explicit Buttons
1764 @subsection Location
1766 @cindex explicit button, summarizing
1767 @cindex button, summarizing
1768 @cindex button, help
1769 The Ebut/Help menu can be used to summarize a single explicit button or
1770 all such buttons within a single buffer. The buttons summarized may
1771 then be activated directly from the summary.
1773 Ebut/Help/BufferButs summarizes the explicit buttons in the order in
1774 which they appear in the buffer. Ebut/Help/CurrentBut summarizes only
1775 the button at point. Ebut/Help/OrderedButs summarizes the buttons in
1776 alphabetical order. All of these summary commands eliminate duplicate
1777 instances of buttons from their help displays.
1779 @cindex explicit button, searching
1780 @cindex button, searching
1781 Ebut/Search prompts for a search pattern and searches across all the
1782 locations in which you have previously created explicit buttons. It
1783 asks you whether to match to any part of a button label or only complete
1784 labels. It then displays a list of button matches with a single line of
1785 surrounding context from their sources. Any button in the match list
1786 may be activated as usual. An Action Key press on the surrounding context
1787 jumps to the associated source line or a press on the filename preceding
1788 the matches jumps to the file without selecting a particular line.
1790 There are presently no user-level facilities for globally locating buttons
1791 created by others or for searching on particular button attributes.
1793 @node Buttons in Mail, Buttons in News, Location, Utilizing Explicit Buttons
1794 @subsection Buttons in Mail
1798 Hyperbole allows the embedding of buttons within electronic mail
1799 messages that are composed in Emacs with the standard @code{(mail)}
1800 command, normally bound to @{@kbd{C-x m}@} or with other Emacs-based
1801 mail composing functions. An enhanced mail reader can then be used
1802 to activate the buttons within messages just like any other buttons.
1804 @cindex button, mailing
1805 @cindex button, posting
1806 @cindex mailing buttons
1807 @cindex posting buttons
1809 @cindex mailer initialization
1817 @vindex file, hmail.el
1818 Hyperbole automatically supports the following mail readers: Rmail,
1819 @ref{Rmail,,,emacs, the GNU Emacs Manual}, VM, @ref{Introduction,,,vm,
1820 the VM Manual}, and PIEmail, and MH-e. Button inclusion and activation
1821 within USENET news articles is also supported in the same fashion via
1822 the GNUS news reader, @ref{Introduction,,,gnus, the GNUS Manual}, if
1823 available at your site. (The @file{hmail.el} file provides a
1824 generalized interface that can be used to hook in other mail or news
1825 readers if the necessary interface functions are written.)
1827 @vindex mail-yank-original
1829 @cindex mail inclusion
1830 All explicit buttons to be mailed must be created within the outgoing
1831 message buffer. There is no present support for including text from
1832 other buffers or files which contain explicit buttons, except for the
1833 ability to yank the contents of a message being replied to, together
1834 with all of its buttons, via the @code{(mail-yank-original)} command
1835 bound to @{@kbd{C-c C-y}@}. From a user's perspective, buttons are
1836 created in precisely the same way as in any other buffer. They also
1837 appear just like any other buttons to both the message sender and the
1838 reader who uses the Hyperbole enhanced readers. Button operation may be
1839 tested any time before a message is sent. A person who does not use
1840 Hyperbole enhanced mail readers can still send messages with embedded
1841 buttons since mail composing is independent of any mail reader
1844 Hyperbole buttons embedded within received mail messages act just like
1845 any other buttons. The mail does not contain any of the action type
1846 definitions used by the buttons, so the receiver must have these or she
1847 will receive an error when she activates the buttons. Buttons which
1848 appear in message @emph{Subject} lines are copied to summary buffers
1849 whenever such summaries are generated. Thus, they may be activated from
1850 either the message or summary buffers.
1852 Nothing bad will happen if a mail message with explicit buttons is sent
1853 to a non-Hyperbole user. The user will simply see the text
1854 of the message followed by a series of lines of button data at its end.
1855 Hyperbole mail users never see this data in its raw form.
1857 @vindex smail:comment
1858 @cindex mail comment
1859 In order to alert readers of your mail messages that you can utilize
1860 Hyperbole mail buttons, the system automatically inserts a comment into
1861 each mail message that you compose to announce this fact. The variable,
1862 @var{smail:comment} controls this behavior. See its documentation for
1863 technical details. By default, it produces a message of the form:
1866 Comments: Hyperbole mail buttons accepted, vX.XX.
1869 @vindex file, ~/.emacs
1871 where the X's indicate your Hyperbole version number. You can cut this
1872 out of particular messages before you send them. If you don't want any
1873 message at all, add the following to your @file{~/.emacs} file before
1874 the point at which you load Hyperbole.
1877 (setq smail:comment nil)
1880 @cindex actype, link-to-mail
1881 A final mail-related facility provided by Hyperbole is the ability to
1882 save a pointer to a received mail message by creating an explicit button
1883 with a @code{link-to-mail} action type. When prompted for the mail
1884 message to link to, if you press the Action Key on an Rmail message, the
1885 appropriate parameter will be copied to the argument prompt, as
1886 described in @ref{Entering Arguments}.
1889 @node Buttons in News, , Buttons in Mail, Utilizing Explicit Buttons
1890 @subsection Buttons in News
1892 @cindex button, posting
1893 @cindex news reader/poster
1894 @cindex posting news
1897 @vindex file, hgnus.el
1898 @vindex file, hsite.el
1899 Explicit buttons may be embedded within outgoing USENET news articles
1900 and may be activated from news articles that are being read. This
1901 support is available for the GNUS news reader. It is enabled by default
1902 within @file{hsite.el} by autoloading the @file{hgnus.el} file.
1904 All Hyperbole support should work just as it does when reading or
1905 sending mail. @xref{Buttons in Mail}. When reading news, buttons which
1906 appear in message @emph{Subject} lines may be activated within the GNUS
1907 subject buffer as well as the article buffer. When posting news, the
1908 *post-news* buffer is used for outgoing news articles rather than the
1911 Remember that the articles you post do not contain the action type
1912 definitions used by the buttons, so the receiver must have these or she
1913 will receive an error when he activates the buttons. You should also
1914 keep in mind that most USENET readers will not be using Hyperbole, so if
1915 they receive a news article containing explicit buttons, they will
1916 wonder what the button data at the end of the message is. You should
1917 therefore limit distribution of such messages. For example, if most
1918 people at your site read news with GNUS and use Hyperbole, it would be
1919 reasonable to embed buttons in postings to local newsgroups.
1921 @cindex news comment
1922 In order to alert readers of your postings that you can utilize
1923 Hyperbole mail buttons embedded within personal replies,
1924 the system automatically inserts the same comment that is included
1925 within mail messages to announce this fact. @xref{Buttons in Mail}, for
1926 details and an explanation of how to turn this feature off.
1928 @node Smart Keys, Menus, Buttons, Top
1932 @cindex mouse support
1937 Hyperbole provides two special @dfn{Smart Keys} that perform
1938 context-sensitive operations, the Action Key and the Assist Key. By
1939 default, the @dfn{Action Key} is bound to your shift-middle mouse button (or
1940 shift-left on a 2-button mouse) and the @dfn{Assist Key} is bound to your
1941 shift-right mouse button, assuming Hyperbole is run under an external window
1942 system. (InfoDock users should use the middle mouse button as the
1943 Action Key, instead.)
1945 @findex hmouse-shift-buttons
1946 Mouse configuration is automatic for InfoDock, XEmacs, and Epoch under
1947 the X window system and for GNU Emacs versions 18 and 19 under X,
1948 OpenWindows, NEXTSTEP, SunView and Apollo's Display Manager, assuming
1949 your Emacs program has been built with support for any of these window
1950 systems. The command, @code{hmouse-shift-buttons}, can be used to
1951 select between shifted and unshifted Smart Mouse Keys.
1956 By default (if @var{hkey-init} is set to @code{t} in @file{hsite.el}),
1957 then @{@kbd{M-@key{RET}}@} may also be used as the Action Key and
1958 @{@kbd{C-u M-@key{RET}}@} may be used as the Assist Key. In many
1959 read-only modes like Dired and Rmail,
1960 @{@key{RET}@} also functions as the Action Key. These key bindings allow
1961 context sensitive operation from any keyboard.
1963 @cindex key binding, smart keys
1964 @cindex smart key commands
1967 @findex action-mouse-key
1968 @findex assist-mouse-key
1969 If you prefer other key bindings, simply bind the commands
1970 @code{action-key} and @code{assist-key} to keyboard keys.
1971 @code{hkey-either} may be used instead if you prefer a single
1972 key binding for both commands; a prefix argument then invokes
1975 You may also bind @code{action-mouse-key} and @code{assist-mouse-key}
1976 to mouse keys, as you like.
1978 @cindex button activation
1981 The Action Key generally selects entities, creates links and
1982 activates buttons. The Assist Key generally provides help,
1983 such as reporting on a button's attributes, or serves a complementary
1984 function to whatever the Action Key does within a context.
1986 @cindex Smart Key operation
1987 You can get a summary of what the Smart Keys do in all of their
1988 different contexts by pressing the Assist Key in the right
1989 corner (within the rightmost 3 characters) of a window modeline or by
1990 using the Hyperbole Doc/SmartKy menu entry.
1992 The following table is an example of this summary. Much of the browsing
1993 power of Hyperbole comes from use of the Smart Keys, so you should spend
1994 some time practicing how to use them. This table may appear daunting at
1995 first, but as you practice and notice that the Smart Keys do just a few
1996 context-sensitive things per editor mode, you will find it easy to just
1997 point and click and let Hyperbole do the rest.
1999 For extensive reference documentation on the Smart Keys, @ref{Smart
2005 @include hypb-mouse.txt
2010 @include hypb-mouse.txt
2014 @vindex action-key-default-function
2015 @vindex assist-key-default-function
2016 Note how the last line in the table explains the default behavior of the
2017 Smart Keys. That is what they do when they cannot find a context match
2018 at your current location. See the documentation for the variables
2019 @var{action-key-default-function} and @var{assist-key-default-function}
2020 for information on how to customize the behavior of the Smart Keys
2021 within default contexts.
2023 @cindex Hyperbole help
2024 A prime design criterion of Hyperbole's user interface is that one
2025 should be able to see what an operation will do before using it.
2026 The Assist Key shows you what a button or minibuffer menu item will do
2027 before you activate it. Hyperbole also shows the result of directly
2028 selecting an argument value with the mouse, to provide feedback as to
2029 whether the right item has been selected. A second click is necessary
2030 before an argument is accepted and processed.
2032 @cindex Smart Key help
2033 @cindex help, Smart Key
2034 @cindex context sensitive help
2035 When you use a mouse and you want to find out what either of the Smart
2036 Keys does within a context, depress the one you want to check on and
2037 hold it down, then press the other and release as you please. A help
2038 buffer will pop up explaining the actions that will be performed in that
2039 context, if any. A press of either Smart Key at the end of that
2040 help buffer will restore your display to its configuration prior to
2045 By default (if @var{hkey-init} is left set equal to @code{t} in
2046 @file{hsite.el}), then @{@kbd{C-h A}@} will display this same
2047 context-sensitive help for the Action Key while @{@kbd{C-u C-h
2048 A}@} will display the help for the Assist Key. Note that
2049 @{@kbd{C-h a}@} will perform a function unrelated to Hyperbole, so you
2050 must press the shift key when you hit the @kbd{A} character.
2052 @cindex Smart Key toggle
2053 @cindex mouse key toggle
2054 @vindex file, ~/.emacs
2055 @vindex file, hsite.el
2057 When Hyperbole is installed, a key may be bound which allows you
2058 to switch between the Smart Key mouse bindings and your prior ones.
2059 @kbd{C-h w hmouse-toggle-bindings @key{RET}} should show you any key
2060 which performs this command. If no key binding has been established or
2061 if you prefer one of your own, simply select a key and bind it
2062 within your @file{~/.emacs} file. For example, @code{(global-set-key
2063 "\C-ct" 'hmouse-toggle-bindings)}.
2066 @node Menus, Entering Arguments, Smart Keys, Top
2073 @cindex menubar, Hyperbole menu
2074 Under InfoDock, XEmacs, and Emacs 19, pulldown and popup menus are
2075 available to invoke Hyperbole commands, including those from the rolodex
2076 and the outliner. These menus operate like any other X window menus.
2077 Use the Quit command on the Hyperbole menubar menu to get rid of the
2078 menu if you do not need it. Invoking Hyperbole again will add the menu
2079 back to the menubar.
2081 @cindex minibuffer menus
2082 This section discusses only the specialized @dfn{minibuffer menus} that
2083 appear in the minibuffer window and that work with all Emacs versions.
2084 Minibuffer menu items may be selected from either the keyboard or via
2085 mouse clicks. When used with the keyboard, they provide rapid command
2086 access similar to key bindings.
2089 @vindex action-key-default-function
2090 @cindex menu, top level
2091 The top level menu is invoked from a key given in your @file{hsite.el}
2092 file (by default, @{@kbd{C-h h}@}) or via an Action Key press in a
2093 location with no other action defined. The menu will appear in the
2094 minibuffer and should look mostly like so:
2098 Hy4> Act Butfile/ Doc/ Ebut/ Gbut/ Hist Ibut/ Msg/ Otl/ Rolo/ Win/
2102 The above menu items can be summarized as follows:
2107 Perform the action associated with any button at point or prompt for the
2108 name of an explicit button to activate if point is not on one.
2110 @cindex menu, ButFile
2111 @cindex button file, HYPB
2114 Display a local or global file of buttons, providing easy access.
2115 @file{HYPB} for a local button file and @file{~/.hyperb/HYPB} for your
2116 global file. These are good places to start your button creation testing.
2120 All explicit button commands.
2125 Hyperbole documentation quick access. Contains Types/ submenu for
2126 documentation on Hyperbole implicit button and action types.
2128 @cindex menu, Global Buttons
2130 All global button commands. Global buttons are accessed by name
2131 rather than by direct selection.
2133 @cindex menu, History
2136 Jumps back to last position in button traversal history.
2138 @cindex menu, Implicit Buttons
2140 All implicit button commands.
2142 @cindex menu, Message
2144 Hyperbole-specific mail and news messaging support commands.
2145 Use this to send mail to the Hyperbole discussion list or to
2146 add/modify your entry on a Hyperbole mail list.
2148 @cindex menu, Outliner
2150 Autonumbered, structured outliner and hyper-node manager commands.
2153 @cindex menu, Rolodex
2155 Hierarchical, multi-file rolodex lookup and edit commands.
2158 @cindex menu, Window Configurations
2159 @cindex menu, Windows
2161 Window configuration management such as adding and restoring window
2162 configurations by name. @xref{Window Configurations}.
2168 @cindex help, menu items
2169 All menu items are selected via the first character of their names
2170 (letter case does not matter) or via a press of the Action Key. "/" at
2171 the end of an item name indicates that it brings up a sub-menu. A press
2172 of the Assist Key on an item displays help for the item, including the
2173 action that it performs.
2178 While a menu is active, to re-activate the top-level Hyperbole menu, you
2179 must use @{@kbd{C-t}@}. This allows you to browse the submenus and then
2180 return to the top. You can quit without selecting an item by using
2181 @{@kbd{q}@}. @{@kbd{C-g}@} aborts whether you are at a menu prompt or
2182 any other Hyperbole prompt.
2186 @node Entering Arguments, Outliner, Menus, Top
2187 @chapter Entering Arguments
2189 @cindex argument entry
2190 @cindex direct selection
2191 @cindex double click
2192 Many Hyperbole commands prompt you for arguments. The standard
2193 Hyperbole user interface has an extensive core of argument types that it
2194 recognizes. Whenever Hyperbole is prompting you for an argument, it
2195 knows the type that it needs and provides some error checking to help
2196 you get it right. More importantly, it allows you to press the Action
2197 Key within an entity that you want to use as an argument and it will grab the
2198 appropriate thing and show it to you at the input prompt within the
2199 minibuffer. If you press the Action Key again at the same point (click
2200 with a mouse) on the same thing again, it accepts the entity as the
2201 argument and moves on. Thus, a double click registers a desired
2202 argument. Double-quoted strings, pathnames, mail messages, Info nodes,
2203 dired listings, buffers, numbers, completion items and so forth are all
2204 recognized at appropriate times. All of the argument types mentioned in
2205 the documentation for the Emacs Lisp @code{(interactive)} function are
2206 recognized. Experiment a little and you will quickly get used to this
2207 direct selection technique.
2210 Wherever possible, standard Emacs completion is offered, see
2211 @ref{Completion,,,emacs, the Gnu Emacs Manual}. Remember to use @{@kbd{?}@}
2212 to see what your possibilities for an argument are. Once you have a
2213 list of possible completions on screen, you can double click the Action
2214 Key on any one to enter it as the argument.
2217 @node Outliner, Rolodex, Entering Arguments, Top
2222 @cindex relative autonumber
2223 @cindex permanent identifier
2225 @cindex hyperlink anchor
2226 The Hyperbole outliner, also known as the Koutliner (pronounced
2227 Kay-outliner), produces structured, autonumbered documents composed of
2228 hierarchies of cells. Each @dfn{cell} has two identifiers, a
2229 @dfn{relative identifier} indicating its present position within the
2230 outline and a @dfn{permanent identifier} called an @dfn{idstamp},
2231 suitable for use within hyperlink references to the cell. The idstamp
2232 is typically not displayed but is available when needed.
2233 @xref{Autonumbering}.
2235 Cells also store their time of creation and the user who created the
2236 cell. User-defined attributes may also be added to cells. @xref{Cell
2239 @cindex menu, Outline
2240 The outliner works only under GNU Emacs version 19 or higher, XEmacs
2241 version 19.9 or higher or under InfoDock. You can tell whether you are
2242 running a version of Emacs which supports the outliner by hitting
2243 @{@kbd{C-h h}@} to display the Hyperbole menu. If you see an
2244 @code{Otl/} entry in the menu, then the outliner is available.
2245 Otherwise, the outliner does not work with your version of Emacs, so
2246 this section of the manual will not be of interest to you. (The same is
2247 true of the Hyperbole/Outline pulldown menu; if it appears, the outliner
2248 is available for use.)
2250 @vindex file, EXAMPLE.kotl
2251 @cindex menu, Outline/Example
2252 This chapter expands on the information given in @file{EXAMPLE.kotl}
2253 file included with Hyperbole. Use @{@kbd{C-h h o e}@} to display that
2254 file. It is an actual outline file that explains major outliner
2255 operations. You can test out the viewing and motion commands with this
2256 file. If you want to experiment with editing operations, use @{@kbd{C-x
2257 C-w}@} to write the outline to a temporary file such as,
2258 @file{/tmp/e.kotl}, and then use @{@kbd{C-x C-q}@} to make the outline
2261 @xref{Outliner Keys}, for a full summary of the key bindings and
2262 commands available in the outliner.
2266 * Creating Outlines::
2273 * Outliner History::
2277 @node Menu Commands, Creating Outlines, Outliner, Outliner
2278 @section Menu Commands
2280 The Otl/ menu entry on the Hyperbole top-level menu provides access to
2281 a number of major outliner commands:
2285 @cindex outliner commands
2286 @cindex Koutliner commands
2287 @findex kotl-mode:show-all
2288 @findex kvspec:toggle-blank-lines
2290 @findex kotl-mode:hide-sublevels
2291 @findex kotl-mode:hide-tree
2292 @findex kotl-mode:kill-tree
2293 @findex klink:create
2294 @findex kotl-mode:overview
2295 @findex kotl-mode:show-tree
2296 @findex kotl-mode:top-cells
2297 @findex kvspec:activate
2298 @cindex menu, Outline
2299 Menu Item Command Description
2300 ====================================================================
2301 All kotl-mode:show-all Expand all cells
2302 Blanks kvspec:toggle-blank-lines Toggle blank lines on or off
2303 Create kfile:find Edit or create an outline
2304 Downto kotl-mode:hide-sublevels Hide cells deeper than a level
2305 Examp <sample outliner file> Show self-descriptive example
2306 Hide kotl-mode:hide-tree Hide tree with root at point
2307 Info <outliner documentation> Show outliner manual section
2308 Kill kotl-mode:kill-tree Kill the current tree
2309 Link klink:create Create a link to another cell
2310 Overvw kotl-mode:overview Show first line of each cell
2311 Show kotl-mode:show-tree Show tree with root at point
2312 Top kotl-mode:top-cells Collapse to top-level cells
2313 Vspec kvspec:activate Set a view specification
2314 ====================================================================
2319 @node Creating Outlines, Autonumbering, Menu Commands, Outliner
2320 @section Creating Outlines
2322 @cindex outline file suffix
2323 @cindex outline, creating
2324 @vindex file, .kotl suffix
2325 In addition to the Otl/Create menu item, you can create and experiment
2326 with outline files simply by finding a file, @{@kbd{C-x C-f}@} with a
2327 @file{.kotl} suffix. @file{.kot} will also work for DOS or
2328 Windows-impaired users.
2331 @cindex top-level cell
2332 @cindex cell, top-level
2333 @cindex cell, idstamp 0
2334 When a new koutline is created, an invisible root cell is created. Its
2335 permanent and relative ids are both 0, and it is considered to be at
2336 level 0 in the outline. All visible cells in the outline are at level 1
2337 or deeper, and thus are descendants of this root cell. Some koutliner
2338 commands prompt for cell numbers as arguments. An argument of 0 makes
2339 commands operate upon the entire outline.
2341 An initial level 1 cell is also created to make it easy to start
2342 entering text in the outline. A koutline always has at least one
2345 @xref{Autonumbering}, which explains how cells are labeled according to their
2346 respective levels in the outline and how these labels are updated as the
2347 structure of the outline changes.
2350 @node Autonumbering, Idstamps, Creating Outlines, Outliner
2351 @section Autonumbering
2354 @cindex relative identifier
2355 @xref{Adding and Killing}, which explains how to add new cells to or remove
2356 cells from a koutline. As you do this, or as you promote or demote
2357 cells within the outline, the labels preceding the contents of each cell
2358 automatically update to reflect the new structure. These labels are
2359 also known as @dfn{autonumbers} and as @dfn{relative ids} because they
2360 change as the structure changes.
2362 @cindex outline structure
2363 The outline structure is shown by these labels and by the indentation of
2364 each outline level. Normally, each deeper level is indented another
2365 three characters, to reflect the nesting.
2367 @cindex label type, alpha
2368 @cindex label type, legal
2369 @cindex alpha labels
2370 @cindex legal labels
2371 @cindex outline, label type
2372 The default autonumbers are called @dfn{alphanumeric labels} because
2373 they alternate between using numbers and letters to distinguish each
2374 successive level. Each alphanumeric label uniquely identifies a cell's
2375 position in an outline, so that there is no need to scan back to prior
2376 cells to see what the current section number of an outline is. This is
2377 similar to a legal numbering scheme but without all the period
2378 characters between level numbers. As an example, 1b3 is equivalent to a
2379 legal label of 1.2.3. Both refer to the 3rd cell at level 3,
2380 below the 2nd child of the first cell at level 1. Said another way,
2381 this is the 3rd child of the 1st cell's 2nd child. In other words, it
2382 is easier to visualize hierarchies than to talk about them.
2384 Alphanumeric labels are the default because they are shorter and easier
2385 to read aloud than equivalent legal ones. They also simplify
2386 distinguishing between even and odd level labels because of the
2387 alternating character set.
2390 @cindex label type, changing
2391 You can change the labeling scheme used in a particular outline with the
2392 command @{@kbd{C-c C-l}@}. A @{@kbd{?}@} then will show all of your
2393 options. Legal labels, partial alpha labels (single level autonumbering
2394 where only the last part of the level number is shown, as commonly seen
2395 in other outliner products), idstamps (permanent cell ids), and star
2396 outline level labels (Emacs asterisk-based outline labeling) are all
2397 available. Or you may choose to turn autonumbering off. Cells are
2398 still indented to reflect the outline structure whether or not labels
2401 @cindex label separator, changing
2402 @cindex cell, label separator
2403 @cindex outline, label separator
2406 A cell label is normally followed by two spaces, called the @dfn{label
2407 separator}, prior to the start of the cell contents. You can change the
2408 separator with for the current outline with @{@kbd{C-c M-l}@}.
2409 @{@kbd{C-u C-c M-l}@} will additionally change the default separator
2410 value used when new outlines are created (for the current session only).
2411 For example, use the value ". " to get a trailing period after each cell
2412 label. The separator must be at least two characters long but may be
2415 @vindex file, ~/.emacs
2416 @cindex initialization file
2417 If you find a separator that you prefer for all outlines, change the
2418 separator setting permanently by adding the following line to your Emacs
2419 initialization file, @file{~/.emacs}, substituting for `your-separator':
2421 @cindex label separator, default
2422 @vindex kview:default-label-separator
2424 (setq kview:default-label-separator "your-separator")
2428 @node Idstamps, Editing, Autonumbering, Outliner
2431 @cindex permanent identifier
2433 Idstamps (permanent ids) are associated with each cell and can be
2434 used in hyperlinks that are maintained as cells are reordered in a file.
2435 @xref{Links}. Idstamps may also be displayed in place of the outline
2436 level relative ids. Use @{@kbd{C-c C-l id RET}@}.
2438 @cindex idstamp counter
2439 An idstamp counter for each outline starts at 0 and is incremented by
2440 one each time a cell is added to the outline. This idstamp stays with
2441 the cell no matter where it is moved within the outline. If the cell is
2442 deleted, its idstamp is not reused.
2445 @cindex top-level cell
2446 @cindex cell, top-level
2447 @cindex cell, idstamp 0
2449 The 0 idstamp is always assigned to the root node of the entire outline.
2450 This node is never visible within the outline, but is used so that the
2451 outline may be treated as a single tree when needed. Idstamps always
2452 begin with a 0, as in 012, to distinguish them from relative ids.
2455 @node Editing, Viewing, Idstamps, Outliner
2458 You edit text and move around in the Koutliner just as you would in any
2459 other Emacs buffer, except when you want to deal with the structural
2460 components of an outline. Within the contents of a cell, all of your
2461 standard editing keys should work properly. You can just type in text
2462 and the left and right margins of the lines will be maintained for you.
2463 @xref{Filling}, for the times when you need to refill a paragraph or to
2464 control when filling occurs.@refill
2466 Don't invoke editing commands with @{@kbd{M-x command-name @key{RET}}@}
2467 since the Koutliner uses special differently named commands made to act
2468 like the regular editing commands but which account for the structure
2469 and indentation in koutlines.
2471 @cindex cell, selection
2472 You can use the mouse to select parts of the contents of a single cell
2473 for editing. But don't drag across cell boundaries and then edit the
2474 selected region, since that can destroy the outline structure.
2477 * Adding and Killing::
2479 * Relocating and Copying::
2482 * Splitting and Appending::
2483 * Inserting and Importing::
2486 @node Adding and Killing, Relocating and Copying, Editing, Editing
2487 @subsection Adding and Killing
2493 @cindex cell, adding
2494 @cindex cell, creating
2495 @{@kbd{C-j}@} adds a new cell as a successor sibling of the
2496 current cell, that is, the next cell at the same level as the current
2497 cell. If you enter a positive number as a prefix argument, that number
2498 of cells will be inserted, all at the same level. @{@kbd{C-u C-j}@} is
2499 handled specially. It adds a single cell as a child of the current cell.
2500 @{@kbd{C-c a}@} does the same thing. @{@kbd{C-c p}@} adds the cell as
2501 the successor of the current cell's parent.
2507 @cindex cell, killing
2508 @cindex cell, yanking contents
2509 @cindex tree, killing
2510 @{@kbd{C-c C-k}@} kills the current cell and its entire subtree.
2511 @{@kbd{C-c k}@} kills the contents of a cell from point through the end
2512 of the cell; it does not remove the cell itself. @{@kbd{C-u C-c k}@}
2513 kills the entire contents of the cell regardless of the location of
2514 point. You may then yank the contents into another cell or another
2515 buffer with @{@kbd{C-y}@}.
2518 @node Relocating and Copying, Moving Around, Adding and Killing, Editing
2519 @subsection Relocating and Copying
2523 @cindex tree, promoting
2524 @cindex tree, demoting
2525 @dfn{Demotion} is the act of moving a tree down one or more levels in the
2526 outline. The new tree will become either the successor or the first
2527 child of the cell which precedes it in the outline. @dfn{Promotion} is
2528 the inverse operation. Note that trees (cells and their entire
2529 substructure) are promoted and demoted, not individual cells.
2533 Trees may be demoted or promoted by pressing @{@key{TAB}@} or
2534 @{@kbd{M-@key{TAB}}@} respectively, as in most outliners today.
2535 @{@kbd{M-0 @key{TAB}}@} and @{@kbd{M-0 M-@key{TAB}}@} demote and
2536 promote trees and additionally refill each cell that is not specially
2537 marked to prevent refilling. @xref{Filling}. A positive or negative
2538 prefix argument to these commands promotes or demotes the tree up to a
2539 maximum of the number of levels given by the argument. The outline may
2540 not support movement of the tree by the number of levels requested.
2542 @cindex tree, copying
2543 @cindex tree, moving
2544 @cindex Action Key, cell argument
2545 @kindex Action Key, cell argument
2546 For maximum flexibility in rearranging outlines, there are commands that
2547 move or copy entire trees. Each of these commands prompts for the label
2548 of the root cell to move or copy and for second cell at the new location
2549 for the moved or copied tree. You can either accept the default
2550 provided, type in the cell label or when a mouse is available, simple
2551 double click with the Action Key on the contents of a cell. The
2552 Koutliner knows to use the cell's label in such cases.
2554 In these following commands, words delimited with <> represent the
2555 arguments for which each command prompts. Note how the use of prefix
2556 arguments changes each command's behavior from insertion at the sibling
2557 level to insertion at the child level.
2562 Copy <tree> to be the successor of <cell>.
2565 Copy <tree> to follow as the first child of <cell>.
2569 Copy <tree> to be the predecessor of <cell>.
2572 Copy <tree> to be the first child of the parent of <cell>.
2576 Move <tree> to be the successor of <cell>.
2579 Move <tree> to follow as the first child of <cell>.
2583 Move <tree> to precede <cell>.
2586 Move <tree> to be the first child of the parent of <cell>.
2589 @cindex mouse, moving trees
2590 If you have mouse support under Hyperbole, you can move entire trees
2591 with mouse clicks. Simply click the Assist Key within the indentation
2592 to the left of a cell and you will be prompted for a tree to move.
2593 Double click the Action Key within the contents the root cell of the tree
2594 to move and then double click within the contents of the root cell of the
2595 tree you want it to follow as a sucessor.
2597 Copying and moving only work within a single outline right now, so don't
2598 try to use them to move trees across different outline files. You can,
2599 however, copy an outline tree to a non-outline buffer with:
2601 @cindex tree, exporting
2602 @cindex outline, exporting
2603 @cindex tree, mailing
2604 @cindex outline, mailing
2605 @cindex exporting an outline
2606 @cindex mailing an outline
2610 Copy <tree> to a non-koutline buffer.
2613 Copy a <tree> to an outgoing mail message.
2616 @node Moving Around, Filling, Relocating and Copying, Editing
2617 @subsection Moving Around
2619 @cindex outline, motion
2620 In addition to normal Emacs movement commands, you can move within a
2621 cell or from one cell or tree to another.
2626 Move to the beginning of the current cell.
2629 Move to the end of the current cell.
2633 Move to the next visible cell, regardless of level.
2636 Move to the previous visible cell, regardless of level.
2640 Move forward to this cell's successor, if any.
2643 Move backward to this cell's predecessor, if any.
2647 Move to the first child of the current cell, if any.
2650 Move to the parent cell of the current cell, if any.
2654 Move to the first sibling at the current level within this tree.
2657 Move to the last sibling at the current level within this tree.
2661 Move to the level 1 root cell of the current tree.
2664 Move to the last cell in the tree rooted at point, regardless of level.
2668 @node Filling, Transposing, Moving Around, Editing
2671 @cindex outline, filling
2672 Filling is the process of extending lines that are shorter than the
2673 right margin and reducing lines which extend past the margin by moving
2674 words among the lines. Commands are provided to fill a paragraph within
2675 a cell or a whole cell, which may have multiple paragraphs.
2678 @cindex cell, filling
2679 @cindex paragraph, filling
2680 @cindex tree, filling
2688 @{@kbd{M-q}@} or @{@kbd{M-j}@} refills a paragraph within a
2689 cell so that its lines wrap within the current margin settings.
2690 @{@kbd{C-c M-q}@} or @{@kbd{C-c M-j}@} refills all paragraphs within a
2691 cell. @{@kbd{C-M-q}@} or @{@kbd{C-M-j}@} refills all cells within a
2692 tree. See your Emacs or InfoDock manual for information on how to set
2693 the left and right margins.
2695 @vindex kotl-mode:refill-flag
2697 @cindex attribute, no-fill
2698 @cindex cell, no-fill attribute
2699 Set the variable, @var{kotl-mode:refill-flag}, to t if you want
2700 moving, promoting, demoting, exchanging, splitting and appending cells
2701 to also automatically refill each cell. Generally, this is not
2702 recommended since if you happen to move a cell that you have carefully
2703 formatted and forgot to give it a `no-fill' property, your formatting
2707 @node Transposing, Splitting and Appending, Filling, Editing
2708 @subsection Transposing
2710 The Koutliner move and copy commands rearrange entire trees. The
2711 following two commands, in contrast, exchange the locations of two
2715 @cindex cell, transposing
2716 @cindex cell, exchanging
2717 @cindex exchanging cells
2718 @cindex transposing cells
2719 @{@kbd{C-c e}@} prompts for two cell addresses and exchanges the cell
2723 @{@kbd{C-c t}@} does not prompt. It exchanges the current
2724 and immediatly prior cell, regardless of their levels. If there is no
2725 prior cell it exchanges the current and next cell.
2727 @cindex cell, mark and point
2729 @{@kbd{M-0 C-c t}@} exchanges the cells in which point and mark fall.
2730 @{@kbd{C-c t}@} with a non-zero numeric prefix argument, N, moves
2731 the current tree past maximally the next N visible cells. If there are
2732 fewer visible, it makes the current cell the last cell in the outline.
2735 @node Splitting and Appending, Inserting and Importing, Transposing, Editing
2736 @subsection Splitting and Appending
2738 @cindex splitting a cell
2739 @cindex cell, splitting
2742 You can split one cell into two adjacent sibling cells with @{@kbd{C-c
2743 s}@}. This leaves the cell contents preceding point in the current
2744 cell, minus any trailing whitespace, and moves the contents following
2745 point to a new sibling cell which is inserted into the outline.
2746 @{@kbd{C-u C-c s}@} instead adds the new cell as the first child of the
2747 original cell, rather than as its successor.
2749 All cell attributes in the original cell are propagated to the new one,
2750 aside from the creation attributes and idstamp.
2753 @cindex cell, appending
2754 @cindex appending to a cell
2755 @cindex attribute, no-fill
2756 @cindex cell, no-fill attribute
2757 @{@kbd{C-c +}@} appends the contents of a specified cell to the end of
2758 another cell. It has no effect on cell attributes, except that if one
2759 cell has a `no-fill' attribute that prevents all but user requested
2760 filling of a cell, then the cell appended to inherits this property.
2761 This helps maintain any special formatting the appended text may have.
2764 @node Inserting and Importing, , Splitting and Appending, Editing
2765 @subsection Inserting and Importing
2767 @cindex outline, inserting into
2768 @cindex outline, importing into
2772 @cindex outline, foreign file
2773 The elements of another buffer or file may be inserted into a koutline
2774 as a set of cells by using the @{@kbd{C-x i}@} command. When prompted,
2775 you may use a buffer name or file name from which to insert, though
2776 completion is provided only for file names.
2779 The elements from the original buffer are converted into kcells and
2780 inserted as the successors of the current cell. If @{@kbd{C-u C-x i}@}
2781 is used, they are instead inserted as the inital children of the current
2784 @vindex kimport:mode-alist
2785 @vindex kimport:suffix-alist
2786 @cindex outline, conversion
2788 @cindex outline mode
2789 @cindex koutline mode
2790 @cindex file, importing
2791 @cindex importing a file
2792 See the documentation for the variables, kimport:mode-alist and
2793 kimport:suffix-alist, for information on mode and suffix-specific
2794 conversions performed on file elements before they are inserted. This
2795 same conversion process applies if you invoke @{@kbd{M-x kotl-mode
2796 RET}@} in a non-koutline buffer or if you perform a generic file import
2797 as described later in this section.
2799 @findex kotl-mode:insert-file-contents
2800 Use @{@kbd{M-x kotl-mode:insert-file-contents RET}@} to insert the
2801 entire contents of a file into the current cell at the location of
2804 @findex kimport:file
2805 The outliner presently supports conversion of three types of files into
2806 koutline files. You can choose to import a file into an existing
2807 koutline, following the tree at point, or to create a new koutline of
2808 the imported file contents. @{@kbd{M-x kimport:file RET}@} will select
2809 the importation type based on the buffer or file name suffix of the file
2813 If you want to convert a buffer from some other mode into a koutline and
2814 then want to save the converted buffer back to its original file,
2815 thereby replacing the original format, then use @{@kbd{M-x kotl-mode
2816 RET}@} to convert the buffer into a koutline. Remember that you will
2817 lose the old format of the buffer when you do this.
2819 Use one of the following commands if you really need explicit control over the
2820 type of importation used on some text. With these commands, your
2821 original file remains intact.
2823 @findex kimport:text
2825 Use @{@kbd{M-x kimport:text RET}@} and you will be prompted for a text
2826 buffer or file to import and the new koutline buffer or file to create
2827 from its text. It will also import the contents, attributes and level
2828 structure of cells from a koutline.
2830 @findex kimport:star-outline
2831 @cindex emacs outline
2832 @cindex star outline
2833 Star outlines are standard Emacs outlines where each entry begins with
2834 one or more asterisk characters. Use @{@kbd{M-x kimport:star-outline
2835 RET}@} and you will be prompted for the star outline buffer or file to
2836 import and the new koutline buffer or file to create.
2838 @cindex Augment outline
2839 @findex kimport:aug-post-outline
2840 (Skip this if you are unfamiliar with the Augment system.) Files
2841 exported from the Augment system as text often have alphanumeric
2842 statement identifiers on the right side. You can import such files
2843 while maintaining there outline structure. Use @{@kbd{M-x
2844 kimport:aug-post-outline RET}@} and you will be prompted for the Augment
2845 buffer or file to import and the koutline to create.
2848 @node Viewing, Links, Editing, Outliner
2851 @cindex outline, viewing
2853 The Koutliner has very flexible viewing facilities to allow you to
2854 effectively browse and study large amounts of material.
2857 * Hiding and Showing::
2861 @node Hiding and Showing, View Specs, Viewing, Viewing
2862 @subsection Hiding and Showing
2864 @cindex outline, hiding
2865 @cindex outline, showing
2870 Individual cells, branches, or particular levels in the outline may be
2871 hidden or shown. These commands work even when an outline buffer is
2872 read-only, e.g. when its file is not checked out of a version control
2873 system yet, so that you can get effective views of an outline without
2874 editing it. Some of these commands affect the current view spec,
2882 Hide (collapse) the tree rooted at point.
2887 Show (expand) the tree rooted at point.
2889 @cindex outline, all cells
2890 @cindex cell, show all
2893 Show (expand) all of the cells in the outline.
2895 @cindex cell, show levels
2896 @cindex outline, show levels
2899 Show all of the cells down to a particular <level>. You are prompted
2900 for the level or a prefix argument may be given.
2902 @cindex subtree, hide
2903 @cindex tree, hide subtree
2904 @cindex cell, hide subtree
2905 @cindex hide subtree
2908 Hide the subtree at point, excluding the root cell.
2909 @cindex subtree, show
2910 @cindex tree, show subtree
2911 @cindex cell, show subtree
2912 @cindex show subtree
2913 @item M-x kotl-mode:show-subtree
2914 Show the subtree at point. Use @{@kbd{C-c C-s}@} to achieve a similar
2915 effect. The only difference is that it will expand the root cell too.
2918 @cindex outline, overview
2921 Show an overview of the outline by showing only the first line of
2922 every cell. This also turns off blank lines between cells to maximize
2923 your view of the outline.
2924 @cindex top-level view
2925 @cindex outline, top-level
2928 Show a top-level view of the outline by showing only the first line of
2929 each level one cell. This does not turn off blank lines.
2932 @kindex Action Key, hide or show cell
2933 @cindex Action Key, hide or show cell
2934 @cindex cell, collapse
2935 @cindex cell, expand
2937 A click or a press of the Action Key within a cell's body, but not on a
2938 Hyperbole button, toggles between hiding and showing the tree rooted at
2939 point. Try it with either your mouse or with @{@kbd{M-@key{RET}}@}.
2942 @node View Specs, , Hiding and Showing, Viewing
2943 @subsection View Specs
2946 @cindex modeline, view spec
2947 @vindex kvspec:string
2948 @cindex pipe character
2951 @dfn{View specifications} (view specs, for short) are short codes used
2952 to control the view of a koutline. The view specs in effect for an
2953 outline are always displayed in the modeline of the outline's window,
2954 following the outline buffer name, unless the variable,
2955 @var{kvspec:string}, has been set to @code{nil} to disable view spec
2956 modeline display. The modeline display appears as <|viewspec> so that
2957 you can easily pick them out. The | (pipe character) is also used in
2958 links that specify view specs to indicate the start of a view spec
2959 sequence. @xref{Links}.
2961 @cindex outline, view specs
2962 The current view spec is saved whenever the outline is saved. The next
2963 time the outline is read in, this will be the initial view.
2965 The rest of this section documents the the view spec characters that are
2966 presently supported and explains how to invoke a view spec. There is no
2967 user-level way to add your own view spec characters, so all character
2968 codes are reserved for future use.
2971 @cindex view spec, setting
2972 @cindex view spec, changing
2973 @cindex changing the view spec
2974 @cindex setting the view spec
2975 @{@kbd{C-c C-v}@} prompts for a new view spec setting in which the following
2976 codes are valid. Any invalid characters in a view spec are ignored.
2977 Characters are evaluated in an order meant to do the right thing, even
2978 when you use conflicting view spec characters. The standard initial
2979 view spec is <|ben>.
2981 @cindex view spec, characters
2983 @cindex view spec, all lines and levels
2985 Show all cell levels and all lines in cells.
2988 @cindex blank lines, toggle
2989 @cindex view spec, blank lines
2991 @cindex toggling blank lines
2993 Turn on blank lines between cells. Without this character, blank lines
2994 will be turned off. You can also use the @{@kbd{C-c b}@} key binding to
2995 toggle line numbers on and off independent of any other view settings.
2997 @cindex view spec, lines per cell
2999 @cindex collapse lines
3000 @cindex cutoff lines
3002 Hide any lines greater than N in each cell. 0 means don't cutoff any
3006 @cindex view spec, ellipses
3008 Show ellipses when some content of a cell or its subtree is hidden.
3011 @cindex cell, hiding levels
3013 @cindex view spec, show levels
3015 Hide cells at levels deeper than N. 0 means don't hide any cells.
3018 @cindex view spec, label type
3019 @vindex kview:default-label-type
3020 @cindex default label type
3022 Turn on the default label type, as given by the variable,
3023 @var{kview:default-label-type}. Normally, this is alphanumeric labels.
3024 @cindex label type, idstamps
3027 @cindex label type, alpha
3029 Display alpha labels.
3030 @cindex label type, partial alpha
3032 Display partial alpha labels (don't use this, as full alpha labels are
3034 @cindex label type, legal
3036 Display legal labels.
3037 @cindex label type, star
3038 @cindex label type, asterisk
3040 Display star labels. A level three cell would have three asterisks as a
3042 @cindex label type, no labels
3044 Turn off labels. (n viewspec is removed from modeline).
3047 @cindex view spec, example
3048 As a test, use @{@kbd{C-h h o e}@} to display the example koutline.
3049 Then use @{@kbd{C-c C-v}@} to set a view spec of `c2l1'. This will turn
3050 off blank lines, clip each cell after its second line, and hide all
3051 cells below level one.
3054 @node Links, Cell Attributes, Viewing, Outliner
3060 @cindex <> delimiters
3061 Hyperlinks may be embedded in cells and may refer to other cells or
3062 external sources of information. Explicit Hyperbole buttons may be
3063 created as usual via mouse drags, @ref{By Dragging, Creation Via Action
3064 Key Drags}. A @dfn{klink} is a special implicit link button, delimited
3065 by <> separators, that jumps to a specific outline cell. This section
3068 @kindex Action Key, klink
3069 @cindex Action Key, klink
3070 @cindex klink, activating
3071 @cindex klink referent
3072 Press the Action Key over a klink to follow it. This will flash the
3073 klink as a button and then will display its referent in the other
3074 window. If the klink contains a view spec, that will be used when the
3075 referent is displayed.
3077 @cindex klink, inserting
3079 There are a number of easy ways to insert klinks into koutlines. If you
3080 have mouse support under Hyperbole, simply click the Action Key within
3081 the indentation to the left of a cell text. If you then double click on
3082 some cell, a link to that cell will be inserted where you started. From
3083 a keyboard, use @{@kbd{C-c l}@} when in a koutline or @{@kbd{C-h h o
3084 l}@} when not in a koutline to insert a klink. Since klinks are
3085 implicit buttons, you can type in the text of the klink just as you see
3086 it in the examples below and it will work exactly as if it had been
3087 entered with the insert link command.
3089 @cindex klink, formats
3091 There are basically three forms of klinks:
3094 @cindex internal klink
3095 @cindex klink, internal
3098 <@@ 2b=06> is an internal klink, since it refers to the koutline in which
3099 it is embedded. When activated, it jumps to the cell within the current
3100 outline which has permanent id `06' and relative id `2b'. <@@ 06> does
3101 the same thing, as does <@@ 2b>, though this latter form will not
3102 maintain the link properly if the cell is moved elsewhere within the
3103 outline. The form, <@@ 2b=06 |ben> additionally sets the view spec of
3104 the current outline back to the default value, with a blank line between
3105 each cell and all levels and lines of cells displayed.
3107 @cindex external klink
3108 @cindex klink, external
3110 The second klink format is an external link to another koutline, such
3111 as, <EXAMPLE.kotl, 3=012 |c1e>, which displays the named file, starting
3112 at the cell 3 (whose permanent identifer is 012), with the view
3113 specification of: blank lines turned off, cutoff after one line per
3114 cell, and show ellipses for cells or trees which are clipped.
3116 @cindex klink, view spec
3117 @cindex view spec klink
3119 The third format simply allows you to set a view spec for the current
3120 koutline. For example, <|ben>, when activated, sets the view in the
3121 current outline to display blank lines, ellipses following collapsed
3122 lines and standard alphanumeric numbering.
3126 @node Cell Attributes, Outliner History, Links, Outliner
3127 @section Cell Attributes
3129 @cindex cell, attribute
3131 @dfn{Attributes} are named variables whose values are specific to a
3132 particular outline cell. Thus, each cell has its own attribute list.
3133 Every cell has three standard attributes:
3136 @cindex idstamp attribute
3138 The permanent id of the cell, typically used in cross-file hyperlinks
3139 that reference the cell.
3141 @cindex creator attribute
3142 @cindex e-mail address
3143 @cindex mail address
3145 The e-mail address of the person who created this cell.
3147 @cindex create-time attribute
3148 @cindex cell, creation time
3150 The time at which the cell was created. This is stored in a form that
3151 allows for easy data comparisons but is displayed in a human readable
3152 format, such as "Jan 28 18:27:59 CST 1994".
3156 @cindex attribute, adding
3157 @cindex attribute, modifying
3158 @cindex attribute, removing
3159 @{@kbd{C-c C-i}@} is the command to add an attribute to or to modify an
3160 existing attribute in the cell at point. Think of it as inserting an
3161 attribute value. To remove an attribute from cell, set its value to
3165 @cindex attribute, no-fill
3166 @cindex cell, no-fill attribute
3167 @cindex no-fill attribute
3168 @vindex kotl-mode:refill-flag
3169 The `no-fill' attribute is special. When added with a non-nil value, it
3170 prevents moving, promoting, demoting, exchanging, splitting and
3171 appending cells from refilling the cell, even if the variable,
3172 @var{kotl-mode:refill-flag}, is set to t. It does not prevent you from
3173 invoking explicit commands that refill the cell. @xref{Filling}.
3175 @kindex Assist Key, listing attributes
3176 @cindex Assist Key, listing attributes
3177 @cindex listing attributes
3178 @cindex outline, attribute list
3179 The attribute lists for the cells in the tree rooted at point can be
3180 displayed by pressing the Assist Key within the contents of a cell.
3184 @{@kbd{C-c h}@} prompts for a cell label and displays the cell's
3185 attributes. @{@kbd{C-u C-c h}@} prompts for a cell label and displays
3186 the attributes for it and its subtree; use 0 as the kcell id to see
3187 attributes for all visible cells in the outline.
3190 @node Outliner History, , Cell Attributes, Outliner
3191 @section Outliner History
3196 Much of the Hyperbole outliner design is based upon concepts pioneered
3197 in the NLS/Augment system, @cite{[Eng84a]}. Augment treated documents as
3198 a hierarchical set of nodes, called statements, rather than cells.
3199 Every Augment document utilized this intrinsic structure.
3201 @cindex distributed collaboration
3202 @cindex collaboration
3203 The system could rapidly change the view of a document by collapsing,
3204 expanding, generating, clipping, filtering, including or reordering
3205 these nodes. It could also map individual views to multiple workstation
3206 displays across a network to aid in distributed, collaborative work.
3208 @cindex knowledge transfer
3209 @cindex idea structuring
3210 @cindex cross referencing
3211 These facilities aided greatly in idea structuring, cross-referencing,
3212 and knowledge transfer. The Koutliner is a start at bringing
3213 these capabilities back into the mainstream of modern computing culture.
3216 @node Rolodex, Window Configurations, Outliner, Top
3221 Hyperbole includes a complete, advanced rolodex system, Wrolo, for
3222 convenient management of hierarchical, record-oriented information.
3224 @cindex rolo, buttons in
3225 Hyperbole buttons may be included within rolodex records and then
3226 manually activated whenever their records are retrieved.
3228 @vindex file, wrolo.el
3229 See the description at the top of the @file{wrolo.el} file for
3230 details on programmatic interfacing to the rolodex. The following
3231 subsections explain use and basic customization of the rolodex.
3240 @node Rolo Concepts, Rolo Menu, Rolodex, Rolodex
3241 @section Rolo Concepts
3243 @cindex rolodex file
3244 @cindex rolodex entry
3245 The rolodex manages and searches rolodex files. A @dfn{rolodex file}
3246 consists of an optional header which starts and ends with a line of
3247 equal signs (at least three equal signs starting at the beginning of a
3248 line), followed by any non-negative number of rolodex records. You must
3249 manually add a header to any rolodex file if you want it to have one.
3252 Here is an example of a simple rolodex file.
3256 ==================================================================
3258 <Last-Name>, <First> <Email> W<Work#> F<Fax#>
3259 ==================================================================
3260 * Smith, John <js@@hiho.com> W708-555-2001 F708-321-1492
3261 Chief Ether Maintainer, HiHo Industries
3266 We call rolodex records, @dfn{entries}. Entries begin with a delimiter,
3267 some number of `*' characters at the beginning of a line. Entries may
3268 be arranged in a hierarchy, where child entries begin with one more `*'
3269 characters than do their parents. Top level entries begin with a single
3272 Beyond this initial delimiter, entries are completely free-form text.
3273 It is best to use a "lastname, firstname" format, however, when adding
3274 contact entries into a rolodex. Then the rolodex system will
3275 automatically keep your entries alphabetized as you enter them. You'll
3276 also be able to sort them whenever you desire.
3278 Any search done on the rolodex scans the full text of each entry.
3279 During a search, the rolodex file header separator lines and anything in
3280 between are appended to the buffer of matched entries before any entries
3281 are retrieved from the file. Whenever an entry is matched, it and all
3282 of its descendant entries are retrieved. If your Emacs version supports
3283 textual highlighting, each search match is highlighted for quick, visual
3287 For example, a search on "Company" could retrieve the following:
3291 ==================================================================
3293 ==================================================================
3301 Thus, searching for Company retrieves all listed employees.
3302 Searching for Manager turns up all Underlings.
3305 @node Rolo Menu, Rolo Keys, Rolo Concepts, Rolodex
3308 @cindex rolodex menu
3309 The Rolo/ menu entry on the Hyperbole top-level menu provides the
3310 user interface to the rolodex. The rolo menu provides access to the
3315 @cindex rolodex commands
3316 @cindex Wrolo commands
3318 @findex rolo-display-matches
3321 @findex rolo-mail-to
3327 Menu Item Command Description
3328 ====================================================================
3329 Add rolo-add Adds a rolodex entry
3330 Display rolo-display-matches Displays last matches again
3331 Edit rolo-edit Edits an existing rolodex entry
3332 Info Displays Rolodex manual entry
3333 Kill rolo-kill Removes an entry from the rolodex
3334 Mail rolo-mail Mail to address following point
3335 Order rolo-sort Sorts all levels in rolodex
3336 RegexFind rolo-grep Finds all entries containing
3337 a regular expression
3338 StringFind rolo-fgrep Finds all entries containing
3340 WordFind rolo-word Finds all entries containing
3341 a string of whole words
3342 Yank rolo-yank Inserts first matching rolodex
3344 ====================================================================
3348 A prefix argument used with either of the find commands listed above
3349 limits the search to a maximum number of matches given by the argument.
3350 The search is terminated whenever that number of matches is found.
3352 For any of the above commands that prompt for a name, you may use the
3353 form parent/child to locate a child entry below a parent entry. So for
3354 a rolodex which looked like so:
3365 You could edit the Underlings entry by identifying it as
3366 Company/Manager/Underlings. Do not use this hierarchical notation in
3367 search expressions since the whole rolodex will be searched anyway.
3368 Thus, "Underlings" as a search pattern will find an entry containing
3369 "Underlings" at any level in a hierarchy, like so:
3375 @node Rolo Keys, Rolo Settings, Rolo Menu, Rolodex
3379 @cindex rolodex, editing an entry
3380 Use the @{@kbd{e}@} key to edit the entry at point within the rolodex
3384 @cindex rolodex keys
3385 After a rolodex search is performed, point is left in the @dfn{rolodex
3386 match buffer}, @file{*Rolodex*}, which uses @code{wrolo-mode} to
3387 simplify browsing many rolodex matches. Press @{@kbd{?}@} when in the
3388 match buffer for a summary of available keys.
3393 @cindex rolodex, highlighting matches
3394 @cindex rolodex, finding matches
3395 @cindex rolodex, moving through matches
3396 If your Emacs version supports textual highlighting, each search match
3397 is highlighted for quick, visual location. @{@key{TAB}@} moves point
3398 forward to successive spans of text which match the search expression.
3399 @{@kbd{M-@key{TAB}}@} or @{@kbd{r}@} moves point backward to earlier
3400 matches. These keys allow you to quickly find the matching entry of
3401 most interest to you if your search expression failed to narrow the
3402 matches sufficiently.
3406 @cindex rolodex, extending a match
3407 @cindex rolodex, interactive searching
3408 If you want to extend the match expression with some more characters to
3409 find a particular entry, use @{@kbd{M-s}@}, which performs an
3410 interactive search forward for the match expression. You can add or
3411 delete characters to this expression to find different occurences.
3412 @{@kbd{C-r}@} will reverse the direction of the search.
3418 @cindex rolodex, outlining
3419 Single key outlining commands are also available for browsing matches.
3420 If your search matches a large number of entries, use
3421 @{@kbd{t}@} to get a top-level overview of all the entries. Each entry
3422 is collapsed so that only its first line shows. Press @{@kbd{s}@} to
3423 show (expand) the entry at point. Use @{@kbd{h}@} to hide (collapse)
3424 the entry again. Press @{@kbd{a}@} to expand all entries in the buffer.
3426 Many other keys are defined to help you move through matching entries.
3428 @cindex rolodex, moving to entries
3432 Move to the previous entry at the same level as the current entry.
3435 Move to the next entry at the same level as the current entry.
3438 Move to the next entry at any level.
3441 Move to the previous entry at any level.
3444 Move the the previous entry one level up.
3449 Move to the beginning of the buffer.
3454 Move to the end of the buffer.
3457 Scroll backward a windowful.
3460 Scroll forward a windowful.
3464 @cindex rolodex, quitting
3465 Once you have found an entry of interest and you want to remove the
3466 rolodex match buffer, use @{@kbd{q}@} to quit. This will restore your
3467 current frame to its state prior to the rolodex search.
3469 @node Rolo Settings, , Rolo Keys, Rolodex
3470 @section Rolo Settings
3472 @vindex rolo-highlight-face
3473 @cindex rolodex, highlighting matches
3474 If textual highlighting is available in your Emacs on your current
3475 display type, the rolodex uses the value of @var{rolo-highlight-face} as
3476 the face to use to highlight search matches.
3478 @vindex rolo-kill-buffers-after-use
3479 The buffers containing the rolodex files are not killed after a search
3480 on the assumption that another search is likely to follow within this
3481 Emacs session. You may wish to change this behavior with the following
3482 setting: @code{(setq rolo-kill-buffers-after-use t)}.
3484 @vindex rolo-save-buffers-after-use
3485 After an entry is killed, the modified rolodex file is automatically
3486 saved. If you would rather always save files yourself, use this
3487 setting: @code{(setq rolo-save-buffers-after-use nil)}.
3489 @vindex rolo-email-format
3490 When adding an entry from within a buffer containing a mail message, the
3491 rolodex add function will extract the sender's name and e-mail address
3492 and prompt you with the name as a default. If you accept it, it will
3493 enter the name and the email address using the format given by the
3494 @var{rolo-email-format} variable. See its documentation if you want to
3497 @vindex rolo-file-list
3498 @cindex rolodex, personal
3499 The files used in any rolodex search are given by the
3500 @var{rolo-file-list} variable, whose default value is
3501 @code{("~/.rolodex.otl")}, so that searches initially scan only your
3502 personal rolodex. Any entries added to this list should be file
3503 pathnames. If a file in the list does not exist or is not readable, it
3504 is skipped. Files are searched in the order in which they appear in the
3505 list. In general, you should leave your personal rolodex file as the
3506 first entry in the list, since this is the only file to which the rolo
3507 menu Add command adds entries.@refill
3509 @vindex rolo-entry-regexp
3510 The rolodex entry start delimiter is given by the regular expression
3511 variable, @var{rolo-entry-regexp}, whose default value is "^\*+".
3513 @vindex rolo-hdr-regexp
3514 A rolodex file may begin with an optional header section which is copied
3515 to the match display buffer whenever any matches are found during a
3516 search. The start and end lines of this header are controlled by
3517 the regular expression variable, @var{rolo-hdr-regexp}, whose default
3518 value is "^===". This allows lines of all equal signs to visually
3519 separate matching entries from multiple files retrieved from a single
3522 @node Window Configurations, Developing with Hyperbole, Rolodex, Top
3523 @chapter Window Configurations
3525 @cindex window configurations
3526 @cindex restoring windows
3527 @cindex saving window configurations
3528 @vindex file, wconfig.el
3529 Hyperbole includes the @file{wconfig.el} package which lets you save and
3530 restore window configurations, i.e@. the window layout and buffers
3531 displayed within an Emacs frame. This is useful to save a particular
3532 working context and then to jump back to it at a later time during an
3533 Emacs session. It is also useful during demonstrations to pull up many
3534 informational artifacts all at once, e.g@. all of the windows for a
3535 particular subsystem. None of this information is stored between Emacs
3536 sessions, so your window configurations will last only through a single
3539 The wconfig library provides two distinct means of managing window
3540 configurations. The first means associates a name with each stored
3541 window configuration. The name can then be used to retrieve the window
3542 configuration later. The second means uses a ring structure to save
3543 window configurations and then allows browsing through the sequence of
3544 saved configurations.
3546 The Win/ menu entry on the Hyperbole top-level menu displays a menu of
3547 window configuration commands:
3551 WinConfig> AddName DeleteName RestoreName PopRing SaveRing YankRing
3556 @cindex wconfig commands
3557 @cindex window configuration commands
3558 @findex wconfig-add-by-name
3559 @findex wconfig-delete-by-name
3560 @findex wconfig-restore-by-name
3561 @findex wconfig-delete-pop
3562 @findex wconfig-ring-save
3563 @findex wconfig-yank-pop
3564 Menu Item Command Description
3565 ====================================================================
3566 AddName wconfig-add-by-name Name current wconfig
3567 DeleteName wconfig-delete-by-name Delete wconfig with name
3568 RestoreName wconfig-restore-by-name Restore wconfig by name
3570 PopRing wconfig-delete-pop Restore and delete wconfig
3571 SaveRing wconfig-ring-save Store wconfig to ring
3572 YankRing wconfig-yank-pop Restore next wconfig
3573 ====================================================================
3577 Saving and restoring window configurations by name is the easiest
3578 method, but it requires that you input the chosen name from the
3579 keyboard. The ring commands permit saving and restoring through mouse
3580 interaction only, if so desired. The prior section, @ref{Smart Keys},
3581 mentions how to save and restore window configurations with the Smart Keys.
3582 Since the ring commands are a bit more complex than their by-name
3583 counterparts, the following paragraphs explain them in more detail.
3586 Wconfig creates a ring structure that operates just like the Emacs
3587 @var{kill-ring}, @ref{Kill Ring,,,emacs, The GNU Emacs Manual}, but its
3588 elements are window configurations rather than text regions. One can
3589 add an element to the ring based upon the current window configuration.
3590 After several elements are in the ring, one can walk through all of them
3591 in sequence until the desired configuration is restored.
3593 @findex wconfig-ring-save
3594 SaveRing executes the @code{wconfig-ring-save} command which
3595 saves the current window configuration to the ring.
3597 @findex wconfig-yank-pop
3598 YankRing executes the @code{wconfig-yank-pop} command. It restores the
3599 window configuration from the currently pointed to configuration in the
3600 ring. It does not delete this configuration from the ring but it does
3601 move the pointer to the prior ring element. Repeated calls to this
3602 command thus restore successive window configurations until the ring
3603 pointer wraps around. Simply stop when a desired configuration appears
3604 and use @{@kbd{q}@} to quit from the minibuffer menu.
3606 @findex wconfig-delete-pop
3607 PopRing calls the @code{wconfig-delete-pop} command.
3608 It is used to restore a previously saved configuration and at the same
3609 time delete it from the ring. Simply stop when a desired configuration
3610 appears and use @{@kbd{q}@} to quit from the minibuffer menu.
3612 @vindex wconfig-ring-max
3613 The maximum number of elements the ring can hold is set by the
3614 @var{wconfig-ring-max} variable whose default is 10. Any saves beyond
3615 this value cause deletion of the oldest element in the ring before
3618 @node Developing with Hyperbole, Glossary, Window Configurations, Top
3619 @chapter Developing with Hyperbole
3621 This chapter is only for people who are familiar with Emacs Lisp and
3622 wish to customize Hyperbole, to extend it, or to develop other systems
3623 using Hyperbole as a base.
3628 * Explicit Button Technicalities::
3629 * Encapsulating Systems::
3630 * Embedding Hyperbole::
3633 @node Hook Variables, Creating Types, Developing with Hyperbole, Developing with Hyperbole
3634 @section Hook Variables
3637 @cindex hook variables
3638 Hyperbole provides a number of hook variables that allow you to adjust
3639 its basic operations to meet your own needs, without requiring you to
3640 change the code for those operations.
3642 We find it best to always set the value of hook variables either to nil
3643 or to a list of function names of no arguments, each of which will be
3644 called in sequence when the hook is triggered.
3646 Given the name of a function, a Hyperbole hook variable triggered within
3647 that function has the same name as the function with a @code{-hook}
3648 appended. Hyperbole provides the following hook variables:
3652 @vindex hyperb:init-hook
3653 @item hyperb:init-hook
3654 For customization at Hyperbole initialization time. Use this to load
3655 any personal Hyperbole type definitions you might have. It is run after
3656 Hyperbole support code is loaded but before Hyperbole session
3657 initializations take place.
3659 @vindex action:act-hook
3660 @vindex hbut:current
3661 @item action:act-hook
3662 Run before each Hyperbole button activation.
3663 The variable @var{hbut:current} contains the button to be activated when
3666 @vindex ebut:create-hook
3667 @item ebut:create-hook
3668 To add to the Hyperbole explicit button creation process.
3670 @vindex ebut:delete-hook
3671 @item ebut:delete-hook
3672 To add to the Hyperbole explicit button deletion process.
3674 @vindex ebut:modify-hook
3675 @item ebut:modify-hook
3676 Executed when an explicit button's attributes are modified.
3678 @vindex hibtypes:begin-load-hook
3679 @item hibtypes:begin-load-hook
3680 Executed prior to loading of standard Hyperbole implicit button types.
3681 Used to load site-specific low priority implicit button types since
3682 lowest priority ibtypes are loaded first.
3684 @vindex hibtypes:end-load-hook
3685 @item hibtypes:end-load-hook
3686 Executed after loading of standard Hyperbole implicit button types.
3687 Used to load site-specific high priority implicit button types since
3688 highest priority ibtypes are loaded last.
3690 @vindex htype:create-hook
3691 @item htype:create-hook
3692 Executed when a Hyperbole type (e.g@. action type or implicit button
3693 type) is added to the environment.
3695 @vindex htype:delete-hook
3696 @item htype:delete-hook
3697 Executed when a type is deleted from the environment.
3699 @vindex kotl-mode-hook
3700 @item kotl-mode-hook
3701 Executed when a Koutline is created or read in or when kotl-mode is
3704 @vindex wrolo-display-hook
3705 @item wrolo-display-hook
3706 Executed when rolodex matches are displayed.
3708 @vindex wrolo-mode-hook
3709 @item wrolo-mode-hook
3710 Executed when a rolodex match buffer is created and put into wrolo-mode.
3712 @vindex wrolo-yank-reformat-function
3713 @cindex yank, reformatting
3714 @item wrolo-yank-reformat-function
3715 A variable whose value may be set to a function of two arguments, START
3716 and END, indicating the region of the rolodex entry yanked into the
3717 current buffer by the rolo-yank command. The function may reformat this
3718 region to meed user-specific needs.
3723 Hyperbole also makes use of a number of external Emacs hook variables.
3727 @vindex find-file-hooks
3728 @cindex button highlighting
3729 @item find-file-hooks
3730 This is called whenever a file is read into a GNU Emacs buffer.
3731 Hyperbole uses it to highlight any buttons within files when run under
3732 any NEXTSTEP or X window system-based versions of GNU Emacs.
3734 @vindex write-file-hooks
3735 @cindex button data saving
3736 @item write-file-hooks
3737 This is called whenever a GNU Emacs buffer is written to a file.
3738 Hyperbole uses it to save any modified button data associated with the
3743 Hyperbole mail and news facilities also utilize a number of external hook
3744 variables. These hide button data and highlight buttons if possible.
3745 See the various support files for details.
3748 @node Creating Types, Explicit Button Technicalities, Hook Variables, Developing with Hyperbole
3749 @section Creating Types
3751 @cindex type definition
3752 @cindex type redefinition
3754 To define or redefine a single Hyperbole type, you may either:
3760 @findex eval-last-sexp
3762 move your Emacs point to within the type definition and use
3763 @{@kbd{C-M-x}@} @code{(eval-defun)} (only works in Emacs Lisp mode);
3766 or move your point to the end of the last line of the type definition and
3767 use @{@kbd{C-x C-e}@} @code{(eval-last-sexp)} (works in most modes).
3770 @cindex Hyperbole types
3771 @vindex class, htype
3772 The functions from the @code{htype} class may be applied to any
3773 Hyperbole types, if needed.
3775 @vindex file, hactypes.el
3776 @vindex file, hibtypes.el
3777 The following subsections explain the specifics of Hyperbole type
3778 definitions which are beyond standard practice for Emacs Lisp programming.
3779 See the definitions of the standard types in @file{hactypes.el}
3780 and @file{hibtypes.el} for examples.
3783 * Action Type Creation::
3784 * Implicit Button Types::
3787 @node Action Type Creation, Implicit Button Types, Creating Types, Creating Types
3788 @subsection Action Type Creation
3790 @findex actype:create
3791 @vindex file, hactypes.el
3792 @vindex file, hbut.el
3793 New forms of explicit buttons may be created by adding new action types
3794 to a Hyperbole environment. The file, @file{hactypes.el}, provides
3795 many examples of working action types.
3797 @cindex action type, creation
3799 @findex actype:create
3800 An action type is created, i.e@. loaded into the Hyperbole environment,
3801 with the @code{(defact)} function (which is an alias for
3802 @code{(actype:create)}). The calling signature for this function is
3803 given in its documentation; it is the same as that of @code{(defun)}
3804 except that a documentation string is required. (An interactive calling
3805 form is also required if the action type has formal parameters and is to
3806 be used in explicit button definitions. Implicit buttons never use an
3807 action type's interactive form. It is good practice to include an
3808 interactive form since the type creator cannot know how users may choose
3809 to apply the type.)@refill
3811 An action type's parameters are used differently than those of a
3812 function being called. Its interactive calling form is used when an
3813 explicit button is created to prompt for type-specific button
3814 attributes. The rest of its body is used when a button with that action
3815 type is activated. Then the button attributes together with the action
3816 type body are used to form an action that is executed in response to the
3817 button activation. The action's result is returned to the action caller
3818 unless it returns nil, in which case t is returned to the caller to
3819 ensure that it registers the performance of the action.
3821 An action type body may perform any computation using Emacs Lisp and
3822 Hyperbole functions.
3824 @cindex interactive form
3826 The interactive calling form for an action type is of the same form as
3827 that of a regular Emacs Lisp function definition (see the documentation
3828 for the Emacs Lisp @code{(interactive)} form). It may additionally use
3829 Hyperbole command character extensions when the form is given as a
3830 string. Each such extension character @emph{must} be preceded by a plus
3831 sign, @code{+}, in order to be recognized since such characters may also
3832 have standard interactive form meanings.
3834 The present Hyperbole extension characters are:
3837 @cindex argument, Info node
3838 @cindex interactive cmd char, +I
3840 Prompts for an existing Info node name and file.
3842 @cindex argument, kcell
3843 @cindex argument, koutline
3844 @cindex interactive cmd char, +K
3846 Prompts for an existing kcell identifier, either a full outline level
3847 identifier or a permanent idstamp.
3849 @cindex interactive cmd char, +M
3850 @cindex argument, mail message
3852 Prompts for a mail message date and the file name it resides in.
3853 The mail parameters prompted for by this character code are likely to
3854 change in the future.
3856 @cindex argument, view spec
3857 @cindex interactive cmd char, +V
3859 Prompts for a Hyperbole view specification.
3860 Not yet available for use.
3864 @vindex class, hargs
3865 @cindex argument, reading
3866 Arguments are read by the functions in Hyperbole's @code{hargs} class,
3867 rather than the standard Lisp @code{read} functions, in order to allow
3868 direct selection of arguments via the Action Key.
3870 If an action type create is successful, the symbol that Hyperbole uses
3871 internally to reference the type is returned. @code{Nil} is returned on
3872 failure so that you may test whether or not the operation succeeds.
3874 Once you have defined an action type within your present Hyperbole
3875 environment, you can create new explicit buttons which use it. There is
3876 no explicit button type beyond its action type, so no further work is
3879 @findex actype:delete
3880 Call @code{(actype:delete)} to remove an action type from a Hyperbole
3881 environment. It takes a single parameter which should be the same type
3882 symbol used in the type definition call (not the Hyperbole symbol
3883 returned by the call).
3885 @node Implicit Button Types, , Action Type Creation, Creating Types
3886 @subsection Implicit Button Types
3888 @cindex implicit button type
3891 @findex ibtype:create
3892 An implicit button type is created or loaded via the @code{(defib)}
3893 function (which is an alias for @code{(ibtype:create)}). The calling
3894 signature for this function is given in its documentation; it is the
3895 same as that of @code{(defun)}, but with a number of constraints. The
3896 parameter list should always be empty since no parameters will be used.
3897 A documentation string is required. The type's body follows this.
3899 @cindex ibtype, predicate
3900 @cindex ibtype, argument
3901 @cindex ibtype, return val
3902 @cindex ibtype, actype
3903 The body of an implicit button type is a predicate which determines
3904 whether or not point is within an implicit button of the type. If not,
3905 the predicate returns @code{nil}. If so, it may optionally setup to
3906 flash the button and then perform one or more actions. A call of the
3907 form: @code{(ibut:label-set label start-pos end-pos)} is used to setup
3908 the button flashing, if desired. This is then typically immediately
3909 followed by an action invocation of the form:
3910 @code{(hact 'actype &rest actype-arguments)}. It is imperative that all
3911 actions (non-predicate code) be invoked through the @code{(hact)}
3912 function rather than directly or your ibtypes will not work properly.
3913 (Hyperbole first tests to see if any ibtype matches the current context
3914 before activating any type, so it ensures that @code{(hact)} calls are
3915 disabled during this testing.) Any action types used may be created
3916 before or after the implicit button type definition but obviously should
3917 be defined before any implicit buttons of the given type are activated;
3918 an error will result, otherwise.
3920 If an implicit button type create is successful, the symbol that
3921 Hyperbole uses internally to reference the type is returned. @code{Nil}
3922 is returned on failure so that you may test whether or not the operation
3923 succeeds. Implicit button type names and action type names may be the
3924 same without any conflict. In fact, such naming is encouraged when an
3925 implicit button type is the exclusive user of an action type.
3927 @findex ibtype:delete
3928 Call @code{(ibtype:delete)} to remove an implicit button type from a
3929 Hyperbole environment. It takes a single parameter which should be the
3930 same type symbol used in the type definition call (not the Hyperbole
3931 symbol returned by the call). This will not delete the action type used
3932 by the implicit button; that must be done separately.
3934 @cindex ibtype, help
3936 @vindex class, hattr
3938 @vindex file, hib-kbd.el
3939 By default, a request for help on an implicit button will display the
3940 button's attributes in the same manner as is done for explicit buttons.
3941 For some implicit button types, other forms of help will be more
3942 appropriate. If an Emacs Lisp function is defined whose name is formed
3943 from the concatenation of the type name followed by @code{:help}, e.g@.
3944 @code{my-ibtype:help}, it is used to respond to requests for
3945 help on buttons of that type. Any such function should take a single
3946 argument of an implicit button construct. (This is what
3947 @code{(ibut:at-p)} returns when point is within an implicit button
3948 context.) The button may be queried for its attributes using functions
3949 from the @code{hbut} and @code{hattr} classes. See the @file{hib-kbd.el}
3950 file for an example of a custom help function.
3952 @node Explicit Button Technicalities, Encapsulating Systems, Creating Types, Developing with Hyperbole
3953 @section Explicit Button Technicalities
3955 * Button Label Normalization::
3956 * Operational and Storage Formats::
3957 * Programmatic Button Creation::
3960 @node Button Label Normalization, Operational and Storage Formats, Explicit Button Technicalities, Explicit Button Technicalities
3961 @subsection Button Label Normalization
3962 @cindex normalized label
3963 @cindex button label
3965 @vindex hbut:label-to-key
3966 Hyperbole uses a normalized form of button labels called button keys (or
3967 label keys) for all internal operations. See the documentation for the
3968 function @code{(hbut:label-to-key)} for details of the normalization
3969 process. The normalized form permits Hyperbole to recognize buttons that
3970 are the same but whose labels appear different from one another, due to
3971 text formatting conventions. For example, all of the following would
3972 be recognized as the same button.
3975 <(fake button)> <( fake button)>
3987 @vindex hbut:fill-prefix-regexps
3990 @cindex button, multiple lines
3991 @cindex button, split across lines
3992 The last three examples demonstrate how Hyperbole ignores common fill
3993 prefix patterns that happen to fall within the middle of a button label
3994 that spans multiple lines. As long as such buttons are selected with
3995 point at a location within the label's first line, the button will be
3996 recognized. The variable @var{hbut:fill-prefix-regexps} holds the list
3997 of fill prefixes recognized when embedded within button labels. All
3998 such prefixes are recognized (one per button label), regardless of the
3999 setting of the GNU Emacs variable, @var{fill-prefix}, so no user
4000 intervention is required.
4002 @node Operational and Storage Formats, Programmatic Button Creation, Button Label Normalization, Explicit Button Technicalities
4003 @subsection Operational and Storage Formats
4005 @cindex explicit button, formats
4006 @cindex explicit button, storage
4007 @cindex storage manager
4008 @cindex button attributes
4009 @vindex hbut:current
4010 Hyperbole uses a terse format to store explicit buttons and a more
4011 meaningful one to show users and to manipulate during editing. The
4012 terse format consists solely of button attribute values whereas the edit
4013 format includes an attribute name with each attribute value. A button
4014 in edit format consists of a Lisp symbol together with its attribute list
4015 which holds the attribute names and values. In this way, buttons may be
4016 passed along from function to function simply by passing the symbol to
4017 which the button is attached. Most functions utilize the pre-defined
4018 @var{hbut:current} symbol by default to store and retrieve the last
4019 encountered button in edit format.
4021 @vindex class, hbdata
4024 The @code{hbdata} class handles the terse, stored format. The
4025 @code{hbut}, @code{ebut}, and @code{ibut} classes work with the
4026 name/value format. This separation permits the wholesale replacement of
4027 the storage manager with another, with any interface changes hidden from
4028 any Hyperbole client programming.
4030 @node Programmatic Button Creation, , Operational and Storage Formats, Explicit Button Technicalities
4031 @subsection Programmatic Button Creation
4033 @cindex explicit button, creation
4034 A common need when developing with Hyperbole is the ability to create or
4035 modify explicit buttons without user interaction. For example, an
4036 application might require the addition of an explicit summary button to
4037 a file for each new mail message a user reads that contains a set of
4038 keywords. The user could then check the summary file and jump to
4039 desired messages quickly.
4042 @vindex file, hbut.el
4045 The Hyperbole class @code{ebut} supports programmatic access to explicit
4046 buttons. See it within the @file{hbut.el} file for full details. The
4047 documentation for @code{(ebut:create)} explains the set of attributes
4048 settings necessary to create an explicit button. For operations over
4049 the whole set of buttons within the visible (non-narrowed) portion of a
4050 buffer, use the @code{(ebut:map)} function.
4053 @node Encapsulating Systems, Embedding Hyperbole, Explicit Button Technicalities, Developing with Hyperbole
4054 @section Encapsulating Systems
4056 @vindex file, hsys-*
4057 @cindex Hyperbole, system encapsulation
4058 @cindex system encapsulation
4059 A powerful use of implicit button types is to provide a Hyperbole-based
4060 interface to external systems. The basic idea is to interpret patterns
4061 output by the application as implicit buttons.
4063 See the @file{hsys-*} files for examples of how to do this.
4064 Encapsulations are provided for the following systems (the systems
4065 themselves are not included with Hyperbole):
4068 @item World-Wide Web
4069 The world-wide web system originally developed at CERN, that now spans
4070 the Internet universe. This is automatically loaded by Hyperbole so
4071 that a press of the Action Key follows a URL.
4074 The Wide Area Information Systems full text-retrieval system orginally
4075 developed at Thinking Machines and then later at WAIS Inc.
4078 A hypertextual storage manager that stores textual nodes as records with
4079 locking so that multiple users can read and edit hypertexts.
4083 @node Embedding Hyperbole, , Encapsulating Systems, Developing with Hyperbole
4084 @section Embedding Hyperbole
4086 [NOTE: We have never done this ourselves, though we have done similar
4087 things which leads us to infer that the task should not be difficult.]
4089 @cindex Hyperbole API
4091 @cindex programming interface
4092 @cindex Hyperbole, embedding
4093 The standard Emacs-based Hyperbole user interface has purposely been
4094 separated from the Hyperbole backend to support the development of
4095 alternative interfaces and the embedding of Hyperbole functionality
4096 within other system prototypes. The Hyperbole backend functionality
4097 that system developers can make use of is called its Application
4098 Programming Interface (API). The API may be used to make server-based
4099 calls to Hyperbole when Emacs is run as a non-interactive (batch)
4100 process, with its input/output streams attached to another process.
4102 The public functions and variables from the following files may be
4103 considered the present Hyperbole API:
4106 @file{hact.el}, @file{hargs.el}, @file{hbmap.el}, @file{hbut.el},
4107 @file{hhist.el}, @file{hmail.el}, @file{hmoccur.el}, @file{hpath.el},
4108 @file{htz.el}, @file{hypb.el}, @file{set.el}, @file{wconfig.el},
4109 @file{wrolo.el}, and @file{wrolo-logic.el}.@refill
4112 Note when looking at these files, that they are divided into sections
4113 that separate one data abstraction (class) from another. A line of
4114 dashes within a class separates public parts of the class from the
4115 private parts that follow the line.
4117 This API does not include the Hyperbole outliner, as it has been
4118 designed for interactive use, rather than programmatic extensibility.
4119 You can certainly study its code, below the @file{hyperbole/kotl/}
4120 directory and learn to program it, however.
4123 @node Glossary, Smart Key Reference, Developing with Hyperbole, Top
4126 Concepts pertinent to operational usage of Hyperbole are defined here.
4127 If some GNU Emacs terms are unfamiliar to you, @ref{Glossary, Emacs
4128 Glossary,, emacs, the GNU Emacs Manual}.
4134 An executable behavior associated with a Hyperbole button. A specific
4135 class of actions which display entities are called @emph{links},
4136 such as a link to a file.
4140 See @emph{Smart Key}.
4144 A behavioral specification for use within Hyperbole buttons. Action
4145 types usually contain a set of parameters which must be given values for
4146 each button with which they are associated. An action type together
4147 with a set of values, called arguments, may be considered an @emph{action}.
4148 @emph{Actype} is a synonym for action type.
4152 Request for a Hyperbole button to perform its action.
4153 Ordinarily the user presses a key which selects and activates a button.
4158 A standard GNU Emacs Lisp package which allows one to use pathnames
4159 that are accessible via the Internet File Transfer Protocol (ftp) just
4160 like other pathnames, for example when finding a file. The
4161 latest version of ange-ftp may always be obtained via anonymous ftp to:
4162 @file{/ftp.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.gz}.
4166 A button-specific value fed to a Hyperbole type specification when the
4167 button is activated.
4171 See @emph{Smart Key}.
4175 Slot names associated with Hyperbole buttons. An @emph{attribute value}
4176 is associated with each button attribute.
4181 @cindex interactive computing
4185 @cindex outline processor
4187 @cindex digital signature
4190 The Augment system, originally named NLS, was a pioneering research and
4191 production system aimed at augmenting human intellect and group
4192 knowledge processing capabilities through integrated tools and
4193 organizational development strategies. This approach led to the
4194 invention of much of interactive computing technology decades ahead of
4195 other efforts, including: the mouse, screen windows, true hypertext,
4196 outline processors, groupware, and digitally signed documents.
4197 @xref{References}, which cites several Douglas Engelbart papers on the
4198 subject. The Koutliner concept emerged from studies of publicly
4199 available information concerning Augment.
4203 A selectable Hyperbole construct which performs an action. A button
4204 consists of a set of attributes that includes: a textual label, a
4205 category, a type and zero or more arguments. @emph{Explicit buttons}
4206 also have creator, create time, last modifier, and last modifier time
4209 Buttons provide the user's gateway to information. The user sees and
4210 interacts with button labels, the rest of the button data is managed
4211 invisibly by Hyperbole and displayed only in response to user queries.
4213 @cindex button activation
4214 @item button activation
4215 See @emph{activation}.
4217 @cindex button attributes
4218 @item button attributes
4219 See @emph{attributes}.
4223 Lists of button attribute values explicitly saved and managed by Hyperbole.
4224 One list for each button created by Hyperbole.
4226 @cindex button file, local
4227 @item button file, local
4228 A per-directory file named @file{HYPB} that may be used to store any
4229 desired buttons and may then be displayed via a menu selection whenever
4230 a user is within that directory.
4232 @cindex button file, personal
4233 @item button file, personal
4234 A per-user file named @file{HYPB} that may be used to store any desired
4235 buttons and may then be displayed via a menu selection.
4239 A normalized form of a @emph{button label} used internally by Hyperbole.
4241 @cindex button label
4243 A text string that visually indicates a Hyperbole button location and
4244 provides it with a name and unique identifier. Within a buffer, buttons
4245 with the same label are considered separate views of the same button and
4246 so behave exactly alike. Since button labels are simply text strings,
4247 they may be embedded within any text to provide non-linear information
4248 or operational access points.
4250 The maximum length of a button label is limited by the variable
4253 @cindex button selection
4254 @item button selection
4255 The act of designating a Hyperbole button upon which to operate.
4256 Use the Action Key to select a button.
4260 A high-level, conceptual grouping of Hyperbole buttons into classes.
4261 @emph{Implicit} and @emph{explicit} groupings represent categories.
4269 The set of koutline cells which share a common parent cell and are one
4270 level deeper than the parent.
4274 A group of functions and variables with the same prefix in their names,
4275 used to provide an interface to an internal or external Hyperbole
4280 A programmatic or positional state recognized by Hyperbole.
4281 We speak of Smart Key and implicit button contexts. Both are typically
4282 defined in terms of surrounding patterns within a buffer, but may be
4283 defined by arbitrary Emacs Lisp predicates. (Context may come to have a
4284 broader meaning within future versions of Hyperbole.)
4288 See @emph{Hyperbole environment}.
4292 The much larger successor to ange-ftp. It does the same thing as
4293 ange-ftp but works with more types of ftp hosts. See @emph{ange-ftp}.
4295 @cindex explicit button
4296 @item explicit button
4297 A button created and managed by Hyperbole. By default, explicit buttons
4298 are delimited like this @code{<(fake button)>}. Direct selection is
4299 used to operate upon an explicit button.
4301 @cindex global button
4304 A form of explicit button which is typically accessed by name rather
4305 than direct selection. Global buttons are useful when one wants
4306 quick access to actions such as jumping to common file locations or for
4307 performing sequences of operations. One need not locate them since they
4308 are always available by name, with full completion offered. All global
4309 buttons are stored in the file given by the variable @var{gbut:file} and
4310 may be activated as regular explicit buttons by visiting this file. By
4311 default, this is the same as the user's personal button file.
4313 @cindex global button file
4314 @item global button file
4315 See @emph{button file, personal}.
4318 @cindex hook variable
4320 A variable that permits customization of an existing function's
4321 operation without the need to edit the function's code. See also the
4322 documentation for the function @code{(run-hooks)}.
4326 A flexible, programmable information management and viewing system built
4327 on top of GNU Emacs. It utilizes a button-action model and supports
4328 hypertextual linkages. Hyperbole is all things to all people.
4330 @cindex Hyperbole environment
4331 @item Hyperbole environment
4332 A programmatic context within which Hyperbole operates. This includes
4333 the set of Hyperbole types defined and the set of Hyperbole code modules
4334 loaded. It does not include the set of accessible buttons.
4335 Although the entire Emacs environment is available to Hyperbole, we do
4336 not speak of this as part of the Hyperbole environment.
4340 A text or group of texts which may be explored in a non-linear fashion
4341 through associative linkages embedded throughout the text. Instead of
4342 simply referring to other pieces of work, hypertext references when
4343 followed actually take you to the works themselves.
4345 @cindex implicit button
4346 @item implicit button
4347 A button recognized contextually by Hyperbole. Such buttons contain no
4348 button data. See also @emph{implicit button type}.
4350 @cindex implicit button type
4351 @item implicit button type
4352 A specification of how to recognize and activate implicit buttons of a
4353 specific kind. Implicit button types often utilize structure internal
4354 to documents created and managed without Hyperbole assistance, for
4355 example, programming documentation. @emph{Ibtype} is a synonym for
4356 implicit button type. See also @emph{system encapsulation}.
4358 @cindex instance number
4359 @item instance number
4360 A colon prefaced number appended to the label of a newly created button
4361 when the button's label duplicates the label of an existing button in
4362 the current buffer. This number makes the label unique and so allows
4363 any number of buttons with the same base label within a single buffer.
4367 A hierarchically ordered grouping of cells which may be stored as a file
4368 and viewed and edited as an outline.
4372 Koutliner, the Hyperbole outliner, is a powerful autonumbering outliner
4373 with permanent hypertext anchors for easy hyperlinking and view
4374 specs for rapid outline view alteration.
4378 Cells or kcells are elements within koutlines. Each cell contains
4379 textual and graphical contents, a relative identifier, a permanent
4380 identifier and a set of attributes such as the user who created the cell
4381 and the time of creation. See also @emph{Koutliner}.
4385 A reference from a Hyperbole button to an entity. The referenced entity
4386 is sometimes called a @emph{node} or @emph{referent}.
4387 A specific class of actions which display entities are called
4388 @emph{links}, such as a link to a file.
4390 @cindex local button file
4391 @item local button file
4392 See @emph{button file, local}.
4394 @cindex minibuffer window
4395 @item minibuffer window
4396 The one line window at the bottom of a frame where messages and prompts
4399 @cindex minibuffer menu
4400 @item minibuffer menu
4401 A Hyperbole menu displayed in the minibuffer window. Each menu item
4402 within a minibuffer menu begins with a different letter that can be used
4403 to invoke the item (case doesn't matter). Items that display other
4404 menus end with a forward slash, /.
4406 @cindex mouse button
4409 See @emph{Smart Key}.
4413 See @emph{link} or @emph{cell}.
4417 See @emph{koutline}.
4421 Any koutline cell which has children.
4425 The previous same level koutline cell with the same parent.
4429 A boolean (nil = false, non-nil = true) Lisp expression typically
4430 evaluated as part of a conditional expression.
4438 Wrolo, the Hyperbole rolodex, provides rapid lookup of multi-line,
4439 hierarchically ordered free form text records.
4443 A koutline cell which has cells below it. All such cells share the same
4447 @vindex smart-scroll-proportional
4448 @cindex proportional scrolling
4451 A context-sensitive key used within Hyperbole and beyond. Actually,
4452 there are two Smart Keys, the Action Key and the Assist Key. The
4453 Action Key, typically bound to the shift-middle mouse key (or shift-left
4454 mouse key on a 2-button mouse), activates Hyperbole buttons and scrolls
4455 the current buffer line to the top of the window when pressed at the end
4456 of a line. The Assist Key, typically bound to the shift-right mouse
4457 key, explains what a Hyperbole button does or scrolls the current line
4458 to the bottom of the window when pressed at the end of a line. (See the
4459 documentation for the variable, @var{smart-scroll-proportional}, for
4460 information on how to make these keys scroll forward and backward a
4461 windowful at a time).
4463 To see what a Smart Key will do within a particular context, depress and
4464 hold the key at the point desired and depress the other Smart Key. A
4465 buffer containing a description of its contextual function will then be
4466 displayed. You may release the two keys in any order after you have
4467 them both depressed. A press of the Assist Key in an unsupported
4468 context displays a summary of Smart Key functions in each context, as
4469 does the Doc/SmartKy menu item.
4471 @cindex source buffer
4473 @item source buffer / file
4474 The buffer or file within which a Hyperbole button is embedded.
4478 All of the cells in a koutline which share the same root cell, excluding
4483 The next same level koutline cell with the same parent.
4485 @cindex system encapsulation
4486 @item system encapsulation
4487 Use of Hyperbole to provide an improved or simply consistent user
4488 interface to another system. Typically, implicit button types are
4489 defined to recognize and activate button-type constructs managed by the
4494 The set of cells in a koutline that share a common root cell, including
4499 A perspective on some information. A view can affect the extent of the
4500 information displayed, its format, modes used to operate on it, its
4501 display location and so forth.
4505 A terse (and to the uninitiated, cryptic) string that specifies a
4506 particular view of koutline or a link referent. If a view spec is in
4507 use in a buffer, the view spec appears in the modeline delimited by
4512 @node Smart Key Reference, Outliner Keys, Glossary, Top
4513 @appendix Smart Key Reference
4515 This appendix supplies complete documentation on Smart Key operation. It is
4516 quite extensive and is meant for reference rather than sequential reading.
4517 @xref{Smart Keys}, for a description of the Smart Keys. That section also
4518 describes how to get context-sensitive Smart Key help, with which you can
4519 explore Smart Key operation bit by bit.
4521 Smart Key operations are context-sensitive. Contexts are described herein as
4522 conditionals, e.g@. when depressed here, if this is true, etc. Each Smart
4523 Key context is listed in the order in which it will be checked. The first
4524 matching context is always the one applied. Within each context, the
4525 actions performed by the Action and Assist Keys are listed.
4528 * Smart Mouse Keys::
4529 * Smart Keyboard Keys::
4532 @node Smart Mouse Keys, Smart Keyboard Keys, Smart Key Reference, Smart Key Reference
4533 @section Smart Mouse Keys
4535 @cindex Smart Mouse Keys
4536 Smart Key drags and modeline presses can only be used when running under
4537 a window system with mouse key support. So keep in mind that the
4538 operations in this section apply only if you have mouse support within
4539 Hyperbole. The Smart Key operations in, @ref{Smart Keyboard Keys},
4540 apply to both mouse and keyboard Smart Key usage.
4544 @cindex drag, side edge
4546 If dragged from a side-by-side window edge or from the immediate left of
4547 a vertical scroll bar:
4549 Resizes adjacent window sides to the point of drag release.
4555 @cindex drag, between windows
4556 If dragged from inside one window to another:
4558 Creates a new link button at the drag start location, linked to the
4559 drag end location. If drag start position is within a button,
4560 modifies the button to link to drag end location.
4562 Swaps buffers in the two windows.
4569 @cindex drag, horizontal
4570 @cindex horizontal drag
4571 If dragged horizontally within a single window while depressed
4572 (hmouse-x-drag-sensitivity sets the minimal horizontal movement which
4575 Goes to buffer end if drag was to the right, otherwise goes to beginning.
4577 Splits window vertically if drag was to the right, otherwise deletes
4584 @cindex depress, modeline
4585 @cindex modeline depress
4586 If depressed within a window mode line:
4588 (1) clicked on left edge of a window's modeline,
4589 window's buffer is buried (placed at bottom of buffer list);
4590 (2) clicked on right edge of a window's modeline,
4591 the Info buffer is displayed, or if already displayed and the
4592 modeline clicked belongs to a window displaying Info, the Info
4594 (3) clicked anywhere in the middle of a window's modeline,
4595 the functions listed in 'assist-key-modeline-hook' are
4597 (4) dragged vertically from modeline to within a window,
4598 the modeline is moved to point of key release, thereby resizing
4599 its window and potentially its vertical neighbors.
4601 (1) clicked on left edge of a window's modeline,
4602 bottom buffer in buffer list is unburied and placed in window;
4603 (2) clicked on right edge of a window's modeline,
4604 the summary of Smart Key behavior is displayed, or if already
4605 displayed and the modeline clicked belongs to a window displaying
4606 the summary, the summary buffer is hidden;
4607 (3) clicked anywhere in the middle of a window's modeline,
4608 a popup menu (if available) is displayed;
4609 (4) dragged vertically from modeline to within a window,
4610 the modeline is moved to point of key release, thereby resizing
4611 its window and potentially its vertical neighbors.
4618 @cindex drag, vertical
4619 @cindex vertical drag
4620 If dragged vertically within a single window while depressed
4621 (hmouse-y-drag-sensitivity sets the minimal vertical movement which
4624 Splits current window into two side-by-side windows.
4630 @cindex drag, diagonal
4631 @cindex diagonal drag
4632 If dragged diagonally within a single window while depressed
4633 (hmouse-x-diagonal-sensitivity and hmouse-y-diagonal-sensitivity set the
4634 minimal diagonal movement which registers a drag):
4636 Save current window configuration onto a ring of window configurations.
4638 Restores prior window configuration from ring. A prefix argument N
4639 specifies the Nth prior configuration from the ring.
4645 @node Smart Keyboard Keys, , Smart Mouse Keys, Smart Key Reference
4646 @section Smart Keyboard Keys
4648 @cindex Smart Keyboard Keys
4651 When prompting for a Hyperbole argument, a press in the minibuffer:
4653 Terminates this minibuffer argument.
4655 Offers completion help for current minibuffer argument.
4661 When reading a Hyperbole menu item or a Hyperbole completion-based argument:
4663 Returns value selected at point if any, else nil. If
4664 value is the same as the contents of the minibuffer, it is used as the
4665 current minibuffer argument, otherwise, the minibuffer is erased and
4666 value is inserted there.
4669 Displays Hyperbole menu item help when item is selected.
4673 @vindex smart-scroll-proportional
4674 @cindex proportional scrolling
4678 @cindex click, end of line
4679 @cindex end of line click
4680 When pressed at the end of a line but not the end of a buffer:
4682 Scrolls up according to value of smart-scroll-proportional. If
4683 smart-scroll-proportional is nil or if point is on the top
4684 window line, scrolls up (forward) a windowful. Otherwise, tries to
4685 bring current line to top of window. Leaves point at end of line and
4686 returns t if scrolled, nil if not.
4688 Scrolls down according to value of smart-scroll-proportional. If
4689 smart-scroll-proportional is nil or if point is on the
4690 bottom window line, scrolls down (backward) a windowful. Otherwise,
4691 tries to bring current line to bottom of window. Leaves point at end of
4692 line and returns t if scrolled, nil if not.
4698 @cindex click, button
4699 @cindex button click
4700 When pressed on a Hyperbole button:
4704 Displays help for button, typically a summary of its attributes.
4710 If pressed within a buffer in View major or minor mode:
4712 Scrolls buffer forward a windowful and quits from view mode when at
4713 the last line of the buffer.
4715 Scrolls buffer backward a windowful.
4721 When pressed within a Hyperbole outliner buffer (kotl-mode):
4723 (1) at the end of buffer, uncollapse and unhide all cells in view;
4724 (2) within a cell, if its subtree is hidden then show it,
4726 (3) between cells or within the read-only indentation region to the
4727 left of a cell, then move point to prior location and begin
4728 creation of a klink to some other outline cell; hit the Action
4729 Key twice to select the link referent cell;
4730 (4) anywhere else, scroll up a windowful.
4732 (1) at the end of buffer, collapse all cells and hide all non-level-one
4734 (2) on a header line but not at the beginning or end, display
4735 properties of each cell in kotl beginning at point;
4736 (3) between cells or within the read-only indentation region to the
4737 left of a cell, then move point to prior location and prompt to
4738 move one tree to a new location in the outline; hit the Action
4739 Key twice to select the tree to move and where to move it;
4740 (4) anywhere else, scroll down a windowful.
4746 When pressed on a Smart Menu item:
4750 Displays help for item.
4757 When pressed at the end of a Help buffer:
4759 Restores window configuration prior to help display.
4765 When pressed within an OO-Browser listing window:
4767 (1) in a blank buffer or at the end of a buffer, browser help
4768 information is displayed in the viewer window;
4769 (2) at the beginning of a (non-single char) class name, the class'
4770 ancestors are listed;
4771 (3) at the end of an entry line, scrolls listing up;
4772 (4) on the '...', following a class name, point is moved to the class
4773 descendency expansion;
4774 (5) before an element name, the implementor classes of the name are
4776 (6) anywhere else on an entry line, the source is displayed for editing.
4778 (1) in a blank buffer, a selection list of buffer files is displayed;
4779 (2) at the beginning of a (non-single char) entry, the class'
4780 descendants are listed;
4781 (3) at the end of an entry line, scrolls listing down;
4782 (4) on the '...', following a class name, point is moved to the class
4784 (5) anywhere else on a class entry line, lists the class' elements;
4785 (6) anywhere else on an element line, lists the element's implementor
4787 (7) on a blank line following all entries, the current listing buffer
4794 When pressed within an OO-Browser Command Help Menu buffer:
4796 Executes an OO-Browser command whose key binding is at point.
4798 Displays help for an OO-Browser command whose key binding is at point.
4804 When pressed on an identifier within an OO-Browser source file:
4806 Tries to display identifier definition.
4815 When pressed within a C source code file:
4817 Jumps to the definition of selected C construct:
4818 (1) on a '#include' statement, the include file is displayed;
4819 Look for include file in directory lists
4820 'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
4821 (2) on a C identifier, the identifier definition is displayed,
4822 assuming the identifier is found within an 'etags' generated tag file
4823 in the current directory or any of its ancestor directories.
4824 (3) if 'smart-c-use-lib-man' is non-nil, the C identifier is
4825 recognized as a library symbol, and a man page is found for the
4826 identifier, then the man page is displayed.
4828 Jumps to the next tag matching an identifier at point.
4834 When pressed within an assembly source code file:
4836 Jumps to the definition of selected assembly construct:
4837 (1) on an include statement, the include file is displayed;
4838 Look for include file in directory list
4839 'smart-asm-include-dirs'.
4840 (2) on an identifier, the identifier definition is displayed,
4841 assuming the identifier is found within an 'etags' generated
4842 tag file in the current directory or any of its ancestor
4845 Jumps to the next tag matching an identifier at point.
4852 When pressed within a C++ source code file:
4854 Jumps to the definition of selected C+ construct:
4855 (1) on a '#include' statement, the include file is displayed;
4856 Look for include file in directory lists
4857 'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
4858 (2) on a C++ identifier, the identifier definition is displayed,
4859 assuming the identifier is found within an 'etags' generated tag file
4860 in the current directory or any of its ancestor directories.
4861 (3) if 'smart-c-use-lib-man' is non-nil, the C++ identifier is
4862 recognized as a library symbol, and a man page is found for the
4863 identifier, then the man page is displayed.
4865 Jumps to the next tag matching an identifier at point.
4871 When pressed within a Objective-C source code file:
4873 Jumps to the definition of selected C+ construct:
4874 (1) on a '#include' statement, the include file is displayed;
4875 Look for include file in directory lists
4876 'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
4877 (2) on an Objective-C identifier, the identifier definition is displayed,
4878 assuming the identifier is found within an 'etags' generated tag file
4879 in the current directory or any of its ancestor directories.
4880 (3) if 'smart-c-use-lib-man' is non-nil, the Objective-C identifier is
4881 recognized as a library symbol, and a man page is found for the
4882 identifier, then the man page is displayed.
4884 Jumps to the next tag matching an identifier at point.
4891 When pressed on a Lisp symbol within a Lisp code buffer:
4893 Jumps to the definition of any selected Lisp construct.
4894 If on an Emacs Lisp require, load, or autoload clause and 'find-library'
4895 from load-library package by Hallvard Furuseth <hallvard@@ifi.uio.no> has
4896 been loaded, jumps to library source, if possible.
4898 Jumps to the next tag matching an identifier at point or if using the
4899 "wtags" package and identifier is an Emacs Lisp symbol, then displays
4900 documentation for the symbol.
4906 When the OO-Browser has been loaded and the press is within a C++ buffer:
4908 Jumps to the definition of selected C++ construct via OO-Browser support.
4909 (1) on a '#include' statement, the include file is displayed;
4910 Look for include file in directory lists
4911 'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
4912 (2) within a method declaration, its definition is displayed;
4913 (3) on a class name, the class definition is shown.
4919 When the OO-Browser has been loaded and the press is within a
4922 Jumps to the definition of selected Objective-C construct via
4924 (1) on a '#include' statement, the include file is displayed;
4925 Look for include file in directory lists
4926 'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
4927 (2) within a method declaration, its definition is displayed;
4928 (3) on a class name, the class definition is shown.
4934 When pressed within an occur-mode or moccur-mode buffer:
4936 Jumps to the source buffer and line of the current occurrence.
4943 When pressed within a calendar-mode buffer:
4945 (1) at the end of the buffer, the calendar is scrolled forward 3 months;
4946 (2) to the left of any dates on a calendar line, the calendar is scrolled
4948 (3) on a date, the diary entries for the date, if any, are displayed.
4950 (1) at the end of the buffer, the calendar is scrolled backward 3 months;
4951 (2) to the left of any dates on a calendar line, the calendar is scrolled
4953 (3) anywhere else, all dates with marking diary entries are marked in the
4960 When pressed within a man page apropos buffer:
4962 (1) on a UNIX man apropos entry, the man page for that entry is
4963 displayed in another window;
4964 (2) on or after the last line, the buffer in the other window is
4965 scrolled up a windowful.
4967 (1) on a UNIX man apropos entry, the man page for that entry is
4968 displayed in another window;
4969 (2) on or after the last line, the buffer in the other window is
4970 scrolled down a windowful.
4976 If Smart Menu package has been loaded and 'hkey-always-display-menu' is
4979 Pops up a window with a Smart Menu of commands.
4980 Menu displayed is selected by (smart-menu-choose-menu).
4987 If pressed within an outline-mode buffer or when 'selective-display' is
4990 Collapses, expands, and moves outline entries.
4991 (1) after an outline heading has been cut via the Action Key, then paste
4992 the cut heading at point;
4993 (2) at the end of buffer, show all buffer text
4994 (3) at the beginning of a heading line, cut the headings subtree from the
4996 (4) on a header line but not at the beginning or end, if headings
4997 subtree is hidden then show it, otherwise hide it;
4998 (5) anywhere else, scroll up a windowful.
5000 (1) after an outline heading has been cut via the Action Key, allow
5001 multiple pastes throughout the buffer (last paste should be done
5002 with the Action Key, not the Assist Key);
5003 (2) at the end of buffer, hide all bodies in buffer;
5004 (3) at the beginning of a heading line, cut the current heading (sans
5005 subtree) from the buffer;
5006 (4) on a header line but not at the beginning or end, if heading body is
5007 hidden then show it, otherwise hide it;
5008 (5) anywhere else, scroll down a windowful.
5015 @cindex Info browsing
5016 If pressed within an Info manual node:
5018 (1) the first line of an Info Menu Entry or Cross Reference, the desired
5020 (2) the Up,Next,or Previous entries of a Node Header (first line),
5021 the desired node is found;
5022 (3) the File entry of a Node Header (first line),
5023 the 'Top' node within that file is found;
5024 (4) at the end of the current node, the Next node is found (this will
5025 descend subtrees if the function 'Info-global-next' is bound);
5026 (5) anywhere else (e.g@. at the end of a line), the current node entry is
5027 scrolled up a windowful.
5029 (1) the first line of an Info Menu Entry or Cross Reference, the desired
5031 (2) the Up,Next,or Previous entries of a Node Header (first line),
5032 the last node in the history list is found;
5033 (3) the File entry of a Node Header (first line),
5034 the 'DIR' root-level node is found;
5035 (4) at the end of the current node, the Previous node is found (this will
5036 return from subtrees if the function 'Info-global-prev is bound);
5037 (5) anywhere else (e.g@. at the end of a line), the current node entry is
5038 scrolled down a windowful.
5045 If pressed within a Hyperbole-supported mail reader, 'hmail:reader', or mail
5046 summary mode, 'hmail:lister', buffer at:
5048 (1) a msg buffer, within the first line or at the end of a message,
5049 the next undeleted message is displayed;
5050 (2) a msg buffer within the first line of an Info cross reference, the
5051 reference is followed;
5052 (3) anywhere else in a msg buffer, the window is scrolled up one
5054 (4) a msg summary buffer on a header entry, the message corresponding to
5055 the header is displayed in the msg window;
5056 (5) a msg summary buffer, on or after the last line, the messages marked
5057 for deletion are expunged.
5059 (1) a msg buffer, within the first line or at the end of a message,
5060 the previous undeleted message is displayed;
5061 (2) a msg buffer within the first line of an Info cross reference, the
5062 reference is followed;
5063 (3) anywhere else in a msg buffer, the window is scrolled down one
5065 (4) a msg summary buffer on a header entry, the message corresponding to
5066 the header is marked as deleted;
5067 (5) a msg summary buffer, on or after the last line, all messages are
5075 @cindex GNUS browsing
5076 If pressed within a GNUS listing of newsgroups buffer at:
5078 (1) a GNUS-GROUP line, that newsgroup is read;
5079 (2) to the left of any GNUS-GROUP line, on any of the whitespace, the
5080 current group is unsubscribed or resubscribed;
5081 (3) at the end of the GNUS-GROUP buffer, after all lines, checks for new
5084 (1) a GNUS-GROUP line, that newsgroup is read;
5085 (2) to the left of any GNUS-GROUP line, on any of the whitespace, the
5086 user is prompted for a group name to subscribe or unsubscribe to;
5087 (3) at the end of the GNUS-GROUP buffer, after all lines, quits from the
5095 If pressed within a GNUS newsreader subject listing buffer at:
5097 (1) a GNUS-SUBJECT line, that article is read, marked deleted, and
5099 (2) at the end of the GNUS-SUBJECT buffer, the next undeleted article
5100 is read or the next group is entered.
5102 (1) a GNUS-SUBJECT line, that article is read and scrolled backward;
5103 (2) at the end of the GNUS-SUBJECT buffer, the subject is exited, the
5104 user is returned to group mode.
5110 If pressed within a GNUS newsreader article buffer at:
5112 (1) the first line or end of an article, the next unread message is
5114 (2) the first line of an Info cross reference, the reference is followed;
5115 (3) anywhere else, the window is scrolled up a windowful.
5117 (1) the first line or end of an article, the previous message is
5119 (2) the first line of an Info cross reference, the reference is followed;
5120 (3) anywhere else, the window is scrolled down a windowful.
5127 @cindex click, buffer menu
5129 If pressed within a listing of buffers (Buffer-menu-mode):
5131 (1) on the first column of an entry, the selected buffer is marked for
5133 (2) on the second column of an entry, the selected buffer is marked to be
5135 (3) anywhere else within an entry line, all saves and deletes are done,
5136 and selected buffers are displayed, including the one just clicked
5137 on (if in the OO-Browser, only the selected buffer is displayed);
5138 (4) on or after the last line in the buffer, all saves and deletes are
5141 (1) on the first or second column of an entry, the selected buffer is
5142 unmarked for display and for saving or deletion;
5143 (2) anywhere else within an entry line, the selected buffer is marked for
5145 (3) on or after the last line in the buffer, all display, save, and delete
5146 marks on all entries are undone.
5152 @cindex click, dired
5153 @cindex dired browsing
5154 If pressed within a dired-mode buffer:
5156 (1) within an entry line, the selected file/directory is displayed
5157 for editing in the other window;
5158 (2) on or after the last line in the buffer, if any deletes are to be
5159 performed, they are executed after user verification, otherwise, this
5160 dired invocation is quit.
5162 (1) on a '~' character, all backup files in the directory are marked for
5164 (2) on a '#' character, all auto-save files in the directory are marked
5166 (3) anywhere else within an entry line, the current entry is marked for
5168 (4) on or after the last line in the buffer, all delete marks on all
5177 @cindex tar archive browsing
5178 @cindex extracting from tar files
5179 If pressed within a tar-mode buffer:
5181 (1) within an entry line, the selected file/directory is displayed
5182 for editing in the other window;
5183 (2) on or after the last line in the buffer, if any deletes are to be
5184 performed, they are executed after user verification, otherwise, this
5185 tar file browser is quit.
5187 (1) on an entry line, the current entry is marked for deletion;
5188 (2) on or after the last line in the buffer, all delete marks on all
5195 @cindex man page references
5196 If pressed on a cross reference within a man page entry section labeled
5197 NAME, SEE ALSO, or PACKAGES USED, or within a man page C routine
5198 specification (see 'smart-man-c-routine-ref') and man page buffer
5199 has either an attached file or else a @var{man-path} local variable
5200 containing its pathname:
5202 Displays man page or source code for cross reference.
5208 @cindex click, world-wide web
5211 @cindex world-wide web
5212 If pressed on a world-wide web universal resource locator:
5214 Displays the URL referent at point.
5216 Goes back to a previously displayed web page.
5222 @cindex game, gomoku
5224 If pressed in a Gomoku game buffer.
5226 Makes a move at the space pointed to.
5228 Takes back a prior move made at the space pointed to.
5234 @cindex click, wrolo matches
5235 @cindex wrolo matches
5236 If pressed within an entry in the wrolo match display buffer:
5238 The entry is edited in the other window.
5242 @node Outliner Keys, Suggestion or Bug Reporting, Smart Key Reference, Top
5243 @appendix Outliner Keys
5245 @cindex outliner keys
5246 This appendix summarizes the specialized key bindings available when
5247 editing an outline with Hyperbole. Each key is shown together with its
5248 command binding and the documentation for that command. Normal emacs
5249 editing keys are modified to account for the structure within outlines.
5250 An outliner command which overloads an Emacs command named @emph{cmd}
5251 would be named @emph{kotl-mode:cmd}.
5256 @item kfile:write @{@kbd{C-x C-w}@}
5257 Write current outline to FILE.
5259 @findex klink:create
5260 @item klink:create @{@kbd{C-c l}@}
5261 Insert at point an implicit link to REFERENCE.
5262 REFERENCE should be a cell-ref or a string containing "filename, cell-ref".
5263 See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
5265 @findex kotl-mode:add-cell
5266 @item kotl-mode:add-cell @{@key{LFD}@}
5267 Add a cell following current cell at optional RELATIVE-LEVEL with CONTENTS string.
5268 Optional prefix arg RELATIVE-LEVEL means add as sibling if nil or >= 0, as child
5269 if equal to universal argument, @kbd{C-u}, and as sibling of current cell's
5270 parent, otherwise. If added as sibling of current level, RELATIVE-LEVEL is
5271 used as a repeat count for the number of cells to add.
5273 Return last newly added cell.
5275 @findex kotl-mode:add-child
5276 @item kotl-mode:add-child @{@kbd{C-c a}@}
5277 Add a new cell to current kview as first child of current cell.
5279 @findex kotl-mode:add-parent
5280 @item kotl-mode:add-parent @{@kbd{C-c p}@}
5281 Add a new cell to current kview as sibling of current cell's parent.
5283 @findex kotl-mode:append-cell
5284 @item kotl-mode:append-cell @{@kbd{C-c +}@}
5285 Append CONTENTS-CELL to APPEND-TO-CELL.
5286 APPEND-TO-CELL is refilled if neither cell has a no-fill property and
5287 kotl-mode:refill-flag is enabled.
5289 @findex kotl-mode:back-to-indentation
5290 @item kotl-mode:back-to-indentation @{@kbd{M-m}@}
5291 Move point to the first non-read-only non-whitespace character on this line.
5293 @findex kotl-mode:backward-cell
5294 @item kotl-mode:backward-cell @{@kbd{C-c C-b}@}
5295 Move to prefix ARGth prior cell (same level) within current view.
5296 Return number of cells left to move.
5298 @findex kotl-mode:backward-char
5299 @item kotl-mode:backward-char @{@kbd{C-b}@}
5300 Move point backward ARG (or 1) characters and return point.
5302 @findex kotl-mode:backward-kill-word
5303 @item kotl-mode:backward-kill-word @{@kbd{M-DEL}@}
5304 Kill up to prefix ARG words preceding point within a single cell.
5306 @findex kotl-mode:backward-sentence
5307 @item kotl-mode:backward-sentence @{@kbd{M-a}@}
5308 Move point backward ARG (or 1) sentences and return point.
5310 @findex kotl-mode:backward-word
5311 @item kotl-mode:backward-word @{@kbd{M-b}@}
5312 Move point backward ARG (or 1) words and return point.
5314 @findex kotl-mode:beginning-of-buffer
5315 @item kotl-mode:beginning-of-buffer @{@kbd{M-<}@}
5316 Move point to beginning of buffer and return point.
5318 @findex kotl-mode:beginning-of-cell
5319 @item kotl-mode:beginning-of-cell @{@kbd{C-c ,}@}
5320 Move point to beginning of current or ARGth - 1 prior cell and return point.
5322 @findex kotl-mode:beginning-of-line
5323 @item kotl-mode:beginning-of-line @{@kbd{C-a}@}
5324 Move point to beginning of current or ARGth - 1 line and return point.
5326 @findex kotl-mode:beginning-of-tree
5327 @item kotl-mode:beginning-of-tree @{@kbd{C-c ^}@}
5328 Move point to the level 1 root of the current cell's tree.
5329 Leave point at the start of the cell.
5331 @findex kotl-mode:center-line
5332 @item kotl-mode:center-line @{@kbd{M-s}@}
5334 Center the line point is on, within the width specified by @var{fill-column}.
5335 This means adjusting the indentation so that it equals the distance between
5336 the end of the text and @var{fill-column}.
5338 @findex kotl-mode:center-paragraph
5339 @item kotl-mode:center-paragraph @{@kbd{M-S}@}
5340 Center each nonblank line in the paragraph at or after point.
5341 See @code{center-line} for more info.
5343 @findex kotl-mode:copy-after
5344 @item kotl-mode:copy-after @{@kbd{C-c c}@}
5345 Copy tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
5346 If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
5347 TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
5349 Leave point at the start of the root cell of the new tree.
5351 @findex kotl-mode:copy-before
5352 @item kotl-mode:copy-before @{@kbd{C-c C-c}@}
5353 Copy tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
5354 If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
5355 TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
5357 Leave point at the start of the root cell of the new tree.
5359 @findex kotl-mode:copy-to-buffer
5360 @item kotl-mode:copy-to-buffer @{@kbd{C-c M-c}@}
5361 Copy outline tree rooted at CELL-REF to a non-koutline BUFFER.
5362 Use 0 to copy the whole outline buffer.
5364 @findex kotl-mode:copy-to-register
5365 @item kotl-mode:copy-to-register @{@kbd{C-x x}@}
5366 Copy into REGISTER the region START to END.
5367 With optional prefix arg DELETE-FLAG, delete region.
5369 @findex kotl-mode:delete-backward-char
5370 @item kotl-mode:delete-backward-char @{@kbd{DEL}@}
5371 Delete up to the preceding prefix ARG characters.
5372 Return number of characters deleted.
5373 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
5374 Does not delete across cell boundaries.
5376 @findex kotl-mode:delete-blank-lines
5377 @item kotl-mode:delete-blank-lines @{@kbd{C-x C-o}@}
5378 On blank line within a cell, delete all surrounding blank lines, leaving just one.
5379 On isolated blank line, delete that one.
5380 On nonblank line, delete all blank lines that follow it.
5382 If nothing but whitespace follows point until the end of a cell, delete all
5383 whitespace at the end of the cell.
5385 @findex kotl-mode:delete-char
5386 @item kotl-mode:delete-char @{@kbd{C-d}@}
5387 Delete up to prefix ARG characters following point.
5388 Return number of characters deleted.
5389 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
5390 Does not delete across cell boundaries.
5392 @findex kotl-mode:delete-indentation
5393 @item kotl-mode:delete-indentation @{@kbd{M-^}@}
5394 Join this line to previous and fix up whitespace at join.
5395 If there is a fill prefix, delete it from the beginning of this line.
5396 With argument, join this line to following line.
5398 @findex kotl-mode:demote-tree
5399 @vindex kotl-mode:refill-flag
5400 @item kotl-mode:demote-tree @{@kbd{TAB}@}
5401 Move current kotl a maximum of prefix ARG levels lower in current view.
5402 Each cell is refilled iff its @emph{no-fill} attribute is nil and
5403 @var{kotl-mode:refill-flag} is non-nil. With prefix ARG = 0, cells are
5404 demoted up to one level and kotl-mode:refill-flag is treated as true.
5406 @findex kotl-mode:down-level
5407 @item kotl-mode:down-level @{@kbd{C-c C-d}@}
5408 Move down prefix ARG levels lower within current tree.
5410 @findex kotl-mode:end-of-buffer
5411 @item kotl-mode:end-of-buffer @{@kbd{M->}@}
5412 Move point to end of buffer and return point.
5414 @findex kotl-mode:end-of-cell
5415 @item kotl-mode:end-of-cell @{@kbd{C-c .}@}
5416 Move point to end of current or ARGth - 1 succeeding cell and return point.
5418 @findex kotl-mode:end-of-line
5419 @item kotl-mode:end-of-line @{@kbd{C-e}@}
5420 Move point to end of current or ARGth - 1 line and return point.
5422 @findex kotl-mode:end-of-tree
5423 @item kotl-mode:end-of-tree @{@kbd{C-c $}@}
5424 Move point to the last cell in tree rooted at the current cell.
5425 Leave point at the start of the cell.
5427 @findex kotl-mode:exchange-cells
5428 @item kotl-mode:exchange-cells @{@kbd{C-c e}@}
5429 Exchange CELL-REF-1 with CELL-REF-2 in current view. Don't move point.
5431 @findex kotl-mode:fill-cell
5432 @item kotl-mode:fill-cell @{@kbd{C-c M-j}@}
5433 Fill current cell within current view if it does not have the 'no-fill attribute.
5434 With optional JUSTIFY, justify cell as well.
5435 IGNORE-COLLAPSED-P is used when caller has already expanded cell, indicating
5436 it is not collapsed.
5438 @findex kotl-mode:fill-paragraph
5439 @item kotl-mode:fill-paragraph @{@kbd{C-x f}@}
5440 Fill current paragraph within cell. With optional JUSTIFY, justify
5441 paragraph as well. Ignore any non-nil no-fill attribute attached to the
5444 @findex kotl-mode:fill-tree
5445 @item kotl-mode:fill-tree @{@kbd{C-M-j}@}
5446 Refill each cell within the tree whose root is at point.
5448 @findex kotl-mode:first-sibling
5449 @item kotl-mode:first-sibling @{@kbd{C-c <}@}
5450 Move point to the first sibling of the present cell.
5451 Leave point at the start of the cell or at its present position if it is
5452 already within the first sibling cell.
5454 @findex kotl-mode:fkey-backward-char
5455 @item kotl-mode:fkey-backward-char @{@kbd{left}@}
5456 Move point backward ARG (or 1) characters and return point.
5458 @findex kotl-mode:fkey-forward-char
5459 @item kotl-mode:fkey-forward-char @{@kbd{right}@}
5460 Move point forward ARG (or 1) characters and return point.
5462 @findex kotl-mode:fkey-next-line
5463 @item kotl-mode:fkey-next-line @{@kbd{down}@}
5464 Move point to ARGth next line and return point.
5466 @findex kotl-mode:fkey-previous-line
5467 @item kotl-mode:fkey-previous-line @{@kbd{up}@}
5468 Move point to ARGth previous line and return point.
5470 @findex kotl-mode:forward-cell
5471 @item kotl-mode:forward-cell @{@kbd{C-c C-f}@}
5472 Move to prefix ARGth following cell (same level) within current view.
5473 Return number of cells left to move.
5475 @findex kotl-mode:forward-char
5476 @item kotl-mode:forward-char @{@kbd{C-f}@}
5477 Move point forward ARG (or 1) characters and return point.
5479 @findex kotl-mode:forward-para
5480 @item kotl-mode:forward-para @{@kbd{M-n}@}
5481 Move to prefix ARGth next cell (any level) within current view.
5483 @findex kotl-mode:forward-paragraph
5484 @item kotl-mode:forward-paragraph @{@kbd{M-]}@}
5485 Move to prefix ARGth next cell (any level) within current view.
5487 @findex kotl-mode:forward-sentence
5488 @item kotl-mode:forward-sentence @{@kbd{M-e}@}
5489 Move point forward ARG (or 1) sentences and return point.
5491 @findex kotl-mode:forward-word
5492 @item kotl-mode:forward-word @{@kbd{M-f}@}
5493 Move point forward ARG (or 1) words and return point.
5495 @findex kotl-mode:goto-cell
5496 @item kotl-mode:goto-cell @{@kbd{C-c g}@}
5497 Move point to start of cell given by CELL-REF. (See 'kcell:ref-to-id'.)
5498 Return point iff CELL-REF is found within current view.
5499 With a prefix argument, CELL-REF is assigned the argument value for use
5502 Optional second arg, ERROR-P, non-nil means signal an error if CELL-REF is
5503 not found within current view. Will signal same error if called
5504 interactively when CELL-REF is not found.
5506 @findex kotl-mode:hide-sublevels
5507 @item kotl-mode:hide-sublevels @{@kbd{C-X $}@}
5508 Hide all cells in outline at levels deeper than LEVELS-TO-KEEP (a
5509 number). Shows any hidden cells within LEVELS-TO-KEEP. 1 is the first
5512 @findex kotl-mode:hide-subtree
5513 @item kotl-mode:hide-subtree @{@kbd{C-M-h}@}
5514 Hide subtree, ignoring root, at optional CELL-REF (defaults to cell at
5517 @findex kotl-mode:hide-tree
5518 @item kotl-mode:hide-tree @{@kbd{C-c BS}@}
5519 Collapse kotl rooted at optional CELL-REF (defaults to cell at point).
5521 @findex kotl-mode:insert-file
5522 @item kotl-mode:insert-file @{@kbd{C-x i}@}
5523 Insert each paragraph in IMPORT-FROM as a separate cell in the current view.
5524 Insert as sibling cells following the current cell. IMPORT-FROM may be a
5525 buffer name or file name (file name completion is provided).
5527 @findex kotl-mode:insert-register
5528 @item kotl-mode:insert-register @{@kbd{C-c r i}@}
5529 Insert contents of register REGISTER at point in current cell.
5530 REGISTER is a character naming the register to insert.
5531 Normally puts point before and mark after the inserted text.
5532 If optional second arg is non-nil, puts mark before and point after.
5533 Interactively, second arg is non-nil if prefix arg is supplied.
5535 @findex kotl-mode:just-one-space
5536 @item kotl-mode:just-one-space @{@kbd{M-\}@}
5537 Delete all spaces and tabs around point and leave one space.
5539 @findex kotl-mode:kcell-help
5540 @item kotl-mode:kcell-help @{@kbd{C-c h}@}
5541 Display a temporary buffer with CELL-REF's properties.
5542 CELL-REF defaults to current cell.
5543 Optional prefix arg CELLS-FLAG selects the cells to print:
5544 If = 1, print CELL-REF's cell only;
5545 If > 1, print CELL-REF's visible kotl (the tree rooted at CELL-REF);
5546 If < 1, print all visible cells in current view (CELL-REF is not used).
5548 See also the documentation for @code{kotl-mode:properties}.
5550 @findex kotl-mode:kill-contents
5551 @item kotl-mode:kill-contents @{@kbd{C-c k}@}
5552 Kill contents of cell from point to cell end.
5553 With prefix ARG, kill entire cell contents.
5555 @findex kotl-mode:kill-line
5556 @item kotl-mode:kill-line @{@kbd{C-k}@}
5557 Kill ARG lines from point.
5559 @findex kotl-mode:kill-region
5560 @item kotl-mode:kill-region @{@kbd{C-w}@}
5561 Kill region between START and END within a single kcell.
5562 With optional COPY-P equal to 't, copy region to kill ring but does not
5563 kill it. With COPY-P any other non-nil value, return region as a
5564 string without affecting kill ring.
5566 If the buffer is read-only and COPY-P is nil, the region will not be deleted
5567 but it will be copied to the kill ring and then an error will be signaled.
5569 @findex kotl-mode:kill-ring-save
5570 @item kotl-mode:kill-ring-save @{@kbd{M-w}@}
5571 Copy region between START and END within a single kcell to kill ring.
5573 @findex kotl-mode:kill-sentence
5574 @item kotl-mode:kill-sentence @{@kbd{M-k}@}
5575 Kill up to prefix ARG (or 1) sentences following point within a single cell.
5577 @findex kotl-mode:kill-tree
5578 @item kotl-mode:kill-tree @{@kbd{C-c C-k}@}
5579 Kill ARG following trees starting with tree rooted at point.
5580 If ARG is not a non-positive number, nothing is done.
5582 @findex kotl-mode:kill-word
5583 @item kotl-mode:kill-word @{@kbd{M-d}@}
5584 Kill up to prefix ARG words following point within a single cell.
5586 @findex kotl-mode:last-sibling
5587 @item kotl-mode:last-sibling @{@kbd{C-c >}@}
5588 Move point to the last sibling of the present cell.
5589 Leave point at the start of the cell or at its present position if it is
5590 already within the last sibling cell.
5592 @findex kotl-mode:mail-tree
5593 @item kotl-mode:mail-tree @{@kbd{C-c @@}@}
5594 Mail outline tree rooted at CELL-REF. Use "0" for whole outline buffer.
5596 @findex kotl-mode:move-after
5597 @item kotl-mode:move-after @{@kbd{C-c m}@}
5598 Move tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
5599 If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
5600 TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
5601 With optional COPY-P, copies tree rather than moving it.
5603 Leave point at original location but return the tree's new start point.
5605 @findex kotl-mode:move-before
5606 @item kotl-mode:move-before @{@kbd{C-c RET}@}
5607 Move tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
5608 If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
5609 TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
5610 With optional COPY-P, copies tree rather than moving it.
5612 Leave point at original location but return the tree's new start point.
5614 @findex kotl-mode:newline
5615 @item kotl-mode:newline @{@kbd{RET}@}
5616 Insert a newline. With ARG, insert ARG newlines.
5617 In Auto Fill mode, if no numeric arg, break the preceding line if it is
5620 @findex kotl-mode:next-cell
5621 @item kotl-mode:next-cell @{@kbd{C-c C-n}@}
5622 Move to prefix ARGth next cell (any level) within current view.
5624 @findex kotl-mode:next-line
5625 @item kotl-mode:next-line @{@kbd{C-n}@}
5626 Move point to ARGth next line and return point.
5628 @findex kotl-mode:open-line
5629 @item kotl-mode:open-line @{@kbd{C-o}@}
5630 Insert a newline and leave point before it.
5631 With arg N, insert N newlines.
5633 @findex kotl-mode:overview
5634 @item kotl-mode:overview @{@kbd{C-c C-o}@}
5635 Show only the first line of each cell in the current outline.
5637 @findex kotl-mode:previous-cell
5638 @item kotl-mode:previous-cell @{@kbd{C-c C-p}@}
5639 Move to prefix ARGth previous cell (any level) within current view.
5641 @findex kotl-mode:previous-line
5642 @item kotl-mode:previous-line @{@kbd{C-p}@}
5643 Move point to ARGth previous line and return point.
5645 @findex kotl-mode:promote-tree
5646 @vindex kotl-mode:refill-flag
5647 @item kotl-mode:promote-tree @{@kbd{M-TAB}@}
5648 Move current kotl a maximum of prefix ARG levels higher in current view.
5649 Each cell is refilled iff its @emph{no-fill} attribute is nil and
5650 @var{kotl-mode:refill-flag} is non-nil. With prefix ARG = 0, cells are
5651 promoted up to one level and kotl-mode:refill-flag is treated as true.
5653 @findex kotl-mode:scroll-down
5654 @item kotl-mode:scroll-down @{@kbd{M-v}@}
5655 Scroll text of current window downward ARG lines; or a windowful if no ARG.
5657 @findex kotl-mode:scroll-up
5658 @item kotl-mode:scroll-up @{@kbd{C-v}@}
5659 Scroll text of current window upward ARG lines; or a windowful if no ARG.
5661 @findex kotl-mode:set-cell-attribute
5662 @item kotl-mode:set-cell-attribute @{@kbd{C-c C-i}@}
5663 Include ATTRIBUTE VALUE with the current cell or the cell at optional POS.
5664 Replaces any existing value that ATTRIBUTE has.
5665 When called interactively, it displays the setting in the minibuffer as
5668 @findex kotl-mode:set-fill-prefix
5669 @item kotl-mode:set-fill-prefix @{@kbd{C-x l}@}
5670 Sets fill prefix to line up to point.
5671 With prefix arg TURN-OFF or at begin of line, turns fill prefix off.
5673 @findex kotl-mode:show-all
5674 @item kotl-mode:show-all @{@kbd{C-c C-a}@}
5675 Show (expand) all cells in current view.
5677 @findex kotl-mode:show-subtree
5678 @item kotl-mode:show-subtree
5679 Show subtree, ignoring root, at optional CELL-REF (defaults to cell at
5682 @findex kotl-mode:show-tree
5683 @item kotl-mode:show-tree @{@kbd{C-c C-s}@}
5684 Display fully expanded kotl rooted at CELL-REF.
5686 @findex kotl-mode:split-cell
5687 @item kotl-mode:split-cell @{@kbd{C-c s}@}
5688 Split cell into two cells and move to new cell.
5689 Cell contents after point become part of newly created cell.
5690 Default is to create new cell as sibling of current cell.
5691 With optional universal ARG, @kbd{C-u}, new cell is added as child of
5694 @findex kotl-mode:top-cells
5695 @item kotl-mode:top-cells @{@kbd{C-c C-t}@}
5696 Collapse all level 1 cells in view and hide any deeper sublevels.
5698 @findex kotl-mode:transpose-cells
5699 @item kotl-mode:transpose-cells @{@kbd{C-c t}@}
5700 Exchange current and previous visible cells, leaving point after both.
5701 If no previous cell, exchange current with next cell.
5702 With prefix ARG, take current cell and move it past ARG cells.
5703 With prefix ARG = 0, interchange the cell that contains point with the cell
5706 @findex kotl-mode:transpose-chars
5707 @item kotl-mode:transpose-chars @{@kbd{C-t}@}
5708 Interchange characters around point, moving forward one character.
5709 With prefix ARG, take character before point and drag it forward past ARG
5710 other characters (backward if ARG negative).
5711 If no prefix ARG and at end of line, the previous two characters are
5714 @findex kotl-mode:transpose-lines
5715 @item kotl-mode:transpose-lines @{@kbd{C-x C-t}@}
5716 Exchange current line and previous line, leaving point after both.
5717 If no previous line, exchange current with next line.
5718 With prefix ARG, take previous line and move it past ARG lines.
5719 With prefix ARG = 0, interchange the line that contains point with the line
5722 @findex kotl-mode:transpose-words
5723 @item kotl-mode:transpose-words @{@kbd{M-t}@}
5724 Interchange words around point, leaving point after both words.
5725 With prefix ARG, take word before or around point and drag it forward past
5726 ARG other words (backward if ARG negative). If ARG is zero, the words around
5727 or after point and around or after mark are interchanged.
5729 @findex kotl-mode:up-level
5730 @item kotl-mode:up-level @{@kbd{C-c C-u}@}
5731 Move up prefix ARG levels higher in current outline view.
5733 @findex kotl-mode:yank
5734 @item kotl-mode:yank @{@kbd{C-y}@}
5735 Reinsert the last stretch of killed text.
5736 More precisely, reinsert the stretch of killed text most recently
5737 killed OR yanked. Put point at end, and set mark at beginning.
5738 With just C-u as argument, same but put point at beginning (and mark at end).
5739 With argument N, reinsert the Nth most recently killed stretch of killed
5741 See also the command M-x kotl-mode:yank-pop.
5743 @findex kotl-mode:yank-pop
5744 @item kotl-mode:yank-pop @{@kbd{M-y}@}
5745 Replace just-yanked stretch of killed text with a different stretch.
5746 This command is allowed only immediately after a @code{yank} or a
5747 @code{yank-pop}. At such a time, the region contains a stretch of
5748 reinserted previously-killed text. @code{yank-pop} deletes that text
5749 and inserts in its place a different stretch of killed text.
5751 With no argument, the previous kill is inserted.
5752 With argument N, insert the Nth previous kill.
5753 If N is negative, this is a more recent kill.
5755 The sequence of kills wraps around, so that after the oldest one
5756 comes the newest one.
5758 @findex kotl-mode:zap-to-char
5759 @item kotl-mode:zap-to-char @{@kbd{M-z}@}
5760 Kill up to and including prefix ARG'th occurrence of CHAR.
5761 Goes backward if ARG is negative; error if CHAR not found.
5763 @findex kview:set-label-type
5764 @item kview:set-label-type @{@kbd{C-c C-l}@}
5765 Change kview's label display type to NEW-TYPE, updating all displayed labels.
5766 See documentation for variable, kview:default-label-type, for
5767 valid values of NEW-TYPE.
5769 @findex kvspec:activate
5770 @item kvspec:activate @{@kbd{C-c C-v}@}
5771 Activate optional VIEW-SPEC or existing view spec in the current koutline.
5772 VIEW-SPEC is a string. See <$@{hyperb:dir@}/kotl/EXAMPLE.kotl, 2b17=048> for
5773 details on valid view specs.
5775 @findex kvspec:toggle-blank-lines
5776 @item kvspec:toggle-blank-lines @{@kbd{C-c b}@}
5777 Toggle blank lines between cells on or off.
5781 @node Suggestion or Bug Reporting, Questions and Answers, Outliner Keys, Top
5782 @appendix Suggestion or Bug Reporting
5784 @xref{Mail Lists}, for complete details on Hyperbole mailing lists and
5787 @cindex version description
5788 @cindex Hyperbole version
5789 If you find any errors in Hyperbole's operation or documentation, feel
5790 free to report them to the Hyperbole bug list:
5791 <bug-hyperbole@@gnu.org>. You need to be subscribed to the list todo
5792 that. See @xref{Mail Lists}, for details. Be sure to use the
5793 Msg/Compose-Hypb-Mail minibuffer menu item whenever you send a message
5794 to the mail list since it will insert important system version
5795 information for you.
5797 If you use Hyperbole mail or news support, @ref{Buttons in Mail}, a
5798 click with your Action Key on the Hyperbole mail list address
5799 will insert a description of your Hyperbole configuration information
5800 into your outgoing message, so that you do not have to type it. This is
5801 useful when composing a reply for the Hyperbole mail list. Otherwise,
5802 be sure to include your Emacs, Hyperbole and window system versions in
5803 your message. Your Hyperbole version number can be found in the
5804 top-level Hyperbole menu.
5806 Please use your subject line to state the position that your message
5807 takes on the topic that it addresses, e.g@. send "Subject: Basic bug in
5808 top-level Hyperbole menu." rather than "Subject: Hyperbole bug". This
5809 simple rule makes all e-mail communication much easier.
5811 If you have suggestions on how to improve Hyperbole, send them to the
5812 same address. Here are some issues you might address:
5816 What did you like and dislike about the system?
5818 What kinds of tasks, if any, does it seem to help you with?
5820 What did you think of the Emacs-based user interface?
5822 How was the Hyperbole Manual and other documentation?
5824 Was the setup trivial, average or hard?
5826 What areas of Hyperbole would you like to see expanded/added?
5828 How does it compare to other hypertext tools you have used?
5830 Was it easy or difficult to create your own types? Why?
5832 Did you get any use out of the external system encapsulations?
5835 @node Questions and Answers, Future Work, Suggestion or Bug Reporting, Top
5836 @appendix Questions and Answers
5840 @cindex mouse key bindings
5841 @findex hmouse-setup
5842 @findex hmouse-get-bindings
5843 @vindex file, hmouse-sh.el
5844 @vindex file, hmouse-reg.el
5845 @item How can I change the Smart Mouse Key bindings?
5846 @findex hmouse-shift-buttons
5847 Since the Smart Mouse Keys are set up for use under five different Emacs
5848 configurations, there is no easy way to provide user level
5849 customization. The command, @code{hmouse-shift-buttons}, can be used to
5850 select between shifted and unshifted Smart Mouse Keys. Any other mouse
5851 key binding changes must be done by editing the @code{hmouse-setup} and
5852 @code{hmouse-get-bindings} functions in the @file{hmouse-sh.el} and
5853 @file{hmouse-reg.el} files.
5855 @vindex file, hmouse-key.el
5856 @vindex file, hui-window.el
5858 @vindex hmouse-alist
5859 The @var{hkey-alist} and @var{hmouse-alist} variable
5860 settings in @file{hui-mouse.el} and @file{hui-window.el} must be altered
5861 if you want to change what the Smart Keys do in particular contexts.
5862 You should then update the Smart Key summary documentation in the file,
5863 @file{hypb-mouse.txt}, and potentially the same summary in this manual.
5866 @item Missing Action Types
5868 What if someone sends a mail message with a button for which I do
5869 not have the action type? Or a button whose link referent I can't access?
5871 You receive an error that an action type is not defined or a link
5872 referent is not accessible/readable if you try to use the button. This
5873 is hardly different than trying to get through a locked door without a
5874 key; you try the doorknob, find that it is locked, and then realize that
5875 you need to take a different approach or else give up.
5877 Like all communication, people need to coordinate, which usually
5878 requires an iterative process. If you get a mail message with a button
5879 for which you don't have the action type, you mail the sender and
5882 @cindex global button, modify
5883 @item How can I modify a number of global buttons in succession?
5885 Rather than typing the name for each, it is quicker to jump to the
5886 global button file and edit the buttons there as you would any explicit
5887 buttons. By default, the ButFile/PersonalFile menu item takes you to
5888 the file where global buttons are saved.
5890 @item Why is all the button data scattered across directories?
5892 When you think of a hyper-space that you depend on every day, you don't
5893 want to have a single point of failure make you incapable of doing work.
5894 With Hyperbole, if some directories become unavailable for a particular
5895 time (e.g@. the filesystems on which they reside are dismounted) you can
5896 still work elsewhere with minimal effect. We believe this to be a
5897 compelling factor to leave the design with external button data storage.
5899 This design also permits the potential addition of buttons to read-only
5902 @item Why are action types defined separately from their implicit button types?
5904 Any category of button can make use of an action type. Some action types
5905 are useful as behavior definitions for a variety of button categories,
5906 so all action types are defined separately to give them independence
5907 from those types which apply them.
5909 For implicit button types that require a lot of code, it is useful to
5910 add a module that includes the implicit button type definition, its
5911 action type definition and supporting code.
5916 @node Future Work, References, Questions and Answers, Top
5917 @appendix Future Work
5920 This appendix is included for a number of reasons:
5924 to better allow you to assess whether to work with Hyperbole by
5925 providing sketches of possible additions:
5927 to direct further development effort towards known needs;
5929 and to acknowledge known weaknesses in the current system.
5934 Note that due to a lack of volunteers to further develop Hyperbole, much
5935 of this work may not be done. So if you want to see these features,
5936 encourage qualified people to volunteer.
5938 @item Button Copying, Killing, and Yanking
5939 There is as yet no means of transferring explicit buttons among buffers.
5940 We realize this is a critical need. Users should be able to manipulate
5941 text with embedded buttons in ordinary ways. This will probably be
5942 implemented only for versions of Emacs 19 and higher. It will store the
5943 button attributes as text attributes within the buffers so that if a
5944 button is copied, its attributes follow. When a buffer is saved, the
5945 attributes also will be saved.
5948 Trails are an extension to the basic history mechanism presently offered
5949 by Hyperbole. Trails will allow a user to capture, edit and store a
5950 specific sequence and set of views of information for later replay by
5951 other users. Conditional branching may also be supported.
5953 @item Outliner View Mode
5954 This will complement the outliner editing mode by using simple one
5955 character keys that normally insert characters to instead modify the
5956 view of an outline and to move around in it, for ease of study.
5957 Switching between view and edit modes will also be simple.
5959 @item Storage of button data within button source files
5960 The current design choice of storing buttons external to the source file
5961 was made under the assumption that people should be able to look at
5962 files that contain Hyperbole buttons with any standard editor or tool
5963 and not be bothered by the ugly button data (since they won't be able to
5964 utilize the buttons anyway, they don't need to see or have access to
5967 In many contexts, embedding the button data within the source files may
5968 be a better choice, so a provision which would allow selection of either
5969 configuration may be added. Here are some of the PROs and CONs of both
5977 Button data in source file
5978 Documents can stand alone. All edit operators have
5979 Normal file operations apply. to account for file
5981 Simplifies creation and internal components.
5982 facility expansion for
5983 structured and multi-media
5986 Button data external to source file
5987 Files can be displayed and Currently, bdata for
5988 printed exactly as they look. whole directory is
5989 No special display formatting locked when any bdata
5990 is necessary. entry is locked.
5992 Button-based searches and
5993 database-type lookup operations
5994 need only search one file
6000 @item Forms-based Interfaces
6002 This will allow one to create buttons more flexibly. For example, button
6003 attributes could be given in any order. Entry of long code sequences,
6004 quick note taking and cross-referencing would also be made easier.
6006 @item Collaboration Support
6008 From the early stages of Hyperbole design, collaborative work
6009 environments have been considered. A simple facility has demonstrated
6010 broadcast of button activations to a number of workstations on a local
6011 area network, so that one user can lead others around an information
6012 space, as during an online design review. (This facility was never
6013 adapted to the current Hyperbole release, however.) We shall do some
6014 work in specific collaborative mechanisms, but we also expect that
6015 others who concentrate in collaborative work will provide more extensive
6020 @node References, Key Binding Index, Future Work, Top
6021 @appendix References
6025 Akscyn, R. M., D. L. McCracken and E. A. Yoder. KMS: A
6026 Distributed Hypermedia System for Managing Knowledge in Organizations.
6027 @emph{Communications of the ACM}, Vol. 31, No. 7, July 1988, pp. 820-835.
6030 Brown, P. J. Turning Ideas into Products: The Guide System.
6031 @emph{Proceedings of Hypertext '87}, November 13-15, 1987, Chapel Hill, NC.
6032 ACM: NY, NY, pp. 33-40.
6035 Conklin, Jeff. Hypertext: An Introduction and Survey. @emph{IEEE
6036 Computer}, Vol. 20, No. 9, September 1987, pp. 17-41.
6039 Engelbart, D., and W. English. A research center for augmenting
6040 human intellect. @emph{Proceedings of the Fall Joint Computer Conference},
6041 33, 1, AFIPS Press: Montvale, NJ, 1968, pp. 395-410.
6044 Engelbart, D. C. Authorship Provisions in Augment.
6045 @emph{Proceedings of the 1984 COMPCON Conference (COMPCON '84 Digest)},
6046 February 27-March 1, 1984, San Francisco, CA. IEEE Computer Society Press,
6047 Spring, 1984. 465-472. (OAD,2250,)
6050 Engelbart, D. C. Collaboration Support Provisions in Augment.
6051 @emph{Proceedings of the AFIPS Office Automation Conference (OAC '84 Digest)},
6052 February, 1984, Los Angeles, CA, 1984. 51-58. (OAD,2221,)
6055 Foss, C. L. Effective Browsing in Hypertext Systems.
6056 @emph{Proceedings of the Conference on User-Oriented Content-Based Text and
6057 Image Handling (RIAO 88)}, March 21-24, MIT, Cambridge MA. Centre de Hautes
6058 Etudes Internationales d'Informatique Documentaire, 1988, pp. 82-98.
6061 Garrett, N., K. E. Smith and N. Meyrowitz. Intermedia: Issues,
6062 Strategies, and Tactics in the Design of a Hypermedia Document System.
6063 @emph{Computer-Supported Cooperative Work (CSCW '86) Proceedings}, December
6064 3-5, Austin, TX, 1986, pp. 163-174.
6067 Halasz, F. G., T. P. Moran and R. H. Trigg. NoteCards in a
6068 Nutshell. @emph{Proceedings of the CHI and GI '87 Conference on Human Factors
6069 in Computing Systems}, Toronto, J. M. Carroll and P. P. Tanner, (editors),
6070 ACM: NY, NY, April 1987, pp. 45-52.
6073 Harvey, G. @emph{Understanding HyperCard.} Alameda, CA: SYBEX, Inc.,
6077 Kaplan, S., A. M. Carroll, C. Love and D. M. LaLiberte.
6078 @emph{Epoch 4.0 Manual.} Department of Computer Science, University of
6079 Illinois, Urbana, March 1992.
6081 @item [KaKaBeLaDr90]
6082 Kaplan, S. J., M. D. Kapor, E. J. Belove, R. A. Landsman, and
6083 T. R. Drake. AGENDA: A personal Information Manager. @emph{Communications
6084 of the ACM}, No. 33, July 1990, pp. 105-116.
6087 Nelson, T. H. @emph{Computer Lib/Dream Machines.} MicroSoft Press,
6091 Nelson, T. H. @emph{Literary Machines, Edition 87.1}. Available
6092 from the Distributors, 702 South Michigan, South Bend, IN 46618, 1987.
6095 Norman, D. A. and S. W. Draper, editors. @emph{User Centered System
6096 Design.} Lawrence Erlbaum Associates: Hillsdale, New Jersey, 1986.
6099 Shneiderman, B. The future of interactive systems and the emergence
6100 of direct manipulation. @emph{Behavior and Information Technology}, Vol. 1,
6104 Stallman, R. @emph{GNU Emacs Manual.} Free Software Foundation,
6105 Cambridge: MA, March 1987.
6108 Trigg, R., L. Suchman, and F. Halasz. Supporting collaboration in
6109 NoteCards. @emph{Proceedings of the CSCW '86 Conference}, Austin, TX,
6110 December 1986, pp. 147-153.
6113 Trigg, R. H., T. P. Moran and F. G. Halasz. Adaptability and
6114 Tailorability in NoteCards. @emph{Proceedings of INTERACT '87}, Stuttgart,
6115 West Germany, September 1987.
6118 Weiner, B. @emph{PIEmail: A Personalized Information Environment
6119 Mail Tool.} Department of Computer Science Masters Project, Brown
6120 University: Providence, RI, May 10, 1992.
6123 Yankelovich, N., B. J. Haan, N. Meyrowitz and S. M. Drucker.
6124 Intermedia: The Concept and the Construction of a Seamless Information
6125 Environment. @emph{IEEE Computer}, Vol. 21, No. 1, January 1988, pp. 81-96.
6128 Yoder, E. A., R. M. Akscyn and D. L. McCracken. Collaboration in
6129 KMS, A Shared Hypermedia System. @emph{Proceedings of the 1989 ACM Conference
6130 on Human Factors in Computer Systems (CHI '89)}, April 30-May 4, 1989,
6131 Austin, TX, ACM: NY,NY, 1989, pp. 37-42.
6136 @c ***************************
6138 @c ***************************
6140 @node Key Binding Index, Code and File Index, References, Top
6141 @unnumbered Key Binding Index
6145 @node Code and File Index, Concept Index, Key Binding Index, Top
6146 @unnumbered Code and File Index
6150 @node Concept Index, , Code and File Index, Top
6151 @unnumbered Concept Index
projects / packages / blob