Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Koutline Interactive Documentation #413

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Koutline Interactive Documentation #413

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a10842
Add initial draft of koutliner documentation
chookity-pokk Dec 6, 2023
a4351cc
Removed old file
chookity-pokk Dec 6, 2023
efee55a
Rough finish of koutliner interactive demo
chookity-pokk Jan 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 217 additions & 0 deletions interactive-demos/KOUTLINER.kotl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
;; -*- Mode: kotl -*-
"Kotl-4.0" ;; file-format

1. The Koutliner is part of the Hypberbole information management
system.

2. The Koutliner produces hierarchically structered files
consisting of trees of cells.


2a. A Cell is an element of the outline which has its own display
label and unique, permanent identifier (idstamp).


2b. Idstamps support the creation of hyperlinks to cells which
are maintained as the structure of the outline changes.


3. Starting a Koutline:

3a. First things first, go ahead and create a file that has the
extension ".ktol". It should start with the 1. at the
top. You'll just go ahead and add some text to that first
cell, and when you are ready to add another cell just use {C-j}.


3b. Using {C-j} launches a new cell as a sibling after the
current cell. To add a cell that is a non-negative prefix
argument, use {C-u C-j} or {C-c a} which will add the cell as
a child of the current cell. Examples of this are used above.
Using {C-j} on 1. creates 2. whereas using {C-u C-j} on 2. creates 2a.
From there though we use {C-j} again to create 2b.

3c. Now that we know how to create more cells and add a child to
the current cell, lets talk about the autonumbering. Full
auto-numbering in Augment (1a2) or legal (1.1.2) formats. You
can change the format by using {C-c C-l} and select and
option. For the purpose of this I am using the legal format
because I find it easier to refer to, but feel free to use
whichever you are more comfortable with.


3d. Great, we got our auto-numbering how we want it, let's talk
label seperators. By default the Koutliner seperates labels
from cell contents by two spaces. If you would like to change
the serperator for the current outline, use {C-c M-l}. Go
ahead and try that out and change it to ": " (no quotation
marks). Feel free to change it back if you'd like, or change
it to anything else! Now let's say you really like having the
seperator being ": ", and would like that to be the default
for all Koutliner files from now on, you can change that with
{C-u C-c M-l}.


3e. We've covered how to create cells, change the numbering and
change the seperators, now it's time to talk about how to delete
cells. To test this out, create a child of this cell {C-u C-j},
and when it takes you to that cell you realize that you really
don't need it. Well, luckily deleting it is as simple as {C-c C-k}.
Go ahead and run that, and the cell will be deleted!


3f. Now lets say you simply want to get rid of the contents of a
cell without getting rid of the cell as a whole. Go ahead and
run {C-u C-c k}. You don't want to delete all the contents of
the cell, just from that cursor to the end of it? Well
Koutliner has got you covered with {C-c k}!


3g. Sometimes you don't want to delete a cell, you just want to
move the position of it so your Koutline has a better
flow. Let's go ahead and test this by creating two children
of our current cell. With {C-u C-j} then {C-j}.


3g1. Secondly we want this cell second.

3g2. Firstly, we want this cell first. To make that happen we
use {C-c m} which will prompt us with which cell we want
to move, and which cell we want afterwards. Go ahead and
change the positions of these two cells.

3h. Now let's say we want to promote/demote our cells. We can do
that with {M-TAB} and {SHIFT-TAB}. This will also move the
children of the parent cell. To test this out, let's go ahead
and do {M-TAB} to the below cell!

3i. Movement within a Koutline file

