xemacs-beta: man/hyperbole.texi comparison

comparison man/hyperbole.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	ac2d302a0011

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+\input texinfo
+@c
+@c FILE:         hypb.texi
+@c SUMMARY:      The Hyperbole User Manual for V3
+@c USAGE:        Hardcopy man from TeX; Info man from 'texinfo-format-buffer'.
+@c
+@c AUTHOR:       Bob Weiner
+@c ORG:          Brown U.
+@c
+@c ORIG-DATE:     6-Nov-91 at 11:18:03
+@c LAST-MOD:      3-Nov-95 at 23:55:27 by Bob Weiner
+@c %**start of header (This is for running Texinfo on a region.)
+@setfilename ../info/hyperbole.info
+@settitle Hyperbole User Manual
+@c %**end of header (This is for running Texinfo on a region.)
+@synindex vr fn
+@iftex
+@finalout
+@end iftex
+@titlepage
+@sp 4
+@center @titlefont{Hyperbole Manual}
+@sp 1
+@center Everyday Information Management
+@sp 5
+@center Bob Weiner
+@sp 1
+@center E-mail: <hyperbole@@hub.ucsb.edu>  (This is a mail list.)
+@sp 2
+@center Edition 4.01
+@sp 2
+@center November 3, 1995
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 1992, 1993, 1994, 1995  Free Software Foundation, Inc.
+All trademarks referenced herein are trademarks of their respective
+holders.
+@setchapternewpage odd
+@end titlepage
+@page
+@node Top, Introduction, (dir), (dir)
+@c  node-name,  next,  previous,  up
+@unnumbered Preface
+@ifinfo
+@noindent
+Copyright @copyright{} 1991, 1992, 1993, 1994, 1995  Free Software Foundation, Inc.
+All trademarks referenced herein are trademarks of their respective holders.
+@end ifinfo
+This edition of the Hyperbole User Manual is for use with any version
+4.01 or greater of Hyperbole.
+Hyperbole is free software; you can use it, redistribute it and/or modify it
+without fee under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option) any later
+version.
+Hyperbole is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with GNU Emacs or XEmacs; see the file COPYING.  If not, write to
+the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+@cindex credits
+@cindex InfoDock, obtaining
+@cindex Hyperbole, obtaining
+@cindex anonymous ftp
+Hyperbole was designed and written by Bob Weiner.  Motorola,
+Inc@. funded and donated this work for free redistribution as part of
+the InfoDock integrated software engineering and productivity toolset.
+For information on how to obtain Hyperbole, @ref{Obtaining}.  InfoDock
+can be found at the same location.
+This manual explains user operation and summarizes basic developer
+facilities of Hyperbole.  This major release of Hyperbole concentrates
+on providing convenient access to information and control over its
+display.  The Hyperbole outliner emphasizes flexible views and structure
+manipulation within bodies of information.
+@cindex Hyperbole
+@cindex hypertext
+@cindex Emacs Lisp
+@cindex Emacs 19
+@cindex Epoch
+@cindex XEmacs
+@cindex Lucid Emacs
+Hyperbole (pronounced Hi-purr-boe-lee) is an open, efficient,
+programmable information management and hypertext system.  It is
+intended for everyday work on any UNIX platform supported by GNU Emacs.
+It works well with the versions of Emacs that support multiple X or
+NEXTSTEP windows: Emacs 19, XEmacs (formerly called Lucid Emacs) and
+Epoch.  Hyperbole allows hypertext buttons to be embedded within
+unstructured and structured files, mail messages and news articles.  It
+offers intuitive mouse-based control of information display within
+multiple windows.  It also provides point-and-click access to Info
+manuals, ftp archives, Wide-Area Information Servers (WAIS), and the
+World-Wide Web (WWW) hypertext system through encapsulations of software
+that support these protocols.
+@noindent
+Hyperbole consists of four parts:
+@table @bullet
+@item Info Management
+an interactive information management interface, including a powerful
+rolodex, which anyone can use.  It is easy to pick up and use since it
+introduces only a few new mechanisms and provides user-level facilities
+through a menu interface, which you control from the keyboard or the
+mouse;
+@item Hypertext Outliner
+an outliner with multi-level autonumbering and permanent ids attached to
+each outline node for use as hypertext link anchors, plus flexible view
+specifications that can be embedded within links or used interactively;
+@item Button Types
+a set of hyper-button types that provides core hypertext and other
+behaviors.  Users can make simple changes to button types and those
+familiar with Emacs Lisp can quickly prototype and deliver new types;
+@item Programming Library
+a set of programming library classes for system developers who want to
+integrate Hyperbole with another user interface or as a back-end to a
+distinct system.  (All of Hyperbole is written in Emacs Lisp for ease of
+modification.  Although Hyperbole was initially designed as a prototype,
+it has been engineered for real-world usage and is well structured.)
+@end table
+@cindex GNU Emacs
+@kindex C-h t
+@vindex file, DEMO
+@cindex demonstration
+@cindex button demo
+Hyperbole may be used simply for browsing through documents
+pre-configured with Hyperbole buttons, in which case, one can safely
+ignore most of the information in this manual.  The @file{DEMO} file
+included in the Hyperbole distribution demonstrates many of Hyperbole's
+standard facilities.  It offers a much less technical introduction for
+Hyperbole users by providing good examples of how buttons may be
+used and an introduction to the outliner.
+So if this manual is too detailed for your taste, you can skip it
+entirely and just jump right into the demonstration, normally by typing
+@{@kbd{C-h h d d}@}, assuming Hyperbole has already been installed at
+your site.  Otherwise, @ref{Installation}, for Hyperbole installation
+and configuration information.
+Many users, however, will want to do more than browse with Hyperbole,
+e.g@.  create their own buttons.  The standard Hyperbole button editing
+user interface is GNU Emacs-based, so a basic familiarity with the Emacs
+editing model is useful.  The material covered in the GNU Emacs
+tutorial, normally bound to @{@kbd{C-h t}@} within Emacs, is more than
+sufficient as background.  If some GNU Emacs terms are unfamiliar to
+you, @ref{Glossary, Emacs Glossary,, emacs, the GNU Emacs Manual}.
+Before we delve into Hyperbole, a number of acknowledgments are in
+order.  Peter Wegner has encouraged the growth in this work.  Morris
+Moore has helped me pursue my own research visions and kept me striving
+for excellence.  Doug Engelbart has shown me the bigger picture and
+continues to be an inspiration.  His work provides a model from which I
+am beginning to draw.  Kellie Clark and I jointly designed the Hyperbole
+outliner while sharing a life together.  Chris Nuzum, as a user of
+Hyperbole, has helped demonstrate its power since its inception; he
+knows how to work with Hyperbole far better than I.
+@menu
+* Introduction::
+* Installation::
+* Buttons::
+* Smart Keys::
+* Menus::
+* Entering Arguments::
+* Outliner::
+* Rolodex::
+* Window Configurations::
+* Developing with Hyperbole::
+* Glossary::
+* Smart Key Reference::
+* Outliner Keys::
+* Suggestion or Bug Reporting::
+* Questions and Answers::
+* Future Work::
+* References::
+* Key Binding Index::
+* Code and File Index::
+* Concept Index::
+--- The Detailed Node Listing ---
+Introduction
+* Hyperbole Overview::
+* Mail Lists::
+* Manual Overview::
+Installation
+* Obtaining::
+* Building::
+* Installing::
+* Configuring::
+Configuring
+* Internal Viewers::
+* External Viewers::
+* Link Variable Substitution::
+* Button Colors::
+Buttons
+* Explicit Buttons::
+* Global Buttons::
+* Implicit Buttons::
+* Action Types::
+* Button Type Precedence::
+* Button Files::
+* Utilizing Explicit Buttons::
+Utilizing Explicit Buttons
+* Creation::
+* Renaming::
+* Deletion::
+* Modification::
+* Location::
+* Buttons in Mail::
+* Buttons in News::
+Creation
+* By Dragging::                 Creation Via Action Key Drags
+* By Menu::                     Creation Via Menus
+Outliner
+* Menu Commands::
+* Creating Outlines::
+* Autonumbering::
+* Idstamps::
+* Editing::
+* Viewing::
+* Links::
+* Cell Attributes::
+* Outliner History::
+Editing
+* Adding and Killing::
+* Moving Around::
+* Relocating and Copying::
+* Filling::
+* Transposing::
+* Splitting and Appending::
+* Inserting and Importing::
+Viewing
+* Hiding and Showing::
+* View Specs::
+Rolodex
+* Rolo Concepts::
+* Rolo Menu::
+* Rolo Keys::
+* Rolo Settings::
+Developing with Hyperbole
+* Hook Variables::
+* Creating Types::
+* Explicit Button Technicalities::
+* Encapsulating Systems::
+* Embedding Hyperbole::
+Creating Types
+* Action Type Creation::
+* Implicit Button Types::
+Explicit Button Technicalities
+* Button Label Normalization::
+* Operational and Storage Formats::
+* Programmatic Button Creation::
+Smart Key Reference
+* Smart Mouse Keys::
+* Smart Keyboard Keys::
+@end menu
+@node Introduction, Installation, Top, Top
+@chapter Introduction
+This chapter describes what Hyperbole is, lists some of its potential
+applications, explains how to subscribe to its mail lists, and then
+summarizes the structure of the rest of the manual.
+@menu
+* Hyperbole Overview::
+* Mail Lists::
+* Manual Overview::
+@end menu
+@node Hyperbole Overview, Mail Lists, Introduction, Introduction
+@section   Hyperbole Overview
+@cindex button
+A Hyperbole user works with @emph{buttons} embedded within textual
+documents; he may create, modify, move or delete buttons.  Each button
+performs a specific action, such as linking to a file or executing a
+shell command.
+@cindex button, explicit
+@cindex button, global
+@cindex button, implicit
+@cindex button category
+@cindex explicit button
+@cindex global button
+@cindex implicit button
+There are three categories of Hyperbole buttons:
+@table @dfn
+@item explicit buttons
+created by Hyperbole, accessible from within a single document;
+@item global buttons
+created by Hyperbole, accessible anywhere within a user's network of
+documents;
+@item implicit buttons
+created and managed by other programs or embedded within the structure
+of a document, accessible from within a single document.  Hyperbole
+recognizes implicit buttons by contextual patterns given in their type
+specifications (explained later).
+@end table
+Explicit Hyperbole buttons may be embedded within any type of text file.
+Implicit buttons may be recognized anywhere within a text file,
+depending on the implicit button types that are available.  All global
+buttons are stored in a single location and activated by entering their
+names, rather than by direct selection, the means used to activate
+explicit and implicit buttons.
+@noindent
+To summarize:
+@example
+Button Category   Active Within        Activation Means      Managed By
+========================================================================
+Explicit          a single document    direct selection      Hyperbole
+Global            any document         specifying its name   Hyperbole
+Implicit          a matching context   direct selection      other tools
+========================================================================
+@end example
+@cindex terminal use
+Hyperbole buttons may be clicked upon with a mouse to activate them or
+to describe their actions.  Thus, a user can always check how a button
+will act before activating it.  Buttons may also be activated from a
+keyboard.  (In fact, virtually all Hyperbole operations, including menu
+usage, may be performed from any standard character terminal interface,
+so one need not be anchored to a workstation all day).  @xref{Smart
+Keys}.
+@cindex Hyperbole features
+Hyperbole does not enforce any particular hypertext or information
+management model, but instead allows you to organize your information in
+large or small chunks as you see fit.  The Hyperbole outliner organizes
+information hierarchies which may also contain links to external
+information sources.
+@noindent
+Some of Hyperbole's most important features include:
+@itemize @bullet
+@item
+Buttons may link to information or may execute procedures, such as
+starting or communicating with external programs;
+@item
+One simply drags between a button source location and a link destination
+to create or to modify a link button.  The same result can be achieved
+from the keyboard.
+@item
+Buttons may be embedded within electronic mail messages;
+@item
+Outlines allow rapid browsing, editing and movement of chunks of
+information organized into trees (hierarchies);
+@item
+Other hypertext and information retrieval systems may be encapsulated
+under a Hyperbole user interface (a number of samples are provided).
+@end itemize
+@cindex Hyperbole applications
+@noindent
+Typical Hyperbole applications include:
+@table @strong
+@item personal information management
+Overlapping link paths provide a variety of views into an information space.
+A search facility locates buttons in context and permits quick selection.
+@item documentation and code browsing
+Cross-references may be embedded within documentation.  One can add a
+point-and-click interface to existing documentation, link code with
+associated design documents, or jump to the definition of an identifier
+by selecting its name within code or documentation.
+@item brainstorming
+The Hyperbole outliner, @xref{Outliner}, is an
+effective tool for capturing ideas and then quickly reorganizing them in
+a meaningful way.  Links to related ideas are easy to create,
+eliminating the need to copy and paste information into a single place.
+@item help/training systems
+Tutorials containing buttons can show students how things work while
+explaining the concepts, e.g@. an introduction to local commands.  This
+technique can be much more effective than written documentation alone.
+@item archive managers
+Programs that manage archives from incoming information streams may be
+supplemented by having them add topic-based buttons that link to the
+archive holdings.  Users can then search and create their own links to
+archive entries.
+@end table
+@node Mail Lists, Manual Overview, Hyperbole Overview, Introduction
+@section   Mail Lists
+If you maintain or use Hyperbole, you should consider joining one of the
+two Hyperbole interest mailing lists.  @xref{Menus}, and the description
+of the the Msg/ menu item, for a convenient means of joining and mailing
+to these lists.
+@cindex mail lists
+@cindex e-mail
+There are several Hyperbole-related mail addresses.  Learn what each is
+for before you mail to any of them.
+@cindex mail list requests
+@cindex joining a mail list
+@cindex subscribing to a mail list
+@cindex unsubscribing from a mail list
+@format
+<hyperbole-request@@hub.ucsb.edu>
+<hyperbole-announce-request@@hub.ucsb.edu>
+@end format
+@display
+@strong{All} mail concerning administration of the Hyperbole mailing
+lists should be sent to the appropriate one of these addresses.  That
+includes addition, change, or deletion requests.  Don't consider sending
+such a request to a Hyperbole mail list or people will wonder why you
+don't know that all Internet mail lists have a -request address for
+administrative requests.@refill
+Use the following formats on your subject line to execute requests,
+where you substitute your own values for the <> delimited items.@refill
+Subject: Subscribe '<' <user@@domain> '>' (<your name>).
+Subject: Unsubscribe '<' <user@@domain> '>'.
+To change your address, you must unsubscribe your old address in one
+message and then subscribe your new address in another message.@refill
+For example:
+To: hyperbole-announce-request@@hub.ucsb.edu
+Subject: Unsubscribe <joe@@any.com>.
+To: hyperbole-announce-request@@hub.ucsb.edu
+Subject: Subscribe <joe@@any.com> (Joe Williams).
+@end display
+@noindent
+There are two Hyperbole-related mail lists.  Subscribe to one or the other,
+not to both.
+@cindex hyperbole mail list
+@format
+<hyperbole@@hub.ucsb.edu>
+@end format
+@display
+Mail list for discussion of all Hyperbole issues.  Bug reports and
+suggestions may also be sent here.@refill
+@cindex e-mail, effective communication
+@cindex effective communication
+Always use your Subject and/or Summary: lines to state the position that
+your message takes on the topic that it addresses.
+For example, send:
+Subject: Basic bug in top-level minibuffer menu.
+rather than:
+Subject: Hyperbole bug.
+Statements end with periods, questions with question marks (typically),
+and high energy, high impact declarations with exclamation points.  This
+simple rule makes all e-mail communication much easier for recipients to
+handle appropriately.@refill
+@cindex Hyperbole version
+@cindex Emacs version
+@vindex emacs-version
+If you ask a question, your subject line should end with a ?,
+e.g@. "Subject: How can man page SEE ALSOs be made implicit buttons?"  A
+"Subject: Re: How can ..." then indicates an answer to the question.
+Question messages should normally include your Hyperbole and Emacs
+version numbers and clearly explain your problem and surrounding issues.
+Otherwise, you will simply waste the time of those who may want to help
+you.  (Your top-level Hyperbole menu shows its version number and @{@kbd{M-x
+emacs-version @key{RET}}@} gives the other.)@refill
+If you ask questions, you should consider adding to the discussion by
+telling people the kinds of work you are doing or contemplating doing
+with Hyperbole.  In this way, the list will not be overwhelmed by
+messages that ask for, but provide no information.@refill
+@end display
+@cindex hyperbole-announce mail list
+@format
+<hyperbole-announce@@hub.ucsb.edu>
+@end format
+@display
+Those who don't want to participate in the discussion but want to hear
+about bug fixes and new releases of Hyperbole should subscribe to this
+list.  Anyone on the `hyperbole' list is automatically on this one too,
+so there is no need to subscribe to this one in that case.  This list is
+for official fixes and announcements so don't send your own fixes here.
+Send them to `hyperbole' instead.
+@end display
+@node Manual Overview,  , Mail Lists, Introduction
+@section   Manual Overview
+Remember that the @file{DEMO} file included in the Hyperbole
+distribution demonstrates many of Hyperbole's standard facilities,
+(@pxref{Top, Preface}) for more details.
+@xref{Glossary}, for definitions of Hyperbole terms for quick
+reference, so in some cases terms are not precisely defined within the
+text.  Be sure to reference the glossary if a term is unclear to you.
+Although you need not have a keen understanding of all of these terms, a
+quick scan of the Glossary should help throughout Hyperbole use.
+If you have a question, feature suggestion or bug report on Hyperbole,
+follow the instructions given in @ref{Suggestion or Bug Reporting}.  A few
+commonly asked questions are answered in the manual, @ref{Questions and
+Answers}.  If you are interested in classic articles on hypertext,
+@ref{References}.
+@xref{Installation}, for explanations of how to obtain, install, configure
+and load Hyperbole for use.
+@xref{Buttons}, for an overview of Hyperbole buttons and how to use them.
+@xref{Smart Keys}, for an explanation of the innovative,
+context-sensitive mouse and keyboard Action and Assist Keys offered by
+Hyperbole.  @xref{Smart Key Reference}, for a complete reference on what
+the Action and Assist Keys do in each particular context that they
+recognize.
+(Keep in mind as you read about how to use Hyperbole that in many cases,
+it provides a number of overlapping interaction methods are provided to
+support different work styles and hardware limitations.  You need learn
+only one with which you can become comfortable, in such instances.)
+@xref{Menus}, for summaries of Hyperbole menu commands and how to use
+the minibuffer-based menus that work on dumb terminals.
+@xref{Entering Arguments}, for special support that Hyperbole provides for
+entering arguments when prompted for them.
+@xref{Outliner}, for concept and usage information on the
+autonumbered, hypertextual outliner.  A full summary of the outliner
+commands that are bound to keys may be found in @ref{Outliner Keys}.
+@xref{Rolodex}, for concept and usage information on the
+rapid lookup, hierarchical, free text record management system included
+with Hyperbole.
+@xref{Window Configurations}, for instructions on how to save and restore
+the set of buffers and windows that appear with a frame.  This feature
+lets you switch among working contexts easily, even on a dumb terminal.
+Such configurations only last throughout your current editor session.
+Developers comfortable with Emacs Lisp will want to continue on through
+to, @ref{Developing with Hyperbole}.
+@xref{Future Work}, for future directions in Hyperbole's evolution.
+@node Installation, Buttons, Introduction, Top
+@chapter Installation
+@cindex installation
+Hyperbole must be installed at your site before you can use it.  The
+following sections explain how to obtain, install and configure
+Hyperbole for use.
+@vindex file, hsite.el
+@cindex customization, init
+If you want to customize the basic Hyperbole initialization sequence for
+yourself rather than the users at your site, you should make a personal
+copy of the @file{hsite.el} file, modify it the way you want, and then
+load it.  (If you are familiar with Emacs Lisp, @ref{Hook Variables}.)
+@menu
+* Obtaining::
+* Building::
+* Installing::
+* Configuring::
+@end menu
+@node Obtaining, Building, Installation, Installation
+@section   Obtaining
+@cindex InfoDock
+@cindex ftp
+@cindex anonymous ftp
+Hyperbole is actually part of an integrated tool framework that we have
+developed called InfoDock.  InfoDock provides a modern user interface on top
+of Emacs, information management, and powerful software development tools,
+all in one package.  Hyperbole or InfoDock can be obtained via anonymous
+ftp on the Internet from:
+@file{ftp://ftp.xemacs.org/pub/infodock}.
+@cindex downloading Hyperbole
+@cindex obtaining Hyperbole
+@cindex Hyperbole, obtaining
+@noindent
+Here are detailed instructions for downloading and unpacking Hyperbole.
+Move to a directory below which you want the @file{hyperbole} directory to
+be created.  Unpacking the Hyperbole archive will create the
+@file{hyperbole} directory and will place all of the files below it.
+@example
+cd <LOCAL-EMACS-LISP-DIR>
+@end example
+@noindent
+Ftp to ftp.xemacs.org  (Internet Host ID = 128.174.252.16):
+@example
+prompt> ftp ftp.xemacs.org
+@end example
+@noindent
+Login as @emph{anonymous} with your own @emph{<user-id>@@<site-name>} as
+a password.
+@example
+Name (ftp.xemacs.org): anonymous
+331 Guest login ok, send EMAIL address (e.g@. user@@host.domain)
+as password.
+Password:
+230 Guest login ok, access restrictions apply.
+@end example
+@noindent
+Move to the Hyperbole directory:
+@example
+ftp> cd pub/infodock
+@end example
+@noindent
+Set your transfer mode to binary:
+@example
+ftp> bin
+200 Type set to I.
+@end example
+@noindent
+Turn off prompting:
+@example
+ftp> prompt
+Interactive mode off.
+@end example
+@noindent
+Retrieve just the Hyperbole archive and any diff-based patches (there may not
+be any patches):
+@example
+ftp> mget hyperbole*
+ftp> mget hdiff*
+@end example
+@noindent
+Close the ftp connection:
+@example
+ftp> quit
+221 Goodbye.
+@end example
+@cindex gzcat
+@cindex zcat
+@cindex gunzip
+@cindex tar archive
+@cindex uncompressing archives
+@cindex unpacking archives
+@noindent
+Unpack the tar archive using the GNU version of the @code{zcat} program,
+sometimes called @code{gzcat} or the @code{gunzip} program:
+@example
+zcat hyperbole*tar.gz | tar xvf -
+or
+gunzip hyperbole*tar.gz; tar xvf hyperbole*tar
+@end example
+@noindent
+Apply any patches you retrieved:
+@example
+cd hyperbole; patch < <patch-file>
+@end example
+@node Building, Installing, Obtaining, Installation
+@section   Building
+@vindex file, Makefile
+@vindex file, hsite.el
+@cindex Hyperbole, building
+@cindex building Hyperbole
+The following explains how to Use the Hyperbole @file{Makefile} to
+compile any needed code, to generate the @file{hsite.el} file used for
+site-specific Hyperbole customization, and to produce printable
+documentation.
+@vindex EMACS, environment variable
+@cindex compiling Lisp
+@cindex Lisp compilation
+Edit the line near the top of @file{Makefile} that represents the emacs
+version that you use, so that it corresponds to the emacs executable
+name used on your system.  Then immediatly below there, set the
+@var{EMACS} variable to the variable name for the emacs that you will
+use to compile the Hyperbole Lisp files.
+@vindex SITE-PRELOADS, environment variable
+You may also have to set the @var{SITE-PRELOADS} variable defined further down
+in the file; follow the instructions that precede the @var{SITE-PRELOADS =}
+line.  Make these changes now and save the @file{Makefile}.
+@cindex HYPERBOLE-DIR
+The following instructions use the term @file{<HYPERBOLE-DIR>/} to refer
+to your @file{hyperbole/} directory, so substitute your own value.
+@noindent
+To install Hyperbole for use with InfoDock, XEmacs, GNU Emacs or Epoch, from
+a shell:
+@example
+cd <HYPERBOLE-DIR>; make
+@end example
+@noindent
+All of the .elc compiled Lisp files are already built for XEmacs and V19, so
+this build will finish very quickly.  If you really want to rebuild all of
+the .elc files, use:
+@example
+cd <HYPERBOLE-DIR>; make all-elc
+@end example
+@cindex Postscript
+@cindex manual, generating Postscript
+@vindex file, man/hyperbole.ps
+@noindent
+To produce the Postscript version of the Hyperbole manual, you must have
+the TeX formatter on your system:
+@example
+cd <HYPERBOLE-DIR>; make ps
+@end example
+@noindent
+To install Hyperbole for use with GNU Emacs V18 or Epoch:
+@example
+cd <HYPERBOLE-DIR>; make all-elc-v18
+@end example
+@noindent
+This will produce a complete set of Emacs V18 .elc files.
+@node Installing, Configuring, Building, Installation
+@section   Installing
+@cindex configuration
+You may want to explore the Hyperbole configuration options before
+installing it.  @xref{Configuring}.  If you just want to get up and
+running quickly, however, there is no need to configure anything, just
+follow these instructions to install Hyperbole.
+@cindex Hyperbole, initializing
+@cindex initializing Hyperbole
+@cindex installation
+@cindex site initialization
+@vindex file, hsite.el
+@vindex file, ~/.emacs
+Add the following lines to a site initialization file such as
+@file{site-start.el} to set up so that all users have Hyperbole
+loaded for them when they run Emacs.  Otherwise, each user will have to
+add these lines to his own @file{~/.emacs} initialization file.
+@cindex autoloading Hyperbole
+@cindex Hyperbole, autoloading
+@noindent
+To autoload Hyperbole so that it loads only when needed:
+@vindex hyperb:dir
+@vindex file, hversion.el
+@vindex file, hyperbole.el
+@lisp
+(defvar hyperb:dir "<HYPERBOLE-DIR>/")
+"Directory where the Hyperbole executable code is kept.
+It must end with a directory separator character.")
+(load (expand-file-name "hversion" hyperb:dir))
+(load (expand-file-name "hyperbole" hyperb:dir))
+@end lisp
+@cindex loading Hyperbole
+@cindex Hyperbole, loading
+This establishes a few key bindings and sets up Hyperbole to
+automatically load whenever you activate its menu.  If you would rather
+have the whole Hyperbole system loaded when you start up so that you can
+always use the Smart Keys and other facilities, add the additional line:
+@lisp
+(require 'hsite)
+@end lisp
+If you use mouse keys, be sure to add the above lines after any setup of
+mouse key bindings, to ensure that Hyperbole's mouse keys are properly
+initialized.  @xref{Smart Keys}, for further details.  If you use any
+Hyperbole mail or news support, @ref{Buttons in Mail}, be certain to
+perform all of your personal mail/news initializations before the point
+at which you load Hyperbole.  Otherwise, the mail/news support may not
+be configured properly.  For example, if you use the Emacs add-on
+Supercite package, its setup should come before Hyperbole initialization.
+@cindex Hyperbole manual
+@noindent
+The Hyperbole Manual is included in the distribution in two forms:
+@cindex Info manual
+@cindex Texinfo manual
+@vindex file, man/hyperbole.info
+@vindex file, man/hyperbole.texi
+@example
+@file{man/hyperbole.info}   - online version
+@file{man/hyperbole.texi}   - source form
+@end example
+@vindex Info-directory-list
+@noindent
+To add pointers to the Info version of the Hyperbole manual within your
+Info directory, follow these instructions.  If @var{Info-directory-list}
+is bound as a variable within your Emacs (all versions except V18 and
+Epoch), then you can simply set it so that <HYPERBOLE-DIR> is an element
+in the list:
+@lisp
+(setq Info-directory-list (cons "<HYPERBOLE-DIR>" Info-directory-list))
+@end lisp
+@noindent
+Otherwise, from a shell:
+@vindex Info-directory
+@example
+cd to the directory given by your @var{Info-directory} variable
+rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .
+@end example
+@noindent
+For all versions of Emacs, add an Info menu entry for the Hyperbole
+manual in your Info @file{dir} file (the `*' should be placed in the
+first column of the file):
+@example
+* Hyperbole::  GNU Emacs-based everyday information management system.
+Use @{C-h h d d@} for a demonstration.  Includes context-sensitive
+mouse and keyboard support, a powerful rolodex, an autonumbered
+outliner with hyperlink anchors for each outline cell, and extensible
+hypertext facilities including hyper-links in mail and news messages.
+@end example
+@cindex invoking Hyperbole
+@cindex starting Hyperbole
+@cindex Hyperbole, starting
+@cindex Hyperbole main menu
+@kindex C-h h
+@findex hyperbole
+That's all there is to the installation.  Once Hyperbole has been
+installed for use at your site, you can invoke it with @{@kbd{C-h h}@}
+or @{@kbd{M-x hyperbole @key{RET}}@} to bring up the Hyperbole main menu
+in the minibuffer window.
+@node Configuring,  , Installing, Installation
+@section   Configuring
+@cindex configuration
+@vindex file, hyperbole.el
+@vindex file, hsite.el
+There are many Hyperbole configuration options that may be changed by
+editing the @file{hyperbole.el} and @file{hsite.el} files in the
+@file{hyperbole/} directory.  The following sections discuss the
+configuration options most likely to be of interest to users.
+@menu
+* Internal Viewers::
+* External Viewers::
+* Link Variable Substitution::
+* Button Colors::
+@end menu
+@node Internal Viewers, External Viewers, Configuring, Configuring
+@subsection  Internal Viewers
+@vindex hpath:display-alist
+@vindex file, hsite.el
+@cindex file display function
+@cindex display function
+@cindex internal viewer
+@cindex link, display function
+When given a file name, Hyperbole will by default display the file for
+editing within an Emacs buffer.  The @var{hpath:display-alist} variable
+can be used to specify file name patterns, such as matching suffixes,
+which will invoke a special Emacs Lisp function to display any matching
+files within Emacs.  This can be used to format raw data files for
+convenient display.
+Configure the @var{hpath:display-alist} variable in @file{hsite.el}.
+Its value is an association list whose elements are
+(<file-name-regular-expression> . <function-of-one-arg>) pairs.  Any
+path whose name matches a <file-name-regular-expression> will be
+displayed by calling the associated <function-of-one-arg> with the file
+name as the argument.@refill
+@xref{External Viewers}, for instructions on associating file names with
+external, window-system specific viewers.
+@node External Viewers, Link Variable Substitution, Internal Viewers, Configuring
+@subsection  External Viewers
+@vindex hpath:find-alist
+@vindex file, hsite.el
+@cindex window system
+@cindex external program
+@cindex external viewer
+@cindex link, viewer program
+If you will be using Hyperbole under a window system, you may want to
+configure the @var{hpath:find-alist} variable in @file{hsite.el} to
+support hyperlinks which open files using non-Emacs tools, e.g@. a
+fax reader or a bitmap viewer.
+The value of @var{hpath:find-alist} is determined when Hyperbole is
+initialized based upon the current window system and the version of
+Emacs in use.  The value is an association list whose elements are
+(<file-name-regular-expression> . <viewer-program>) pairs.  Any path
+whose name matches a <file-name-regular-expression> will be
+displayed using the corresponding viewer-program.  If a <viewer-program>
+entry contains a @code{%s} string, the filename to display will be
+substituted at that point within the string.  Otherwise, the filename
+will be appended to the <viewer-program> entry.  See the "x-suffixes"
+and "nextstep-suffixes" settings within the definition of
+@var{hpath:find-alist} as examples.@refill
+@node Link Variable Substitution, Button Colors, External Viewers, Configuring
+@subsection  Link Variable Substitution
+@vindex hpath:variables
+@cindex environment variables
+@cindex Emacs Lisp variables
+@cindex Lisp variables
+Another variable to consider modifying in the @file{hsite.el} file is
+@var{hpath:variables}.   This variable consists of a list of Emacs Lisp
+variable names, each of which may have a pathname or a list of pathnames
+as a value.  Whenever a Hyperbole file or directory link button is
+created, its pathname is compared against the values in
+@var{hpath:variables}.  The first match found, if any, is selected and
+its associated variable name is substituted into the link pathname, in
+place of its literal value.  When the link is resolved (the button is
+activated), Hyperbole replaces each variable with the first matching
+value from this list.  (Environment variables are also replaced whenever
+link paths are resolved.
+This permits sharing of links over wide areas, where the variable values
+may differ between link creator and link activator.  The entire process
+is wholly transparent to the user; it is explained here simply to help
+you in deciding whether or not to modify the value of
+@var{hpath:variables}.
+@node Button Colors,  , Link Variable Substitution, Configuring
+@subsection  Configuring Button Colors
+@cindex XEmacs support
+@cindex Emacs 19 support
+@cindex Epoch support
+@cindex button highlighting
+@cindex button flashing
+@vindex file, hui-ep*.el
+@findex hproperty:cycle-but-color
+When Hyperbole is run under a window system together with Emacs 19,
+XEmacs or Epoch, it automatically highlights any explicit buttons in
+a buffer and makes them flash when selected.  The main setting
+you may want change is the selection of a color (or style) for button
+highlighting and button flashing.  See the @file{hui-*-b*.el} files for
+lists of potential colors and the code which supports this behavior.  A
+call to @code{(hproperty:cycle-but-color)} within a Hyperbole
+initialization sequence in the @file{hsite.el} file changes the color
+used to highlight and flash explicit buttons.
+@cindex button emphasis
+@vindex hproperty:but-emphasize-p
+@vindex file, hsite.el
+Additionally, under XEmacs and Emacs 19, if @var{hproperty:but-emphasize-p}
+is set to @code{t} in @file{hsite.el}, then whenever the mouse pointer
+moves over an explicit button, it will be emphasized in a different
+color or style.  This emphasis is in addition to any non-mouse-sensitive
+button highlighting.
+@cindex button highlighting, forcing
+@findex hproperty:but-create
+If you read in a file with explicit buttons before you load Hyperbole,
+these buttons won't be highlighted.  Load Hyperbole and then use
+@code{M-x hproperty:but-create @key{RET}} to highlight the buttons in
+the current buffer.
+@node Buttons, Smart Keys, Installation, Top
+@chapter Buttons
+This chapter explains the user-level notion of Hyperbole buttons.
+Hyperbole buttons that are stored in files persist across Emacs
+sessions, so they provide a convenient means of linking from one
+information source to another.
+@menu
+* Explicit Buttons::
+* Global Buttons::
+* Implicit Buttons::
+* Action Types::
+* Button Type Precedence::
+* Button Files::
+* Utilizing Explicit Buttons::
+@end menu
+@node Explicit Buttons, Global Buttons, Buttons, Buttons
+@section   Explicit Buttons
+@cindex explicit button
+@cindex button, explicit
+@cindex button label
+Hyperbole creates and manages @emph{explicit buttons} which look like
+this @code{<(fake button)>} to a Hyperbole user.  They are quickly
+recognizable, yet relatively non-distracting as one scans the text in
+which they are embedded.  The text between the @code{<(} and
+@code{)>} delimiters is called the @dfn{button label}.  Spacing between
+words within a button label is irrelevant to Hyperbole, so button labels
+may wrap across several lines without causing a problem.
+@cindex button data
+@cindex button attribute
+@vindex file, .hypb
+Hyperbole stores the @dfn{button data} that gives an explicit button its
+behavior, separately from the button label, in a file named @file{.hypb}
+within the same directory as the file in which the button is created.
+Thus, all files in the same directory share a common button data file.
+Button data is comprised of individual @dfn{button attribute} values.  A
+user never sees this data in its raw form but may see a formatted
+version by asking for help on a button.
+@cindex button, moving
+@cindex moving buttons
+Explicit buttons may be freely moved about within the buffer in which
+they are created.  (No present support exists for moving buttons between
+buffers).  A single button may also appear multiple times within the
+same buffer; one simply copies the button label with its delimiters
+to a new location in such cases.
+Each explicit button is assigned an action type which determines the
+actions that it performs.  @dfn{Link action types} connect buttons to
+particular types of referents.  @dfn{Activation} of such buttons then
+displays the referents.
+@cindex linking, in-place
+@cindex Hyperbole data model
+Hyperbole does not manage referent data; this is left to the
+applications that generate the data.  This means that Hyperbole
+provides in-place linking and does not require reformatting of data to
+integrate it with a Hyperbole framework.
+@node Global Buttons, Implicit Buttons, Explicit Buttons, Buttons
+@section   Global Buttons
+@cindex global button
+@cindex button, global
+@cindex button label
+Access to explicit buttons depends upon the information on your screen
+since they are embedded within particular buffers.  Sometimes it is
+useful to activate buttons without regard to the information with which
+you are presently working.  In such instances, you use @dfn{global
+buttons}, which are simply explicit buttons which may be activated or
+otherwise operated upon by entering their labels when they are prompted
+for, rather than selecting the buttons within a buffer.
+If you want a permanent link to a file section that you can follow at
+any time, you can use a global button.  Or what about an Emacs keyboard
+macro that you use frequently?  Create an @code{exec-kbd-macro} button
+with an easy to type name and then you can easily activate it whenever
+the need arises.
+@node Implicit Buttons, Action Types, Global Buttons, Buttons
+@section   Implicit Buttons
+@cindex button, implicit
+@cindex implicit button
+Implicit buttons are those defined by the natural structure of a
+document.  They are identified by contextual patterns which limit the
+locations or states in which they can appear.  Their behavior is
+determined by one or more actions which they trigger when activated.  An
+action is derived from either a Hyperbole action type specification,
+@ref{Action Types}, or an Emacs Lisp function.  Implicit
+button types may use the same action types that explicit buttons do.
+@vindex file, hibtypes.el
+@cindex context
+Implicit buttons never have any button data associated with them.  They
+are recognized in context based on predicate matches defined within
+implicit button types.  For example, Hyperbole recognizes file names
+enclosed in double quotes and can quickly display their associated files
+in response to simple mouse clicks.
+@cindex ibtypes, list of
+@noindent
+See @file{hibtypes.el} for complete examples.  Standard implicit button
+types include (in alphabetical order):
+@table @code
+@item annot-bib
+@findex ibtypes::annot-bib
+@cindex bibliography
+@cindex reference
+Displays annotated bibliography entries referenced internally, delimeters = [].
+References must be delimited by square brackets, must begin with a
+word constituent character, and must not be in buffers whose
+names begin with a ' ' or '*' character.
+@item completion
+@findex ibtypes::completion
+@cindex completion
+Inserts completion at point into minibuffer or other window.
+@item dir-summary
+@findex ibtypes::dir-summary
+@vindex file, MANIFEST
+@vindex file, DIR
+Detects filename buttons in files named "MANIFEST" or "DIR".
+Displays selected files.
+Each file name must be at the beginning of the line and must be followed
+by one or more spaces and then another non-space, non-parenthesis, non-brace
+character.
+@item doc-id
+@findex ibtypes::doc-id
+@cindex online library
+@cindex document identifier
+Displays an index entry for a site-specific document given its id.  Ids
+must be delimited by 'doc-id-start' and 'doc-id-end' and must match the
+function given by 'doc-id-p'.  This permits creation of catalogued
+online libraries.  See @file{$@{hyperb:dir@}/hib-doc-id.el} for more
+information.@refill
+@item elisp-compiler-msg
+@findex ibtypes::elisp-compiler-msg
+@cindex byte compiler error
+@cindex Emacs Lisp compiler error
+@cindex compiler error
+Jumps to source code for definition associated with byte-compiler error
+message.  Works when activated anywhere within an error line.
+@item debugger-source
+@findex ibtypes::debugger-source
+@cindex gdb
+@cindex dbx
+@cindex xdb
+@cindex stack frame
+@cindex breakpoint
+@cindex source line
+Jumps to source line associated with debugger stack frame or breakpoint lines.
+This works with gdb, dbx, and xdb.  Such lines are recognized in any buffer.
+@item grep-msg
+@findex ibtypes::grep-msg
+@cindex grep
+@cindex compiler error
+Jumps to line associated with grep or compilation error msgs.
+Messages are recognized in any buffer.
+@item hyp-address
+@findex ibtypes::hyp-address
+@cindex Hyperbole mail list
+Turns a Hyperbole e-mail list address into an implicit button which
+inserts Hyperbole environment information.
+Useful when sending mail to a Hyperbole mail list.  See also the
+documentation for @code{actypes::hyp-config}.
+@item hyp-source
+@findex ibtypes::hyp-source
+@cindex Hyperbole report
+Turns source location entries in Hyperbole reports into buttons that jump to the associated location.
+@item Info-node
+@findex ibtypes::Info-node
+@cindex Info node
+Makes "(file)node" buttons display the associated Info node.
+@item kbd-key
+@findex ibtypes::kbd-key
+@cindex key sequence
+Executes a key sequence delimited by curly braces.
+Key sequences should be in human readable form, e.g@. @{@kbd{C-b}@}.
+Forms such as @{@}, @{@}, and @{^b@} will not be recognized.
+@item klink
+@findex ibtypes::klink
+@cindex klink
+@cindex koutline link
+@cindex kcell link
+Follows a link delimited by <> to a koutline cell.
+See documentation for @code{actypes::link-to-kotl} for valid link
+specifiers.
+@item mail-address
+@findex ibtypes::mail-address
+@cindex e-mail address
+@cindex rolodex address
+@cindex address
+If on an e-mail address in a specific buffer type, mail to that address
+in another window. Applies to the rolodex match buffer, any buffer
+attached to a file in @var{rolo-file-list}, or any buffer with @file{mail}
+or @file{rolo} (case-insensitive) within its name.
+@item man-apropos
+@findex ibtypes::man-apropos
+@item UNIX manual
+@item man pages
+@item man apropos
+Makes man apropos entries display associated man pages when selected.
+@item patch-msg
+@findex ibtypes::patch-msg
+@cindex patch output
+Jumps to source code associated with output from the @code{patch}
+program.  Patch applies diffs to source code.
+@item pathname
+@findex ibtypes::pathname
+@findex hpath:at-p
+@findex hpath:find
+@vindex hpath:suffixes
+@cindex ange-ftp
+@cindex efs
+@cindex pathname
+@cindex remote path
+@cindex filename
+@cindex link, pathname
+Makes a delimited, valid pathname display the path entry.
+Also works for delimited and non-delimited ange-ftp and efs pathnames.
+See @code{hpath:at-p} function documentation for possible delimiters.
+See @var{hpath:suffixes} variable documentation for suffixes that are
+added to or removed from pathname when searching for a valid match.
+See @code{hpath:find} function documentation and
+@var{hpath:display-alist} and @var{hpath:find-alist} variable
+documentation for special file display options.
+@item rfc
+@findex ibtypes::rfc
+@cindex Internet RFC
+@cindex Request For Comment
+@cindex RFC
+@cindex ange-ftp
+@cindex efs
+Retrieves and displays an Internet rfc referenced at point.
+Requires ange-ftp or efs when needed for remote retrievals.  The
+following formats are recognized: RFC822, rfc-822, and RFC 822.  The
+@var{hpath:rfc} variable specifies the location from which to retrieve
+RFCs."
+@item rfc-toc
+@findex ibtypes::rfc-toc
+@cindex Internet RFC
+@cindex Request For Comment
+@cindex RFC
+@cindex table of contents
+Summarizes contents of an Internet rfc from anywhere within rfc buffer.
+Each line in summary may be selected to jump to section.
+@item text-toc
+@findex ibtypes::text-toc
+@cindex table of contents
+@cindex toc implicit button type
+Jumps to the text file section referenced by a table of contents entry
+at point. File name must contain @file{README} and there must be a
+`Table of Contents' or `Contents' label on a line by itself (it may
+begin with an asterisk), preceding the table of contents.  Each toc
+entry must begin with some whitespace followed by one or more asterisk
+characters.  Each file section name line must start with one or more
+asterisk characters at the very beginning of the line.
+@item www-url
+@findex ibtypes::www-url
+@cindex URL
+@cindex World-wide Web
+@cindex WWW
+@cindex Action Key, web browsing
+@kindex Action Key, web browsing
+@vindex action-key-url-function
+When not in a w3 browser buffer, follow any non-ftp url (link) at point.
+The variable, @var{action-key-url-function}, can be used to customize
+the url browser that is used.
+@end table
+The Hyperbole Smart Keys offer extensive additional context-sensitive
+point-and-click type behavior beyond these standard implicit button
+types.  @xref{Smart Keys}.
+@node Action Types, Button Type Precedence, Implicit Buttons, Buttons
+@section   Action Types
+@cindex action type
+@cindex argument, use
+@cindex action
+@dfn{Action types} provide action procedures that specify button behavior.
+The arguments needed by an action type are prompted for at button creation
+time.  When a button is activated, the stored arguments are fed to the
+action type's @dfn{action} body to achieve the desired result.  Hyperbole
+handles all of this transparently.
+@cindex actypes, list of
+@noindent
+Standard action types in alphabetical order include:
+@table @code
+@item annot-bib
+@findex actypes::annot-bib
+Follows internal ref KEY within an annotated bibliography, delimiters=[].
+@item completion
+@findex actypes::completion
+Inserts completion at point into minibuffer or other window.
+Unless at end of buffer or if completion has already been inserted, then
+deletes completions window.
+@item eval-elisp
+@findex actypes::eval-elisp
+Evaluates a Lisp expression LISP-EXPR.
+@item exec-kbd-macro
+@findex actypes::exec-kbd-macro
+Executes KBD-MACRO REPEAT-COUNT times.
+KBD-MACRO may be a string of editor command characters or a function symbol.
+Optional REPEAT-COUNT nil means execute once, zero means repeat until
+error.
+@item exec-shell-cmd
+@findex actypes::exec-shell-cmd
+Executes a SHELL-CMD string asynchronously.
+Optional non-nil second argument INTERNAL-CMD means do not display the shell
+command line executed.  Optional non-nil third argument KILL-PREV means
+kill last output to shell buffer before executing SHELL-CMD.
+@item exec-window-cmd
+@findex actypes::exec-window-cmd
+Executes an external window-based SHELL-CMD string asynchronously.
+@item hyp-config
+@findex actypes::hyp-config
+Inserts Hyperbole configuration info at end of optional OUT-BUF or current.
+@item hyp-request
+@findex actypes::hyp-request
+Inserts Hyperbole mail list request help into optional OUT-BUF or current.
+@item hyp-source
+@findex actypes::hyp-source
+Displays a buffer or file from a line beginning with 'hbut:source-prefix'.
+@item kbd-key
+@findex actypes::kbd-key
+Executes the function binding for KEY-SEQUENCE, delimited by @{@}.
+Returns t if a KEY-SEQUENCE has a binding, else nil.
+@item link-to-buffer-tmp
+@findex actypes::link-to-buffer-tmp
+Displays a BUFFER in another window.
+Link is generally only good for current Emacs session.
+Use 'link-to-file' instead for a permanent link.
+@item link-to-directory
+@findex actypes::link-to-directory
+Displays a DIRECTORY in Dired mode in another window.
+@item link-to-doc
+@findex actypes::link-to-doc
+Displays online version of a document given by DOC-ID, in other window.
+If the online version of a document is not found in
+@var{doc-id-indices}, an error is signalled.
+@item link-to-ebut
+@findex actypes::link-to-ebut
+Performs action given by another button, specified by KEY and KEY-FILE.
+@item link-to-elisp-doc
+@findex actypes::link-to-elisp-doc
+Displays documentation for FUNC-SYMBOL.
+@item link-to-file
+@findex actypes::link-to-file
+Displays a PATH in another window scrolled to optional POINT.
+With POINT, buffer is displayed with POINT at the top of the window.
+@item link-to-file-line
+@findex actypes::link-to-file-line
+Displays a PATH in another window scrolled to LINE-NUM.
+@item link-to-kcell
+@findex actypes::link-to-kcell
+Displays FILE with kcell given by CELL-REF at the top of the window.
+CELL-REF may be a kcell's display label or its permanant idstamp.
+If FILE is nil, the current buffer is used.
+If CELL-REF is nil, the first cell in the view is shown.
+@item link-to-kotl
+@findex actypes::link-to-kotl
+Displays at the top of another window the referent pointed to by LINK.
+LINK may be of any of the following forms, with or without delimiters:
+@example
+< pathname [, cell-ref] >
+< [-!&] pathname >
+< @@ cell-ref >
+@end example
+@noindent
+See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
+@item link-to-Info-node
+@findex actypes::link-to-Info-node
+Displays an Info NODE in another window.
+NODE must be a string of the form '(file)nodename'.
+@item link-to-mail
+@findex actypes::link-to-mail
+Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window.
+See documentation for the variable @var{hmail:init-function} for
+information on how to specify a mail reader to use.
+@item link-to-regexp-match
+@findex actypes::link-to-regexp-match
+Finds REGEXP's Nth occurrence in FILE and displays location at window top.
+Returns t if found, signals an error if not.
+@item link-to-rfc
+@findex actypes::link-to-rfc
+Retrieves and displays an Internet rfc given by RFC-NUM.
+RFC-NUM may be a string or an integer.  Requires ange-ftp or efs for
+remote retrievals.
+@item link-to-string-match
+@findex actypes::link-to-string-match
+Finds STRING's Nth occurrence in FILE and displays location at window top.
+Returns t if found, nil if not.
+@item man-show
+@findex actypes::man-show
+Displays man page on TOPIC, which may be of the form @code{<command>(<section>}).
+@item rfc-toc
+@findex actypes::rfc-toc
+Computes and displays summary of an Internet rfc in BUF-NAME.
+Assumes point has already been moved to start of region to summarize.
+Optional OPOINT is point to return to in BUF-NAME after displaying summary.
+@item text-toc
+@findex actypes::text-toc
+@cindex table of contents
+@cindex toc action type
+Jumps to the text file SECTION referenced by a table of contents entry
+at point.
+@item www-url
+@findex actypes::www-url
+@cindex URL
+@cindex World-wide Web
+@cindex WWW
+@vindex action-key-url-function
+Follows a link given by URL.
+The variable, @var{action-key-url-function}, can be used to customize
+the url browser that is used.
+@end table
+@cindex action
+@vindex hui:ebut-prompt-for-action
+The use of action types provides a convenient way of specifying button
+behavior without the need to know how to program.  Expert users who are
+familiar with Emacs Lisp, however, may find that they often want to
+tailor button actions in a variety of ways not easily captured within a
+type system.  In such cases, @var{hui:ebut-prompt-for-action} should be
+set non-nil.  This will cause Hyperbole to prompt for an action to
+override the button's action type at each explicit button creation.  For
+those cases where the action type is sufficient, a nil value should be
+entered for the action.  An action may be any Lisp form that may be
+evaluated.
+@node Button Type Precedence, Button Files, Action Types, Buttons
+@section   Button Type Precedence
+@cindex button precedence
+@cindex button label overlap
+Explicit buttons always take precedence over implicit buttons.  Thus, if
+a button selection is made which falls within both an explicit and
+implicit button, only the explicit button will be selected.  Explicit
+button labels are not allowed to overlap; Hyperbole's behavior in such
+cases is undefined.
+@cindex ibtype, evaluation order
+If there is no explicit button at point during a selection request, then
+each implicit button type predicate is tested in turn until one returns
+non-nil or all are exhausted.  Since two implicit button types may have
+overlapping domains (those contexts in which their predicates are true),
+only the first matching type is used.  The type predicates are tested
+in @strong{reverse} order of definition, i.e@. most recently entered
+types are tested first, so that personal types defined after standard
+system types take precedence.  It is important to keep this order in
+mind when defining new implicit button types.  By making their match
+predicates as specific as possible, one can minimize any overlapping of
+implicit button type domains.
+@cindex type redefinition
+Once a type name is defined, its precedence relative to other types
+remains the same even if you redefine the body of the type, as long as
+you don't change its name.  This allows incremental modifications to
+types without having to worry about shifts in type precedence.
+@xref{Creating Types}, for information on how to develop
+or modify types.
+@node Button Files, Utilizing Explicit Buttons, Button Type Precedence, Buttons
+@section   Button Files
+@cindex button files
+It is often convenient to create lists of buttons that can be used as
+menus to provide centralized access to distributed information pools or
+for other purposes.  These files can serve as useful roadmaps to help
+efficiently guide a user through both unfamiliar and highly familiar
+information spaces.  Files that are created specifically for this
+purpose, we call @dfn{button files}.
+@vindex hbmap:filename
+@cindex button file, personal
+@cindex button file, directory
+The Hyperbole menu system provides quick access to two types of these
+button files: personal and directory-specific, through the ButFile menu.
+(The variable, @var{hbmap:filename}, contains the base name of these
+standard button files.  Its standard value is @file{HYPB}.)
+@vindex dir, ~/.hyperb
+@vindex hbmap:dir-user
+@cindex global button
+A personal button file may serve as a user's own roadmap to frequently
+used resources.  Selection of the ButFile/PersonalFile menu item
+displays this file for editing.  The default personal button file is
+stored within the directory given by the @var{hbmap:dir-user} variable
+whose standard value is @file{~/.hyperb}.  The standard Hyperbole
+configuration also appends all global buttons to the end of this file,
+one per line, as they are created.  So you can edit or annotate them
+within the file.
+A directory-specific button file may exist for each file system
+directory.  Such files are useful for explaining the contents of
+directories and pointing readers to particular highlights within the
+directories.  Selection of the ButFile/DirFile menu item displays the
+button file for the current directory; this provides an easy means of
+updating this file when working on a file within the same directory.
+If you want to view some other directory-specific button file, simply
+use the normal Emacs file finding commands.
+One might suggest that menu quick access be provided for group-specific
+and site-specific button files.  Instead, link buttons to such things
+should be placed at the top of your personal button file.  This provides
+a more flexible means of quick access.
+@node Utilizing Explicit Buttons,  , Button Files, Buttons
+@section   Utilizing Explicit Buttons
+Explicit buttons are a fundamental building block for creating personal
+or organizational hypertext networks with Hyperbole.  This section
+summarizes the user-level operations available for managing these
+buttons.
+@menu
+* Creation::
+* Renaming::
+* Deletion::
+* Modification::
+* Location::
+* Buttons in Mail::
+* Buttons in News::
+@end menu
+@node Creation, Renaming, Utilizing Explicit Buttons, Utilizing Explicit Buttons
+@subsection  Creation
+@menu
+* By Dragging::                 Creation Via Action Key Drags
+* By Menu::                     Creation Via Menus
+@end menu
+@node By Dragging, By Menu, Creation, Creation
+@subsubsection Creation Via Action Key Drags
+@cindex explicit button, creation
+@cindex button, creation
+@cindex link, creation
+@cindex drag
+@cindex Action Key drag
+The most efficient way to create an explicit button interactively is to
+use the mouse Action Key to drag from a button source window to a window
+showing its link referent.  More specifically, you should split your
+current Emacs frame into two windows: one which contains the point at
+which you want a button to be inserted and another which shows the point
+to which you want to link.  Depress the mouse Action Key at the point at
+which the button should be inserted, drag to the other window and
+release it at the point of the link referent.  The process becomes quite
+simple with a little practice. (@xref{By Menu, Creation Via Menus}, for a
+more detailed explanation of the explicit button creation process.)
+Hyperbole uses the link referent context to determine the type of link
+to make.  If there are a few different types of links which are
+applicable from the context, you will be prompted with a list of the
+types.  Simply use the Action Key or the first letter of the link
+type to select one of the type names and to finish the link creation.
+Hyperbole will then insert explicit button delimiters around the button
+label and will display a message in the minibuffer indicating both the
+button name and its action/link type.
+@kindex M-o
+@kindex C-u M-o
+@kindex C-x o
+@findex hkey-operate
+If you run Emacs under a window system, you can emulate an Action Key
+drag from the keyboard by: hitting @{@kbd{M-o}@}, the
+@code{hkey-operate} command, at the button source location, moving
+to the link destination, e.g@. with @{@kbd{C-x o}@}, and then hitting
+@{@kbd{M-o}@} again.  This simulates a depress and then release of the
+Action Key.  @{@kbd{C-u M-o}@} emulates drags of the Assist Key.
+This will not work when Hyperbole is run from a dumb terminal Emacs
+session since drag actions are not supported without a window system.
+@page
+@node By Menu,  , By Dragging, Creation
+@subsubsection Creation Via Menus
+You can alternatively use the Hyperbole menus to create explicit
+buttons.  First, mark a short region of text in any fashion allowed by
+GNU Emacs and then select the Hyperbole menu item sequence, Ebut/Create.
+You will be prompted for the button's label with the marked region as
+the default.  If you accept the default and enter the rest of the
+information you are prompted for, the button will be created within the
+current buffer and Hyperbole will surround the marked region with
+explicit button delimiters to indicate success.
+If you do not mark a region before invoking the button create command,
+you will be prompted for both a label and a target buffer for the button
+and the delimited label text will be inserted into the target buffer
+after a successful button creation.
+After Hyperbole has the button label and its target buffer, it will
+prompt you for an action type for the button.  Use the @{@kbd{?}@}
+completion help key to see the available types.  The type selected
+determines any following values for which you will be prompted.
+@cindex button instance
+@cindex instance number
+If a previous button with the same label exists in the same buffer,
+Hyperbole will add an @dfn{instance number} to the label when it adds
+the delimiters so that the name is unique.  Thus, you don't have to
+worry about accidental button name conflicts.  If you want the same
+button to appear in multiple places within the buffer, just enter the
+label again and delimit it yourself.  Hyperbole will interpret all
+occurrences of the same delimited label within a buffer as the same
+button.
+@cindex link, creation
+If you create link buttons using the Hyperbole menus, the best technique
+is to place on screen both the source buffer for the button and the
+buffer to which it will link.  Mark the region of text to use for your
+button label, invoke the button create command from the menu, choose an
+action type which begins with @code{link-to-} and then use the direct
+selection techniques mentioned in @ref{Entering Arguments}, to select
+the link referent.
+@node Renaming, Deletion, Creation, Utilizing Explicit Buttons
+@subsection  Renaming
+@cindex explicit button, renaming
+@cindex button, renaming
+Once an explicit button has been created, its label text must be
+treated specially.  Any inter-word spacing within the label may be
+freely changed, as may happen when a paragraph is refilled.  But a
+special command must be invoked to rename it.
+The rename command operates in two different ways.  If point is within a
+button label when it is invoked, it will tell you to edit the button
+label and then invoke the rename command again.  The second invocation
+will actually rename the button.  If instead the command is originally
+invoked outside of any explicit button, it will prompt for the button
+label to replace and the label to replace it with and then will perform
+the rename.  All occurrences of the same button in the buffer will be
+renamed, so you need locate only one occurrence of the button.
+@vindex file, .~/.emacs
+@vindex file, hsite.el
+@kindex C-c C-r
+The rename command may be invoked from the Hyperbole menu via
+Ebut/Rename.  A faster method is to use a key bound to the
+@code{hui:ebut-rename} command.  Your site installation may include such
+a key.  @{@kbd{C-h w hui:ebut-rename @key{RET}}@} should show you any
+key it is on.  If no key binding has been established or if you prefer
+one of your own, simply bind it within your @file{~/.emacs} file.  We
+recommend the @{@kbd{C-c C-r}@} key, as in: @code{(global-set-key
+"\C-c\C-r" 'hui:ebut-rename)}.
+@node Deletion, Modification, Renaming, Utilizing Explicit Buttons
+@subsection  Deletion
+@cindex explicit button, deleting
+@cindex button, deleting
+Ebut/Delete works similarly to the Rename command but deletes the
+selected button.  The button's delimiters are removed to confirm the
+delete.  If the delete command is invoked with a prefix argument, then
+both the button label and the delimiters are removed as confirmation.
+@vindex hui:ebut-delete-confirm-p
+Presently there is no way to recover a deleted button; it must
+be recreated.  Therefore, the @var{hui:ebut-delete-confirm-p} variable
+is true by default, causing Hyperbole to require confirmation before
+interactively deleting explicit buttons.  Set it to nil if you prefer no
+confirmation.
+@node Modification, Location, Deletion, Utilizing Explicit Buttons
+@subsection  Modification
+@cindex explicit button, modifying
+@cindex button, modifying
+@cindex Smart Mouse Key drag
+Ebut/Modify prompts you with each of the elements from the button's
+data list and allows you to modify each in turn.
+There is a quicker way to modify explicit link buttons.  Simply drag with the
+mouse Action Key from within the button label to a link destination in a
+different window, just as you would when creating a new button with a mouse
+drag.  Remember that drags may also be emulated from the keyboard.
+@xref{Creation}.
+@node Location, Buttons in Mail, Modification, Utilizing Explicit Buttons
+@subsection  Location
+@cindex explicit button, summarizing
+@cindex button, summarizing
+@cindex button, help
+The Ebut/Help menu can be used to summarize a single explicit button or
+all such buttons within a single buffer.  The buttons summarized may
+then be activated directly from the summary.
+Ebut/Help/BufferButs summarizes the explicit buttons in the order in
+which they appear in the buffer.  Ebut/Help/CurrentBut summarizes only
+the button at point.  Ebut/Help/OrderedButs summarizes the buttons in
+alphabetical order.  All of these summary commands eliminate duplicate
+instances of buttons from their help displays.
+@cindex explicit button, searching
+@cindex button, searching
+Ebut/Search prompts for a search pattern and searches across all the
+locations in which you have previously created explicit buttons.  It
+asks you whether to match to any part of a button label or only complete
+labels.  It then displays a list of button matches with a single line of
+surrounding context from their sources.  Any button in the match list
+may be activated as usual.  An Action Key press on the surrounding context
+jumps to the associated source line or a press on the filename preceding
+the matches jumps to the file without selecting a particular line.
+There are presently no user-level facilities for globally locating buttons
+created by others or for searching on particular button attributes.
+@node Buttons in Mail, Buttons in News, Location, Utilizing Explicit Buttons
+@subsection  Buttons in Mail
+@kindex C-x m
+@findex mail
+Hyperbole allows the embedding of buttons within electronic mail
+messages that are composed in Emacs with the standard @code{(mail)}
+command, normally bound to @{@kbd{C-x m}@} or with other Emacs-based
+mail composing functions.  An enhanced mail reader can then be used
+to activate the buttons within messages just like any other buttons.
+@cindex button, mailing
+@cindex button, posting
+@cindex mailing buttons
+@cindex posting buttons
+@cindex mail reader
+@cindex mailer initialization
+@cindex RMAIL
+@cindex VM
+@cindex PIEmail
+@cindex MH-e
+@cindex GNUS
+@cindex USENET
+@cindex news
+@vindex file, hmail.el
+Hyperbole automatically supports the following mail readers:  Rmail,
+@ref{Rmail,,,emacs, the GNU Emacs Manual}, VM, @ref{Introduction,,,vm,
+the VM Manual}, and PIEmail, and MH-e.  Button inclusion and activation
+within USENET news articles is also supported in the same fashion via
+the GNUS news reader, @ref{Introduction,,,gnus, the GNUS Manual}, if
+available at your site.  (The @file{hmail.el} file provides a
+generalized interface that can be used to hook in other mail or news
+readers if the necessary interface functions are written.)
+@vindex mail-yank-original
+@kindex C-c C-y
+@cindex mail inclusion
+All explicit buttons to be mailed must be created within the outgoing
+message buffer. There is no present support for including text from
+other buffers or files which contain explicit buttons, except for the
+ability to yank the contents of a message being replied to, together
+with all of its buttons, via the @code{(mail-yank-original)} command
+bound to @{@kbd{C-c C-y}@}.  From a user's perspective, buttons are
+created in precisely the same way as in any other buffer.  They also
+appear just like any other buttons to both the message sender and the
+reader who uses the Hyperbole enhanced readers.  Button operation may be
+tested any time before a message is sent.  A person who does not use
+Hyperbole enhanced mail readers can still send messages with embedded
+buttons since mail composing is independent of any mail reader
+choice.
+Hyperbole buttons embedded within received mail messages act just like
+any other buttons.  The mail does not contain any of the action type
+definitions used by the buttons, so the receiver must have these or she
+will receive an error when she activates the buttons.  Buttons which
+appear in message @emph{Subject} lines are copied to summary buffers
+whenever such summaries are generated.  Thus, they may be activated from
+either the message or summary buffers.
+Nothing bad will happen if a mail message with explicit buttons is sent
+to a non-Hyperbole user.  The user will simply see the text
+of the message followed by a series of lines of button data at its end.
+Hyperbole mail users never see this data in its raw form.
+@vindex smail:comment
+@cindex mail comment
+In order to alert readers of your mail messages that you can utilize
+Hyperbole mail buttons, the system automatically inserts a comment into
+each mail message that you compose to announce this fact.  The variable,
+@var{smail:comment} controls this behavior.  See its documentation for
+technical details.  By default, it produces a message of the form:
+@example
+Comments: Hyperbole mail buttons accepted, vX.XX.
+@end example
+@vindex file, ~/.emacs
+@noindent
+where the X's indicate your Hyperbole version number.  You can cut this
+out of particular messages before you send them.  If you don't want any
+message at all, add the following to your @file{~/.emacs} file before
+the point at which you load Hyperbole.
+@lisp
+(setq smail:comment nil)
+@end lisp
+@cindex actype, link-to-mail
+A final mail-related facility provided by Hyperbole is the ability to
+save a pointer to a received mail message by creating an explicit button
+with a @code{link-to-mail} action type.  When prompted for the mail
+message to link to, if you press the Action Key on an Rmail message, the
+appropriate parameter will be copied to the argument prompt, as
+described in @ref{Entering Arguments}.
+@node Buttons in News,  , Buttons in Mail, Utilizing Explicit Buttons
+@subsection  Buttons in News
+@cindex button, posting
+@cindex news reader/poster
+@cindex posting news
+@cindex GNUS
+@cindex USENET
+@vindex file, hgnus.el
+@vindex file, hsite.el
+Explicit buttons may be embedded within outgoing USENET news articles
+and may be activated from news articles that are being read.  This
+support is available for the GNUS news reader.  It is enabled by default
+within @file{hsite.el} by autoloading the @file{hgnus.el} file.
+All Hyperbole support should work just as it does when reading or
+sending mail.  @xref{Buttons in Mail}.  When reading news, buttons which
+appear in message @emph{Subject} lines may be activated within the GNUS
+subject buffer as well as the article buffer.  When posting news, the
+*post-news* buffer is used for outgoing news articles rather than the
+*mail* buffer.
+Remember that the articles you post do not contain the action type
+definitions used by the buttons, so the receiver must have these or she
+will receive an error when he activates the buttons.  You should also
+keep in mind that most USENET readers will not be using Hyperbole, so if
+they receive a news article containing explicit buttons, they will
+wonder what the button data at the end of the message is.  You should
+therefore limit distribution of such messages.  For example, if most
+people at your site read news with GNUS and use Hyperbole, it would be
+reasonable to embed buttons in postings to local newsgroups.
+@cindex news comment
+In order to alert readers of your postings that you can utilize
+Hyperbole mail buttons embedded within personal replies,
+the system automatically inserts the same comment that is included
+within mail messages to announce this fact.  @xref{Buttons in Mail}, for
+details and an explanation of how to turn this feature off.
+@node Smart Keys, Menus, Buttons, Top
+@chapter Smart Keys
+@cindex Smart Key
+@cindex mouse support
+@cindex Action Key
+@cindex Assist Key
+@kindex Action Key
+@kindex Assist Key
+Hyperbole provides two special @dfn{Smart Keys} that perform
+context-sensitive operations, the Action Key and the Assist Key.  By
+default, the @dfn{Action Key} is bound to your shift-middle mouse button (or
+shift-left on a 2-button mouse) and the @dfn{Assist Key} is bound to your
+shift-right mouse button, assuming Hyperbole is run under an external window
+system.  (InfoDock users should use the middle mouse button as the
+Action Key, instead.)
+@findex hmouse-shift-buttons
+Mouse configuration is automatic for InfoDock, XEmacs, and Epoch under
+the X window system and for GNU Emacs versions 18 and 19 under X,
+OpenWindows, NEXTSTEP, SunView and Apollo's Display Manager, assuming
+your Emacs program has been built with support for any of these window
+systems.  The command, @code{hmouse-shift-buttons}, can be used to
+select between shifted and unshifted Smart Mouse Keys.
+@vindex hkey-init
+@kindex C-u M-RET
+@kindex M-RET
+By default (if @var{hkey-init} is set to @code{t} in @file{hsite.el}),
+then @{@kbd{M-@key{RET}}@} may also be used as the Action Key and
+@{@kbd{C-u M-@key{RET}}@} may be used as the Assist Key.  In many
+read-only modes like Dired and Rmail,
+@{@key{RET}@} also functions as the Action Key.  These key bindings allow
+context sensitive operation from any keyboard.
+@cindex key binding, smart keys
+@cindex smart key commands
+@findex action-key
+@findex assist-key
+@findex action-mouse-key
+@findex assist-mouse-key
+If you prefer other key bindings, simply bind the commands
+@code{action-key} and @code{assist-key} to keyboard keys.
+@code{hkey-either} may be used instead if you prefer a single
+key binding for both commands; a prefix argument then invokes
+@code{assist-key}.
+You may also bind @code{action-mouse-key} and @code{assist-mouse-key}
+to mouse keys, as you like.
+@cindex button activation
+@cindex activation
+@cindex button help
+The Action Key generally selects entities, creates links and
+activates buttons.  The Assist Key generally provides help,
+such as reporting on a button's attributes, or serves a complementary
+function to whatever the Action Key does within a context.
+@cindex Smart Key operation
+You can get a summary of what the Smart Keys do in all of their
+different contexts by pressing the Assist Key in the right
+corner (within the rightmost 3 characters) of a window modeline or by
+using the Hyperbole Doc/SmartKy menu entry.
+The following table is an example of this summary.  Much of the browsing
+power of Hyperbole comes from use of the Smart Keys, so you should spend
+some time practicing how to use them.  This table may appear daunting at
+first, but as you practice and notice that the Smart Keys do just a few
+context-sensitive things per editor mode, you will find it easy to just
+point and click and let Hyperbole do the rest.
+For extensive reference documentation on the Smart Keys, @ref{Smart
+Key Reference}.
+@page
+@iftex
+@example
+@include ../etc/hypb-mouse.txt
+@end example
+@end iftex
+@ifinfo
+@format
+@include ../etc/hypb-mouse.txt
+@end format
+@end ifinfo
+@vindex action-key-default-function
+@vindex assist-key-default-function
+Note how the last line in the table explains the default behavior of the
+Smart Keys.  That is what they do when they cannot find a context match
+at your current location.  See the documentation for the variables
+@var{action-key-default-function} and @var{assist-key-default-function}
+for information on how to customize the behavior of the Smart Keys
+within default contexts.
+@cindex Hyperbole help
+A prime design criterion of Hyperbole's user interface is that one
+should be able to see what an operation will do before using it.
+The Assist Key shows you what a button or minibuffer menu item will do
+before you activate it.   Hyperbole also shows the result of directly
+selecting an argument value with the mouse, to provide feedback as to
+whether the right item has been selected.  A second click is necessary
+before an argument is accepted and processed.
+@cindex Smart Key help
+@cindex help, Smart Key
+@cindex context sensitive help
+When you use a mouse and you want to find out what either of the Smart
+Keys does within a context, depress the one you want to check on and
+hold it down, then press the other and release as you please.  A help
+buffer will pop up explaining the actions that will be performed in that
+context, if any.  A press of either Smart Key at the end of that
+help buffer will restore your display to its configuration prior to
+invoking help.
+@kindex C-h A
+@vindex hkey-init
+By default (if @var{hkey-init} is left set equal to @code{t} in
+@file{hsite.el}), then @{@kbd{C-h A}@} will display this same
+context-sensitive help for the Action Key while @{@kbd{C-u C-h
+A}@} will display the help for the Assist Key.  Note that
+@{@kbd{C-h a}@} will perform a function unrelated to Hyperbole, so you
+must press the shift key when you hit the @kbd{A} character.
+@cindex Smart Key toggle
+@cindex mouse key toggle
+@vindex file, ~/.emacs
+@vindex file, hsite.el
+@kindex C-c t
+When Hyperbole is installed, a key may be bound which allows you
+to switch between the Smart Key mouse bindings and your prior ones.
+@kbd{C-h w hmouse-toggle-bindings @key{RET}} should show you any key
+which performs this command.  If no key binding has been established or
+if you prefer one of your own, simply select a key and bind it
+within your @file{~/.emacs} file.  For example, @code{(global-set-key
+"\C-ct" 'hmouse-toggle-bindings)}.
+@node Menus, Entering Arguments, Smart Keys, Top
+@chapter Menus
+@cindex InfoDock
+@cindex XEmacs
+@cindex Emacs 19
+@cindex menu use
+@cindex menubar, Hyperbole menu
+Under InfoDock, XEmacs, and Emacs 19, pulldown and popup menus are
+available to invoke Hyperbole commands, including those from the rolodex
+and the outliner.  These menus operate like any other X window menus.
+Use the Quit command on the Hyperbole menubar menu to get rid of the
+menu if you do not need it.  Invoking Hyperbole again will add the menu
+back to the menubar.
+@cindex minibuffer menus
+This section discusses only the specialized @dfn{minibuffer menus} that
+appear in the minibuffer window and that work with all Emacs versions.
+Minibuffer menu items may be selected from either the keyboard or via
+mouse clicks.  When used with the keyboard, they provide rapid command
+access similar to key bindings.
+@kindex C-h h
+@vindex action-key-default-function
+@cindex menu, top level
+The top level menu is invoked from a key given in your @file{hsite.el}
+file (by default, @{@kbd{C-h h}@}) or via an Action Key press in a
+location with no other action defined.  The menu will appear in the
+minibuffer and should look mostly like so:
+@noindent
+@example
+Hy4>  Act Butfile/ Doc/ Ebut/ Gbut/ Hist Ibut/ Msg/ Otl/ Rolo/ Win/
+@end example
+@noindent
+The above menu items can be summarized as follows:
+@table @strong
+@cindex menu, Act
+@item Act
+Perform the action associated with any button at point or prompt for the
+name of an explicit button to activate if point is not on one.
+@cindex menu, ButFile
+@cindex button file, HYPB
+@vindex file, HYPB
+@item Butfile/
+Display a local or global file of buttons, providing easy access.
+@file{HYPB} for a local button file and @file{~/.hyperb/HYPB} for your
+global file.  These are good places to start your button creation testing.
+@cindex menu, EBut
+@item Ebut/
+All explicit button commands.
+@cindex menu, Doc
+@cindex menu, Types
+@item Doc/
+Hyperbole documentation quick access.  Contains Types/ submenu for
+documentation on Hyperbole implicit button and action types.
+@cindex menu, Global Buttons
+@item Gbut/
+All global button commands.  Global buttons are accessed by name
+rather than by direct selection.
+@cindex menu, History
+@cindex history
+@item Hist
+Jumps back to last position in button traversal history.
+@cindex menu, Implicit Buttons
+@item Ibut/
+All implicit button commands.
+@cindex menu, Message
+@item Msg/
+Hyperbole-specific mail and news messaging support commands.
+Use this to send mail to the Hyperbole discussion list or to
+add/modify your entry on a Hyperbole mail list.
+@cindex menu, Outliner
+@item Otl/
+Autonumbered, structured outliner and hyper-node manager commands.
+@xref{Outliner}.
+@cindex menu, Rolodex
+@item Rolo/
+Hierarchical, multi-file rolodex lookup and edit commands.
+@xref{Rolodex}.
+@cindex menu, Window Configurations
+@cindex menu, Windows
+@item Win/
+Window configuration management such as adding and restoring window
+configurations by name. @xref{Window Configurations}.
+@end table
+@cindex submenus
+@cindex menu help
+@cindex help, menu items
+All menu items are selected via the first character of their names
+(letter case does not matter) or via a press of the Action Key.  "/" at
+the end of an item name indicates that it brings up a sub-menu.  A press
+of the Assist Key on an item displays help for the item, including the
+action that it performs.
+@kindex C-t
+@kindex q
+@kindex C-g
+While a menu is active, to re-activate the top-level Hyperbole menu, you
+must use @{@kbd{C-t}@}.  This allows you to browse the submenus and then
+return to the top.  You can quit without selecting an item by using
+@{@kbd{q}@}.  @{@kbd{C-g}@} aborts whether you are at a menu prompt or
+any other Hyperbole prompt.
+@node Entering Arguments, Outliner, Menus, Top
+@chapter Entering Arguments
+@cindex argument entry
+@cindex direct selection
+@cindex double click
+Many Hyperbole commands prompt you for arguments.  The standard
+Hyperbole user interface has an extensive core of argument types that it
+recognizes.  Whenever Hyperbole is prompting you for an argument, it
+knows the type that it needs and provides some error checking to help
+you get it right.  More importantly, it allows you to press the Action
+Key within an entity that you want to use as an argument and it will grab the
+appropriate thing and show it to you at the input prompt within the
+minibuffer.  If you press the Action Key again at the same point (click
+with a mouse) on the same thing again, it accepts the entity as the
+argument and moves on.  Thus, a double click registers a desired
+argument.  Double-quoted strings, pathnames, mail messages, Info nodes,
+dired listings, buffers, numbers, completion items and so forth are all
+recognized at appropriate times.  All of the argument types mentioned in
+the documentation for the Emacs Lisp @code{(interactive)} function are
+recognized.  Experiment a little and you will quickly get used to this
+direct selection technique.
+@cindex completion
+Wherever possible, standard Emacs completion is offered, see
+@ref{Completion,,,emacs, the Gnu Emacs Manual}.  Remember to use @{@kbd{?}@}
+to see what your possibilities for an argument are.  Once you have a
+list of possible completions on screen, you can double click the Action
+Key on any one to enter it as the argument.
+@node Outliner, Rolodex, Entering Arguments, Top
+@chapter Outliner
+@cindex outliner
+@cindex autonumber
+@cindex relative autonumber
+@cindex permanent identifier
+@cindex idstamp
+@cindex hyperlink anchor
+The Hyperbole outliner, also known as the Koutliner (pronounced
+Kay-outliner), produces structured, autonumbered documents composed of
+hierarchies of cells.  Each @dfn{cell} has two identifiers, a
+@dfn{relative identifier} indicating its present position within the
+outline and a @dfn{permanent identifier} called an @dfn{idstamp},
+suitable for use within hyperlink references to the cell.  The idstamp
+is typically not displayed but is available when needed.
+@xref{Autonumbering}.
+Cells also store their time of creation and the user who created the
+cell.  User-defined attributes may also be added to cells.  @xref{Cell
+Attributes}.
+@cindex menu, Outline
+The outliner works only under GNU Emacs version 19 or higher, XEmacs
+version 19.9 or higher or under InfoDock.  You can tell whether you are
+running a version of Emacs which supports the outliner by hitting
+@{@kbd{C-h h}@} to display the Hyperbole menu.  If you see an
+@code{Otl/} entry in the menu, then the outliner is available.
+Otherwise, the outliner does not work with your version of Emacs, so
+this section of the manual will not be of interest to you.  (The same is
+true of the Hyperbole/Outline pulldown menu; if it appears, the outliner
+is available for use.)
+@vindex file, EXAMPLE.kotl
+@cindex menu, Outline/Example
+This chapter expands on the information given in @file{EXAMPLE.kotl}
+file included with Hyperbole.  Use @{@kbd{C-h h o e}@} to display that
+file.  It is an actual outline file that explains major outliner
+operations.  You can test out the viewing and motion commands with this
+file.  If you want to experiment with editing operations, use @{@kbd{C-x
+C-w}@} to write the outline to a temporary file such as,
+@file{/tmp/e.kotl}, and then use @{@kbd{C-x C-q}@} to make the outline
+editable.
+@xref{Outliner Keys}, for a full summary of the key bindings and
+commands available in the outliner.
+@menu
+* Menu Commands::
+* Creating Outlines::
+* Autonumbering::
+* Idstamps::
+* Editing::
+* Viewing::
+* Links::
+* Cell Attributes::
+* Outliner History::
+@end menu
+@node Menu Commands, Creating Outlines, Outliner, Outliner
+@section   Menu Commands
+The Otl/ menu entry on the Hyperbole top-level menu provides access to
+a number of major outliner commands:
+@example
+@group
+@cindex outliner commands
+@cindex Koutliner commands
+@findex kotl-mode:show-all
+@findex kvspec:toggle-blank-lines
+@findex kfile:find
+@findex kotl-mode:hide-sublevels
+@findex kotl-mode:hide-tree
+@findex kotl-mode:kill-tree
+@findex klink:create
+@findex kotl-mode:overview
+@findex kotl-mode:show-tree
+@findex kotl-mode:top-cells
+@findex kvspec:activate
+@cindex menu, Outline
+Menu Item    Command                    Description
+====================================================================
+All          kotl-mode:show-all         Expand all cells
+Blanks       kvspec:toggle-blank-lines  Toggle blank lines on or off
+Create       kfile:find                 Edit or create an outline
+Downto       kotl-mode:hide-sublevels   Hide cells deeper than a level
+Examp        <sample outliner file>     Show self-descriptive example
+Hide         kotl-mode:hide-tree        Hide tree with root at point
+Info         <outliner documentation>   Show outliner manual section
+Kill         kotl-mode:kill-tree        Kill the current tree
+Link         klink:create               Create a link to another cell
+Overvw       kotl-mode:overview         Show first line of each cell
+Show         kotl-mode:show-tree        Show tree with root at point
+Top          kotl-mode:top-cells        Collapse to top-level cells
+Vspec        kvspec:activate            Set a view specification
+====================================================================
+@end group
+@end example
+@node Creating Outlines, Autonumbering, Menu Commands, Outliner
+@section   Creating Outlines
+@cindex outline file suffix
+@cindex outline, creating
+@vindex file, .kotl suffix
+In addition to the Otl/Create menu item, you can create and experiment
+with outline files simply by finding a file, @{@kbd{C-x C-f}@} with a
+@file{.kotl} suffix.  @file{.kot} will also work for DOS or
+Windows-impaired users.
+@cindex root cell
+@cindex top-level cell
+@cindex cell, top-level
+@cindex cell, idstamp 0
+When a new koutline is created, an invisible root cell is created.  Its
+permanent and relative ids are both 0, and it is considered to be at
+level 0 in the outline.  All visible cells in the outline are at level 1
+or deeper, and thus are descendants of this root cell.  Some koutliner
+commands prompt for cell numbers as arguments.  An argument of 0 makes
+commands operate upon the entire outline.
+An initial level 1 cell is also created to make it easy to start
+entering text in the outline.  A koutline always has at least one
+visible cell in it.
+@xref{Autonumbering}, which explains how cells are labeled according to their
+respective levels in the outline and how these labels are updated as the
+structure of the outline changes.
+@node Autonumbering, Idstamps, Creating Outlines, Outliner
+@section   Autonumbering
+@cindex autonumber
+@cindex relative identifier
+@xref{Adding and Killing}, which explains how to add new cells to or remove
+cells from a koutline.  As you do this, or as you promote or demote
+cells within the outline, the labels preceding the contents of each cell
+automatically update to reflect the new structure.  These labels are
+also known as @dfn{autonumbers} and as @dfn{relative ids} because they
+change as the structure changes.
+@cindex outline structure
+The outline structure is shown by these labels and by the indentation of
+each outline level.  Normally, each deeper level is indented another
+three characters, to reflect the nesting.
+@cindex label type, alpha
+@cindex label type, legal
+@cindex alpha labels
+@cindex legal labels
+@cindex outline, label type
+The default autonumbers are called @dfn{alphanumeric labels} because
+they alternate between using numbers and letters to distinguish each
+successive level.  Each alphanumeric label uniquely identifies a cell's
+position in an outline, so that there is no need to scan back to prior
+cells to see what the current section number of an outline is.  This is
+similar to a legal numbering scheme but without all the period
+characters between level numbers.  As an example, 1b3 is equivalent to a
+legal label of 1.2.3.  Both refer to the 3rd cell at level 3,
+below the 2nd child of the first cell at level 1.  Said another way,
+this is the 3rd child of the 1st cell's 2nd child.  In other words, it
+is easier to visualize hierarchies than to talk about them.
+Alphanumeric labels are the default because they are shorter and easier
+to read aloud than equivalent legal ones.  They also simplify
+distinguishing between even and odd level labels because of the
+alternating character set.
+@kindex C-c C-l
+@cindex label type, changing
+You can change the labeling scheme used in a particular outline with the
+command @{@kbd{C-c C-l}@}.  A @{@kbd{?}@} then will show all of your
+options.  Legal labels, partial alpha labels (single level autonumbering
+where only the last part of the level number is shown, as commonly seen
+in other outliner products), idstamps (permanent cell ids), and star
+outline level labels (Emacs asterisk-based outline labeling) are all
+available.  Or you may choose to turn autonumbering off.  Cells are
+still indented to reflect the outline structure whether or not labels
+are displayed.
+@cindex label separator, changing
+@cindex cell, label separator
+@cindex outline, label separator
+@kindex C-c M-l
+@kindex C-u C-c M-l
+A cell label is normally followed by two spaces, called the @dfn{label
+separator}, prior to the start of the cell contents.  You can change the
+separator with for the current outline with @{@kbd{C-c M-l}@}.
+@{@kbd{C-u C-c M-l}@} will additionally change the default separator
+value used when new outlines are created (for the current session only).
+For example, use the value ". " to get a trailing period after each cell
+label.  The separator must be at least two characters long but may be
+longer.
+@vindex file, ~/.emacs
+@cindex initialization file
+If you find a separator that you prefer for all outlines, change the
+separator setting permanently by adding the following line to your Emacs
+initialization file, @file{~/.emacs}, substituting for `your-separator':
+@cindex label separator, default
+@vindex kview:default-label-separator
+@lisp
+(setq kview:default-label-separator "your-separator")
+@end lisp
+@node Idstamps, Editing, Autonumbering, Outliner
+@section   Idstamps
+@cindex permanent identifier
+@cindex idstamp
+Idstamps (permanent ids) are associated with each cell and can be
+used in hyperlinks that are maintained as cells are reordered in a file.
+@xref{Links}.  Idstamps may also be displayed in place of the outline
+level relative ids.  Use @{@kbd{C-c C-l id RET}@}.
+@cindex idstamp counter
+An idstamp counter for each outline starts at 0 and is incremented by
+one each time a cell is added to the outline.  This idstamp stays with
+the cell no matter where it is moved within the outline.  If the cell is
+deleted, its idstamp is not reused.
+@cindex root cell
+@cindex top-level cell
+@cindex cell, top-level
+@cindex cell, idstamp 0
+@cindex idstamp 0
+The 0 idstamp is always assigned to the root node of the entire outline.
+This node is never visible within the outline, but is used so that the
+outline may be treated as a single tree when needed.  Idstamps always
+begin with a 0, as in 012, to distinguish them from relative ids.
+@node Editing, Viewing, Idstamps, Outliner
+@section   Editing
+You edit text and move around in the Koutliner just as you would in any
+other Emacs buffer, except when you want to deal with the structural
+components of an outline.  Within the contents of a cell, all of your
+standard editing keys should work properly.  You can just type in text
+and the left and right margins of the lines will be maintained for you.
+@xref{Filling}, for the times when you need to refill a paragraph or to
+control when filling occurs.@refill
+Don't invoke editing commands with @{@kbd{M-x command-name @key{RET}}@}
+since the Koutliner uses special differently named commands made to act
+like the regular editing commands but which account for the structure
+and indentation in koutlines.
+@cindex cell, selection
+You can use the mouse to select parts of the contents of a single cell
+for editing.  But don't drag across cell boundaries and then edit the
+selected region, since that can destroy the outline structure.
+@menu
+* Adding and Killing::
+* Moving Around::
+* Relocating and Copying::
+* Filling::
+* Transposing::
+* Splitting and Appending::
+* Inserting and Importing::
+@end menu
+@node Adding and Killing, Relocating and Copying, Editing, Editing
+@subsection  Adding and Killing
+@kindex C-j
+@kindex C-u c-j
+@kindex C-c a
+@kindex C-c p
+@cindex cell, adding
+@cindex cell, creating
+@{@kbd{C-j}@} adds a new cell as a successor sibling of the
+current cell, that is, the next cell at the same level as the current
+cell.  If you enter a positive number as a prefix argument, that number
+of cells will be inserted, all at the same level.  @{@kbd{C-u C-j}@} is
+handled specially.  It adds a single cell as a child of the current cell.
+@{@kbd{C-c a}@} does the same thing.  @{@kbd{C-c p}@} adds the cell as
+the successor of the current cell's parent.
+@kindex C-c C-k
+@kindex C-c k
+@kindex C-u C-c k
+@kindex C-y
+@cindex cell, killing
+@cindex cell, yanking contents
+@cindex tree, killing
+@{@kbd{C-c C-k}@} kills the current cell and its entire subtree.
+@{@kbd{C-c k}@} kills the contents of a cell from point through the end
+of the cell; it does not remove the cell itself.  @{@kbd{C-u C-c k}@}
+kills the entire contents of the cell regardless of the location of
+point.  You may then yank the contents into another cell or another
+buffer with @{@kbd{C-y}@}.
+@node Relocating and Copying, Moving Around, Adding and Killing, Editing
+@subsection  Relocating and Copying
+@cindex promotion
+@cindex demotion
+@cindex tree, promoting
+@cindex tree, demoting
+@dfn{Demotion} is the act of moving a tree down one or more levels in the
+outline.  The new tree will become either the successor or the first
+child of the cell which precedes it in the outline.  @dfn{Promotion} is
+the inverse operation.  Note that trees (cells and their entire
+substructure) are promoted and demoted, not individual cells.
+@kindex @key{TAB}
+@kindex M-@key{TAB}
+Trees may be demoted or promoted by pressing @{@key{TAB}@} or
+@{@kbd{M-@key{TAB}}@} respectively, as in most outliners today.
+@{@kbd{M-0 @key{TAB}}@} and @{@kbd{M-0 M-@key{TAB}}@} demote and
+promote trees and additionally refill each cell that is not specially
+marked to prevent refilling.  @xref{Filling}.  A positive or negative
+prefix argument to these commands promotes or demotes the tree up to a
+maximum of the number of levels given by the argument.  The outline may
+not support movement of the tree by the number of levels requested.
+@cindex tree, copying
+@cindex tree, moving
+@cindex Action Key, cell argument
+@kindex Action Key, cell argument
+For maximum flexibility in rearranging outlines, there are commands that
+move or copy entire trees.  Each of these commands prompts for the label
+of the root cell to move or copy and for second cell at the new location
+for the moved or copied tree.  You can either accept the default
+provided, type in the cell label or when a mouse is available, simple
+double click with the Action Key on the contents of a cell.  The
+Koutliner knows to use the cell's label in such cases.
+In these following commands, words delimited with <> represent the
+arguments for which each command prompts.  Note how the use of prefix
+arguments changes each command's behavior from insertion at the sibling
+level to insertion at the child level.
+@table @kbd
+@kindex C-c c
+@item C-c c
+Copy <tree> to be the successor of <cell>.
+@kindex C-u C-c c
+@itemx C-u C-c c
+Copy <tree> to follow as the first child of <cell>.
+@kindex C-c C-c
+@item C-c C-c
+Copy <tree> to be the predecessor of <cell>.
+@kindex C-u C-c C-c
+@itemx C-u C-c C-c
+Copy <tree> to be the first child of the parent of <cell>.
+@kindex C-c m
+@item C-c m
+Move <tree> to be the successor of <cell>.
+@kindex C-u C-c m
+@itemx C-u C-c m
+Move <tree> to follow as the first child of <cell>.
+@kindex C-c C-m
+@item C-c C-m
+Move <tree> to precede <cell>.
+@kindex C-u C-c C-m
+@itemx C-u C-c C-m
+Move <tree> to be the first child of the parent of <cell>.
+@end table
+@cindex mouse, moving trees
+If you have mouse support under Hyperbole, you can move entire trees
+with mouse clicks.  Simply click the Assist Key within the indentation
+to the left of a cell and you will be prompted for a tree to move.
+Double click the Action Key within the contents the root cell of the tree
+to move and then double click within the contents of the root cell of the
+tree you want it to follow as a sucessor.
+Copying and moving only work within a single outline right now, so don't
+try to use them to move trees across different outline files.  You can,
+however, copy an outline tree to a non-outline buffer with:
+@cindex tree, exporting
+@cindex outline, exporting
+@cindex tree, mailing
+@cindex outline, mailing
+@cindex exporting an outline
+@cindex mailing an outline
+@table @kbd
+@kindex C-c M-c
+@item C-c M-c
+Copy  <tree> to a non-koutline buffer.
+@kindex C-c @@
+@itemx C-c @@
+Copy a <tree> to an outgoing mail message.
+@end table
+@node Moving Around, Filling, Relocating and Copying, Editing
+@subsection  Moving Around
+@cindex outline, motion
+In addition to normal Emacs movement commands, you can move within a
+cell or from one cell or tree to another.
+@table @kbd
+@kindex C-c ,
+@item C-c ,
+Move to the beginning of the current cell.
+@kindex C-c .
+@itemx C-c .
+Move to the end of the current cell.
+@kindex C-c C-n
+@item C-c C-n
+Move to the next visible cell, regardless of level.
+@kindex C-c C-p
+@itemx C-c C-p
+Move to the previous visible cell, regardless of level.
+@kindex C-c C-f
+@item C-c C-f
+Move forward to this cell's successor, if any.
+@kindex C-c C-b
+@itemx C-c C-b
+Move backward to this cell's predecessor, if any.
+@kindex C-c C-d
+@item C-c C-d
+Move to the first child of the current cell, if any.
+@kindex C-c C-u
+@itemx C-c C-u
+Move to the parent cell of the current cell, if any.
+@kindex C-c <
+@item C-c <
+Move to the first sibling at the current level within this tree.
+@kindex C-c >
+@itemx C-c >
+Move to the last sibling at the current level within this tree.
+@kindex C-c ^
+@item C-c ^
+Move to the level 1 root cell of the current tree.
+@kindex C-c $
+@itemx C-c $
+Move to the last cell in the tree rooted at point, regardless of level.
+@end table
+@node Filling, Transposing, Moving Around, Editing
+@subsection  Filling
+@cindex outline, filling
+Filling is the process of extending lines that are shorter than the
+right margin and reducing lines which extend past the margin by moving
+words among the lines.  Commands are provided to fill a paragraph within
+a cell or a whole cell, which may have multiple paragraphs.
+@cindex filling
+@cindex cell, filling
+@cindex paragraph, filling
+@cindex tree, filling
+@cindex margin
+@kindex M-q
+@kindex M-j
+@kindex C-c M-q
+@kindex C-c M-j
+@kindex C-M-q
+@kindex C-M-j
+@{@kbd{M-q}@} or @{@kbd{M-j}@} refills a paragraph within a
+cell so that its lines wrap within the current margin settings.
+@{@kbd{C-c M-q}@} or @{@kbd{C-c M-j}@} refills all paragraphs within a
+cell.  @{@kbd{C-M-q}@} or @{@kbd{C-M-j}@} refills all cells within a
+tree.  See your Emacs or InfoDock manual for information on how to set
+the left and right margins.
+@vindex kotl-mode:refill-flag
+@cindex refilling
+@cindex attribute, no-fill
+@cindex cell, no-fill attribute
+Set the variable, @var{kotl-mode:refill-flag}, to t if you want
+moving, promoting, demoting, exchanging, splitting and appending cells
+to also automatically refill each cell.  Generally, this is not
+recommended since if you happen to move a cell that you have carefully
+formatted and forgot to give it a `no-fill' property, your formatting
+will be lost.
+@node Transposing, Splitting and Appending, Filling, Editing
+@subsection  Transposing
+The Koutliner move and copy commands rearrange entire trees.  The
+following two commands, in contrast, exchange the locations of two
+individual cells.
+@kindex C-c e
+@cindex cell, transposing
+@cindex cell, exchanging
+@cindex exchanging cells
+@cindex transposing cells
+@{@kbd{C-c e}@} prompts for two cell addresses and exchanges the cell
+locations.
+@kindex C-c t
+@{@kbd{C-c t}@} does not prompt.  It exchanges the current
+and immediatly prior cell, regardless of their levels.  If there is no
+prior cell it exchanges the current and next cell.
+@cindex cell, mark and point
+@kindex M-0 C-c t
+@{@kbd{M-0 C-c t}@} exchanges the cells in which point and mark fall.
+@{@kbd{C-c t}@} with a non-zero numeric prefix argument, N, moves
+the current tree past maximally the next N visible cells.  If there are
+fewer visible, it makes the current cell the last cell in the outline.
+@node Splitting and Appending, Inserting and Importing, Transposing, Editing
+@subsection  Splitting and Appending
+@cindex splitting a cell
+@cindex cell, splitting
+@kindex C-c s
+@kindex C-u C-c s
+You can split one cell into two adjacent sibling cells with @{@kbd{C-c
+s}@}.  This leaves the cell contents preceding point in the current
+cell, minus any trailing whitespace, and moves the contents following
+point to a new sibling cell which is inserted into the outline.
+@{@kbd{C-u C-c s}@} instead adds the new cell as the first child of the
+original cell, rather than as its successor.
+All cell attributes in the original cell are propagated to the new one,
+aside from the creation attributes and idstamp.
+@kindex C-c +
+@cindex cell, appending
+@cindex appending to a cell
+@cindex attribute, no-fill
+@cindex cell, no-fill attribute
+@{@kbd{C-c +}@} appends the contents of a specified cell to the end of
+another cell.  It has no effect on cell attributes, except that if one
+cell has a `no-fill' attribute that prevents all but user requested
+filling of a cell, then the cell appended to inherits this property.
+This helps maintain any special formatting the appended text may have.
+@node Inserting and Importing,  , Splitting and Appending, Editing
+@subsection  Inserting and Importing
+@cindex outline, inserting into
+@cindex outline, importing into
+@cindex importation
+@cindex insertion
+@kindex C-x i
+@cindex outline, foreign file
+The elements of another buffer or file may be inserted into a koutline
+as a set of cells by using the @{@kbd{C-x i}@} command.  When prompted,
+you may use a buffer name or file name from which to insert, though
+completion is provided only for file names.
+@kindex C-u C-x i
+The elements from the original buffer are converted into kcells and
+inserted as the successors of the current cell.  If @{@kbd{C-u C-x i}@}
+is used, they are instead inserted as the inital children of the current
+cell.
+@vindex kimport:mode-alist
+@vindex kimport:suffix-alist
+@cindex outline, conversion
+@findex kotl-mode
+@cindex outline mode
+@cindex koutline mode
+@cindex file, importing
+@cindex importing a file
+See the documentation for the variables, kimport:mode-alist and
+kimport:suffix-alist, for information on mode and suffix-specific
+conversions performed on file elements before they are inserted.  This
+same conversion process applies if you invoke @{@kbd{M-x kotl-mode
+RET}@} in a non-koutline buffer or if you perform a generic file import
+as described later in this section.
+@findex kotl-mode:insert-file-contents
+Use @{@kbd{M-x kotl-mode:insert-file-contents RET}@} to insert the
+entire contents of a file into the current cell at the location of
+point.
+@findex kimport:file
+The outliner presently supports conversion of three types of files into
+koutline files.  You can choose to import a file into an existing
+koutline, following the tree at point, or to create a new koutline of
+the imported file contents.  @{@kbd{M-x kimport:file RET}@} will select
+the importation type based on the buffer or file name suffix of the file
+to import.
+@findex kotl-mode
+If you want to convert a buffer from some other mode into a koutline and
+then want to save the converted buffer back to its original file,
+thereby replacing the original format, then use @{@kbd{M-x kotl-mode
+RET}@} to convert the buffer into a koutline.  Remember that you will
+lose the old format of the buffer when you do this.
+Use one of the following commands if you really need explicit control over the
+type of importation used on some text.  With these commands, your
+original file remains intact.
+@findex kimport:text
+@cindex text file
+Use @{@kbd{M-x kimport:text RET}@} and you will be prompted for a text
+buffer or file to import and the new koutline buffer or file to create
+from its text.  It will also import the contents, attributes and level
+structure of cells from a koutline.
+@findex kimport:star-outline
+@cindex emacs outline
+@cindex star outline
+Star outlines are standard Emacs outlines where each entry begins with
+one or more asterisk characters.  Use @{@kbd{M-x kimport:star-outline
+RET}@} and you will be prompted for the star outline buffer or file to
+import and the new koutline buffer or file to create.
+@cindex Augment outline
+@findex kimport:aug-post-outline
+(Skip this if you are unfamiliar with the Augment system.)  Files
+exported from the Augment system as text often have alphanumeric
+statement identifiers on the right side.  You can import such files
+while maintaining there outline structure.  Use @{@kbd{M-x
+kimport:aug-post-outline RET}@} and you will be prompted for the Augment
+buffer or file to import and the koutline to create.
+@node Viewing, Links, Editing, Outliner
+@section   Viewing
+@cindex outline, viewing
+@cindex view
+The Koutliner has very flexible viewing facilities to allow you to
+effectively browse and study large amounts of material.
+@menu
+* Hiding and Showing::
+* View Specs::
+@end menu
+@node Hiding and Showing, View Specs, Viewing, Viewing
+@subsection  Hiding and Showing
+@cindex outline, hiding
+@cindex outline, showing
+@cindex collapsing
+@cindex expanding
+@cindex hiding
+@cindex showing
+Individual cells, branches, or particular levels in the outline may be
+hidden or shown.  These commands work even when an outline buffer is
+read-only, e.g. when its file is not checked out of a version control
+system yet, so that you can get effective views of an outline without
+editing it.  Some of these commands affect the current view spec,
+@ref{View Specs}.
+@table @kbd
+@cindex hide tree
+@cindex tree, show
+@kindex C-c C-h
+@item C-c C-h
+Hide (collapse) the tree rooted at point.
+@cindex show tree
+@cindex tree, show
+@kindex C-c C-s
+@itemx C-c C-s
+Show (expand) the tree rooted at point.
+@cindex outline, all cells
+@cindex cell, show all
+@kindex C-c C-a
+@item C-c C-a
+Show (expand) all of the cells in the outline.
+@cindex level
+@cindex cell, show levels
+@cindex outline, show levels
+@kindex C-x $
+@itemx C-x $
+Show all of the cells down to a particular <level>.  You are prompted
+for the level or a prefix argument may be given.
+@cindex subtree, hide
+@cindex tree, hide subtree
+@cindex cell, hide subtree
+@cindex hide subtree
+@kindex C-M-h
+@item C-M-h
+Hide the subtree at point, excluding the root cell.
+@cindex subtree, show
+@cindex tree, show subtree
+@cindex cell, show subtree
+@cindex show subtree
+@itemx M-x kotl-mode:show-subtree
+Show the subtree at point.  Use @{@kbd{C-c C-s}@} to achieve a similar
+effect.  The only difference is that it will expand the root cell too.
+@cindex overview
+@cindex outline, overview
+@kindex C-c C-o
+@item C-c C-o
+Show an overview of the outline by showing only the first line of
+every cell.  This also turns off blank lines between cells to maximize
+your view of the outline.
+@cindex top-level view
+@cindex outline, top-level
+@kindex C-c C-t
+@itemx C-c C-t
+Show a top-level view of the outline by showing only the first line of
+each level one cell.  This does not turn off blank lines.
+@end table
+@kindex Action Key, hide or show cell
+@cindex Action Key, hide or show cell
+@cindex cell, collapse
+@cindex cell, expand
+@kindex M-@key{RET}
+A click or a press of the Action Key within a cell's body, but not on a
+Hyperbole button, toggles between hiding and showing the tree rooted at
+point.  Try it with either your mouse or with @{@kbd{M-@key{RET}}@}.
+@node View Specs,  , Hiding and Showing, Viewing
+@subsection  View Specs
+@cindex view spec
+@cindex modeline, view spec
+@vindex kvspec:string
+@cindex pipe character
+@cindex |
+@cindex <|viewspec>
+@dfn{View specifications} (view specs, for short) are short codes used
+to control the view of a koutline.  The view specs in effect for an
+outline are always displayed in the modeline of the outline's window,
+following the outline buffer name, unless the variable,
+@var{kvspec:string}, has been set to @code{nil} to disable view spec
+modeline display.  The modeline display appears as <|viewspec> so that
+you can easily pick them out.  The | (pipe character) is also used in
+links that specify view specs to indicate the start of a view spec
+sequence.  @xref{Links}.
+@cindex outline, view specs
+The current view spec is saved whenever the outline is saved.  The next
+time the outline is read in, this will be the initial view.
+The rest of this section documents the the view spec characters that are
+presently supported and explains how to invoke a view spec.  There is no
+user-level way to add your own view spec characters, so all character
+codes are reserved for future use.
+@kindex C-c C-v
+@cindex view spec, setting
+@cindex view spec, changing
+@cindex changing the view spec
+@cindex setting the view spec
+@{@kbd{C-c C-v}@} prompts for a new view spec setting in which the following
+codes are valid.  Any invalid characters in a view spec are ignored.
+Characters are evaluated in an order meant to do the right thing, even
+when you use conflicting view spec characters.  The standard initial
+view spec is <|ben>.
+@cindex view spec, characters
+@table @kbd
+@cindex view spec, all lines and levels
+@item a
+Show all cell levels and all lines in cells.
+@kindex C-c b
+@cindex blank lines, toggle
+@cindex view spec, blank lines
+@kindex C-c b
+@cindex toggling blank lines
+@item b
+Turn on blank lines between cells.  Without this character, blank lines
+will be turned off.  You can also use the @{@kbd{C-c b}@} key binding to
+toggle line numbers on and off independent of any other view settings.
+@cindex view spec, lines per cell
+@cindex hide lines
+@cindex collapse lines
+@cindex cutoff lines
+@item cN
+Hide any lines greater than N in each cell.  0 means don't cutoff any
+lines.
+@cindex ellipses
+@cindex view spec, ellipses
+@item e
+Show ellipses when some content of a cell or its subtree is hidden.
+@cindex level
+@cindex cell, hiding levels
+@cindex hide levels
+@cindex view spec, show levels
+@item lN
+Hide cells at levels deeper than N.  0 means don't hide any cells.
+@cindex label type
+@cindex view spec, label type
+@vindex kview:default-label-type
+@cindex default label type
+@item n
+Turn on the default label type, as given by the variable,
+@var{kview:default-label-type}.  Normally, this is alphanumeric labels.
+@cindex label type, idstamps
+@itemx n0
+Display idstamps.
+@cindex label type, alpha
+@itemx n1
+Display alpha labels.
+@cindex label type, partial alpha
+@itemx n2
+Display partial alpha labels (don't use this, as full alpha labels are
+better).
+@cindex label type, legal
+@itemx n.
+Display legal labels.
+@cindex label type, star
+@cindex label type, asterisk
+@itemx n*
+Display star labels.  A level three cell would have three asterisks as a
+label, for example.
+@cindex label type, no labels
+@itemx n~
+Turn off labels.  (n viewspec is removed from modeline).
+@end table
+@cindex view spec, example
+As a test, use @{@kbd{C-h h o e}@} to display the example koutline.
+Then use @{@kbd{C-c C-v}@} to set a view spec of `c2l1'.  This will turn
+off blank lines, clip each cell after its second line, and hide all
+cells below level one.
+@node Links, Cell Attributes, Viewing, Outliner
+@section   Links
+@cindex link
+@cindex hyperlink
+@cindex klink
+@cindex <> delimiters
+Hyperlinks may be embedded in cells and may refer to other cells or
+external sources of information.  Explicit Hyperbole buttons may be
+created as usual via mouse drags, @ref{By Dragging, Creation Via Action
+Key Drags}.  A @dfn{klink} is a special implicit link button, delimited
+by <> separators, that jumps to a specific outline cell.  This section
+discusses klinks.
+@kindex Action Key, klink
+@cindex Action Key, klink
+@cindex klink, activating
+@cindex klink referent
+Press the Action Key over a klink to follow it.  This will flash the
+klink as a button and then will display its referent in the other
+window.  If the klink contains a view spec, that will be used when the
+referent is displayed.
+@cindex klink, inserting
+@kindex C-c l
+There are a number of easy ways to insert klinks into koutlines.  If you
+have mouse support under Hyperbole, simply click the Action Key within
+the indentation to the left of a cell text.  If you then double click on
+some cell, a link to that cell will be inserted where you started.  From
+a keyboard, use @{@kbd{C-c l}@} when in a koutline or @{@kbd{C-h h o
+l}@} when not in a koutline to insert a klink.  Since klinks are
+implicit buttons, you can type in the text of the klink just as you see
+it in the examples below and it will work exactly as if it had been
+entered with the insert link command.
+@cindex klink, formats
+@noindent
+There are basically three forms of klinks:
+@table @bullet
+@cindex internal klink
+@cindex klink, internal
+@cindex <@@ klink>
+@item internal
+<@@ 2b=06> is an internal klink, since it refers to the koutline in which
+it is embedded.  When activated, it jumps to the cell within the current
+outline which has permanent id `06' and relative id `2b'.  <@@ 06> does
+the same thing, as does <@@ 2b>, though this latter form will not
+maintain the link properly if the cell is moved elsewhere within the
+outline.  The form, <@@ 2b=06 |ben> additionally sets the view spec of
+the current outline back to the default value, with a blank line between
+each cell and all levels and lines of cells displayed.
+@cindex external klink
+@cindex klink, external
+@item external
+The second klink format is an external link to another koutline, such
+as, <EXAMPLE.kotl, 3=012 |c1e>, which displays the named file, starting
+at the cell 3 (whose permanent identifer is 012), with the view
+specification of: blank lines turned off, cutoff after one line per
+cell, and show ellipses for cells or trees which are clipped.
+@cindex klink, view spec
+@cindex view spec klink
+@item view spec
+The third format simply allows you to set a view spec for the current
+koutline.  For example, <|ben>, when activated, sets the view in the
+current outline to display blank lines, ellipses following collapsed
+lines and standard alphanumeric numbering.
+@end table
+@node Cell Attributes, Outliner History, Links, Outliner
+@section   Cell Attributes
+@cindex cell, attribute
+@cindex attribute
+@dfn{Attributes} are named variables whose values are specific to a
+particular outline cell.  Thus, each cell has its own attribute list.
+Every cell has three standard attributes:
+@table @bullet
+@cindex idstamp attribute
+@item idstamp
+The permanent id of the cell, typically used in cross-file hyperlinks
+that reference the cell.
+@cindex creator attribute
+@cindex e-mail address
+@cindex mail address
+@item creator
+The e-mail address of the person who created this cell.
+@cindex create-time attribute
+@cindex cell, creation time
+@item create-time
+The time at which the cell was created.  This is stored in a form that
+allows for easy data comparisons but is displayed in a human readable
+format, such as "Jan 28 18:27:59 CST 1994".
+@end table
+@kindex C-c C-i
+@cindex attribute, adding
+@cindex attribute, modifying
+@cindex attribute, removing
+@{@kbd{C-c C-i}@} is the command to add an attribute to or to modify an
+existing attribute in the cell at point.  Think of it as inserting an
+attribute value.  To remove an attribute from cell, set its value to
+@code{nil}.
+@cindex attribute, no-fill
+@cindex cell, no-fill attribute
+@cindex no-fill attribute
+@vindex kotl-mode:refill-flag
+The `no-fill' attribute is special.  When added with a non-nil value, it
+prevents moving, promoting, demoting, exchanging, splitting and
+appending cells from refilling the cell, even if the variable,
+@var{kotl-mode:refill-flag}, is set to t.  It does not prevent you from
+invoking explicit commands that refill the cell.  @xref{Filling}.
+@kindex Assist Key, listing attributes
+@cindex Assist Key, listing attributes
+@cindex listing attributes
+@cindex outline, attribute list
+The attribute lists for the cells in the tree rooted at point can be
+displayed by pressing the Assist Key within the contents of a cell.
+@kindex C-c h
+@kindex C-u C-c h
+@{@kbd{C-c h}@} prompts for a cell label and displays the cell's
+attributes.  @{@kbd{C-u C-c h}@} prompts for a cell label and displays
+the attributes for it and its subtree; use 0 as the kcell id to see
+attributes for all visible cells in the outline.
+@node Outliner History,  , Cell Attributes, Outliner
+@section   Outliner History
+@cindex NLS
+@cindex Augment
+@cindex Engelbart
+Much of the Hyperbole outliner design is based upon concepts pioneered
+in the NLS/Augment system, @cite{[Eng84a]}.  Augment treated documents as
+a hierarchical set of nodes, called statements, rather than cells.
+Every Augment document utilized this intrinsic structure.
+@cindex distributed collaboration
+@cindex collaboration
+The system could rapidly change the view of a document by collapsing,
+expanding, generating, clipping, filtering, including or reordering
+these nodes.  It could also map individual views to multiple workstation
+displays across a network to aid in distributed, collaborative work.
+@cindex knowledge transfer
+@cindex idea structuring
+@cindex cross referencing
+These facilities aided greatly in idea structuring, cross-referencing,
+and knowledge transfer.  The Koutliner is a start at bringing
+these capabilities back into the mainstream of modern computing culture.
+@node Rolodex, Window Configurations, Outliner, Top
+@chapter Rolodex
+@cindex rolodex
+@cindex wrolo
+Hyperbole includes a complete, advanced rolodex system, Wrolo, for
+convenient management of hierarchical, record-oriented information.
+@cindex rolo, buttons in
+Hyperbole buttons may be included within rolodex records and then
+manually activated whenever their records are retrieved.
+@vindex file, wrolo.el
+See the description at the top of the @file{wrolo.el} file for
+details on programmatic interfacing to the rolodex.  The following
+subsections explain use and basic customization of the rolodex.
+@menu
+* Rolo Concepts::
+* Rolo Menu::
+* Rolo Keys::
+* Rolo Settings::
+@end menu
+@node Rolo Concepts, Rolo Menu, Rolodex, Rolodex
+@section   Rolo Concepts
+@cindex rolodex file
+@cindex rolodex entry
+The rolodex manages and searches rolodex files.  A @dfn{rolodex file}
+consists of an optional header which starts and ends with a line of
+equal signs (at least three equal signs starting at the beginning of a
+line), followed by any non-negative number of rolodex records.  You must
+manually add a header to any rolodex file if you want it to have one.
+@noindent
+Here is an example of a simple rolodex file.
+@example
+@group
+==================================================================
+PERSONAL ROLODEX
+<Last-Name>, <First>  <Email>        W<Work#>       F<Fax#>
+==================================================================
+*   Smith, John       <js@@hiho.com> W708-555-2001  F708-321-1492
+Chief Ether Maintainer, HiHo Industries
+10/24/95
+@end group
+@end example
+We call rolodex records, @dfn{entries}.  Entries begin with a delimiter,
+some number of `*' characters at the beginning of a line.  Entries may
+be arranged in a hierarchy, where child entries begin with one more `*'
+characters than do their parents.  Top level entries begin with a single
+`*'.
+Beyond this initial delimiter, entries are completely free-form text.
+It is best to use a "lastname, firstname" format, however, when adding
+contact entries into a rolodex.  Then the rolodex system will
+automatically keep your entries alphabetized as you enter them.  You'll
+also be able to sort them whenever you desire.
+Any search done on the rolodex scans the full text of each entry.
+During a search, the rolodex file header separator lines and anything in
+between are appended to the buffer of matched entries before any entries
+are retrieved from the file.  Whenever an entry is matched, it and all
+of its descendant entries are retrieved.  If your Emacs version supports
+textual highlighting, each search match is highlighted for quick, visual
+location.
+@noindent
+For example, a search on "Company" could retrieve the following:
+@example
+@group
+==================================================================
+COMPANY ROLODEX
+==================================================================
+*    Company
+**     Manager
+***      Underlings
+@end group
+@end example
+@noindent
+Thus, searching for Company retrieves all listed employees.
+Searching for Manager turns up all Underlings.
+@node Rolo Menu, Rolo Keys, Rolo Concepts, Rolodex
+@section   Rolo Menu
+@cindex rolodex menu
+The Rolo/ menu entry on the Hyperbole top-level menu provides the
+user interface to the rolodex.  The rolo menu provides access to the
+following commands:
+@example
+@group
+@cindex rolodex commands
+@cindex Wrolo commands
+@findex rolo-add
+@findex rolo-display-matches
+@findex rolo-edit
+@findex rolo-kill
+@findex rolo-mail-to
+@findex rolo-sort
+@findex rolo-grep
+@findex rolo-fgrep
+@findex rolo-word
+@findex rolo-yank
+Menu Item       Command               Description
+====================================================================
+Add             rolo-add              Adds a rolodex entry
+Display         rolo-display-matches  Displays last matches again
+Edit            rolo-edit             Edits an existing rolodex entry
+Info                                  Displays Rolodex manual entry
+Kill            rolo-kill             Removes an entry from the rolodex
+Mail            rolo-mail             Mail to address following point
+Order           rolo-sort             Sorts all levels in rolodex
+RegexFind       rolo-grep             Finds all entries containing
+a regular expression
+StringFind      rolo-fgrep            Finds all entries containing
+a string
+WordFind        rolo-word             Finds all entries containing
+a string of whole words
+Yank            rolo-yank             Inserts first matching rolodex
+entry at point
+====================================================================
+@end group
+@end example
+A prefix argument used with either of the find commands listed above
+limits the search to a maximum number of matches given by the argument.
+The search is terminated whenever that number of matches is found.
+For any of the above commands that prompt for a name, you may use the
+form parent/child to locate a child entry below a parent entry.  So for
+a rolodex which looked like so:
+@example
+@group
+*    Company
+**     Manager
+***      Underlings
+@end group
+@end example
+@noindent
+You could edit the Underlings entry by identifying it as
+Company/Manager/Underlings.  Do not use this hierarchical notation in
+search expressions since the whole rolodex will be searched anyway.
+Thus, "Underlings" as a search pattern will find an entry containing
+"Underlings" at any level in a hierarchy, like so:
+@example
+***      Underlings
+@end example
+@node Rolo Keys, Rolo Settings, Rolo Menu, Rolodex
+@section   Rolo Keys
+@kindex e
+@cindex rolodex, editing an entry
+Use the @{@kbd{e}@} key to edit the entry at point within the rolodex
+source file.
+@cindex wrolo menu
+@cindex rolodex keys
+After a rolodex search is performed, point is left in the @dfn{rolodex
+match buffer}, @file{*Rolodex*}, which uses @code{wrolo-mode} to
+simplify browsing many rolodex matches.  Press @{@kbd{?}@} when in the
+match buffer for a summary of available keys.
+@kindex TAB
+@kindex M-TAB
+@kindex r
+@cindex rolodex, highlighting matches
+@cindex rolodex, finding matches
+@cindex rolodex, moving through matches
+If your Emacs version supports textual highlighting, each search match
+is highlighted for quick, visual location.  @{@key{TAB}@} moves point
+forward to successive spans of text which match the search expression.
+@{@kbd{M-@key{TAB}}@} or @{@kbd{r}@} moves point backward to earlier
+matches.  These keys allow you to quickly find the matching entry of
+most interest to you if your search expression failed to narrow the
+matches sufficiently.
+@kindex M-s
+@kindex C-r
+@cindex rolodex, extending a match
+@cindex rolodex, interactive searching
+If you want to extend the match expression with some more characters to
+find a particular entry, use @{@kbd{M-s}@}, which performs an
+interactive search forward for the match expression.  You can add or
+delete characters to this expression to find different occurences.
+@{@kbd{C-r}@} will reverse the direction of the search.
+@kindex a
+@kindex h
+@kindex s
+@kindex t
+@cindex rolodex, outlining
+Single key outlining commands are also available for browsing matches.
+If your search matches a large number of entries, use
+@{@kbd{t}@} to get a top-level overview of all the entries.  Each entry
+is collapsed so that only its first line shows.  Press @{@kbd{s}@} to
+show (expand) the entry at point.  Use @{@kbd{h}@} to hide (collapse)
+the entry again.  Press @{@kbd{a}@} to expand all entries in the buffer.
+Many other keys are defined to help you move through matching entries.
+@cindex rolodex, moving to entries
+@table @kbd
+@kindex b
+@item b
+Move to the previous entry at the same level as the current entry.
+@kindex f
+@item f
+Move to the next entry at the same level as the current entry.
+@kindex n
+@item n
+Move to the next entry at any level.
+@kindex p
+@item p
+Move to the previous entry at any level.
+@kindex u
+@item u
+Move the the previous entry one level up.
+@kindex .
+@kindex <
+@item .
+@itemx <
+Move to the beginning of the buffer.
+@kindex ,
+@kindex >
+@item ,
+@itemx >
+Move to the end of the buffer.
+@kindex @key{DEL}
+@item @key{DEL}
+Scroll backward a windowful.
+@kindex @key{SPC}
+@item @key{SPC}
+Scroll forward a windowful.
+@end table
+@kindex q
+@cindex rolodex, quitting
+Once you have found an entry of interest and you want to remove the
+rolodex match buffer, use @{@kbd{q}@} to quit.  This will restore your
+current frame to its state prior to the rolodex search.
+@node Rolo Settings,  , Rolo Keys, Rolodex
+@section   Rolo Settings
+@vindex rolo-highlight-face
+@cindex rolodex, highlighting matches
+If textual highlighting is available in your Emacs on your current
+display type, the rolodex uses the value of @var{rolo-highlight-face} as
+the face to use to highlight search matches.
+@vindex rolo-kill-buffers-after-use
+The buffers containing the rolodex files are not killed after a search
+on the assumption that another search is likely to follow within this
+Emacs session.  You may wish to change this behavior with the following
+setting: @code{(setq rolo-kill-buffers-after-use t)}.
+@vindex rolo-save-buffers-after-use
+After an entry is killed, the modified rolodex file is automatically
+saved.  If you would rather always save files yourself, use this
+setting: @code{(setq rolo-save-buffers-after-use nil)}.
+@vindex rolo-email-format
+When adding an entry from within a buffer containing a mail message, the
+rolodex add function will extract the sender's name and e-mail address
+and prompt you with the name as a default.  If you accept it, it will
+enter the name and the email address using the format given by the
+@var{rolo-email-format} variable.  See its documentation if you want to
+change its value.
+@vindex rolo-file-list
+@cindex rolodex, personal
+The files used in any rolodex search are given by the
+@var{rolo-file-list} variable, whose default value is
+@code{("~/.rolodex.otl")}, so that searches initially scan only your
+personal rolodex.  Any entries added to this list should be file
+pathnames.  If a file in the list does not exist or is not readable, it
+is skipped.  Files are searched in the order in which they appear in the
+list.  In general, you should leave your personal rolodex file as the
+first entry in the list, since this is the only file to which the rolo
+menu Add command adds entries.@refill
+@vindex rolo-entry-regexp
+The rolodex entry start delimiter is given by the regular expression
+variable, @var{rolo-entry-regexp}, whose default value is "^\*+".
+@vindex rolo-hdr-regexp
+A rolodex file may begin with an optional header section which is copied
+to the match display buffer whenever any matches are found during a
+search.  The start and end lines of this header are controlled by
+the regular expression variable, @var{rolo-hdr-regexp}, whose default
+value is "^===".  This allows lines of all equal signs to visually
+separate matching entries from multiple files retrieved from a single
+search.
+@node Window Configurations, Developing with Hyperbole, Rolodex, Top
+@chapter Window Configurations
+@cindex window configurations
+@cindex restoring windows
+@cindex saving window configurations
+@vindex file, wconfig.el
+Hyperbole includes the @file{wconfig.el} package which lets you save and
+restore window configurations, i.e@. the window layout and buffers
+displayed within an Emacs frame.  This is useful to save a particular
+working context and then to jump back to it at a later time during an
+Emacs session.  It is also useful during demonstrations to pull up many
+informational artifacts all at once, e.g@. all of the windows for a
+particular subsystem.  None of this information is stored between Emacs
+sessions, so your window configurations will last only through a single
+session of use.
+The wconfig library provides two distinct means of managing window
+configurations.  The first means associates a name with each stored
+window configuration.  The name can then be used to retrieve the window
+configuration later.  The second means uses a ring structure to save
+window configurations and then allows browsing through the sequence of
+saved configurations.
+The Win/ menu entry on the Hyperbole top-level menu displays a menu of
+window configuration commands:
+@noindent
+@display
+WinConfig>  AddName  DeleteName  RestoreName  PopRing  SaveRing  YankRing
+@end display
+@example
+@group
+@cindex wconfig commands
+@cindex window configuration commands
+@findex wconfig-add-by-name
+@findex wconfig-delete-by-name
+@findex wconfig-restore-by-name
+@findex wconfig-delete-pop
+@findex wconfig-ring-save
+@findex wconfig-yank-pop
+Menu Item       Command                   Description
+====================================================================
+AddName         wconfig-add-by-name       Name current wconfig
+DeleteName      wconfig-delete-by-name    Delete wconfig with name
+RestoreName     wconfig-restore-by-name   Restore wconfig by name
+PopRing         wconfig-delete-pop        Restore and delete wconfig
+SaveRing        wconfig-ring-save         Store wconfig to ring
+YankRing        wconfig-yank-pop          Restore next wconfig
+====================================================================
+@end group
+@end example
+Saving and restoring window configurations by name is the easiest
+method, but it requires that you input the chosen name from the
+keyboard.  The ring commands permit saving and restoring through mouse
+interaction only, if so desired.  The prior section, @ref{Smart Keys},
+mentions how to save and restore window configurations with the Smart Keys.
+Since the ring commands are a bit more complex than their by-name
+counterparts, the following paragraphs explain them in more detail.
+@vindex kill-ring
+Wconfig creates a ring structure that operates just like the Emacs
+@var{kill-ring}, @ref{Kill Ring,,,emacs, The GNU Emacs Manual}, but its
+elements are window configurations rather than text regions.  One can
+add an element to the ring based upon the current window configuration.
+After several elements are in the ring, one can walk through all of them
+in sequence until the desired configuration is restored.
+@findex wconfig-ring-save
+SaveRing executes the @code{wconfig-ring-save} command which
+saves the current window configuration to the ring.
+@findex wconfig-yank-pop
+YankRing executes the @code{wconfig-yank-pop} command.  It restores the
+window configuration from the currently pointed to configuration in the
+ring.  It does not delete this configuration from the ring but it does
+move the pointer to the prior ring element.  Repeated calls to this
+command thus restore successive window configurations until the ring
+pointer wraps around.  Simply stop when a desired configuration appears
+and use @{@kbd{q}@} to quit from the minibuffer menu.
+@findex wconfig-delete-pop
+PopRing calls the @code{wconfig-delete-pop} command.
+It is used to restore a previously saved configuration and at the same
+time delete it from the ring.  Simply stop when a desired configuration
+appears and use @{@kbd{q}@} to quit from the minibuffer menu.
+@vindex wconfig-ring-max
+The maximum number of elements the ring can hold is set by the
+@var{wconfig-ring-max} variable whose default is 10.  Any saves beyond
+this value cause deletion of the oldest element in the ring before
+a new one is added.
+@node Developing with Hyperbole, Glossary, Window Configurations, Top
+@chapter Developing with Hyperbole
+This chapter is only for people who are familiar with Emacs Lisp and
+wish to customize Hyperbole, to extend it, or to develop other systems
+using Hyperbole as a base.
+@menu
+* Hook Variables::
+* Creating Types::
+* Explicit Button Technicalities::
+* Encapsulating Systems::
+* Embedding Hyperbole::
+@end menu
+@node Hook Variables, Creating Types, Developing with Hyperbole, Developing with Hyperbole
+@section   Hook Variables
+@cindex variables
+@cindex hook variables
+Hyperbole provides a number of hook variables that allow you to adjust
+its basic operations to meet your own needs, without requiring you to
+change the code for those operations.
+We find it best to always set the value of hook variables either to nil
+or to a list of function names of no arguments, each of which will be
+called in sequence when the hook is triggered.
+Given the name of a function, a Hyperbole hook variable triggered within
+that function has the same name as the function with a @code{-hook}
+appended.  Hyperbole provides the following hook variables:
+@table @var
+@vindex hyperb:init-hook
+@item hyperb:init-hook
+For customization at Hyperbole initialization time.  Use this to load
+any personal Hyperbole type definitions you might have.  It is run after
+Hyperbole support code is loaded but before Hyperbole session
+initializations take place.
+@vindex action:act-hook
+@vindex hbut:current
+@item action:act-hook
+Run before each Hyperbole button activation.
+The variable @var{hbut:current} contains the button to be activated when
+this is run.
+@vindex ebut:create-hook
+@item ebut:create-hook
+To add to the Hyperbole explicit button creation process.
+@vindex ebut:delete-hook
+@item ebut:delete-hook
+To add to the Hyperbole explicit button deletion process.
+@vindex ebut:modify-hook
+@item ebut:modify-hook
+Executed when an explicit button's attributes are modified.
+@vindex hibtypes:begin-load-hook
+@item hibtypes:begin-load-hook
+Executed prior to loading of standard Hyperbole implicit button types.
+Used to load site-specific low priority implicit button types since
+lowest priority ibtypes are loaded first.
+@vindex hibtypes:end-load-hook
+@item hibtypes:end-load-hook
+Executed after loading of standard Hyperbole implicit button types.
+Used to load site-specific high priority implicit button types since
+highest priority ibtypes are loaded last.
+@vindex htype:create-hook
+@item htype:create-hook
+Executed when a Hyperbole type (e.g@. action type or implicit button
+type) is added to the environment.
+@vindex htype:delete-hook
+@item htype:delete-hook
+Executed when a type is deleted from the environment.
+@vindex kotl-mode-hook
+@item kotl-mode-hook
+Executed when a Koutline is created or read in or when kotl-mode is
+invoked.
+@vindex wrolo-display-hook
+@item wrolo-display-hook
+Executed when rolodex matches are displayed.
+@vindex wrolo-mode-hook
+@item wrolo-mode-hook
+Executed when a rolodex match buffer is created and put into wrolo-mode.
+@vindex wrolo-yank-reformat-function
+@cindex yank, reformatting
+@item wrolo-yank-reformat-function
+A variable whose value may be set to a function of two arguments, START
+and END, indicating the region of the rolodex entry yanked into the
+current buffer by the rolo-yank command.  The function may reformat this
+region to meed user-specific needs.
+@end table
+@noindent
+Hyperbole also makes use of a number of external Emacs hook variables.
+@table @var
+@vindex find-file-hooks
+@cindex button highlighting
+@item find-file-hooks
+This is called whenever a file is read into a GNU Emacs buffer.
+Hyperbole uses it to highlight any buttons within files when run under
+any NEXTSTEP or X window system-based versions of GNU Emacs.
+@vindex write-file-hooks
+@cindex button data saving
+@item write-file-hooks
+This is called whenever a GNU Emacs buffer is written to a file.
+Hyperbole uses it to save any modified button data associated with the
+file's directory.
+@cindex mail hooks
+@cindex news hooks
+Hyperbole mail and news facilities also utilize a number of external hook
+variables.  These hide button data and highlight buttons if possible.
+See the various support files for details.
+@end table
+@node Creating Types, Explicit Button Technicalities, Hook Variables, Developing with Hyperbole
+@section   Creating Types
+@cindex type definition
+@cindex type redefinition
+@noindent
+To define or redefine a single Hyperbole type, you may either:
+@itemize @bullet
+@kindex C-M-x
+@findex eval-defun
+@kindex C-x C-e
+@findex eval-last-sexp
+@item
+move your Emacs point to within the type definition and use
+@{@kbd{C-M-x}@} @code{(eval-defun)} (only works in Emacs Lisp mode);
+@item
+or move your point to the end of the last line of the type definition and
+use @{@kbd{C-x C-e}@} @code{(eval-last-sexp)} (works in most modes).
+@end itemize
+@cindex Hyperbole types
+@vindex class, htype
+The functions from the @code{htype} class may be applied to any
+Hyperbole types, if needed.
+@vindex file, hactypes.el
+@vindex file, hibtypes.el
+The following subsections explain the specifics of Hyperbole type
+definitions which are beyond standard practice for Emacs Lisp programming.
+See the definitions of the standard types in @file{hactypes.el}
+and @file{hibtypes.el} for examples.
+@menu
+* Action Type Creation::
+* Implicit Button Types::
+@end menu
+@node Action Type Creation, Implicit Button Types, Creating Types, Creating Types
+@subsection  Action Type Creation
+@findex actype:create
+@vindex file, hactypes.el
+@vindex file, hbut.el
+New forms of explicit buttons may be created by adding new action types
+to a Hyperbole environment.  The file, @file{hactypes.el}, provides
+many examples of working action types.
+@cindex action type, creation
+@findex defact
+@findex actype:create
+An action type is created, i.e@. loaded into the Hyperbole environment,
+with the @code{(defact)} function (which is an alias for
+@code{(actype:create)}).  The calling signature for this function is
+given in its documentation; it is the same as that of @code{(defun)}
+except that a documentation string is required.  (An interactive calling
+form is also required if the action type has formal parameters and is to
+be used in explicit button definitions.  Implicit buttons never use an
+action type's interactive form.  It is good practice to include an
+interactive form since the type creator cannot know how users may choose
+to apply the type.)@refill
+An action type's parameters are used differently than those of a
+function being called.  Its interactive calling form is used when an
+explicit button is created to prompt for type-specific button
+attributes.  The rest of its body is used when a button with that action
+type is activated.  Then the button attributes together with the action
+type body are used to form an action that is executed in response to the
+button activation.  The action's result is returned to the action caller
+unless it returns nil, in which case t is returned to the caller to
+ensure that it registers the performance of the action.
+An action type body may perform any computation using Emacs Lisp and
+Hyperbole functions.
+@cindex interactive form
+@findex interactive
+The interactive calling form for an action type is of the same form as
+that of a regular Emacs Lisp function definition (see the documentation
+for the Emacs Lisp @code{(interactive)} form).  It may additionally use
+Hyperbole command character extensions when the form is given as a
+string.  Each such extension character @emph{must} be preceded by a plus
+sign, @code{+}, in order to be recognized since such characters may also
+have standard interactive form meanings.
+The present Hyperbole extension characters are:
+@table @strong
+@cindex argument, Info node
+@cindex interactive cmd char, +I
+@item +I
+Prompts for an existing Info node name and file.
+@cindex argument, kcell
+@cindex argument, koutline
+@cindex interactive cmd char, +K
+@item +K
+Prompts for an existing kcell identifier, either a full outline level
+identifier or a permanent idstamp.
+@cindex interactive cmd char, +M
+@cindex argument, mail message
+@item +M
+Prompts for a mail message date and the file name it resides in.
+The mail parameters prompted for by this character code are likely to
+change in the future.
+@cindex argument, view spec
+@cindex interactive cmd char, +V
+@item +V
+Prompts for a Hyperbole view specification.
+Not yet available for use.
+@end table
+@vindex class, hargs
+@cindex argument, reading
+Arguments are read by the functions in Hyperbole's @code{hargs} class,
+rather than the standard Lisp @code{read} functions, in order to allow
+direct selection of arguments via the Action Key.
+If an action type create is successful, the symbol that Hyperbole uses
+internally to reference the type is returned.  @code{Nil} is returned on
+failure so that you may test whether or not the operation succeeds.
+Once you have defined an action type within your present Hyperbole
+environment, you can create new explicit buttons which use it.  There is
+no explicit button type beyond its action type, so no further work is
+necessary.
+@findex actype:delete
+Call @code{(actype:delete)} to remove an action type from a Hyperbole
+environment.  It takes a single parameter which should be the same type
+symbol used in the type definition call (not the Hyperbole symbol
+returned by the call).
+@node Implicit Button Types,  , Action Type Creation, Creating Types
+@subsection  Implicit Button Types
+@cindex implicit button type
+@cindex ibtype
+@findex defib
+@findex ibtype:create
+An implicit button type is created or loaded via the @code{(defib)}
+function (which is an alias for @code{(ibtype:create)}).  The calling
+signature for this function is given in its documentation; it is the
+same as that of @code{(defun)}, but with a number of constraints.  The
+parameter list should always be empty since no parameters will be used.
+A documentation string is required.  The type's body follows this.
+@cindex ibtype, predicate
+@cindex ibtype, argument
+@cindex ibtype, return val
+@cindex ibtype, actype
+The body of an implicit button type is a predicate which determines
+whether or not point is within an implicit button of the type.  If not,
+the predicate returns @code{nil}.  If so, it may optionally setup to
+flash the button and then perform one or more actions.  A call of the
+form: @code{(ibut:label-set label start-pos end-pos)} is used to setup
+the button flashing, if desired.  This is then typically immediately
+followed by an action invocation of the form:
+@code{(hact 'actype &rest actype-arguments)}.  It is imperative that all
+actions (non-predicate code) be invoked through the @code{(hact)}
+function rather than directly or your ibtypes will not work properly.
+(Hyperbole first tests to see if any ibtype matches the current context
+before activating any type, so it ensures that @code{(hact)} calls are
+disabled during this testing.)  Any action types used may be created
+before or after the implicit button type definition but obviously should
+be defined before any implicit buttons of the given type are activated;
+an error will result, otherwise.
+If an implicit button type create is successful, the symbol that
+Hyperbole uses internally to reference the type is returned.  @code{Nil}
+is returned on failure so that you may test whether or not the operation
+succeeds.  Implicit button type names and action type names may be the
+same without any conflict.  In fact, such naming is encouraged when an
+implicit button type is the exclusive user of an action type.
+@findex ibtype:delete
+Call @code{(ibtype:delete)} to remove an implicit button type from a
+Hyperbole environment.  It takes a single parameter which should be the
+same type symbol used in the type definition call (not the Hyperbole
+symbol returned by the call).  This will not delete the action type used
+by the implicit button; that must be done separately.
+@cindex ibtype, help
+@findex ibut:at-p
+@vindex class, hattr
+@vindex class, hbut
+@vindex file, hib-kbd.el
+By default, a request for help on an implicit button will display the
+button's attributes in the same manner as is done for explicit buttons.
+For some implicit button types, other forms of help will be more
+appropriate.  If an Emacs Lisp function is defined whose name is formed
+from the concatenation of the type name followed by @code{:help}, e.g@.
+@code{my-ibtype:help}, it is used to respond to requests for
+help on buttons of that type.  Any such function should take a single
+argument of an implicit button construct.  (This is what
+@code{(ibut:at-p)} returns when point is within an implicit button
+context.)  The button may be queried for its attributes using functions
+from the @code{hbut} and @code{hattr} classes.  See the @file{hib-kbd.el}
+file for an example of a custom help function.
+@node Explicit Button Technicalities, Encapsulating Systems, Creating Types, Developing with Hyperbole
+@section   Explicit Button Technicalities
+@menu
+* Button Label Normalization::
+* Operational and Storage Formats::
+* Programmatic Button Creation::
+@end menu
+@node Button Label Normalization, Operational and Storage Formats, Explicit Button Technicalities, Explicit Button Technicalities
+@subsection  Button Label Normalization
+@cindex normalized label
+@cindex button label
+@cindex button key
+@vindex hbut:label-to-key
+Hyperbole uses a normalized form of button labels called button keys (or
+label keys) for all internal operations.  See the documentation for the
+function @code{(hbut:label-to-key)} for details of the normalization
+process.  The normalized form permits Hyperbole to recognize buttons that
+are the same but whose labels appear different from one another, due to
+text formatting conventions.  For example, all of the following would
+be recognized as the same button.
+@example
+<(fake button)>     <( fake      button)>
+Pam>  <(fake
+Pam>    button)>
+;; <(fake
+;;   button)>
+/* <( fake      */
+/*    button )> */
+@end example
+@vindex hbut:fill-prefix-regexps
+@vindex fill-prefix
+@cindex fill prefix
+@cindex button, multiple lines
+@cindex button, split across lines
+The last three examples demonstrate how Hyperbole ignores common fill
+prefix patterns that happen to fall within the middle of a button label
+that spans multiple lines.  As long as such buttons are selected with
+point at a location within the label's first line, the button will be
+recognized.  The variable @var{hbut:fill-prefix-regexps} holds the list
+of fill prefixes recognized when embedded within button labels.  All
+such prefixes are recognized (one per button label), regardless of the
+setting of the GNU Emacs variable, @var{fill-prefix}, so no user
+intervention is required.
+@node Operational and Storage Formats, Programmatic Button Creation, Button Label Normalization, Explicit Button Technicalities
+@subsection  Operational and Storage Formats
+@cindex explicit button, formats
+@cindex explicit button, storage
+@cindex storage manager
+@cindex button attributes
+@vindex hbut:current
+Hyperbole uses a terse format to store explicit buttons and a more
+meaningful one to show users and to manipulate during editing.  The
+terse format consists solely of button attribute values whereas the edit
+format includes an attribute name with each attribute value.  A button
+in edit format consists of a Lisp symbol together with its attribute list
+which holds the attribute names and values.  In this way, buttons may be
+passed along from function to function simply by passing the symbol to
+which the button is attached.  Most functions utilize the pre-defined
+@var{hbut:current} symbol by default to store and retrieve the last
+encountered button in edit format.
+@vindex class, hbdata
+@vindex class, ebut
+@vindex class, hbut
+The @code{hbdata} class handles the terse, stored format.  The
+@code{hbut}, @code{ebut}, and @code{ibut} classes work with the
+name/value format.  This separation permits the wholesale replacement of
+the storage manager with another, with any interface changes hidden from
+any Hyperbole client programming.
+@node Programmatic Button Creation,  , Operational and Storage Formats, Explicit Button Technicalities
+@subsection  Programmatic Button Creation
+@cindex explicit button, creation
+A common need when developing with Hyperbole is the ability to create or
+modify explicit buttons without user interaction.  For example, an
+application might require the addition of an explicit summary button to
+a file for each new mail message a user reads that contains a set of
+keywords.  The user could then check the summary file and jump to
+desired messages quickly.
+@vindex class, ebut
+@vindex file, hbut.el
+@findex ebut:create
+@findex ebut:map
+The Hyperbole class @code{ebut} supports programmatic access to explicit
+buttons.  See it within the @file{hbut.el} file for full details.  The
+documentation for @code{(ebut:create)} explains the set of attributes
+settings necessary to create an explicit button.  For operations over
+the whole set of buttons within the visible (non-narrowed) portion of a
+buffer, use the @code{(ebut:map)} function.
+@page
+@node Encapsulating Systems, Embedding Hyperbole, Explicit Button Technicalities, Developing with Hyperbole
+@section   Encapsulating Systems
+@vindex file, hsys-*
+@cindex Hyperbole, system encapsulation
+@cindex system encapsulation
+A powerful use of implicit button types is to provide a Hyperbole-based
+interface to external systems.  The basic idea is to interpret patterns
+output by the application as implicit buttons.
+See the @file{hsys-*} files for examples of how to do this.
+Encapsulations are provided for the following systems (the systems
+themselves are not included with Hyperbole):
+@table @bullet
+@item World-Wide Web
+The world-wide web system originally developed at CERN, that now spans
+the Internet universe.  This is automatically loaded by Hyperbole so
+that a press of the Action Key follows a URL.
+@item WAIS
+The Wide Area Information Systems full text-retrieval system orginally
+developed at Thinking Machines and then later at WAIS Inc.
+@item HyperBase
+A hypertextual storage manager that stores textual nodes as records with
+locking so that multiple users can read and edit hypertexts.
+@end table
+@node Embedding Hyperbole,  , Encapsulating Systems, Developing with Hyperbole
+@section   Embedding Hyperbole
+[NOTE: We have never done this ourselves, though we have done similar
+things which leads us to infer that the task should not be difficult.]
+@cindex Hyperbole API
+@cindex API
+@cindex programming interface
+@cindex Hyperbole, embedding
+The standard Emacs-based Hyperbole user interface has purposely been
+separated from the Hyperbole backend to support the development of
+alternative interfaces and the embedding of Hyperbole functionality
+within other system prototypes.  The Hyperbole backend functionality
+that system developers can make use of is called its Application
+Programming Interface (API).  The API may be used to make server-based
+calls to Hyperbole when Emacs is run as a non-interactive (batch)
+process, with its input/output streams attached to another process.
+The public functions and variables from the following files may be
+considered the present Hyperbole API:
+@noindent
+@file{hact.el}, @file{hargs.el}, @file{hbmap.el}, @file{hbut.el},
+@file{hhist.el}, @file{hmail.el}, @file{hmoccur.el}, @file{hpath.el},
+@file{htz.el}, @file{hypb.el}, @file{set.el}, @file{wconfig.el},
+@file{wrolo.el}, and @file{wrolo-logic.el}.@refill
+@noindent
+Note when looking at these files, that they are divided into sections
+that separate one data abstraction (class) from another.  A line of
+dashes within a class separates public parts of the class from the
+private parts that follow the line.
+This API does not include the Hyperbole outliner, as it has been
+designed for interactive use, rather than programmatic extensibility.
+You can certainly study its code, below the @file{hyperbole/kotl/}
+directory and learn to program it, however.
+@node Glossary, Smart Key Reference, Developing with Hyperbole, Top
+@appendix Glossary
+Concepts pertinent to operational usage of Hyperbole are defined here.
+If some GNU Emacs terms are unfamiliar to you, @ref{Glossary, Emacs
+Glossary,, emacs, the GNU Emacs Manual}.
+@table @code
+@cindex action
+@item action
+An executable behavior associated with a Hyperbole button.  A specific
+class of actions which display entities are called @emph{links},
+such as a link to a file.
+@cindex Action Key
+@item Action Key
+See @emph{Smart Key}.
+@cindex action type
+@item action type
+A behavioral specification for use within Hyperbole buttons.  Action
+types usually contain a set of parameters which must be given values for
+each button with which they are associated.  An action type together
+with a set of values, called arguments, may be considered an @emph{action}.
+@emph{Actype} is a synonym for action type.
+@cindex activation
+@item activation
+Request for a Hyperbole button to perform its action.
+Ordinarily the user presses a key which selects and activates a button.
+@cindex ange-ftp
+@cindex ftp
+@item ange-ftp
+A standard GNU Emacs Lisp package which allows one to use pathnames
+that are accessible via the Internet File Transfer Protocol (ftp) just
+like other pathnames, for example when finding a file.  The
+latest version of ange-ftp may always be obtained via anonymous ftp to:
+@file{/ftp.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.gz}.
+@cindex argument
+@item argument
+A button-specific value fed to a Hyperbole type specification when the
+button is activated.
+@cindex Assist Key
+@item Assist Key
+See @emph{Smart Key}.
+@cindex attributes
+@item attributes
+Slot names associated with Hyperbole buttons.  An @emph{attribute value}
+is associated with each button attribute.
+@cindex Augment
+@cindex NLS
+@cindex hypertext
+@cindex interactive computing
+@cindex mouse
+@cindex windows
+@cindex hypertext
+@cindex outline processor
+@cindex groupware
+@cindex digital signature
+@cindex Engelbart
+@item Augment
+The Augment system, originally named NLS, was a pioneering research and
+production system aimed at augmenting human intellect and group
+knowledge processing capabilities through integrated tools and
+organizational development strategies.  This approach led to the
+invention of much of interactive computing technology decades ahead of
+other efforts, including: the mouse, screen windows, true hypertext,
+outline processors, groupware, and digitally signed documents.
+@xref{References}, which cites several Douglas Engelbart papers on the
+subject.  The Koutliner concept emerged from studies of publicly
+available information concerning Augment.
+@cindex button
+@item button
+A selectable Hyperbole construct which performs an action.  A button
+consists of a set of attributes that includes: a textual label, a
+category, a type and zero or more arguments.  @emph{Explicit buttons}
+also have creator, create time, last modifier, and last modifier time
+attributes.
+Buttons provide the user's gateway to information.  The user sees and
+interacts with button labels, the rest of the button data is managed
+invisibly by Hyperbole and displayed only in response to user queries.
+@cindex button activation
+@item button activation
+See @emph{activation}.
+@cindex button attributes
+@item button attributes
+See @emph{attributes}.
+@cindex button data
+@item button data
+Lists of button attribute values explicitly saved and managed by Hyperbole.
+One list for each button created by Hyperbole.
+@cindex button file, local
+@item button file, local
+A per-directory file named @file{HYPB} that may be used to store any
+desired buttons and may then be displayed via a menu selection whenever
+a user is within that directory.
+@cindex button file, personal
+@item button file, personal
+A per-user file named @file{HYPB} that may be used to store any desired
+buttons and may then be displayed via a menu selection.
+@cindex button key
+@item button key
+A normalized form of a @emph{button label} used internally by Hyperbole.
+@cindex button label
+@item button label
+A text string that visually indicates a Hyperbole button location and
+provides it with a name and unique identifier.  Within a buffer, buttons
+with the same label are considered separate views of the same button and
+so behave exactly alike.  Since button labels are simply text strings,
+they may be embedded within any text to provide non-linear information
+or operational access points.
+The maximum length of a button label is limited by the variable
+@var{ebut:max-len}.
+@cindex button selection
+@item button selection
+The act of designating a Hyperbole button upon which to operate.
+Use the Action Key to select a button.
+@cindex category
+@item category
+A high-level, conceptual grouping of Hyperbole buttons into classes.
+@emph{Implicit} and @emph{explicit} groupings represent categories.
+@cindex cell
+@item cell
+See @emph{kcell}.
+@cindex children
+@item children
+The set of koutline cells which share a common parent cell and are one
+level deeper than the parent.
+@cindex class
+@item class
+A group of functions and variables with the same prefix in their names,
+used to provide an interface to an internal or external Hyperbole
+abstraction.
+@cindex context
+@item context
+A programmatic or positional state recognized by Hyperbole.
+We speak of Smart Key and implicit button contexts.  Both are typically
+defined in terms of surrounding patterns within a buffer, but may be
+defined by arbitrary Emacs Lisp predicates.  (Context may come to have a
+broader meaning within future versions of Hyperbole.)
+@cindex environment
+@item environment
+See @emph{Hyperbole environment}.
+@cindex efs
+@item efs
+The much larger successor to ange-ftp.  It does the same thing as
+ange-ftp but works with more types of ftp hosts.  See @emph{ange-ftp}.
+@cindex explicit button
+@item explicit button
+A button created and managed by Hyperbole.  By default, explicit buttons
+are delimited like this @code{<(fake button)>}.  Direct selection is
+used to operate upon an explicit button.
+@cindex global button
+@item global button
+@vindex gbut:file
+A form of explicit button which is typically accessed by name rather
+than direct selection.  Global buttons are useful when one wants
+quick access to actions such as jumping to common file locations or for
+performing sequences of operations.  One need not locate them since they
+are always available by name, with full completion offered.  All global
+buttons are stored in the file given by the variable @var{gbut:file} and
+may be activated as regular explicit buttons by visiting this file.  By
+default, this is the same as the user's personal button file.
+@cindex global button file
+@item global button file
+See @emph{button file, personal}.
+@findex run-hooks
+@cindex hook variable
+@item hook variable
+A variable that permits customization of an existing function's
+operation without the need to edit the function's code.  See also the
+documentation for the function @code{(run-hooks)}.
+@cindex Hyperbole
+@item Hyperbole
+A flexible, programmable information management and viewing system built
+on top of GNU Emacs.  It utilizes a button-action model and supports
+hypertextual linkages.  Hyperbole is all things to all people.
+@cindex Hyperbole environment
+@item Hyperbole environment
+A programmatic context within which Hyperbole operates.  This includes
+the set of Hyperbole types defined and the set of Hyperbole code modules
+loaded.  It does not include the set of accessible buttons.
+Although the entire Emacs environment is available to Hyperbole, we do
+not speak of this as part of the Hyperbole environment.
+@cindex hypertext
+@item hypertext
+A text or group of texts which may be explored in a non-linear fashion
+through associative linkages embedded throughout the text.  Instead of
+simply referring to other pieces of work, hypertext references when
+followed actually take you to the works themselves.
+@cindex implicit button
+@item implicit button
+A button recognized contextually by Hyperbole.  Such buttons contain no
+button data.  See also @emph{implicit button type}.
+@cindex implicit button type
+@item implicit button type
+A specification of how to recognize and activate implicit buttons of a
+specific kind.  Implicit button types often utilize structure internal
+to documents created and managed without Hyperbole assistance, for
+example, programming documentation.  @emph{Ibtype} is a synonym for
+implicit button type.  See also @emph{system encapsulation}.
+@cindex instance number
+@item instance number
+A colon prefaced number appended to the label of a newly created button
+when the button's label duplicates the label of an existing button in
+the current buffer.  This number makes the label unique and so allows
+any number of buttons with the same base label within a single buffer.
+@cindex koutline
+@item koutline
+A hierarchically ordered grouping of cells which may be stored as a file
+and viewed and edited as an outline.
+@cindex Koutliner
+@item Koutliner
+Koutliner, the Hyperbole outliner, is a powerful autonumbering outliner
+with permanent hypertext anchors for easy hyperlinking and view
+specs for rapid outline view alteration.
+@cindex kcell
+@item kcell
+Cells or kcells are elements within koutlines.  Each cell contains
+textual and graphical contents, a relative identifier, a permanent
+identifier and a set of attributes such as the user who created the cell
+and the time of creation.  See also @emph{Koutliner}.
+@cindex link
+@item link
+A reference from a Hyperbole button to an entity.  The referenced entity
+is sometimes called a @emph{node} or @emph{referent}.
+A specific class of actions which display entities are called
+@emph{links}, such as a link to a file.
+@cindex local button file
+@item local button file
+See @emph{button file, local}.
+@cindex minibuffer window
+@item minibuffer window
+The one line window at the bottom of a frame where messages and prompts
+are displayed.
+@cindex minibuffer menu
+@item minibuffer menu
+A Hyperbole menu displayed in the minibuffer window.  Each menu item
+within a minibuffer menu begins with a different letter that can be used
+to invoke the item (case doesn't matter).  Items that display other
+menus end with a forward slash, /.
+@cindex mouse button
+@item mouse button
+@item mouse key
+See @emph{Smart Key}.
+@cindex node
+@item node
+See @emph{link} or @emph{cell}.
+@cindex outline
+@item outline
+See @emph{koutline}.
+@cindex parent
+@item parent
+Any koutline cell which has children.
+@cindex predecessor
+@item predecessor
+The previous same level koutline cell with the same parent.
+@cindex predicate
+@item predicate
+A boolean (nil = false, non-nil = true) Lisp expression typically
+evaluated as part of a conditional expression.
+@cindex referent
+@item referent
+See @emph{link}.
+@cindex rolodex
+@item rolodex
+Wrolo, the Hyperbole rolodex, provides rapid lookup of multi-line,
+hierarchically ordered free form text records.
+@cindex root cell
+@item root cell
+A koutline cell which has cells below it.  All such cells share the same
+root cell.
+@cindex Smart Key
+@vindex smart-scroll-proportional
+@cindex proportional scrolling
+@cindex scrolling
+@item Smart Key
+A context-sensitive key used within Hyperbole and beyond.  Actually,
+there are two Smart Keys, the Action Key and the Assist Key.  The
+Action Key, typically bound to the shift-middle mouse key (or shift-left
+mouse key on a 2-button mouse), activates Hyperbole buttons and scrolls
+the current buffer line to the top of the window when pressed at the end
+of a line.  The Assist Key, typically bound to the shift-right mouse
+key, explains what a Hyperbole button does or scrolls the current line
+to the bottom of the window when pressed at the end of a line.  (See the
+documentation for the variable, @var{smart-scroll-proportional}, for
+information on how to make these keys scroll forward and backward a
+windowful at a time).
+To see what a Smart Key will do within a particular context, depress and
+hold the key at the point desired and depress the other Smart Key.  A
+buffer containing a description of its contextual function will then be
+displayed.  You may release the two keys in any order after you have
+them both depressed.  A press of the Assist Key in an unsupported
+context displays a summary of Smart Key functions in each context, as
+does the Doc/SmartKy menu item.
+@cindex source buffer
+@cindex source file
+@item source buffer / file
+The buffer or file within which a Hyperbole button is embedded.
+@cindex subtree
+@item subtree
+All of the cells in a koutline which share the same root cell, excluding
+the root cell.
+@cindex successor
+@item successor
+The next same level koutline cell with the same parent.
+@cindex system encapsulation
+@item system encapsulation
+Use of Hyperbole to provide an improved or simply consistent user
+interface to another system.  Typically, implicit button types are
+defined to recognize and activate button-type constructs managed by the
+other system.
+@cindex tree
+@item tree
+The set of cells in a koutline that share a common root cell, including
+the root cell.
+@cindex view
+@item view
+A perspective on some information.  A view can affect the extent of the
+information displayed, its format, modes used to operate on it, its
+display location and so forth.
+@cindex view spec
+@item view spec
+A terse (and to the uninitiated, cryptic) string that specifies a
+particular view of koutline or a link referent.  If a view spec is in
+use in a buffer, the view spec appears in the modeline delimited by
+<|view spec>.
+@end table
+@node Smart Key Reference, Outliner Keys, Glossary, Top
+@appendix Smart Key Reference
+This appendix supplies complete documentation on Smart Key operation.  It is
+quite extensive and is meant for reference rather than sequential reading.
+@xref{Smart Keys}, for a description of the Smart Keys.  That section also
+describes how to get context-sensitive Smart Key help, with which you can
+explore Smart Key operation bit by bit.
+Smart Key operations are context-sensitive.  Contexts are described herein as
+conditionals, e.g@. when depressed here, if this is true, etc.  Each Smart
+Key context is listed in the order in which it will be checked.  The first
+matching context is always the one applied.  Within each context, the
+actions performed by the Action and Assist Keys are listed.
+@menu
+* Smart Mouse Keys::
+* Smart Keyboard Keys::
+@end menu
+@node Smart Mouse Keys, Smart Keyboard Keys, Smart Key Reference, Smart Key Reference
+@section   Smart Mouse Keys
+@cindex Smart Mouse Keys
+Smart Key drags and modeline presses can only be used when running under
+a window system with mouse key support.  So keep in mind that the
+operations in this section apply only if you have mouse support within
+Hyperbole.  The Smart Key operations in, @ref{Smart Keyboard Keys},
+apply to both mouse and keyboard Smart Key usage.
+@format
+@group
+@cindex drag, side edge
+@cindex side drag
+If dragged from a side-by-side window edge or from the immediate left of
+a vertical scroll bar:
+ACTION or ASSIST
+Resizes adjacent window sides to the point of drag release.
+@end group
+@end format
+@format
+@group
+@cindex drag, between windows
+If dragged from inside one window to another:
+ACTION
+Creates a new link button at the drag start location, linked to the
+drag end location.  If drag start position is within a button,
+modifies the button to link to drag end location.
+ASSIST
+Swaps buffers in the two windows.
+@end group
+@end format
+@page
+@format
+@group
+@cindex drag, horizontal
+@cindex horizontal drag
+If dragged horizontally within a single window while depressed
+(hmouse-x-drag-sensitivity sets the minimal horizontal movement which
+registers a drag):
+ACTION
+Goes to buffer end if drag was to the right, otherwise goes to beginning.
+ASSIST
+Splits window vertically if drag was to the right, otherwise deletes
+window.
+@end group
+@end format
+@format
+@group
+@cindex depress, modeline
+@cindex modeline depress
+If depressed within a window mode line:
+ACTION
+(1) clicked on left edge of a window's modeline,
+window's buffer is buried (placed at bottom of buffer list);
+(2) clicked on right edge of a window's modeline,
+the Info buffer is displayed, or if already displayed and the
+modeline clicked belongs to a window displaying Info, the Info
+buffer is hidden;
+(3) clicked anywhere in the middle of a window's modeline,
+	 the functions listed in 'assist-key-modeline-hook' are
+called;
+(4) dragged vertically from modeline to within a window,
+the modeline is moved to point of key release, thereby resizing
+its window and potentially its vertical neighbors.
+ASSIST
+(1) clicked on left edge of a window's modeline,
+bottom buffer in buffer list is unburied and placed in window;
+(2) clicked on right edge of a window's modeline,
+the summary of Smart Key behavior is displayed, or if already
+displayed and the modeline clicked belongs to a window displaying
+the summary, the summary buffer is hidden;
+(3) clicked anywhere in the middle of a window's modeline,
+a popup menu (if available) is displayed;
+(4) dragged vertically from modeline to within a window,
+the modeline is moved to point of key release, thereby resizing
+its window and potentially its vertical neighbors.
+@end group
+@end format
+@page
+@format
+@group
+@cindex drag, vertical
+@cindex vertical drag
+If dragged vertically within a single window while depressed
+(hmouse-y-drag-sensitivity sets the minimal vertical movement which
+registers a drag):
+ACTION or ASSIST
+Splits current window into two side-by-side windows.
+@end group
+@end format
+@format
+@group
+@cindex drag, diagonal
+@cindex diagonal drag
+If dragged diagonally within a single window while depressed
+(hmouse-x-diagonal-sensitivity and hmouse-y-diagonal-sensitivity set the
+minimal diagonal movement which registers a drag):
+ACTION
+Save current window configuration onto a ring of window configurations.
+ASSIST
+Restores prior window configuration from ring.  A prefix argument N
+specifies the Nth prior configuration from the ring.
+@end group
+@end format
+@page
+@node Smart Keyboard Keys,  , Smart Mouse Keys, Smart Key Reference
+@section   Smart Keyboard Keys
+@cindex Smart Keyboard Keys
+@format
+@group
+When prompting for a Hyperbole argument, a press in the minibuffer:
+ACTION
+Terminates this minibuffer argument.
+ASSIST
+Offers completion help for current minibuffer argument.
+@end group
+@end format
+@format
+@group
+When reading a Hyperbole menu item or a Hyperbole completion-based argument:
+ACTION
+Returns value selected at point if any, else nil.  If
+value is the same as the contents of the minibuffer, it is used as the
+current minibuffer argument, otherwise, the minibuffer is erased and
+value is inserted there.
+ASSIST
+Displays Hyperbole menu item help when item is selected.
+@end group
+@end format
+@vindex smart-scroll-proportional
+@cindex proportional scrolling
+@cindex scrolling
+@format
+@group
+@cindex click, end of line
+@cindex end of line click
+When pressed at the end of a line but not the end of a buffer:
+ACTION
+Scrolls up according to value of smart-scroll-proportional.  If
+smart-scroll-proportional is nil or if point is on the top
+window line, scrolls up (forward) a windowful.  Otherwise, tries to
+bring current line to top of window.  Leaves point at end of line and
+returns t if scrolled, nil if not.
+ASSIST
+Scrolls down according to value of smart-scroll-proportional.  If
+smart-scroll-proportional is nil or if point is on the
+bottom window line, scrolls down (backward) a windowful.  Otherwise,
+tries to bring current line to bottom of window.  Leaves point at end of
+line and returns t if scrolled, nil if not.
+@end group
+@end format
+@format
+@group
+@cindex click, button
+@cindex button click
+When pressed on a Hyperbole button:
+ACTION
+Activates button.
+ASSIST
+Displays help for button, typically a summary of its attributes.
+@end group
+@end format
+@format
+@group
+If pressed within a buffer in View major or minor mode:
+ACTION
+Scrolls buffer forward a windowful and quits from view mode when at
+the last line of the buffer.
+ASSIST
+Scrolls buffer backward a windowful.
+@end group
+@end format
+@format
+@group
+When pressed within a Hyperbole outliner buffer (kotl-mode):
+ACTION
+(1) at the end of buffer, uncollapse and unhide all cells in view;
+(2) within a cell, if its subtree is hidden then show it,
+otherwise hide it;
+(3) between cells or within the read-only indentation region to the
+left of a cell, then move point to prior location and begin
+	 creation of a klink to some other outline cell; hit the Action
+	 Key twice to select the link referent cell;
+(4) anywhere else, scroll up a windowful.
+ASSIST
+(1) at the end of buffer, collapse all cells and hide all non-level-one
+cells;
+(2) on a header line but not at the beginning or end, display
+properties of each cell in kotl beginning at point;
+(3) between cells or within the read-only indentation region to the
+left of a cell, then move point to prior location and prompt to
+move one tree to a new location in the outline; hit the Action
+Key twice to select the tree to move and where to move it;
+(4) anywhere else, scroll down a windowful.
+@end group
+@end format
+@format
+@group
+When pressed on a Smart Menu item:
+ACTION
+Activates item.
+ASSIST
+Displays help for item.
+@end group
+@end format
+@page
+@format
+@group
+When pressed at the end of a Help buffer:
+ACTION or ASSIST
+Restores window configuration prior to help display.
+@end group
+@end format
+@format
+@group
+When pressed within an OO-Browser listing window:
+ACTION
+(1) in a blank buffer or at the end of a buffer, browser help
+information is displayed in the viewer window;
+(2) at the beginning of a (non-single char) class name, the class'
+ancestors are listed;
+(3) at the end of an entry line, scrolls listing up;
+(4) on the '...', following a class name, point is moved to the class
+descendency expansion;
+(5) before an element name, the implementor classes of the name are
+listed;
+(6) anywhere else on an entry line, the source is displayed for editing.
+ASSIST
+(1) in a blank buffer, a selection list of buffer files is displayed;
+(2) at the beginning of a (non-single char) entry, the class'
+descendants are listed;
+(3) at the end of an entry line, scrolls listing down;
+(4) on the '...', following a class name, point is moved to the class
+expansion;
+(5) anywhere else on a class entry line, lists the class' elements;
+(6) anywhere else on an element line, lists the element's implementor
+classes;
+(7) on a blank line following all entries, the current listing buffer
+is exited.
+@end group
+@end format
+@format
+@group
+When pressed within an OO-Browser Command Help Menu buffer:
+ACTION
+Executes an OO-Browser command whose key binding is at point.
+ASSIST
+Displays help for an OO-Browser command whose key binding is at point.
+@end group
+@end format
+@format
+@group
+When pressed on an identifier within an OO-Browser source file:
+ACTION
+Tries to display identifier definition.
+ASSIST
+Not applicable.
+@end group
+@end format
+@page
+@format
+@group
+When pressed within a C source code file:
+ACTION
+Jumps to the definition of selected C construct:
+(1) on a '#include' statement, the include file is displayed;
+Look for include file in directory lists
+'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
+(2) on a C identifier, the identifier definition is displayed,
+assuming the identifier is found within an 'etags' generated tag file
+in the current directory or any of its ancestor directories.
+(3) if 'smart-c-use-lib-man' is non-nil, the C identifier is
+recognized as a library symbol, and a man page is found for the
+identifier, then the man page is displayed.
+ASSIST
+Jumps to the next tag matching an identifier at point.
+@end group
+@end format
+@format
+@group
+When pressed within an assembly source code file:
+ACTION
+Jumps to the definition of selected assembly construct:
+(1) on an include statement, the include file is displayed;
+Look for include file in directory list
+'smart-asm-include-dirs'.
+(2) on an identifier, the identifier definition is displayed,
+assuming the identifier is found within an 'etags' generated
+	 tag file in the current directory or any of its ancestor
+	 directories.
+ASSIST
+Jumps to the next tag matching an identifier at point.
+@end group
+@end format
+@page
+@format
+@group
+When pressed within a C++ source code file:
+ACTION
+Jumps to the definition of selected C+ construct:
+(1) on a '#include' statement, the include file is displayed;
+Look for include file in directory lists
+'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
+(2) on a C++ identifier, the identifier definition is displayed,
+assuming the identifier is found within an 'etags' generated tag file
+in the current directory or any of its ancestor directories.
+(3) if 'smart-c-use-lib-man' is non-nil, the C++ identifier is
+recognized as a library symbol, and a man page is found for the
+identifier, then the man page is displayed.
+ASSIST
+Jumps to the next tag matching an identifier at point.
+@end group
+@end format
+@format
+@group
+When pressed within a Objective-C source code file:
+ACTION
+Jumps to the definition of selected C+ construct:
+(1) on a '#include' statement, the include file is displayed;
+Look for include file in directory lists
+'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
+(2) on an Objective-C identifier, the identifier definition is displayed,
+assuming the identifier is found within an 'etags' generated tag file
+in the current directory or any of its ancestor directories.
+(3) if 'smart-c-use-lib-man' is non-nil, the Objective-C identifier is
+recognized as a library symbol, and a man page is found for the
+identifier, then the man page is displayed.
+ASSIST
+Jumps to the next tag matching an identifier at point.
+@end group
+@end format
+@page
+@format
+@group
+When pressed on a Lisp symbol within a Lisp code buffer:
+ACTION
+Jumps to the definition of any selected Lisp construct.
+If on an Emacs Lisp require, load, or autoload clause and 'find-library'
+from load-library package by Hallvard Furuseth <hallvard@@ifi.uio.no> has
+been loaded, jumps to library source, if possible.
+ASSIST
+Jumps to the next tag matching an identifier at point or if using the
+"wtags" package and identifier is an Emacs Lisp symbol, then displays
+documentation for the symbol.
+@end group
+@end format
+@format
+@group
+When the OO-Browser has been loaded and the press is within a C++ buffer:
+ACTION or ASSIST
+Jumps to the definition of selected C++ construct via OO-Browser support.
+(1) on a '#include' statement, the include file is displayed;
+Look for include file in directory lists
+'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
+(2) within a method declaration, its definition is displayed;
+(3) on a class name, the class definition is shown.
+@end group
+@end format
+@format
+@group
+When the OO-Browser has been loaded and the press is within a
+Objective-C buffer:
+ACTION or ASSIST
+Jumps to the definition of selected Objective-C construct via
+OO-Browser support.
+(1) on a '#include' statement, the include file is displayed;
+Look for include file in directory lists
+'smart-c-cpp-include-dirs' and 'smart-c-include-dirs'.
+(2) within a method declaration, its definition is displayed;
+(3) on a class name, the class definition is shown.
+@end group
+@end format
+@format
+@group
+When pressed within an occur-mode or moccur-mode buffer:
+ACTION or ASSIST
+Jumps to the source buffer and line of the current occurrence.
+@end group
+@end format
+@page
+@format
+@group
+When pressed within a calendar-mode buffer:
+ACTION
+(1) at the end of the buffer, the calendar is scrolled forward 3 months;
+(2) to the left of any dates on a calendar line, the calendar is scrolled
+backward 3 months;
+(3) on a date, the diary entries for the date, if any, are displayed.
+ASSIST
+(1) at the end of the buffer, the calendar is scrolled backward 3 months;
+(2) to the left of any dates on a calendar line, the calendar is scrolled
+forward 3 months;
+(3) anywhere else, all dates with marking diary entries are marked in the
+calendar window.
+@end group
+@end format
+@format
+@group
+When pressed within a man page apropos buffer:
+ACTION
+(1) on a UNIX man apropos entry, the man page for that entry is
+displayed in another window;
+(2) on or after the last line, the buffer in the other window is
+scrolled up a windowful.
+ASSIST
+(1) on a UNIX man apropos entry, the man page for that entry is
+displayed in another window;
+(2) on or after the last line, the buffer in the other window is
+scrolled down a windowful.
+@end group
+@end format
+@format
+@group
+If Smart Menu package has been loaded and 'hkey-always-display-menu' is
+non-nil:
+ACTION or ASSIST
+Pops up a window with a Smart Menu of commands.
+Menu displayed is selected by (smart-menu-choose-menu).
+@end group
+@end format
+@page
+@format
+@group
+If pressed within an outline-mode buffer or when 'selective-display' is
+non-nil:
+ACTION
+Collapses, expands, and moves outline entries.
+(1) after an outline heading has been cut via the Action Key, then paste
+the cut heading at point;
+(2) at the end of buffer, show all buffer text
+(3) at the beginning of a heading line, cut the headings subtree from the
+buffer;
+(4) on a header line but not at the beginning or end, if headings
+subtree is hidden then show it, otherwise hide it;
+(5) anywhere else, scroll up a windowful.
+ASSIST
+(1) after an outline heading has been cut via the Action Key, allow
+multiple pastes throughout the buffer (last paste should be done
+with the Action Key, not the Assist Key);
+(2) at the end of buffer, hide all bodies in buffer;
+(3) at the beginning of a heading line, cut the current heading (sans
+subtree) from the buffer;
+(4) on a header line but not at the beginning or end, if heading body is
+hidden then show it, otherwise hide it;
+(5) anywhere else, scroll down a windowful.
+@end group
+@end format
+@format
+@group
+@cindex click, Info
+@cindex Info browsing
+If pressed within an Info manual node:
+ACTION
+(1) the first line of an Info Menu Entry or Cross Reference, the desired
+node is found;
+(2) the Up,Next,or Previous entries of a Node Header (first line),
+the desired node is found;
+(3) the File entry of a Node Header (first line),
+the 'Top' node within that file is found;
+(4) at the end of the current node, the Next node is found (this will
+descend subtrees if the function 'Info-global-next' is bound);
+(5) anywhere else (e.g@. at the end of a line), the current node entry is
+scrolled up a windowful.
+ASSIST
+(1) the first line of an Info Menu Entry or Cross Reference, the desired
+node is found;
+(2) the Up,Next,or Previous entries of a Node Header (first line),
+the last node in the history list is found;
+(3) the File entry of a Node Header (first line),
+the 'DIR' root-level node is found;
+(4) at the end of the current node, the Previous node is found (this will
+return from subtrees if the function 'Info-global-prev is bound);
+(5) anywhere else (e.g@. at the end of a line), the current node entry is
+scrolled down a windowful.
+@end group
+@end format
+@page
+@format
+@group
+If pressed within a Hyperbole-supported mail reader, 'hmail:reader', or mail
+summary mode, 'hmail:lister', buffer at:
+ACTION
+(1) a msg buffer, within the first line or at the end of a message,
+the next undeleted message is displayed;
+(2) a msg buffer within the first line of an Info cross reference, the
+reference is followed;
+(3) anywhere else in a msg buffer, the window is scrolled up one
+	 windowful;
+(4) a msg summary buffer on a header entry, the message corresponding to
+the header is displayed in the msg window;
+(5) a msg summary buffer, on or after the last line, the messages marked
+for deletion are expunged.
+ASSIST
+(1) a msg buffer, within the first line or at the end of a message,
+the previous undeleted message is displayed;
+(2) a msg buffer within the first line of an Info cross reference, the
+reference is followed;
+(3) anywhere else in a msg buffer, the window is scrolled down one
+windowful;
+(4) a msg summary buffer on a header entry, the message corresponding to
+the header is marked as deleted;
+(5) a msg summary buffer, on or after the last line, all messages are
+marked undeleted.
+@end group
+@end format
+@format
+@group
+@cindex click, GNUS
+@cindex GNUS browsing
+If pressed within a GNUS listing of newsgroups buffer at:
+ACTION
+(1) a GNUS-GROUP line, that newsgroup is read;
+(2) to the left of any GNUS-GROUP line, on any of the whitespace, the
+current group is unsubscribed or resubscribed;
+(3) at the end of the GNUS-GROUP buffer, after all lines, checks for new
+news.
+ASSIST
+(1) a GNUS-GROUP line, that newsgroup is read;
+(2) to the left of any GNUS-GROUP line, on any of the whitespace, the
+user is prompted for a group name to subscribe or unsubscribe to;
+(3) at the end of the GNUS-GROUP buffer, after all lines, quits from the
+newsreader.
+@end group
+@end format
+@page
+@format
+@group
+If pressed within a GNUS newsreader subject listing buffer at:
+ACTION
+(1) a GNUS-SUBJECT line, that article is read, marked deleted, and
+scrolled forward;
+(2) at the end of the GNUS-SUBJECT buffer, the next undeleted article
+is read or the next group is entered.
+ASSIST
+(1) a GNUS-SUBJECT line, that article is read and scrolled backward;
+(2) at the end of the GNUS-SUBJECT buffer, the subject is exited, the
+user is returned to group mode.
+@end group
+@end format
+@format
+@group
+If pressed within a GNUS newsreader article buffer at:
+ACTION
+(1) the first line or end of an article, the next unread message is
+displayed;
+(2) the first line of an Info cross reference, the reference is followed;
+(3) anywhere else, the window is scrolled up a windowful.
+ASSIST
+(1) the first line or end of an article, the previous message is
+displayed;
+(2) the first line of an Info cross reference, the reference is followed;
+(3) anywhere else, the window is scrolled down a windowful.
+@end group
+@end format
+@page
+@format
+@group
+@cindex click, buffer menu
+@cindex buffer menu
+If pressed within a listing of buffers (Buffer-menu-mode):
+ACTION
+(1) on the first column of an entry, the selected buffer is marked for
+display;
+(2) on the second column of an entry, the selected buffer is marked to be
+saved;
+(3) anywhere else within an entry line, all saves and deletes are done,
+and selected buffers are displayed, including the one just clicked
+on (if in the OO-Browser, only the selected buffer is displayed);
+(4) on or after the last line in the buffer, all saves and deletes are
+done.
+ASSIST
+(1) on the first or second column of an entry, the selected buffer is
+unmarked for display and for saving or deletion;
+(2) anywhere else within an entry line, the selected buffer is marked for
+deletion;
+(3) on or after the last line in the buffer, all display, save, and delete
+marks on all entries are undone.
+@end group
+@end format
+@format
+@group
+@cindex click, dired
+@cindex dired browsing
+If pressed within a dired-mode buffer:
+ACTION
+(1) within an entry line, the selected file/directory is displayed
+for editing in the other window;
+(2) on or after the last line in the buffer, if any deletes are to be
+performed, they are executed after user verification, otherwise, this
+dired invocation is quit.
+ASSIST
+(1) on a '~' character, all backup files in the directory are marked for
+deletion;
+(2) on a '#' character, all auto-save files in the directory are marked
+for deletion;
+(3) anywhere else within an entry line, the current entry is marked for
+deletion;
+(4) on or after the last line in the buffer, all delete marks on all
+entries are undone.
+@end group
+@end format
+@page
+@format
+@group
+@cindex click, tar
+@cindex tar archive browsing
+@cindex extracting from tar files
+If pressed within a tar-mode buffer:
+ACTION
+(1) within an entry line, the selected file/directory is displayed
+for editing in the other window;
+(2) on or after the last line in the buffer, if any deletes are to be
+performed, they are executed after user verification, otherwise, this
+tar file browser is quit.
+ASSIST
+(1) on an entry line, the current entry is marked for deletion;
+(2) on or after the last line in the buffer, all delete marks on all
+entries are undone.
+@end group
+@end format
+@format
+@group
+@cindex man page references
+If pressed on a cross reference within a man page entry section labeled
+NAME, SEE ALSO, or PACKAGES USED, or within a man page C routine
+specification (see 'smart-man-c-routine-ref') and man page buffer
+has either an attached file or else a @var{man-path} local variable
+containing its pathname:
+ACTION or ASSIST
+Displays man page or source code for cross reference.
+@end group
+@end format
+@format
+@group
+@cindex click, world-wide web
+@cindex W3
+@cindex URL
+@cindex world-wide web
+If pressed on a world-wide web universal resource locator:
+ACTION
+Displays the URL referent at point.
+ASSIST
+Goes back to a previously displayed web page.
+@end group
+@end format
+@format
+@group
+@cindex game, gomoku
+@cindex gomoku
+If pressed in a Gomoku game buffer.
+ACTION
+Makes a move at the space pointed to.
+ASSIST
+Takes back a prior move made at the space pointed to.
+@end group
+@end format
+@format
+@group
+@cindex click, wrolo matches
+@cindex wrolo matches
+If pressed within an entry in the wrolo match display buffer:
+ACTION or ASSIST
+The entry is edited in the other window.
+@end group
+@end format
+@node Outliner Keys, Suggestion or Bug Reporting, Smart Key Reference, Top
+@appendix Outliner Keys
+@cindex outliner keys
+This appendix summarizes the specialized key bindings available when
+editing an outline with Hyperbole.  Each key is shown together with its
+command binding and the documentation for that command.  Normal emacs
+editing keys are modified to account for the structure within outlines.
+An outliner command which overloads an Emacs command named @emph{cmd}
+would be named @emph{kotl-mode:cmd}.
+@table @code
+@findex kfile:write
+@item kfile:write  @{@kbd{C-x C-w}@}
+Write current outline to FILE.
+@findex klink:create
+@item klink:create  @{@kbd{C-c l}@}
+Insert at point an implicit link to REFERENCE.
+REFERENCE should be a cell-ref or a string containing "filename, cell-ref".
+See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
+@findex kotl-mode:add-cell
+@item kotl-mode:add-cell  @{@key{LFD}@}
+Add a cell following current cell at optional RELATIVE-LEVEL with CONTENTS string.
+Optional prefix arg RELATIVE-LEVEL means add as sibling if nil or >= 0, as child
+if equal to universal argument, @kbd{C-u}, and as sibling of current cell's
+parent, otherwise.  If added as sibling of current level, RELATIVE-LEVEL is
+used as a repeat count for the number of cells to add.
+Return last newly added cell.
+@findex kotl-mode:add-child
+@item kotl-mode:add-child  @{@kbd{C-c a}@}
+Add a new cell to current kview as first child of current cell.
+@findex kotl-mode:add-parent
+@item kotl-mode:add-parent  @{@kbd{C-c p}@}
+Add a new cell to current kview as sibling of current cell's parent.
+@findex kotl-mode:append-cell
+@item kotl-mode:append-cell  @{@kbd{C-c +}@}
+Append CONTENTS-CELL to APPEND-TO-CELL.
+APPEND-TO-CELL is refilled if neither cell has a no-fill property and
+kotl-mode:refill-flag is enabled.
+@findex kotl-mode:back-to-indentation
+@item kotl-mode:back-to-indentation  @{@kbd{M-m}@}
+Move point to the first non-read-only non-whitespace character on this line.
+@findex kotl-mode:backward-cell
+@item kotl-mode:backward-cell  @{@kbd{C-c C-b}@}
+Move to prefix ARGth prior cell (same level) within current view.
+Return number of cells left to move.
+@findex kotl-mode:backward-char
+@item kotl-mode:backward-char  @{@kbd{C-b}@}
+Move point backward ARG (or 1) characters and return point.
+@findex kotl-mode:backward-kill-word
+@item kotl-mode:backward-kill-word  @{@kbd{M-DEL}@}
+Kill up to prefix ARG words preceding point within a single cell.
+@findex kotl-mode:backward-sentence
+@item kotl-mode:backward-sentence  @{@kbd{M-a}@}
+Move point backward ARG (or 1) sentences and return point.
+@findex kotl-mode:backward-word
+@item kotl-mode:backward-word  @{@kbd{M-b}@}
+Move point backward ARG (or 1) words and return point.
+@findex kotl-mode:beginning-of-buffer
+@item kotl-mode:beginning-of-buffer  @{@kbd{M-<}@}
+Move point to beginning of buffer and return point.
+@findex kotl-mode:beginning-of-cell
+@item kotl-mode:beginning-of-cell  @{@kbd{C-c ,}@}
+Move point to beginning of current or ARGth - 1 prior cell and return point.
+@findex kotl-mode:beginning-of-line
+@item kotl-mode:beginning-of-line  @{@kbd{C-a}@}
+Move point to beginning of current or ARGth - 1 line and return point.
+@findex kotl-mode:beginning-of-tree
+@item kotl-mode:beginning-of-tree  @{@kbd{C-c ^}@}
+Move point to the level 1 root of the current cell's tree.
+Leave point at the start of the cell.
+@findex kotl-mode:center-line
+@item kotl-mode:center-line  @{@kbd{M-s}@}
+@vindex fill-column
+Center the line point is on, within the width specified by @var{fill-column}.
+This means adjusting the indentation so that it equals the distance between
+the end of the text and @var{fill-column}.
+@findex kotl-mode:center-paragraph
+@item kotl-mode:center-paragraph  @{@kbd{M-S}@}
+Center each nonblank line in the paragraph at or after point.
+See @code{center-line} for more info.
+@findex kotl-mode:copy-after
+@item kotl-mode:copy-after  @{@kbd{C-c c}@}
+Copy tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
+If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
+TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
+Leave point at the start of the root cell of the new tree.
+@findex kotl-mode:copy-before
+@item kotl-mode:copy-before  @{@kbd{C-c C-c}@}
+Copy tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
+If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
+TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
+Leave point at the start of the root cell of the new tree.
+@findex kotl-mode:copy-to-buffer
+@item kotl-mode:copy-to-buffer  @{@kbd{C-c M-c}@}
+Copy outline tree rooted at CELL-REF to a non-koutline BUFFER.
+Use 0 to copy the whole outline buffer.
+@findex kotl-mode:copy-to-register
+@item kotl-mode:copy-to-register  @{@kbd{C-x x}@}
+Copy into REGISTER the region START to END.
+With optional prefix arg DELETE-FLAG, delete region.
+@findex kotl-mode:delete-backward-char
+@item kotl-mode:delete-backward-char  @{@kbd{DEL}@}
+Delete up to the preceding prefix ARG characters.
+Return number of characters deleted.
+Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
+Does not delete across cell boundaries.
+@findex kotl-mode:delete-blank-lines
+@item kotl-mode:delete-blank-lines  @{@kbd{C-x C-o}@}
+On blank line within a cell, delete all surrounding blank lines, leaving just one.
+On isolated blank line, delete that one.
+On nonblank line, delete all blank lines that follow it.
+If nothing but whitespace follows point until the end of a cell, delete all
+whitespace at the end of the cell.
+@findex kotl-mode:delete-char
+@item kotl-mode:delete-char  @{@kbd{C-d}@}
+Delete up to prefix ARG characters following point.
+Return number of characters deleted.
+Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
+Does not delete across cell boundaries.
+@findex kotl-mode:delete-indentation
+@item kotl-mode:delete-indentation  @{@kbd{M-^}@}
+Join this line to previous and fix up whitespace at join.
+If there is a fill prefix, delete it from the beginning of this line.
+With argument, join this line to following line.
+@findex kotl-mode:demote-tree
+@vindex kotl-mode:refill-flag
+@item kotl-mode:demote-tree  @{@kbd{TAB}@}
+Move current kotl a maximum of prefix ARG levels lower in current view.
+Each cell is refilled iff its @emph{no-fill} attribute is nil and
+@var{kotl-mode:refill-flag} is non-nil.  With prefix ARG = 0, cells are
+demoted up to one level and kotl-mode:refill-flag is treated as true.
+@findex kotl-mode:down-level
+@item kotl-mode:down-level  @{@kbd{C-c C-d}@}
+Move down prefix ARG levels lower within current tree.
+@findex kotl-mode:end-of-buffer
+@item kotl-mode:end-of-buffer  @{@kbd{M->}@}
+Move point to end of buffer and return point.
+@findex kotl-mode:end-of-cell
+@item kotl-mode:end-of-cell  @{@kbd{C-c .}@}
+Move point to end of current or ARGth - 1 succeeding cell and return point.
+@findex kotl-mode:end-of-line
+@item kotl-mode:end-of-line  @{@kbd{C-e}@}
+Move point to end of current or ARGth - 1 line and return point.
+@findex kotl-mode:end-of-tree
+@item kotl-mode:end-of-tree  @{@kbd{C-c $}@}
+Move point to the last cell in tree rooted at the current cell.
+Leave point at the start of the cell.
+@findex kotl-mode:exchange-cells
+@item kotl-mode:exchange-cells  @{@kbd{C-c e}@}
+Exchange CELL-REF-1 with CELL-REF-2 in current view.  Don't move point.
+@findex kotl-mode:fill-cell
+@item kotl-mode:fill-cell  @{@kbd{C-c M-j}@}
+Fill current cell within current view if it does not have the 'no-fill attribute.
+With optional JUSTIFY, justify cell as well.
+IGNORE-COLLAPSED-P is used when caller has already expanded cell, indicating
+it is not collapsed.
+@findex kotl-mode:fill-paragraph
+@item kotl-mode:fill-paragraph  @{@kbd{C-x f}@}
+Fill current paragraph within cell.  With optional JUSTIFY, justify
+paragraph as well.  Ignore any non-nil no-fill attribute attached to the
+cell.
+@findex kotl-mode:fill-tree
+@item kotl-mode:fill-tree  @{@kbd{C-M-j}@}
+Refill each cell within the tree whose root is at point.
+@findex kotl-mode:first-sibling
+@item kotl-mode:first-sibling  @{@kbd{C-c <}@}
+Move point to the first sibling of the present cell.
+Leave point at the start of the cell or at its present position if it is
+already within the first sibling cell.
+@findex kotl-mode:fkey-backward-char
+@item kotl-mode:fkey-backward-char  @{@kbd{left}@}
+Move point backward ARG (or 1) characters and return point.
+@findex kotl-mode:fkey-forward-char
+@item kotl-mode:fkey-forward-char  @{@kbd{right}@}
+Move point forward ARG (or 1) characters and return point.
+@findex kotl-mode:fkey-next-line
+@item kotl-mode:fkey-next-line  @{@kbd{down}@}
+Move point to ARGth next line and return point.
+@findex kotl-mode:fkey-previous-line
+@item kotl-mode:fkey-previous-line  @{@kbd{up}@}
+Move point to ARGth previous line and return point.
+@findex kotl-mode:forward-cell
+@item kotl-mode:forward-cell  @{@kbd{C-c C-f}@}
+Move to prefix ARGth following cell (same level) within current view.
+Return number of cells left to move.
+@findex kotl-mode:forward-char
+@item kotl-mode:forward-char  @{@kbd{C-f}@}
+Move point forward ARG (or 1) characters and return point.
+@findex kotl-mode:forward-para
+@item kotl-mode:forward-para  @{@kbd{M-n}@}
+Move to prefix ARGth next cell (any level) within current view.
+@findex kotl-mode:forward-paragraph
+@item kotl-mode:forward-paragraph  @{@kbd{M-]}@}
+Move to prefix ARGth next cell (any level) within current view.
+@findex kotl-mode:forward-sentence
+@item kotl-mode:forward-sentence  @{@kbd{M-e}@}
+Move point forward ARG (or 1) sentences and return point.
+@findex kotl-mode:forward-word
+@item kotl-mode:forward-word  @{@kbd{M-f}@}
+Move point forward ARG (or 1) words and return point.
+@findex kotl-mode:goto-cell
+@item kotl-mode:goto-cell  @{@kbd{C-c g}@}
+Move point to start of cell given by CELL-REF.  (See 'kcell:ref-to-id'.)
+Return point iff CELL-REF is found within current view.
+With a prefix argument, CELL-REF is assigned the argument value for use
+as an idstamp.
+Optional second arg, ERROR-P, non-nil means signal an error if CELL-REF is
+not found within current view.  Will signal same error if called
+interactively when CELL-REF is not found.
+@findex kotl-mode:hide-sublevels
+@item kotl-mode:hide-sublevels  @{@kbd{C-X $}@}
+Hide all cells in outline at levels deeper than LEVELS-TO-KEEP (a
+number). Shows any hidden cells within LEVELS-TO-KEEP.  1 is the first
+level.
+@findex kotl-mode:hide-subtree
+@item kotl-mode:hide-subtree  @{@kbd{C-M-h}@}
+Hide subtree, ignoring root, at optional CELL-REF (defaults to cell at
+point).
+@findex kotl-mode:hide-tree
+@item kotl-mode:hide-tree  @{@kbd{C-c BS}@}
+Collapse kotl rooted at optional CELL-REF (defaults to cell at point).
+@findex kotl-mode:insert-file
+@item kotl-mode:insert-file  @{@kbd{C-x i}@}
+Insert each paragraph in IMPORT-FROM as a separate cell in the current view.
+Insert as sibling cells following the current cell.  IMPORT-FROM may be a
+buffer name or file name (file name completion is provided).
+@findex kotl-mode:insert-register
+@item kotl-mode:insert-register  @{@kbd{C-c r i}@}
+Insert contents of register REGISTER at point in current cell.
+REGISTER is a character naming the register to insert.
+Normally puts point before and mark after the inserted text.
+If optional second arg is non-nil, puts mark before and point after.
+Interactively, second arg is non-nil if prefix arg is supplied.
+@findex kotl-mode:just-one-space
+@item kotl-mode:just-one-space  @{@kbd{M-\}@}
+Delete all spaces and tabs around point and leave one space.
+@findex kotl-mode:kcell-help
+@item kotl-mode:kcell-help  @{@kbd{C-c h}@}
+Display a temporary buffer with CELL-REF's properties.
+CELL-REF defaults to current cell.
+Optional prefix arg CELLS-FLAG selects the cells to print:
+If = 1, print CELL-REF's cell only;
+If > 1, print CELL-REF's visible kotl (the tree rooted at CELL-REF);
+If < 1, print all visible cells in current view  (CELL-REF is not used).
+See also the documentation for @code{kotl-mode:properties}.
+@findex kotl-mode:kill-contents
+@item kotl-mode:kill-contents  @{@kbd{C-c k}@}
+Kill contents of cell from point to cell end.
+With prefix ARG, kill entire cell contents.
+@findex kotl-mode:kill-line
+@item kotl-mode:kill-line  @{@kbd{C-k}@}
+Kill ARG lines from point.
+@findex kotl-mode:kill-region
+@item kotl-mode:kill-region  @{@kbd{C-w}@}
+Kill region between START and END within a single kcell.
+With optional COPY-P equal to 't, copy region to kill ring but does not
+kill it.  With COPY-P any other non-nil value, return region as a
+string without affecting kill ring.
+If the buffer is read-only and COPY-P is nil, the region will not be deleted
+but it will be copied to the kill ring and then an error will be signaled.
+@findex kotl-mode:kill-ring-save
+@item kotl-mode:kill-ring-save  @{@kbd{M-w}@}
+Copy region between START and END within a single kcell to kill ring.
+@findex kotl-mode:kill-sentence
+@item kotl-mode:kill-sentence  @{@kbd{M-k}@}
+Kill up to prefix ARG (or 1) sentences following point within a single cell.
+@findex kotl-mode:kill-tree
+@item kotl-mode:kill-tree  @{@kbd{C-c C-k}@}
+Kill ARG following trees starting with tree rooted at point.
+If ARG is not a non-positive number, nothing is done.
+@findex kotl-mode:kill-word
+@item kotl-mode:kill-word  @{@kbd{M-d}@}
+Kill up to prefix ARG words following point within a single cell.
+@findex kotl-mode:last-sibling
+@item kotl-mode:last-sibling  @{@kbd{C-c >}@}
+Move point to the last sibling of the present cell.
+Leave point at the start of the cell or at its present position if it is
+already within the last sibling cell.
+@findex kotl-mode:mail-tree
+@item kotl-mode:mail-tree  @{@kbd{C-c @@}@}
+Mail outline tree rooted at CELL-REF.  Use "0" for whole outline buffer.
+@findex kotl-mode:move-after
+@item kotl-mode:move-after  @{@kbd{C-c m}@}
+Move tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
+If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
+TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
+With optional COPY-P, copies tree rather than moving it.
+Leave point at original location but return the tree's new start point.
+@findex kotl-mode:move-before
+@item kotl-mode:move-before  @{@kbd{C-c RET}@}
+Move tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
+If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
+TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
+With optional COPY-P, copies tree rather than moving it.
+Leave point at original location but return the tree's new start point.
+@findex kotl-mode:newline
+@item kotl-mode:newline  @{@kbd{RET}@}
+Insert a newline.  With ARG, insert ARG newlines.
+In Auto Fill mode, if no numeric arg, break the preceding line if it is
+too long.
+@findex kotl-mode:next-cell
+@item kotl-mode:next-cell  @{@kbd{C-c C-n}@}
+Move to prefix ARGth next cell (any level) within current view.
+@findex kotl-mode:next-line
+@item kotl-mode:next-line  @{@kbd{C-n}@}
+Move point to ARGth next line and return point.
+@findex kotl-mode:open-line
+@item kotl-mode:open-line  @{@kbd{C-o}@}
+Insert a newline and leave point before it.
+With arg N, insert N newlines.
+@findex kotl-mode:overview
+@item kotl-mode:overview  @{@kbd{C-c C-o}@}
+Show only the first line of each cell in the current outline.
+@findex kotl-mode:previous-cell
+@item kotl-mode:previous-cell  @{@kbd{C-c C-p}@}
+Move to prefix ARGth previous cell (any level) within current view.
+@findex kotl-mode:previous-line
+@item kotl-mode:previous-line  @{@kbd{C-p}@}
+Move point to ARGth previous line and return point.
+@findex kotl-mode:promote-tree
+@vindex kotl-mode:refill-flag
+@item kotl-mode:promote-tree  @{@kbd{M-TAB}@}
+Move current kotl a maximum of prefix ARG levels higher in current view.
+Each cell is refilled iff its @emph{no-fill} attribute is nil and
+@var{kotl-mode:refill-flag} is non-nil.  With prefix ARG = 0, cells are
+promoted up to one level and kotl-mode:refill-flag is treated as true.
+@findex kotl-mode:scroll-down
+@item kotl-mode:scroll-down  @{@kbd{M-v}@}
+Scroll text of current window downward ARG lines; or a windowful if no ARG.
+@findex kotl-mode:scroll-up
+@item kotl-mode:scroll-up  @{@kbd{C-v}@}
+Scroll text of current window upward ARG lines; or a windowful if no ARG.
+@findex kotl-mode:set-cell-attribute
+@item kotl-mode:set-cell-attribute  @{@kbd{C-c C-i}@}
+Include ATTRIBUTE VALUE with the current cell or the cell at optional POS.
+Replaces any existing value that ATTRIBUTE has.
+When called interactively, it displays the setting in the minibuffer as
+confirmation.
+@findex kotl-mode:set-fill-prefix
+@item kotl-mode:set-fill-prefix  @{@kbd{C-x l}@}
+Sets fill prefix to line up to point.
+With prefix arg TURN-OFF or at begin of line, turns fill prefix off.
+@findex kotl-mode:show-all
+@item kotl-mode:show-all  @{@kbd{C-c C-a}@}
+Show (expand) all cells in current view.
+@findex kotl-mode:show-subtree
+@item kotl-mode:show-subtree
+Show subtree, ignoring root, at optional CELL-REF (defaults to cell at
+point).
+@findex kotl-mode:show-tree
+@item kotl-mode:show-tree  @{@kbd{C-c C-s}@}
+Display fully expanded kotl rooted at CELL-REF.
+@findex kotl-mode:split-cell
+@item kotl-mode:split-cell  @{@kbd{C-c s}@}
+Split cell into two cells and move to new cell.
+Cell contents after point become part of newly created cell.
+Default is to create new cell as sibling of current cell.
+With optional universal ARG, @kbd{C-u}, new cell is added as child of
+current cell.
+@findex kotl-mode:top-cells
+@item kotl-mode:top-cells  @{@kbd{C-c C-t}@}
+Collapse all level 1 cells in view and hide any deeper sublevels.
+@findex kotl-mode:transpose-cells
+@item kotl-mode:transpose-cells  @{@kbd{C-c t}@}
+Exchange current and previous visible cells, leaving point after both.
+If no previous cell, exchange current with next cell.
+With prefix ARG, take current cell and move it past ARG cells.
+With prefix ARG = 0, interchange the cell that contains point with the cell
+that contains mark.
+@findex kotl-mode:transpose-chars
+@item kotl-mode:transpose-chars  @{@kbd{C-t}@}
+Interchange characters around point, moving forward one character.
+With prefix ARG, take character before point and drag it forward past ARG
+other characters (backward if ARG negative).
+If no prefix ARG and at end of line, the previous two characters are
+exchanged.
+@findex kotl-mode:transpose-lines
+@item kotl-mode:transpose-lines  @{@kbd{C-x C-t}@}
+Exchange current line and previous line, leaving point after both.
+If no previous line, exchange current with next line.
+With prefix ARG, take previous line and move it past ARG lines.
+With prefix ARG = 0, interchange the line that contains point with the line
+that contains mark.
+@findex kotl-mode:transpose-words
+@item kotl-mode:transpose-words  @{@kbd{M-t}@}
+Interchange words around point, leaving point after both words.
+With prefix ARG, take word before or around point and drag it forward past
+ARG other words (backward if ARG negative).  If ARG is zero, the words around
+or after point and around or after mark are interchanged.
+@findex kotl-mode:up-level
+@item kotl-mode:up-level  @{@kbd{C-c C-u}@}
+Move up prefix ARG levels higher in current outline view.
+@findex kotl-mode:yank
+@item kotl-mode:yank  @{@kbd{C-y}@}
+Reinsert the last stretch of killed text.
+More precisely, reinsert the stretch of killed text most recently
+killed OR yanked.  Put point at end, and set mark at beginning.
+With just C-u as argument, same but put point at beginning (and mark at end).
+With argument N, reinsert the Nth most recently killed stretch of killed
+text.
+See also the command M-x kotl-mode:yank-pop.
+@findex kotl-mode:yank-pop
+@item kotl-mode:yank-pop  @{@kbd{M-y}@}
+Replace just-yanked stretch of killed text with a different stretch.
+This command is allowed only immediately after a @code{yank} or a
+@code{yank-pop}.  At such a time, the region contains a stretch of
+reinserted previously-killed text.  @code{yank-pop} deletes that text
+and inserts in its place a different stretch of killed text.
+With no argument, the previous kill is inserted.
+With argument N, insert the Nth previous kill.
+If N is negative, this is a more recent kill.
+The sequence of kills wraps around, so that after the oldest one
+comes the newest one.
+@findex kotl-mode:zap-to-char
+@item kotl-mode:zap-to-char  @{@kbd{M-z}@}
+Kill up to and including prefix ARG'th occurrence of CHAR.
+Goes backward if ARG is negative; error if CHAR not found.
+@findex kview:set-label-type
+@item kview:set-label-type  @{@kbd{C-c C-l}@}
+Change kview's label display type to NEW-TYPE, updating all displayed labels.
+See documentation for variable, kview:default-label-type, for
+valid values of NEW-TYPE.
+@findex kvspec:activate
+@item kvspec:activate  @{@kbd{C-c C-v}@}
+Activate optional VIEW-SPEC or existing view spec in the current koutline.
+VIEW-SPEC is a string.  See <$@{hyperb:dir@}/kotl/EXAMPLE.kotl, 2b17=048> for
+details on valid view specs.
+@findex kvspec:toggle-blank-lines
+@item kvspec:toggle-blank-lines @{@kbd{C-c b}@}
+Toggle blank lines between cells on or off.
+@end table
+@node Suggestion or Bug Reporting, Questions and Answers, Outliner Keys, Top
+@appendix Suggestion or Bug Reporting
+@xref{Mail Lists}, for complete details on Hyperbole mailing lists and
+how to subscribe.
+@cindex version description
+@cindex Hyperbole version
+If you find any errors in Hyperbole's operation or documentation, feel
+free to report them to the Hyperbole discussion list:
+<hyperbole@@hub.ucsb.edu>.  Be sure to use the Msg/Compose-Hypb-Mail
+minibuffer menu item whenever you send a message to the mail list since
+it will insert important system version information for you.
+If you use Hyperbole mail or news support, @ref{Buttons in Mail}, a
+click with your Action Key on the Hyperbole mail list address
+will insert a description of your Hyperbole configuration information
+into your outgoing message, so that you do not have to type it.  This is
+useful when composing a reply for the Hyperbole mail list.  Otherwise,
+be sure to include your Emacs, Hyperbole and window system versions in
+your message.  Your Hyperbole version number can be found in the
+top-level Hyperbole menu.
+Please use your subject line to state the position that your message
+takes on the topic that it addresses, e.g@. send "Subject: Basic bug in
+top-level Hyperbole menu." rather than "Subject: Hyperbole bug".  This
+simple rule makes all e-mail communication much easier.
+If you have suggestions on how to improve Hyperbole, send them to the
+same address.  Here are some issues you might address:
+@itemize @bullet
+@item
+What did you like and dislike about the system?
+@item
+What kinds of tasks, if any, does it seem to help you with?
+@item
+What did you think of the Emacs-based user interface?
+@item
+How was the Hyperbole Manual and other documentation?
+@item
+Was the setup trivial, average or hard?
+@item
+What areas of Hyperbole would you like to see expanded/added?
+@item
+How does it compare to other hypertext tools you have used?
+@item
+Was it easy or difficult to create your own types?  Why?
+@item
+Did you get any use out of the external system encapsulations?
+@end itemize
+@node Questions and Answers, Future Work, Suggestion or Bug Reporting, Top
+@appendix Questions and Answers
+@table @emph
+@cindex Smart Key
+@cindex mouse key bindings
+@findex hmouse-setup
+@findex hmouse-get-bindings
+@vindex file, hmouse-sh.el
+@vindex file, hmouse-reg.el
+@item How can I change the Smart Mouse Key bindings?
+@findex hmouse-shift-buttons
+Since the Smart Mouse Keys are set up for use under five different Emacs
+configurations, there is no easy way to provide user level
+customization.  The command, @code{hmouse-shift-buttons}, can be used to
+select between shifted and unshifted Smart Mouse Keys.  Any other mouse
+key binding changes must be done by editing the @code{hmouse-setup} and
+@code{hmouse-get-bindings} functions in the @file{hmouse-sh.el} and
+@file{hmouse-reg.el} files.
+@vindex file, hmouse-key.el
+@vindex file, hui-window.el
+@vindex hkey-alist
+@vindex hmouse-alist
+The @var{hkey-alist} and @var{hmouse-alist} variable
+settings in @file{hui-mouse.el} and @file{hui-window.el} must be altered
+if you want to change what the Smart Keys do in particular contexts.
+You should then update the Smart Key summary documentation in the file,
+@file{hypb-mouse.txt}, and potentially the same summary in this manual.
+@item Missing Action Types
+What if someone sends a mail message with a button for which I do
+not have the action type?  Or a button whose link referent I can't access?
+You receive an error that an action type is not defined or a link
+referent is not accessible/readable if you try to use the button.  This
+is hardly different than trying to get through a locked door without a
+key; you try the doorknob, find that it is locked, and then realize that
+you need to take a different approach or else give up.
+Like all communication, people need to coordinate, which usually
+requires an iterative process.  If you get a mail message with a button
+for which you don't have the action type, you mail the sender and
+request it.
+@cindex global button, modify
+@item How can I modify a number of global buttons in succession?
+Rather than typing the name for each, it is quicker to jump to the
+global button file and edit the buttons there as you would any explicit
+buttons.  By default, the ButFile/PersonalFile menu item takes you to
+the file where global buttons are saved.
+@item Why is all the button data scattered across directories?
+When you think of a hyper-space that you depend on every day, you don't
+want to have a single point of failure make you incapable of doing work.
+With Hyperbole, if some directories become unavailable for a particular
+time (e.g@. the filesystems on which they reside are dismounted) you can
+still work elsewhere with minimal effect.  We believe this to be a
+compelling factor to leave the design with external button data storage.
+This design also permits the potential addition of buttons to read-only
+media.
+@item Why are action types defined separately from their implicit button types?
+Any category of button can make use of an action type.  Some action types
+are useful as behavior definitions for a variety of button categories,
+so all action types are defined separately to give them independence
+from those types which apply them.
+For implicit button types that require a lot of code, it is useful to
+add a module that includes the implicit button type definition, its
+action type definition and supporting code.
+@end table
+@node Future Work, References, Questions and Answers, Top
+@appendix Future Work
+@noindent
+This appendix is included for a number of reasons:
+@itemize @bullet
+@item
+to better allow you to assess whether to work with Hyperbole by
+providing sketches of possible additions:
+@item
+to direct further development effort towards known needs;
+@item
+and to acknowledge known weaknesses in the current system.
+@end itemize
+@table @asis
+Note that due to a lack of volunteers to further develop Hyperbole, much
+of this work may not be done.  So if you want to see these features,
+encourage qualified people to volunteer.
+@item Button Copying, Killing, and Yanking
+There is as yet no means of transferring explicit buttons among buffers.
+We realize this is a critical need.  Users should be able to manipulate
+text with embedded buttons in ordinary ways.  This will probably be
+implemented only for versions of Emacs 19 and higher.  It will store the
+button attributes as text attributes within the buffers so that if a
+button is copied, its attributes follow.  When a buffer is saved, the
+attributes also will be saved.
+@item Trails
+Trails are an extension to the basic history mechanism presently offered
+by Hyperbole.  Trails will allow a user to capture, edit and store a
+specific sequence and set of views of information for later replay by
+other users.  Conditional branching may also be supported.
+@item Outliner View Mode
+This will complement the outliner editing mode by using simple one
+character keys that normally insert characters to instead modify the
+view of an outline and to move around in it, for ease of study.
+Switching between view and edit modes will also be simple.
+@item Storage of button data within button source files
+The current design choice of storing buttons external to the source file
+was made under the assumption that people should be able to look at
+files that contain Hyperbole buttons with any standard editor or tool
+and not be bothered by the ugly button data (since they won't be able to
+utilize the buttons anyway, they don't need to see or have access to
+them).
+In many contexts, embedding the button data within the source files may
+be a better choice, so a provision which would allow selection of either
+configuration may be added.  Here are some of the PROs and CONs of both
+design choices:
+@sp 1
+@example
+@group
+POSITIVE                        NEGATIVE
+Button data in source file
+Documents can stand alone.      All edit operators have
+Normal file operations apply.   to account for file
+structure and hide
+Simplifies creation and         internal components.
+facility expansion for
+structured and multi-media
+files.
+Button data external to source file
+Files can be displayed and      Currently, bdata for
+printed exactly as they look.   whole directory is
+No special display formatting   locked when any bdata
+is necessary.                   entry is locked.
+Button-based searches and
+database-type lookup operations
+need only search one file
+per directory.
+@end group
+@end example
+@sp 2
+@item Forms-based Interfaces
+This will allow one to create buttons more flexibly.  For example, button
+attributes could be given in any order.  Entry of long code sequences,
+quick note taking and cross-referencing would also be made easier.
+@item Collaboration Support
+From the early stages of Hyperbole design, collaborative work
+environments have been considered.  A simple facility has demonstrated
+broadcast of button activations to a number of workstations on a local
+area network, so that one user can lead others around an information
+space, as during an online design review.  (This facility was never
+adapted to the current Hyperbole release, however.)  We shall do some
+work in specific collaborative mechanisms, but we also expect that
+others who concentrate in collaborative work will provide more extensive
+capabilities.
+@end table
+@node References, Key Binding Index, Future Work, Top
+@appendix References
+@table @b
+@item [AkMcYo88]
+Akscyn, R. M., D. L. McCracken and E. A. Yoder. KMS: A
+Distributed Hypermedia System for Managing Knowledge in Organizations.
+@emph{Communications of the ACM}, Vol. 31, No. 7, July 1988, pp. 820-835.
+@item [Bro87]
+Brown, P. J. Turning Ideas into Products: The Guide System.
+@emph{Proceedings of Hypertext '87}, November 13-15, 1987, Chapel Hill, NC.
+ACM: NY, NY, pp. 33-40.
+@item [Con87]
+Conklin, Jeff. Hypertext: An Introduction and Survey. @emph{IEEE
+Computer}, Vol. 20, No. 9, September 1987, pp. 17-41.
+@item [Eng68]
+Engelbart, D., and W. English.  A research center for augmenting
+human intellect. @emph{Proceedings of the Fall Joint Computer Conference},
+33, 1, AFIPS Press: Montvale, NJ, 1968, pp. 395-410.
+@item [Eng84a]
+Engelbart, D. C. Authorship Provisions in Augment.
+@emph{Proceedings of the 1984 COMPCON Conference (COMPCON '84 Digest)},
+February 27-March 1, 1984, San Francisco, CA. IEEE Computer Society Press,
+Spring, 1984.  465-472. (OAD,2250,)
+@item [Eng84b]
+Engelbart, D. C. Collaboration Support Provisions in Augment.
+@emph{Proceedings of the AFIPS Office Automation Conference (OAC '84 Digest)},
+February, 1984, Los Angeles, CA, 1984. 51-58. (OAD,2221,)
+@item [Fos88]
+Foss, C. L. Effective Browsing in Hypertext Systems.
+@emph{Proceedings of the Conference on User-Oriented Content-Based Text and
+Image Handling (RIAO 88)}, March 21-24, MIT, Cambridge MA. Centre de Hautes
+Etudes Internationales d'Informatique Documentaire, 1988, pp. 82-98.
+@item [GaSmMe86]
+Garrett, N., K. E. Smith and N. Meyrowitz. Intermedia: Issues,
+Strategies, and Tactics in the Design of a Hypermedia Document System.
+@emph{Computer-Supported Cooperative Work (CSCW '86) Proceedings}, December
+3-5, Austin, TX, 1986, pp. 163-174.
+@item [HaMoTr87]
+Halasz, F. G., T. P. Moran and R. H. Trigg. NoteCards in a
+Nutshell. @emph{Proceedings of the CHI and GI '87 Conference on Human Factors
+in Computing Systems}, Toronto, J. M. Carroll and P. P. Tanner, (editors),
+ACM: NY, NY, April 1987, pp. 45-52.
+@item [Har88]
+Harvey, G. @emph{Understanding HyperCard.} Alameda, CA: SYBEX, Inc.,
+1988.
+@item [KaCaLoLa92]
+Kaplan, S., A. M. Carroll, C. Love and D. M. LaLiberte.
+@emph{Epoch 4.0 Manual.} Department of Computer Science, University of
+Illinois, Urbana, March 1992.
+@item [KaKaBeLaDr90]
+Kaplan, S. J., M. D. Kapor, E. J. Belove, R. A.  Landsman, and
+T. R. Drake.  AGENDA: A personal Information Manager.  @emph{Communications
+of the ACM}, No. 33, July 1990, pp. 105-116.
+@item [Nel87a]
+Nelson, T. H.  @emph{Computer Lib/Dream Machines.} MicroSoft Press,
+Redmond, WA, 1987.
+@item [Nel87b]
+Nelson, T. H. @emph{Literary Machines, Edition 87.1}.  Available
+from the Distributors, 702 South Michigan, South Bend, IN 46618, 1987.
+@item [NoDr86]
+Norman, D. A. and S. W. Draper, editors.  @emph{User Centered System
+Design.} Lawrence Erlbaum Associates: Hillsdale, New Jersey, 1986.
+@item [Shn82]
+Shneiderman, B. The future of interactive systems and the emergence
+of direct manipulation.  @emph{Behavior and Information Technology}, Vol. 1,
+1982, pp. 237-256.
+@item [Sta87]
+Stallman, R.  @emph{GNU Emacs Manual.} Free Software Foundation,
+Cambridge: MA, March 1987.
+@item [Tri86]
+Trigg, R., L. Suchman, and F. Halasz.  Supporting collaboration in
+NoteCards.  @emph{Proceedings of the CSCW '86 Conference}, Austin, TX,
+December 1986, pp. 147-153.
+@item [TrMoHa87]
+Trigg, R. H., T. P. Moran and F. G. Halasz.  Adaptability and
+Tailorability in NoteCards. @emph{Proceedings of INTERACT '87}, Stuttgart,
+West Germany, September 1987.
+@item [Wei92]
+Weiner, B.  @emph{PIEmail: A Personalized Information Environment
+Mail Tool.}  Department of Computer Science Masters Project, Brown
+University: Providence, RI, May 10, 1992.
+@item [YaHaMeDr88]
+Yankelovich, N., B. J. Haan, N. Meyrowitz and S. M.  Drucker.
+Intermedia: The Concept and the Construction of a Seamless Information
+Environment. @emph{IEEE Computer}, Vol. 21, No. 1, January 1988, pp.  81-96.
+@item [YoAkMc89]
+Yoder, E. A., R. M. Akscyn and D. L. McCracken.  Collaboration in
+KMS, A Shared Hypermedia System. @emph{Proceedings of the 1989 ACM Conference
+on Human Factors in Computer Systems (CHI '89)}, April 30-May 4, 1989,
+Austin, TX, ACM: NY,NY, 1989, pp. 37-42.
+@end table
+@c ***************************
+@c Indices
+@c ***************************
+@node Key Binding Index, Code and File Index, References, Top
+@unnumbered Key Binding Index
+@printindex ky
+@node Code and File Index, Concept Index, Key Binding Index, Top
+@unnumbered Code and File Index
+@printindex fn
+@node Concept Index,  , Code and File Index, Top
+@unnumbered Concept Index
+@printindex cp
+@page
+@summarycontents
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/hyperbole.texi @ 0:376386a54a3c r19-14