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


File: hyperbole.info,  Node: Creation,  Next: Renaming,  Prev: Utilizing Explicit Buttons,  Up: Utilizing Explicit Buttons

Creation
--------

* Menu:

* By Dragging::                 Creation Via Action Key Drags
* By Menu::                     Creation Via Menus


File: hyperbole.info,  Node: By Dragging,  Next: By Menu,  Prev: Creation,  Up: Creation

Creation Via Action Key Drags
.............................

   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. (*Note Creation Via Menus: By
Menu, 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.

   If you run Emacs under a window system, you can emulate an Action Key
drag from the keyboard by: hitting {`M-o'}, the `hkey-operate' command,
at the button source location, moving to the link destination, e.g.
with {`C-x o'}, and then hitting {`M-o'} again.  This simulates a
depress and then release of the Action Key.  {`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.


File: hyperbole.info,  Node: By Menu,  Prev: By Dragging,  Up: Creation

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 {`?'} completion
help key to see the available types.  The type selected determines any
following values for which you will be prompted.

   If a previous button with the same label exists in the same buffer,
Hyperbole will add an "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.

   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 `link-to-' and then use the
direct selection techniques mentioned in *Note Entering Arguments::, to
select the link referent.


File: hyperbole.info,  Node: Renaming,  Next: Deletion,  Prev: Creation,  Up: Utilizing Explicit Buttons

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.

   The rename command may be invoked from the Hyperbole menu via
Ebut/Rename.  A faster method is to use a key bound to the
`hui:ebut-rename' command.  Your site installation may include such a
key.  {`C-h w hui:ebut-rename 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 `~/.emacs' file.  We recommend the
{`C-c C-r'} key, as in: `(global-set-key "\C-c\C-r" 'hui:ebut-rename)'.


File: hyperbole.info,  Node: Deletion,  Next: Modification,  Prev: Renaming,  Up: Utilizing Explicit Buttons

Deletion
--------

   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.

   Presently there is no way to recover a deleted button; it must be
recreated.  Therefore, the 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.


File: hyperbole.info,  Node: Modification,  Next: Location,  Prev: Deletion,  Up: Utilizing Explicit Buttons

Modification
------------

   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.  *Note Creation::.


File: hyperbole.info,  Node: Location,  Next: Buttons in Mail,  Prev: Modification,  Up: Utilizing Explicit Buttons

Location
--------

   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.

   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.


File: hyperbole.info,  Node: Buttons in Mail,  Next: Buttons in News,  Prev: Location,  Up: Utilizing Explicit Buttons

Buttons in Mail
---------------

   Hyperbole allows the embedding of buttons within electronic mail
messages that are composed in Emacs with the standard `(mail)' command,
normally bound to {`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.

   Hyperbole automatically supports the following mail readers:  Rmail,
*Note Rmail: (emacs)Rmail, VM, *Note Introduction: (vm)Introduction,
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, *Note Introduction: (gnus)Introduction, if available at your
site.  (The `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.)

   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 `(mail-yank-original)' command bound
to {`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 *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.

   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,
SMAIL:COMMENT controls this behavior.  See its documentation for
technical details.  By default, it produces a message of the form:

     Comments: Hyperbole mail buttons accepted, vX.XX.

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 `~/.emacs' file before the
point at which you load Hyperbole.

     (setq smail:comment nil)

   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 `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 *Note Entering Arguments::.


File: hyperbole.info,  Node: Buttons in News,  Prev: Buttons in Mail,  Up: Utilizing Explicit Buttons

Buttons in News
---------------

   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 `hsite.el' by autoloading the `hgnus.el' file.

   All Hyperbole support should work just as it does when reading or
sending mail.  *Note Buttons in Mail::.  When reading news, buttons
which appear in message *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.

   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.  *Note Buttons in Mail::, for details
and an explanation of how to turn this feature off.


File: hyperbole.info,  Node: Smart Keys,  Next: Menus,  Prev: Buttons,  Up: Top

Smart Keys
**********

   Hyperbole provides two special "Smart Keys" that perform
context-sensitive operations, the Action Key and the Assist Key.  By
default, the "Action Key" is bound to your shift-middle mouse button (or
shift-left on a 2-button mouse) and the "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.)

   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, `hmouse-shift-buttons', can be used to select
between shifted and unshifted Smart Mouse Keys.

   By default (if HKEY-INIT is set to `t' in `hsite.el'), then
{`M-RET'} may also be used as the Action Key and {`C-u M-RET'} may be
used as the Assist Key.  In many read-only modes like Dired and Rmail,
{RET} also functions as the Action Key.  These key bindings allow
context sensitive operation from any keyboard.

   If you prefer other key bindings, simply bind the commands
`action-key' and `assist-key' to keyboard keys.  `hkey-either' may be
used instead if you prefer a single key binding for both commands; a
prefix argument then invokes `assist-key'.

   You may also bind `action-mouse-key' and `assist-mouse-key' to mouse
keys, as you like.

   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.

   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, *Note Smart
Key Reference::.

==============================================================================
                                             Smart Keys
Context                         Action Key                 Assist Key
==============================================================================
Hyperbole
  On a menu item                Item is activated          Item help
  On an explicit button         Button is activated        Button help
  Reading argument
    1st press at an arg value   Value copied to minibuffer <- same
    2nd press at an arg value   Value used as argument     <- same
    In minibuffer               Minibuf arg is applied     Completion help
  On an implicit button         Button is activated        Button help
  Within an outline cell        Collapses and expands      Shows tree props
  Left of an outline cell       Creates a klink            Moves a tree
  Wrolo Match Buffer            Edits entries and mails to e-mail addresses

Mouse or Keyboard Display Control
  Line end, not end of buffer
    smart-scroll-proportional
      = t   (default)           Makes curr line top line   Bottom line
      = nil                     Scrolls up a windowful     Scrolls down
  End of Any Help buffer        Screen restored to previous state

Mouse-only Control
  Modeline down & wind release  Resize window height       <- same
  Drag from shared window side
    or from left of scroll bar  Resize window width        <- same
  Drag between windows          Create/modify a link but   Swap window buffers
  Horizontal drag within window
    Left to right               Scroll to buffer end       Split window across
    Right to left               Scroll to buffer begin     Delete window
  Vertical drag within window   Split window sideways      <- same
  Diagonal drag within window   Save ring screen-config    Restore ring config
  Click in modeline
    Left window edge            Bury buffer                Unbury bottom buf
    Right window edge           Info                       Smart Key summary
    Otherwise                   Action Key Hook            Assist Key Hook

Special Modes
  C/C++ Mode                    Jumps to id/include def    Jumps to next def
  Assembly Language Mode        Jumps to id/include def    Jumps to next def
  Any Lisp mode                 Jumps to id def            Jumps to next def
  Emacs Lisp Compiler Error     Jumps to def with error    <- same
  Grep or Occur match           Jumps to match source line <- same
  Multi-buffer occur match      Jumps to match source line <- same
  Outline Major/Minor Modes     Collapses, expands, and moves outline entries
  Man Apropos                   Displays man page entry    <- same
  Man Pages                     Follows cross refs, file refs and C code refs
  Buffer Menu                   Saves, deletes and displays buffers

Emacs Info Reader
  Menu Entry or Cross Ref       Jumps to referent          <- same
  Up, Next or Prev Header       Jumps to referent          Jumps to prior node
  File entry of Header          Jumps to top node          Jumps to (DIR) node
  End of current node           Jumps to next node         Jumps to prev node
  Anywhere else                 Scrolls up a windowful     Scrolls down a wind

Subsystems
  Calendar                      Scrolls or shows appts     Scrolls/marks dates
  Dired Mode                    Views and deletes files from directory listing
  GNUS News Reader              Toggles group subscriptions, gets new news,
                                  and browses articles
  Mail reader and Summaries     Browses, deletes and expunges messages
  OO-Browser                    Browses classes and elements
  Tar Mode                      Views and edits files from tar archive files

Any other context (defaults)    Hyperbole top menu         Smart Key summary
==============================================================================

   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
ACTION-KEY-DEFAULT-FUNCTION and ASSIST-KEY-DEFAULT-FUNCTION for
information on how to customize the behavior of the Smart Keys within
default contexts.

   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.

   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.

   By default (if HKEY-INIT is left set equal to `t' in `hsite.el'),
then {`C-h A'} will display this same context-sensitive help for the
Action Key while {`C-u C-h A'} will display the help for the Assist
Key.  Note that {`C-h a'} will perform a function unrelated to
Hyperbole, so you must press the shift key when you hit the `A'
character.

   When Hyperbole is installed, a key may be bound which allows you to
switch between the Smart Key mouse bindings and your prior ones.  `C-h
w hmouse-toggle-bindings 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 `~/.emacs'
file.  For example, `(global-set-key "\C-ct" 'hmouse-toggle-bindings)'.


File: hyperbole.info,  Node: Menus,  Next: Entering Arguments,  Prev: Smart Keys,  Up: Top

Menus
*****

   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.

   This section discusses only the specialized "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.

   The top level menu is invoked from a key given in your `hsite.el'
file (by default, {`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:

     Hy4>  Act Butfile/ Doc/ Ebut/ Gbut/ Hist Ibut/ Msg/ Otl/ Rolo/ Win/

The above menu items can be summarized as follows:

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

*Butfile/*
     Display a local or global file of buttons, providing easy access.
     `HYPB' for a local button file and `~/.hyperb/HYPB' for your
     global file.  These are good places to start your button creation
     testing.

*Ebut/*
     All explicit button commands.

*Doc/*
     Hyperbole documentation quick access.  Contains Types/ submenu for
     documentation on Hyperbole implicit button and action types.

*Gbut/*
     All global button commands.  Global buttons are accessed by name
     rather than by direct selection.

*Hist*
     Jumps back to last position in button traversal history.

*Ibut/*
     All implicit button commands.

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

*Otl/*
     Autonumbered, structured outliner and hyper-node manager commands.
     *Note Outliner::.

*Rolo/*
     Hierarchical, multi-file rolodex lookup and edit commands.  *Note
     Rolodex::.

*Win/*
     Window configuration management such as adding and restoring window
     configurations by name. *Note Window Configurations::.

   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.

   While a menu is active, to re-activate the top-level Hyperbole menu,
you must use {`C-t'}.  This allows you to browse the submenus and then
return to the top.  You can quit without selecting an item by using
{`q'}.  {`C-g'} aborts whether you are at a menu prompt or any other
Hyperbole prompt.


File: hyperbole.info,  Node: Entering Arguments,  Next: Outliner,  Prev: Menus,  Up: Top

Entering Arguments
******************

   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 `(interactive)'
function are recognized.  Experiment a little and you will quickly get
used to this direct selection technique.

   Wherever possible, standard Emacs completion is offered, see *Note
Completion: (emacs)Completion.  Remember to use {`?'} 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.


File: hyperbole.info,  Node: Outliner,  Next: Rolodex,  Prev: Entering Arguments,  Up: Top

Outliner
********

   The Hyperbole outliner, also known as the Koutliner (pronounced
Kay-outliner), produces structured, autonumbered documents composed of
hierarchies of cells.  Each "cell" has two identifiers, a "relative
identifier" indicating its present position within the outline and a
"permanent identifier" called an "idstamp", suitable for use within
hyperlink references to the cell.  The idstamp is typically not
displayed but is available when needed.  *Note Autonumbering::.

   Cells also store their time of creation and the user who created the
cell.  User-defined attributes may also be added to cells.  *Note Cell
Attributes::.

   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 {`C-h
h'} to display the Hyperbole menu.  If you see an `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.)

   This chapter expands on the information given in `EXAMPLE.kotl' file
included with Hyperbole.  Use {`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 {`C-x C-w'} to write
the outline to a temporary file such as, `/tmp/e.kotl', and then use
{`C-x C-q'} to make the outline editable.

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


File: hyperbole.info,  Node: Menu Commands,  Next: Creating Outlines,  Prev: Outliner,  Up: Outliner

Menu Commands
=============

   The Otl/ menu entry on the Hyperbole top-level menu provides access
to a number of major outliner commands:

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


File: hyperbole.info,  Node: Creating Outlines,  Next: Autonumbering,  Prev: Menu Commands,  Up: Outliner

Creating Outlines
=================

   In addition to the Otl/Create menu item, you can create and
experiment with outline files simply by finding a file, {`C-x C-f'}
with a `.kotl' suffix.  `.kot' will also work for DOS or
Windows-impaired users.

   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.

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


File: hyperbole.info,  Node: Autonumbering,  Next: Idstamps,  Prev: Creating Outlines,  Up: Outliner

Autonumbering
=============

   *Note 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 "autonumbers" and as "relative ids" because
they change as the structure changes.

   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.

   The default autonumbers are called "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.

   You can change the labeling scheme used in a particular outline with
the command {`C-c C-l'}.  A {`?'} 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.

   A cell label is normally followed by two spaces, called the "label
separator", prior to the start of the cell contents.  You can change the
separator with for the current outline with {`C-c M-l'}.  {`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.

   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, `~/.emacs', substituting for `your-separator':

     (setq kview:default-label-separator "your-separator")


File: hyperbole.info,  Node: Idstamps,  Next: Editing,  Prev: Autonumbering,  Up: Outliner

Idstamps
========

   Idstamps (permanent ids) are associated with each cell and can be
used in hyperlinks that are maintained as cells are reordered in a file.
*Note Links::.  Idstamps may also be displayed in place of the outline
level relative ids.  Use {`C-c C-l id RET'}.

   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.

   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.


File: hyperbole.info,  Node: Editing,  Next: Viewing,  Prev: Idstamps,  Up: Outliner

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.
*Note Filling::, for the times when you need to refill a paragraph or to
control when filling occurs.

   Don't invoke editing commands with {`M-x command-name 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.

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


File: hyperbole.info,  Node: Adding and Killing,  Next: Relocating and Copying,  Prev: Editing,  Up: Editing

Adding and Killing
------------------

   {`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.  {`C-u C-j'} is handled specially.
It adds a single cell as a child of the current cell.  {`C-c a'} does
the same thing.  {`C-c p'} adds the cell as the successor of the
current cell's parent.

   {`C-c C-k'} kills the current cell and its entire subtree.  {`C-c
k'} kills the contents of a cell from point through the end of the
cell; it does not remove the cell itself.  {`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
{`C-y'}.


File: hyperbole.info,  Node: Relocating and Copying,  Next: Moving Around,  Prev: Adding and Killing,  Up: Editing

Relocating and Copying
----------------------

   "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.  "Promotion" is the
inverse operation.  Note that trees (cells and their entire
substructure) are promoted and demoted, not individual cells.

   Trees may be demoted or promoted by pressing {TAB} or {`M-TAB'}
respectively, as in most outliners today.  {`M-0 TAB'} and {`M-0
M-TAB'} demote and promote trees and additionally refill each cell that
is not specially marked to prevent refilling.  *Note 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.

   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.

`C-c c'
     Copy <tree> to be the successor of <cell>.

`C-u C-c c'
     Copy <tree> to follow as the first child of <cell>.

`C-c C-c'
     Copy <tree> to be the predecessor of <cell>.

`C-u C-c C-c'
     Copy <tree> to be the first child of the parent of <cell>.

`C-c m'
     Move <tree> to be the successor of <cell>.

`C-u C-c m'
     Move <tree> to follow as the first child of <cell>.

`C-c C-m'
     Move <tree> to precede <cell>.

`C-u C-c C-m'
     Move <tree> to be the first child of the parent of <cell>.

   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:

`C-c M-c'
     Copy  <tree> to a non-koutline buffer.

`C-c @'
     Copy a <tree> to an outgoing mail message.


File: hyperbole.info,  Node: Moving Around,  Next: Filling,  Prev: Relocating and Copying,  Up: Editing

Moving Around
-------------

   In addition to normal Emacs movement commands, you can move within a
cell or from one cell or tree to another.

`C-c ,'
     Move to the beginning of the current cell.

`C-c .'
     Move to the end of the current cell.

`C-c C-n'
     Move to the next visible cell, regardless of level.

`C-c C-p'
     Move to the previous visible cell, regardless of level.

`C-c C-f'
     Move forward to this cell's successor, if any.

`C-c C-b'
     Move backward to this cell's predecessor, if any.

`C-c C-d'
     Move to the first child of the current cell, if any.

`C-c C-u'
     Move to the parent cell of the current cell, if any.

`C-c <'
     Move to the first sibling at the current level within this tree.

`C-c >'
     Move to the last sibling at the current level within this tree.

`C-c ^'
     Move to the level 1 root cell of the current tree.

`C-c $'
     Move to the last cell in the tree rooted at point, regardless of
     level.


File: hyperbole.info,  Node: Filling,  Next: Transposing,  Prev: Moving Around,  Up: Editing

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.

   {`M-q'} or {`M-j'} refills a paragraph within a cell so that its
lines wrap within the current margin settings.  {`C-c M-q'} or {`C-c
M-j'} refills all paragraphs within a cell.  {`C-M-q'} or {`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.

   Set the variable, 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.


File: hyperbole.info,  Node: Transposing,  Next: Splitting and Appending,  Prev: Filling,  Up: Editing

Transposing
-----------

   The Koutliner move and copy commands rearrange entire trees.  The
following two commands, in contrast, exchange the locations of two
individual cells.

   {`C-c e'} prompts for two cell addresses and exchanges the cell
locations.

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

   {`M-0 C-c t'} exchanges the cells in which point and mark fall.
{`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.


File: hyperbole.info,  Node: Splitting and Appending,  Next: Inserting and Importing,  Prev: Transposing,  Up: Editing

Splitting and Appending
-----------------------

   You can split one cell into two adjacent sibling cells with {`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.  {`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.

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


File: hyperbole.info,  Node: Inserting and Importing,  Prev: Splitting and Appending,  Up: Editing

Inserting and Importing
-----------------------

   The elements of another buffer or file may be inserted into a
koutline as a set of cells by using the {`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.

   The elements from the original buffer are converted into kcells and
inserted as the successors of the current cell.  If {`C-u C-x i'} is
used, they are instead inserted as the inital children of the current
cell.

   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 {`M-x kotl-mode RET'} in
a non-koutline buffer or if you perform a generic file import as
described later in this section.

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

   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.  {`M-x kimport:file RET'} will select the
importation type based on the buffer or file name suffix of the file to
import.

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

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

   Star outlines are standard Emacs outlines where each entry begins
with one or more asterisk characters.  Use {`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.

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


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

Viewing
=======

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


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

Hiding and 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, *Note
View Specs::.

`C-c C-h'
     Hide (collapse) the tree rooted at point.

`C-c C-s'
     Show (expand) the tree rooted at point.

`C-c C-a'
     Show (expand) all of the cells in the outline.

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

`C-M-h'
     Hide the subtree at point, excluding the root cell.

`M-x kotl-mode:show-subtree'
     Show the subtree at point.  Use {`C-c C-s'} to achieve a similar
     effect.  The only difference is that it will expand the root cell
     too.

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

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

   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 {`M-RET'}.