3i1. Now that we have enough knowledge to get the basic
movement down, here is a list of commands for cursor
movement,
{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 prev 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 first child of current cell, if any.

{C-c C-u} - Move to parent cell of current cell, if any.

{C-c <} - Move to the first sibling at the current level.
{C-c >} - Move to the last sibling at the current level.

{C-c ^} - Move to the level 1 root of the current tree.
{C-c $} - Move to the last cell in the tree rooted at point.

3i2. And here is a list of tree movement commands.
{[M-down]} - Move current tree past prefix arg same level trees.
{[M-up]} - Move current tree back prefix arg same level trees.

{C-c c} - Copy <tree> to follow as sibling of <cell>.
{C-u C-c c} - Copy <tree> to follow as first child of <cell>.

{C-c C-c} - Copy <tree> to precede <cell>.
{C-u C-c C-c} - Copy <tree> as first child of the parent of <cell>.

{C-c m} - Move <tree> to follow as sibling of <cell>.
{C-u C-c m} - Move <tree> to follow as first child of <cell>.

{C-c C-m} - Move <tree> to precede <cell>.
{C-u C-c C-m} - Move <tree> as first child of the parent
of <cell>.


4. Finally, org table support

4a. You have to use the first line of your cell to label the
tables because the tables can only have blank spaces to their
left

4b. Here are a couple of examples

|--------------------------------+---------------------------|
| Promotion Inside Org Table | Demotion Inside Org Table |
|--------------------------------+---------------------------|
| {M-0 Shift-TAB} or {M-0 M-TAB} | {M-0 TAB} |
| {C-c C-,} | {C-c C-.} |
| {C-c C-<} | {C-c C->} |
|--------------------------------+---------------------------|

|-----------------------------+----------------------------|
| Promotion Outside Org Table | Demotion Outside Org Table |
|-----------------------------+----------------------------|
| {Shift-TAB} or {M-TAB} | {TAB} |
| {M-left} | {M-right} |
| {C-c C-,} | {C-c C-.} |
| {C-c C-<} | {C-c C->} |
|-----------------------------+----------------------------|

To toggle table editing on/off, press the Action Key on any
of the table | symbols and then edit the same way you would
any Org Table.

5. For more information please check out "EXAMPLE.kotl" or
{C-h h k i}


"ben" ;; kvspec:current
38 ;; id-counter
alpha ;; label-type
4 ;; label-min-width
". " ;; label-separator
3 ;; level-indent

;; depth-first kcell attributes
[[0
(creator "[email protected]" create-time "20231206:22:01:16" id-counter 38)]
[1
(creator "[email protected]" create-time "20231206:22:01:16")]
[2
(creator "[email protected]" create-time "20231206:22:01:49")]
[4
(creator "[email protected]" create-time "20231206:22:02:12")]
[5
(creator "[email protected]" create-time "20231206:22:02:21")]
[7
(creator "[email protected]" create-time "20231206:22:03:23")]
[9
(creator "[email protected]" create-time "20231206:22:03:34")]
[10
(creator "[email protected]" create-time "20231206:22:03:42")]
[11
(creator "[email protected]" create-time "20231206:22:05:32")]
[12
(creator "[email protected]" create-time "20231206:22:07:24")]
[13
(creator "[email protected]" create-time "20231206:22:07:53")]
[14
(creator "[email protected]" create-time "20231206:22:07:54")]
[15
(creator "[email protected]" create-time "20231206:22:08:19")]
[17
(creator "[email protected]" create-time "20231206:22:08:54")]
[18
(creator "[email protected]" create-time "20231206:22:09:04")]
[26
(creator "hank@hank-archbtw" create-time "20240107:20:53:30")]
[22
(creator "hank@hank-archbtw" create-time "20240107:20:40:18")]
[24
(creator "hank@hank-archbtw" create-time "20240107:20:40:46")]
[29
(creator "hank@hank-archbtw" create-time "20240107:21:00:02")]
[33
(creator "hank@hank-archbtw" create-time "20240107:21:02:34")]
[36
(creator "hank@hank-archbtw" create-time "20240107:21:03:08")]
[37
(creator "hank@hank-archbtw" create-time "20240107:21:04:09")]
[38
(creator "hank@hank-archbtw" create-time "20240107:21:07:25")]
nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil nil]