This is Info file ../info/hyperbole.info, produced by Makeinfo-1.63
from the input file hyperbole.texi.


File: hyperbole.info,  Node: View Specs,  Prev: Hiding and Showing,  Up: Viewing

View Specs
----------

   "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, KVSPEC:STRING,
has been set to `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.  *Note
Links::.

   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 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.

   {`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>.

`a'
     Show all cell levels and all lines in cells.

`b'
     Turn on blank lines between cells.  Without this character, blank
     lines will be turned off.  You can also use the {`C-c b'} key
     binding to toggle line numbers on and off independent of any other
     view settings.

`cN'
     Hide any lines greater than N in each cell.  0 means don't cutoff
     any lines.

`e'
     Show ellipses when some content of a cell or its subtree is hidden.

`lN'
     Hide cells at levels deeper than N.  0 means don't hide any cells.

`n'
     Turn on the default label type, as given by the variable,
     KVIEW:DEFAULT-LABEL-TYPE.  Normally, this is alphanumeric labels.

`n0'
     Display idstamps.

`n1'
     Display alpha labels.

`n2'
     Display partial alpha labels (don't use this, as full alpha labels
     are better).

`n.'
     Display legal labels.

`n*'
     Display star labels.  A level three cell would have three
     asterisks as a label, for example.

`n~'
     Turn off labels.  (n viewspec is removed from modeline).

   As a test, use {`C-h h o e'} to display the example koutline.  Then
use {`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.


File: hyperbole.info,  Node: Links,  Next: Cell Attributes,  Prev: Viewing,  Up: Outliner

Links
=====

   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, *Note Creation Via Action Key Drags:
By Dragging.  A "klink" is a special implicit link button, delimited by
<> separators, that jumps to a specific outline cell.  This section
discusses klinks.

   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.

   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 {`C-c l'} when in a koutline or {`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.

There are basically three forms of klinks:

*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.

*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.

*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.


File: hyperbole.info,  Node: Cell Attributes,  Next: Outliner History,  Prev: Links,  Up: Outliner

Cell Attributes
===============

   "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:

*idstamp
     The permanent id of the cell, typically used in cross-file
     hyperlinks that reference the cell.

*creator
     The e-mail address of the person who created this cell.

*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".

   {`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
`nil'.

   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,
KOTL-MODE:REFILL-FLAG, is set to t.  It does not prevent you from
invoking explicit commands that refill the cell.  *Note Filling::.

   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.

   {`C-c h'} prompts for a cell label and displays the cell's
attributes.  {`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.


File: hyperbole.info,  Node: Outliner History,  Prev: Cell Attributes,  Up: Outliner

Outliner History
================

   Much of the Hyperbole outliner design is based upon concepts
pioneered in the NLS/Augment system, `[Eng84a]'.  Augment treated
documents as a hierarchical set of nodes, called statements, rather
than cells.  Every Augment document utilized this intrinsic structure.

   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.

   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.


File: hyperbole.info,  Node: Rolodex,  Next: Window Configurations,  Prev: Outliner,  Up: Top

Rolodex
*******

   Hyperbole includes a complete, advanced rolodex system, Wrolo, for
convenient management of hierarchical, record-oriented information.

   Hyperbole buttons may be included within rolodex records and then
manually activated whenever their records are retrieved.

   See the description at the top of the `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::


File: hyperbole.info,  Node: Rolo Concepts,  Next: Rolo Menu,  Prev: Rolodex,  Up: Rolodex

Rolo Concepts
=============

   The rolodex manages and searches rolodex files.  A "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.

Here is an example of a simple rolodex file.

     ==================================================================
                             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

   We call rolodex records, "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.

For example, a search on "Company" could retrieve the following:

     ==================================================================
                             COMPANY ROLODEX
     ==================================================================
     *    Company
     **     Manager
     ***      Underlings

Thus, searching for Company retrieves all listed employees.  Searching
for Manager turns up all Underlings.


File: hyperbole.info,  Node: Rolo Menu,  Next: Rolo Keys,  Prev: Rolo Concepts,  Up: Rolodex

Rolo 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:

     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
     ====================================================================

   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:

     *    Company
     **     Manager
     ***      Underlings

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:

     ***      Underlings


File: hyperbole.info,  Node: Rolo Keys,  Next: Rolo Settings,  Prev: Rolo Menu,  Up: Rolodex

Rolo Keys
=========

   Use the {`e'} key to edit the entry at point within the rolodex
source file.

   After a rolodex search is performed, point is left in the "rolodex
match buffer", `*Rolodex*', which uses `wrolo-mode' to simplify
browsing many rolodex matches.  Press {`?'} when in the match buffer
for a summary of available keys.

   If your Emacs version supports textual highlighting, each search
match is highlighted for quick, visual location.  {TAB} moves point
forward to successive spans of text which match the search expression.
{`M-TAB'} or {`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.

   If you want to extend the match expression with some more characters
to find a particular entry, use {`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.  {`C-r'}
will reverse the direction of the search.

   Single key outlining commands are also available for browsing
matches.  If your search matches a large number of entries, use {`t'}
to get a top-level overview of all the entries.  Each entry is
collapsed so that only its first line shows.  Press {`s'} to show
(expand) the entry at point.  Use {`h'} to hide (collapse) the entry
again.  Press {`a'} to expand all entries in the buffer.

   Many other keys are defined to help you move through matching
entries.

`b'
     Move to the previous entry at the same level as the current entry.

`f'
     Move to the next entry at the same level as the current entry.

`n'
     Move to the next entry at any level.

`p'
     Move to the previous entry at any level.

`u'
     Move to the previous entry one level up.

`.'
`<'
     Move to the beginning of the buffer.

`,'
`>'
     Move to the end of the buffer.

`DEL'
     Scroll backward a windowful.

`SPC'
     Scroll forward a windowful.

   Once you have found an entry of interest and you want to remove the
rolodex match buffer, use {`q'} to quit.  This will restore your
current frame to its state prior to the rolodex search.


File: hyperbole.info,  Node: Rolo Settings,  Prev: Rolo Keys,  Up: Rolodex

Rolo Settings
=============

   If textual highlighting is available in your Emacs on your current
display type, the rolodex uses the value of ROLO-HIGHLIGHT-FACE as the
face to use to highlight search matches.

   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: `(setq rolo-kill-buffers-after-use t)'.

   After an entry is killed, the modified rolodex file is automatically
saved.  If you would rather always save files yourself, use this
setting: `(setq rolo-save-buffers-after-use nil)'.

   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 ROLO-EMAIL-FORMAT variable.  See its documentation if you want to
change its value.

   The files used in any rolodex search are given by the ROLO-FILE-LIST
variable, whose default value is `("~/.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.

   The rolodex entry start delimiter is given by the regular expression
variable, ROLO-ENTRY-REGEXP, whose default value is "^\*+".

   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, 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.


File: hyperbole.info,  Node: Window Configurations,  Next: Developing with Hyperbole,  Prev: Rolodex,  Up: Top

Window Configurations
*********************

   Hyperbole includes the `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:

     WinConfig>  AddName  DeleteName  RestoreName  PopRing  SaveRing  YankRing

     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
     ====================================================================

   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, *Note 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.

   Wconfig creates a ring structure that operates just like the Emacs
KILL-RING, *Note Kill Ring: (emacs)Kill Ring, 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.

   SaveRing executes the `wconfig-ring-save' command which saves the
current window configuration to the ring.

   YankRing executes the `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 {`q'} to quit from the minibuffer menu.

   PopRing calls the `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 {`q'} to quit from the minibuffer menu.

   The maximum number of elements the ring can hold is set by the
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.


File: hyperbole.info,  Node: Developing with Hyperbole,  Next: Glossary,  Prev: Window Configurations,  Up: Top

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::


File: hyperbole.info,  Node: Hook Variables,  Next: Creating Types,  Prev: Developing with Hyperbole,  Up: Developing with Hyperbole

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 `-hook'
appended.  Hyperbole provides the following hook variables:

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.

ACTION:ACT-HOOK
     Run before each Hyperbole button activation.  The variable
     HBUT:CURRENT contains the button to be activated when this is run.

EBUT:CREATE-HOOK
     To add to the Hyperbole explicit button creation process.

EBUT:DELETE-HOOK
     To add to the Hyperbole explicit button deletion process.

EBUT:MODIFY-HOOK
     Executed when an explicit button's attributes are modified.

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.

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.

HTYPE:CREATE-HOOK
     Executed when a Hyperbole type (e.g. action type or implicit button
     type) is added to the environment.

HTYPE:DELETE-HOOK
     Executed when a type is deleted from the environment.

KOTL-MODE-HOOK
     Executed when a Koutline is created or read in or when kotl-mode is
     invoked.

WROLO-DISPLAY-HOOK
     Executed when rolodex matches are displayed.

WROLO-MODE-HOOK
     Executed when a rolodex match buffer is created and put into
     wrolo-mode.

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.

Hyperbole also makes use of a number of external Emacs hook variables.

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.

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.

     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.


File: hyperbole.info,  Node: Creating Types,  Next: Explicit Button Technicalities,  Prev: Hook Variables,  Up: Developing with Hyperbole

Creating Types
==============

To define or redefine a single Hyperbole type, you may either:

   * move your Emacs point to within the type definition and use
     {`C-M-x'} `(eval-defun)' (only works in Emacs Lisp mode);

   * or move your point to the end of the last line of the type
     definition and use {`C-x C-e'} `(eval-last-sexp)' (works in most
     modes).

   The functions from the `htype' class may be applied to any Hyperbole
types, if needed.

   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 `hactypes.el'
and `hibtypes.el' for examples.

* Menu:

* Action Type Creation::
* Implicit Button Types::


File: hyperbole.info,  Node: Action Type Creation,  Next: Implicit Button Types,  Prev: Creating Types,  Up: Creating Types

Action Type Creation
--------------------

   New forms of explicit buttons may be created by adding new action
types to a Hyperbole environment.  The file, `hactypes.el', provides
many examples of working action types.

   An action type is created, i.e. loaded into the Hyperbole
environment, with the `(defact)' function (which is an alias for
`(actype:create)').  The calling signature for this function is given
in its documentation; it is the same as that of `(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.)

   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.

   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 `(interactive)' form).  It may
additionally use Hyperbole command character extensions when the form
is given as a string.  Each such extension character *must* be preceded
by a plus sign, `+', in order to be recognized since such characters
may also have standard interactive form meanings.

   The present Hyperbole extension characters are:

*+I*
     Prompts for an existing Info node name and file.

*+K*
     Prompts for an existing kcell identifier, either a full outline
     level identifier or a permanent idstamp.

*+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.

*+V*
     Prompts for a Hyperbole view specification.  Not yet available for
     use.

   Arguments are read by the functions in Hyperbole's `hargs' class,
rather than the standard Lisp `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.  `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.

   Call `(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).


File: hyperbole.info,  Node: Implicit Button Types,  Prev: Action Type Creation,  Up: Creating Types

Implicit Button Types
---------------------

   An implicit button type is created or loaded via the `(defib)'
function (which is an alias for `(ibtype:create)').  The calling
signature for this function is given in its documentation; it is the
same as that of `(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.

   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 `nil'.  If so, it may optionally setup to flash
the button and then perform one or more actions.  A call of the form:
`(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: `(hact 'actype &rest
actype-arguments)'.  It is imperative that all actions (non-predicate
code) be invoked through the `(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 `(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.  `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.

   Call `(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.

   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 `:help', e.g.
`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 `(ibut:at-p)' returns when
point is within an implicit button context.)  The button may be queried
for its attributes using functions from the `hbut' and `hattr' classes.
See the `hib-kbd.el' file for an example of a custom help function.


File: hyperbole.info,  Node: Explicit Button Technicalities,  Next: Encapsulating Systems,  Prev: Creating Types,  Up: Developing with Hyperbole

Explicit Button Technicalities
==============================

* Menu:

* Button Label Normalization::
* Operational and Storage Formats::
* Programmatic Button Creation::


File: hyperbole.info,  Node: Button Label Normalization,  Next: Operational and Storage Formats,  Prev: Explicit Button Technicalities,  Up: Explicit Button Technicalities

Button Label Normalization
--------------------------

   Hyperbole uses a normalized form of button labels called button keys
(or label keys) for all internal operations.  See the documentation for
the function `(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.

       <(fake button)>     <( fake      button)>
     
       Pam>  <(fake
       Pam>    button)>
     
       ;; <(fake
       ;;   button)>
     
       /* <( fake      */
       /*    button )> */

   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 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, FILL-PREFIX, so no user intervention
is required.


File: hyperbole.info,  Node: Operational and Storage Formats,  Next: Programmatic Button Creation,  Prev: Button Label Normalization,  Up: Explicit Button Technicalities

Operational and Storage Formats
-------------------------------

   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 HBUT:CURRENT symbol by default to store and retrieve the
last encountered button in edit format.

   The `hbdata' class handles the terse, stored format.  The `hbut',
`ebut', and `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.


File: hyperbole.info,  Node: Programmatic Button Creation,  Prev: Operational and Storage Formats,  Up: Explicit Button Technicalities

Programmatic 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.

   The Hyperbole class `ebut' supports programmatic access to explicit
buttons.  See it within the `hbut.el' file for full details.  The
documentation for `(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 `(ebut:map)' function.


File: hyperbole.info,  Node: Encapsulating Systems,  Next: Embedding Hyperbole,  Prev: Explicit Button Technicalities,  Up: Developing with Hyperbole

Encapsulating Systems
=====================

   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 `hsys-*' files for examples of how to do this.
Encapsulations are provided for the following systems (the systems
themselves are not included with Hyperbole):

*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.

*WAIS
     The Wide Area Information Systems full text-retrieval system
     orginally developed at Thinking Machines and then later at WAIS
     Inc.

*HyperBase
     A hypertextual storage manager that stores textual nodes as
     records with locking so that multiple users can read and edit
     hypertexts.


File: hyperbole.info,  Node: Embedding Hyperbole,  Prev: Encapsulating Systems,  Up: Developing with Hyperbole

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.]

   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:

`hact.el', `hargs.el', `hbmap.el', `hbut.el', `hhist.el', `hmail.el',
`hmoccur.el', `hpath.el', `htz.el', `hypb.el', `set.el', `wconfig.el',
`wrolo.el', and `wrolo-logic.el'.

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 `hyperbole/kotl/' directory
and learn to program it, however.

