7. 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. See section 7.3 Autonumbering.

Cells also store their time of creation and the user who created the cell. User-defined attributes may also be added to cells. See section 7.8 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.

See section C. Outliner Keys, for a full summary of the key bindings and commands available in the outliner.

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

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

See section 7.3 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.

7.3 Autonumbering

See section 7.5.1 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")

7.4 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. See section 7.7 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.

7.5 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. See section 7.5.4 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.

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

7.5.2 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. See section 7.5.4 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.

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

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

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

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

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

7.6 Viewing

The Koutliner has very flexible viewing facilities to allow you to effectively browse and study large amounts of material.

7.6.1 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, 7.6.2 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}.

7.6.2 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. See section 7.7 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 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.

7.7 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, Creation Via Action Key Drags. 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:

@bullet{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.

@bullet{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.

@bullet{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.

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

@bullet{idstamp}

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

@bullet{creator}

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

@bullet{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. See section 7.5.4 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.

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

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.