2 "Kotl-4.0" ;; file-format
4 1 The outliner is a part of the Hyperbole information management system.
5 It produces hierarchically structured files consisting of trees of
8 1a A cell is an element of the outline which has its own display label
9 and unique, permanent identifier (idstamp).
11 1b Idstamps support the creation of hyperlinks to cells which are
12 maintained as the structure of an outline changes.
14 2 Features implemented include:
16 2a Full on screen editing (just like a Macintosh). Click to type in a
17 node (we call them cells) and just enter text. Structure is
18 automatically maintained for you. All of the standard Emacs editor
19 command set is supported both through keyboard and mouse interaction.
21 2b Advanced outline processing
23 2b1 Autonumbering: Full auto-numbering in Augment (1a2) or legal
24 (1.1.2) formats. Augment style is the default. Single level
25 autonumbering (only the last part of the level number is shown),
26 as commonly seen in outliner products, is also available, though
27 it has not been tested very much and so is not recommended. Use
28 {C-c C-l ?} to see the full set of label types and to select a
31 2b2 Label Separators: By default, the outliner separates labels from
32 cell contents by two spaces. If you want to change the separator
33 for the current outline, use {C-c M-l}. {C-u C-c M-l} will
34 additionally change the default separator value used when new
35 outlines are created. For example, use the value ". " to get a
36 trailing period after each cell label. The separator must be at
37 least two characters long.
39 2b3 Cell Creation: {C-j} adds a new cell as a sibling following the
40 current cell. A non-negative prefix argument, {C-u C-j} or {C-c
41 a} adds the cell as a child of the current cell. {C-c p} adds the
42 cell as the sibling of the current cell's parent.
44 2b4 Cell and Tree Deletion: {C-c C-k} kills the current cell and its
45 entire subtree. {C-c k} kills the contents of a cell from point
46 through the end of the cell. {C-u C-c k} kills the entire
47 contents of the cell regardless of the location of point. You may
48 then yank the contents into another cell with {C-y}.
50 2b5 Tree Demotion and Promotion: Trees may be demoted or promoted by
51 hitting {TAB} or {M-TAB} respectively, as in most outliners today
52 (their sub-levels move with them). {M-0 TAB} and {M-0 M-TAB} will
53 demote and promote trees and will additionally refill each cell
54 which has not been specially marked to prevent refilling.
56 You can also use a command line interface and either enter cell
57 ids or select the cells to operate upon by using your mouse.
59 2b6 Cell and Tree Filling: {M-q} or {M-j} refills a paragraph within a
60 cell so that its lines wrap within the current margin settings.
61 {C-c M-q} or {C-c M-j} refills all paragraphs within a cell.
62 {C-M-q} or {C-M-j} refills all cells within a tree.
64 Set the variable, kotl-mode:refill-flag, to t if you want moving,
65 promoting, demoting, exchanging, splitting and appending cells to
66 also automatically refill each cell.
68 2b7 Cursor Movement: In addition to normal Emacs movement commands,
69 you can move within a cell or from one cell or tree to another.
71 {C-c ,} - Move to the beginning of the current cell.
72 {C-c .} - Move to the end of the current cell.
74 {C-c C-n} - Move to the next visible cell, regardless of level.
75 {C-c C-p} - Move to the prev visible cell, regardless of level.
77 {C-c C-f} - Move forward to this cell's successor, if any.
78 {C-c C-b} - Move backward to this cell's predecessor, if any.
80 {C-c C-d} - Move to first child of current cell, if any.
82 {C-c C-u} - Move to parent cell of current cell, if any.
84 {C-c <} - Move to the first sibling at the current level.
85 {C-c >} - Move to the last sibling at the current level.
87 {C-c ^} - Move to the level 1 root of the current tree.
88 {C-c $} - Move to the last cell in the tree rooted at point.
90 2b8 Tree Movement and Copying: Entire outline trees can be moved or
91 copied with single commands. Simply invoke the desired command
92 and then double click with the Action Key on the desired root cell
93 for each argument for which you are prompted.
95 Copying and moving only work within a single outline right now, so
96 don't use them to move trees across different outline files. You
97 can, however, copy an outline tree to a non-outline buffer with:
98 {C-c M-c} - Copy a koutline tree to a non-koutline buffer.
99 {C-c @} - Copy a koutline tree to an outgoing mail message.
101 {C-c c} - Copy <tree> to follow as sibling of <cell>.
102 {C-u C-c c} - Copy <tree> to follow as first child of <cell>.
104 {C-c C-c} - Copy <tree> to precede <cell>.
105 {C-u C-c C-c} - Copy <tree> as first child of the parent of <cell>.
107 {C-c m} - Move <tree> to follow as sibling of <cell>.
108 {C-u C-c m} - Move <tree> to follow as first child of <cell>.
110 {C-c C-m} - Move <tree> to precede <cell>.
111 {C-u C-c C-m} - Move <tree> as first child of the parent of <cell>.
113 If you have mouse support under Hyperbole, you can move entire
114 trees with mouse clicks. Simply click the Assist Key within the
115 indentation to the left of a cell text and you will be prompted
116 for a tree to move. Double click the Action Key within the body
117 of the root cell of the tree to move and then double click within
118 the body of the root cell of the tree you want it to follow.
120 2b9 Cell Transposition: The move and copy commands rearrange entire
121 trees. The following two commands exchange the locations of two
124 2b9a {C-c e} prompts for two cell addresses and exchanges the cells.
126 2b9b {C-c t} does not prompt. It exchanges the current and
127 preceding cells. If there is no preceding cell it exchanges
128 the current and next cell.
130 {C-c t} with a prefix argument of zero exchanges the cells in
131 which point and mark fall.
133 {C-c t} with a non-zero numeric prefix argument, N, moves
134 the current tree past maximally the next N visible cells. If
135 there are fewer visible, it makes the current cell the last
138 2b10 Cell Splitting: You can split one cell into two adjacent cells
139 with {C-c s}. This leaves the cell contents preceding point in
140 the current cell, minus any trailing whitespace, and moves the
141 contents following point to a new sibling cell which is inserted
142 into the outline. {C-u C-c s} adds the new cell as the first
143 child of the original cell, rather than as its sibling.
145 All cell attributes in the original cell are propagated to the new
148 2b11 Cell Appending: {C-c +} appends the contents of a specified cell
149 to the end of another cell.
151 2b12 Hiding and Showing: Individual cells, branches, or particular
152 levels in the outline may be hidden or shown. These commands work
153 even when an outline buffer is read-only, e.g. when its file is
154 not checked out of a version control system yet.
156 2b12a {C-c C-h} - Hide (collapse) tree rooted at point.
157 {C-c C-s} - Show (expand) tree rooted at point.
159 {C-c C-a} - Show (expand) all cells in the outline.
160 {C-x $} - Show all cells down to a particular level. The
161 user is prompted for the level or a prefix
162 argument may be given.
164 {C-M-h} - Hide subtree at point, excluding root.
165 {M-x kotl-mode:show-subtree} - Show subtree at point.
167 {C-c C-o} - Overview, show only first line of outline cells.
168 {C-c C-t} - Top-level, hide all cells below level 1 and show
169 only the first line of each level 1 cell.
171 2b12b A click or press of the Action Key within a cell's body, but
172 not on a button, toggles between hiding and showing the tree
175 2b13 Cell Identifiers: Permanent ids are associated with each cell and
176 can be used in hyperlinks that are maintained as cells are
177 reordered in a file. (These ids may also be displayed in place of
178 the outline level relative ids. Use {C-c C-l id RET}.) Permanent
179 ids are numbered from 0, where 0 is the root node of the entire
180 outline. This node is never visible within the outline.
181 Permanent ids always begin with a 0, as in 012, to distinguish
182 them from relative ids.
184 2b14 Cell Attributes: Each cell has its own attribute list. The
185 attribute lists for the cells in the tree rooted at point can be
186 displayed by pressing the Assist Key. {C-c h} prompts for a kcell
187 id and displays its attributes. {C-u C-c h} prompts for a kcell
188 id and displays the attributes for it and its subtree; use 0 as
189 the kcell id to see attributes for all visible cells in the
192 Use {C-c C-i} to add an attribute or to modify an existing
193 attribute to the cell at point.
195 2b15 File Insertion: The elements of another buffer or file may be
196 inserted into a koutline as a set of cells by using the {C-x i}
197 command. When prompted, you may use a buffer name or file name
198 from which to insert.
200 2b15a The cells will be inserted as the successors of the current
201 cell unless {C-u C-x i} is used and then they are inserted as
202 the initial children of the current cell.
204 2b15b See the documentation for the variables, kimport:mode-alist and
205 kimport:suffix-alist, for information on mode and
206 suffix-specific conversions performed on files before they are
207 inserted. This same conversion process applies if you invoke
208 {M-x kotl-mode RET} in a non-koutline buffer or if you perform
209 a generic file import as described in <@ 2b16>.
211 2b15c Use {M-x kotl-mode:insert-file-contents RET} to insert the
212 entire contents of a file into the current cell at the location
215 2b16 File Importation: The outliner presently supports conversion of
216 three types of files into koutline files. You can choose to
217 import a file into an existing koutline, following the tree at
218 point, or to create a new koutline of the imported file contents.
219 {M-x kimport:file RET} will select the importation type based on
220 the buffer or file name suffix of the file to import. Use one of
221 the following commands if you want to control the type of
222 importation explicitly.
226 2b16a1 In a text buffer, use {M-x kotl-mode RET} to convert
227 the buffer into a koutline in-place. You will lose the old
228 format of the buffer when you do this.
230 2b16a2 Use {M-x kimport:text RET} and you will be prompted for a
231 text buffer or file to import and the new koutline buffer or
232 file to create from its text. It will also import the
233 contents, attributes and level structure of cells from a
236 With this command, your original file remains intact.
238 2b16b Star Outline Files: Star outlines are standard Emacs outlines
239 where each entry begins with one or more asterisk characters.
240 Use {M-x kimport:star-outline RET} and you will be prompted
241 for the star outline buffer or file to import and the new
242 koutline buffer or file to create.
244 2b16c Augment Files Numbered on the Right-Side: (Skip this if you are
245 unfamiliar with this sort of file.) Files exported from the
246 Augment system as text often have alphanumeric statement
247 identifiers on the right side.
249 Use {M-x kimport:aug-post-outline RET} and you will be prompted
250 for the augment buffer or file to import and the koutline to
253 2b17 View Specification: Flexible views of outlines may be specified
254 with succinct single character codes.
256 2b17a The current view spec is shown in the modeline after the buffer
257 name, delimited by <|>.
259 2b17b The current view spec is saved whenever the outline is saved.
260 The next time the outline is read in, this will be the initial
261 view. The standard initial viewspec is <|ben>.
263 2b17c {C-c C-v} prompts for a view spec string in which the following
264 codes are valid. Any invalid characters in a view spec are
267 2b17c1 a: Show all cell levels and all lines in cells.
269 2b17c2 b: Turn on blank lines between cells. Without this code,
270 blank lines will be turned off. You can also use the
271 {C-c b} key binding to toggle line numbers on and off
272 independent of any other view settings.
274 2b17c3 cN: Hide any lines greater than N in each cell. 0 means
275 don't cutoff any lines.
277 2b17c4 e: Show ellipses when some content is hidden.
279 2b17c5 lN: Hide cells at levels deeper than N. 0 means don't hide
282 2b17c6 n: Turn on the default label type.
283 n0: Display idstamps.
284 n1: Display alpha labels.
285 n2: Display partial alpha labels (don't use this).
286 n.: Display legal labels.
287 n*: Display star labels.
288 n~: Turn off labels. (n viewspec is removed from modeline).
290 2b17d Try a view spec of 'c2l1' to turn off blank lines, to clip each
291 cell after its second line, and to hide all cells below level
294 2c Hyperlinks may be embedded in cells and may refer to other cells.
295 Explicit Hyperbole buttons may be created as usual via mouse drags,
296 see "(hyperbole.info)By Dragging". A klink is a special implicit
297 link button that jumps to a specific outline cell.
299 2c1 Here are three klink examples:
301 2c1a <@ 2b=06> jumps to the cell within this outline which has
302 permanent id `06' and relative id `2b', namely the preceding
303 sibling of this cell's parent. <@ 06> does the same thing, as
304 does <@ 2b>, though this latter form will not maintain the link
305 properly if the cell is moved elsewhere within the outline.
307 2c1b <EXAMPLE.kotl, 3=012 |c1e> displays the named file, starting at
308 the unimplemented features section whose permanent identifer is
309 012, with the view specification of: blank lines turned off,
310 cutoff after one line per cell, and show ellipses for cells or
311 trees which are clipped.
313 2c1c <|ben> is a klink consisting of just a view specification.
314 When activated, it sets the view in the current outline to
315 display blank lines, ellipses following collapsed lines and
316 standard alphanumeric numbering.
318 2c2 There are a number of easy ways to insert klinks into koutlines.
319 If you have mouse support under Hyperbole, simply click the Action
320 Key within the indentation to the left of a cell text. If you
321 then double click on some cell, a link to that cell will be
322 inserted where you started. From a keyboard, use {C-c l} when in
323 a koutline or {C-h h o l} when not in a koutline to insert a
326 2d The outliner code runs on virtually any UNIX system. It supports dumb
327 terminal, X window, and NEXTSTEP (Display Postscript) displays.
329 3 Features remaining to be implemented:
331 3a Branch handling commands (all cells at same level).
333 3b Copying a single cell without its subtree.
335 3c Replacing one cell or one tree with another.
337 3d Transposing two trees, rather than two cells.
339 3e A small amount of work remains to enable setting different per level
340 fonts and colors, so that outline levels are visually easy to
343 3f Flexible view handling has been only partially implemented.
345 3g The code to export from koutlines to other formats has not yet been
346 written. Exporting to HTML, for example would be very useful.
349 "ben" ;; kvspec:current
353 " " ;; label-separator
356 ;; depth-first kcell attributes
358 (creator "weiner@oakhill.sps.mot.com" create-time "19951102:11:15:03" id-counter 74 file "/usr1/dingus/weiner/hypb/kotl/EXAMPLE.kotl")]
360 (creator "weiner" create-time "19940104:17:38:28")]
362 (creator "weiner@pts.mot.com" create-time "19940610:16:43:55")]
364 (creator "weiner@pts.mot.com" create-time "19940610:16:44:03")]
366 (creator "weiner" create-time "19940104:17:38:29")]
368 (creator "weiner" create-time "19940104:17:38:29")]
370 (creator "weiner" create-time "19940104:17:38:29")]
372 (creator "weiner" create-time "19940104:17:38:29")]
374 (creator "weiner@oakhill.sps.mot.com" create-time "19951028:04:29:13" no-fill t)]
376 (creator "weiner" create-time "19940104:17:38:29")]
378 (creator "weiner" create-time "19940306:18:11:43")]
380 (creator "weiner" create-time "19940104:17:38:29")]
382 (creator "weiner@oakhill.sps.mot.com" create-time "19950614:21:35:17")]
384 (creator "weiner@pts.mot.com" create-time "19940610:22:00:46")]
386 (creator "weiner" create-time "19940127:22:41:42")]
388 (creator "weiner@pts.mot.com" create-time "19940610:16:31:28")]
390 (creator "weiner@pts.mot.com" create-time "19940610:18:55:09")]
392 (creator "weiner@pts.mot.com" create-time "19940610:18:55:57")]
394 (creator "weiner@pts.mot.com" create-time "19940610:16:31:29")]
396 (creator "weiner@oakhill.sps.mot.com" create-time "19951022:22:59:26" no-fill t)]
398 (creator "weiner" create-time "19940104:17:38:29")]
400 (creator "weiner" create-time "19940128:22:50:44")]
402 (creator "weiner" create-time "19940128:22:50:54")]
404 (creator "weiner" create-time "19940104:17:38:29")]
406 (creator "weiner" create-time "19940129:00:27:59")]
408 (creator "weiner@oakhill.sps.mot.com" create-time "19951026:08:32:57" no-fill t)]
410 (creator "weiner@oakhill.sps.mot.com" create-time "19951030:19:18:49" no-fill t)]
412 (creator "weiner@oakhill.sps.mot.com" create-time "19951030:19:19:40" no-fill t)]
414 (creator "weiner@oakhill.sps.mot.com" create-time "19951030:19:23:09" no-fill t)]
416 (creator "weiner@oakhill.sps.mot.com" create-time "19951026:19:31:34" no-fill t)]
418 (creator "weiner@oakhill.sps.mot.com" create-time "19951026:19:33:01" no-fill t)]
420 (creator "weiner@oakhill.sps.mot.com" create-time "19951029:06:24:35" no-fill t)]
422 (creator "weiner@oakhill.sps.mot.com" create-time "19951029:06:24:27" no-fill t)]
424 (creator "weiner@oakhill.sps.mot.com" create-time "19951026:19:33:08" no-fill t)]
426 (creator "weiner@oakhill.sps.mot.com" create-time "19951026:19:33:15" no-fill t)]
428 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:05:55:19" no-fill t)]
430 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:10:07:06" no-fill t)]
432 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:10:07:26" no-fill t)]
434 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:05:55:55" no-fill t)]
436 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:08:56:41" no-fill t)]
438 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:05:57:26" no-fill t)]
440 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:05:58:31" no-fill t)]
442 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:08:57:09" no-fill t)]
444 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:05:59:59" no-fill t)]
446 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:06:00:48" no-fill t)]
448 (creator "weiner@oakhill.sps.mot.com" create-time "19951023:06:05:50" no-fill t)]
450 (creator "weiner" create-time "19940128:03:56:23")]
452 (creator "weiner" create-time "19940128:22:36:54")]
454 (creator "weiner@oakhill.sps.mot.com" create-time "19951024:03:40:05" no-fill t)]
456 (creator "weiner@oakhill.sps.mot.com" create-time "19951024:03:40:13" no-fill t)]
458 (creator "weiner@oakhill.sps.mot.com" create-time "19951024:03:40:42" no-fill t)]
460 (creator "weiner" create-time "19940104:17:38:29")]
462 (creator "weiner" create-time "19940104:17:38:29")]
464 (creator "weiner" create-time "19940104:17:38:29")]
466 (creator "bweiner@pts.mot.com" create-time "19940728:21:56:49")]
468 (creator "weiner@pts.mot.com" create-time "19940610:16:49:34")]
470 (creator "weiner@pts.mot.com" create-time "19940610:16:50:02")]
472 (creator "weiner@pts.mot.com" create-time "19940610:16:50:13")]
474 (creator "weiner" create-time "19940104:17:38:29")]
476 (creator "weiner" create-time "19940104:17:38:29")]
478 (creator "weiner@oakhill.sps.mot.com" create-time "19951101:21:56:21" no-fill t)]
479 nil nil nil nil nil nil nil nil nil nil nil nil nil nil]