GZigZag User's Guide

$Id: ug.html,v 1.16 2002/12/19 17:36:39 Vegai Exp $

Tuomas Lukkalukka@iki.fi
Dept. of Mathematical Information Technology
University of Jyväskylä

This is the first attempt at an user's guide for GZigZag. It is not yet
complete and not a good tutorial but we will try to work on it. Patches
are gladly accepted!
This is work-in-progress: if there are any unclear parts, feel
free to ask me to clarify things.

Note that this document contains some formatting that is best rendered
using a true CSS1 standard-compliant browser such as Mozilla; however,
it should work reasonably well with any browser that can at least ignore
CSS that it doesn't understand. Unfortunately, Netscape Navigator 4.7,
for example, doesn't. Well, that's life...

A non-CSS version exists: you can try by compiling this
document from its WML version with some switches.. (if you came here
through the WWW, there should be an alternate link on the referring
page. However, I like
the pretty rendering by Mozilla so much that that's still the default.

Introduction

GZigZag is a free implementation of Ted Nelson's ZigZag structure.
The ZigZag structure is a revolutionary new way of storing information
in a computer, in that it provides a clear, extensible structure
that can be orthogonally laid over existing information.

This document attempts to help users to get started with GZigZag.
We start at the point where the user has gotten the program to start;
to get to that point, read the other documentation, including
the README files.
Note that this document does not attempt to cover designing sensible
structures: the "Gentle Introduction" document is for that purpose.
Here we only explain how to use the GZigZag implementation of the structure.

GZigZag is a moving target: we will try our best to keep this document
up to date but sometimes it will simply be forgotten and be out
of date. Please notify
us if this happens.

The save model

GZigZag currently stores data in directories, in which there is
one file per dimension and one or two extra files for the contents of the
cells.

In the new, cached and explicit model, the data is loaded at startup
and stored in memory until it is explicitly saved.
Pressing ctrl-S saves the changes.
And indeed, in GZigZag, it is only the changes that are saved:
like CVS, GZigZag stores all the previous saved versions implicitly
as well (XXX Because of timestamp problems, not usable yet).

Viewing and moving around

The initial display of two windows next to each other. To fit them
in this document, they have been horizontally resized but otherwise
the view is exactly what you should get when starting GZigZag.

The first figure shows the two windows next to each other that show
up when starting GZigZag on an empty space.
There are two cursors, the green and the blue cursor, which are
seen on the same cell, the home cell. From the home cell downwards
(poswards on d.2) is the system list, which contains
metainformation about the structure as well as keybindings, which
we shall return to later.

Let's move the blue cursor that defines the center of the
right-hand window down three steps. There are three different
ways to achieve this: either clicking on the "AllFlobViews" cell in the
right-hand window or by pressing the arrow down key thrice,
or (probably the most counterintuitive at first), pressing the
comma (,) key thrice.
This moves the view to the one shown in the next figure.
If your machine is fast enough, it should animate between each step
in order to better show how the cells move around.

The right-hand window, after moving the cursor down three step.
Both cursors are shown in both views, but
moving the blue cursor has moved the center of the right-side view
with it.

The last way is actually the recommended way since it allows you to
keep your hands on the main area of the keyboard at all times: mouse input
is not needed in GZigZag.
The direction keys for the X and Y directions are i, j, l and ','
for the right-hand view and
e, s, f and c for the left-hand view. If you look at the keyboard, you'll
see that they are arranged in two diamond patterns on the keyboard, one
for the left and one for the right hand to use.

If you look at the upper left-hand corner of the windows, you'll see
that X and Y are not the only dimensions here: there is also a third
dimension, Z, on which d.3 is shown by default.
A place in the default structure where d.3 is used can be found
by moving two steps right and one down from "AllFlobViews".
The depth cell is connected to other cells poswards on d.3.
The keys to move the right-hand view along the Z axis are k for poswards
and K (shift-k) for negwards.

A place where the third dimension shown is used, as discussed in
the text.

There are various different views to the structure, press 'v' or
shift-V to cycle through them in either window.

Before going on, you should train yourself to use these keys to move around
in the structure. The direction keys will be used in many places later
on in this guide, since they also form a vital part of the commands.

Editing the structure

This section does not give all the possible operations but
tries to give a subset that will be sufficient. Marking is not discussed.

Creating new cells

We shall start from the home cell.

Press 'n' (for "New cell") and 'l' (the direction key
discussed above) and a new cell is created left of the
blue cursor:

The same would work for the other view, you just need to
use the direction keys for the green cursor after the "n"
command.
For practice, move to the new cell (press 'l') and
press 'n' 'l', 'n' 'j', 'n' 'i' and 'n' ',' to create new cells on all
sides of the new cells. Note that when creating the new cell
leftwards, it is inserted between the first new cell and the
home cell:

Entering text

Now, press Tab and type in some text:

Tab moved you to the text editing mode which is pretty
much like familiar text entry mode in other systems:
the arrow keys move the insertion cursor and typing a character
inserts it.
Press Tab again to move out of text edit mode, and
the insertion cursor vanishes.
(NOTE: one planned feature is to have the background
change when in the edit mode - these pictures were taken
when this did not yet happen).

Try putting more text into the other cells.

Connecting and disconnecting cells

Now we get to the most important part of ZigZag: making
actual structures.
There are actually several different ways of connecting
cells but we shall only cover one because there's no
time to write this user's guide completely yet.

The way to connect two cells is to move the cursor of the
left-hand view (green) and the right-hand view (blue)
on the two cells, press '/' (slash) and a direction
to connect the two cells in.
Connect will fail if either of the two cells is connected
in that direction already, except if one of them is alone
in that dimension, in which case it is inserted next to
the other one.

Hopping

Hopping is a structural operation where cells are reorganized
along a rank.
It's easiest to figure out if you try it: press 'h' and a
direction key.

Alpha-shear

Another structural operation that can be very useful is
the alpha-shear, which changes a connection from the current cell
to another one in the same rank.

It is used by typing 'a' and two directions: first the connection
and then the direction into which the connection is to be moved.

Cell exchange

One more editing operation which helps a lot in making the structure
work the way you want it to. Press '%' (percent) to exchange
the connections of the two accursed cells in the visible X and Y
dimensions.
No other connections (Z or invisible) are touched.

Cloning

Cloning is an important structural operation in GZigZag,
as explained in the Gentle Introduction.
Basically, a clone of a cell is a cell poswards from that
cell on d.clone, but with the special property that their
contents are implied to be the same. Cloning is visually
shown by GZigZag by coloring the clones yellow and the original
light yellow.
A clone of a cell is made by placing the right or left cursor
on the cell and pressing 't' or shift-'t', respectively, and
a direction in which to place the clone.

Pressing shift-T 'l' creates a clone of the left (green) cursor
and places it right of the right-side (blue) cursor:

The system list

In this section, we explain briefly what the system list is, and
what you can do with it.

Basically, the system list contains information for the user interface
of GZigZag, i.e. the types of views, keybindings etc. It is possible to
configure GZigZag to look like something completely different
but you must act carefully: it's fairly easy to accomplish something like
the following:

Hmm, I want to rebind the keys completely. So let's delete the
previous binding list (click) and then I'll start making the
new bindings list (click.. click.... click....) oops, it's not
responding! Right, I just deleted the keybindings list so of
course it will not do anything when I press a key. Duh!

So remember that any changes to the system list are immediately
reflected in the behaviour of the user interface. At some point
we will probably create a mechanism for making delayed changes that you
can commit all at once but this is not yet in place.

The system list starts at the home cell of the space and continues on
d.system, but for your convenience those cells you will most likely want to
use are cloned to a d.2 rank starting from the home cell. The d.2 rank
is freely modifiable but changing the text in any of the system list cells,
or breaking the d.system rank can lead to dire consequences and you probably
shouldn't do that. At a later date, the system list will probably be locked
by default.

The cells on the system list simply enumerate the functions: the
actual cells that describe whatever are connected to the system list
cells on d.1.

Dimension list

The DimLists system list cell has connected to it on d.1
a cyclical rank on d.2, the dimension list.
This list contains the names of dimensions that the views
will cycle through when you press X, Y, Z (possibly with
shift/alt).

Adding a dimension simply involves creating a new cell and
typing the name into that cell. Likewise, deleting a cell
will delete the dimension from the list (but not currently the
connections along that dimension).
NOTE: don't rotate to an empty cell: this will possibly
cause problems: at the very least, a raster error.

The dimension cursors of the different views
are a variety of pink shades.
These dimension selectors of the different views are actually
generic cursors so it would be possible to have different
dimension lists for each X, Y and Z of each view but at the moment
it's not possible to repoint them to a different list except by
trickery. We will probably provide a mechanism for this.

Views

The views are defined on three different cells in the system list:
Views,
AllViews and
CellViews.
These cells have different functions.

The windows cycle through different views by moving in the
list below Views, much like the dimensions are
cycled on the list below DimLists.
The cells below Views describe one particular
view.

The cells below Views are actually clones of
cells below AllViews that actually give those
views' parameters. For instance, the Vanishing and StretchVanishing
rasters use the same Java code but have different parameters
in the structure below AllViews.

The structure below AllViews is simple:
it is a list of the clonable cells (which name the views, but
the name is just decoration for the user: the real information
is in the structural operation of cloning), which are
connected on d.1 to the structure that actually defines the view.

The defining cells are structure along the ZOb structure,
explained better elsewhere (XXX).

Not all views in AllViews are by default cloned to the
main
Views
list for two reasons: first, there are too many views to just cycle
through, and second: some are not yet very stable or useful.
Experimentation with them is encouraged, though.

CellViews
is similar to
Views and
AllViews
in that it also contains a list of cellviews, i.e. how to render
one cell.
This is because currently there are not enough different cellviews
that having a separate list of more possibilities is not necessary.

Bindings

Actions

The keystrokes.

This is a list of (almost) all the currently available keystrokes
in the default bindings. As explained above, it is simple to modify the
bindings.

Default bindings for the orthogonal rasters

$Id: ug.html,v 1.16 2002/12/19 17:36:39 Vegai Exp $

These are still being discussed and are not yet frozen. Note that there is a
panic button: if there is no binding for ESC, it invokes undo.

Key(s)

Binding

Ctrl-S

Commit the current changes to disk.

ijl,kK

Up-left-right-down-Z+-Z- in view 1.

esfcdD

Up-left-right-down-Z+-Z- in view 0.

ndir

Create a new cell in given direction

bdir

Break a connection in given direction

hdir

Hop the accursed cell in the given direction.
Hopping means simply switching the places of
the accursed and the indicated cells in that
rank, no other ranks are affected by
the operation.

xyz

Show next dimension on list on X/Y/Z in view 1

Alt-xyz

Show previous dimension on list on
X/Y/Z in view 1

XYZ

Show next dimension on list on X/Y/Z in view 0

Alt-Shift-XYZ

Show previous dimension on list
on X/Y/Z in view 0

/dir

Connect the center cells of the right and left views
in the given direction, if no connections will be
broken by this.

~

Exchange the cursor positions of the two views (no
other view parameters are changed).

Delete

Delete the center cell of view 1 and move the cursor.
Cursor move tries following directions in order:
X-, X+, Y-, Y+, Z-, Z+ and finally goes to home cell.

m

Mark or unmark the cell in view 1

Enter

Execute cell in view 0, with the cell in view 1
as parameter

v

Change raster in view 1.

V

Change raster in view 0.

Alt-v

Change raster in view 1 backwards.

Alt-V

Change raster in view 0 backwards.

Home

Go home: move view 1 cursor to homecell.

Esc

Move both views to home and reset dimensions to first
three dimensions on first dimlist.

0123456789

Insert the given number into the number insert buffer
for cell IDs.

g

Move view 1 to cell whose ID number was in buffer

G

Move view 0 to cell whose ID number was in buffer

Backspace

Remove one number from the number insert buffer

tdir

Clone the view 1 cursor to given direction (may be
in either view).

Tdir

Clone the view 0 cursor to given direction (may be
in either view).

%

Exchange the X and Y connections of the two
accursed cells with each other.

o

Go to original (rootclone, cell from which accursed
cell was cloned) in view 1.

O

Go to original (rootclone, cell from which accursed
cell was cloned) in view 0.

End dir

Move to te end of the rank in the given direction.

<

Set the cursor of the left-hand-view to the cell the
right-hand view is pointing to.

>

Set the cursor of the right-hand-view to the cell the
left-hand view is pointing to.

-dir

Connect the current view1 cursor into marked cells
in given direction. Direction must be in view 1.

Alt-c

Switch into "curseling" (cursor selection) mode (see
below).

adirdir

Monochug: change one connection. See above.

Text edit mode

Key(s)

Binding

Esc or Tab

Switch off text edit mode

Delete

Delete one character after cursor

Backspace

Delete one character before cursor

Left, Right

Move the cursor within the current cell

Home

Move the cursor to the beginning of the text in
the current cell

End

Move the cursor to the end of the text in
the current cell

Ctrl-A

Move the cursor to the beginning of the current
line in the text of the current cell

Ctrl-E

Move the cursor to the end of the current line
in the text of the current cell

Enter

Insert a line separator in the text before the cursor

any key producing a printable character

Insert the character in the text before the cursor

Curseling (Cursor selection)

As an intermediate for multiple cursors, there is a key binding mode for
"curseling:" cursor selection. In the standard keybindings, Alt-c is used
to go into this mode, which by default supports the following key bindings:

Key(s)

Binding

Tab, Spacebar, Alt-c or Esc

Select this cursor, quit curseling mode.

Left, Right, jl

Select next/last cursor in system cursor list
in view 1.

Up, Down, i,

Select next/last cursor positioned on the same cell
in view 1.

sfec

Like Left/Right/Up/Down, operating on view 0.

Note that you can create four additional cursors through executing the
CreateCursors command, found in the action list, by centering the left view
on it and hitting Enter.