What you need to know to use Semantic Synchrony
(Note to authors: Edit this document not in the wiki, but rather in the graph, at :JwGnhoHw23PfCIyp:.)
The list of critical keyboard shortcuts (there are only 25!) might be helpful while you read this.
SmSn lets you edit a knowledge graph.
A knowledge graph in SmSn consists of passages of writing called notes, connected by relationships. [It will be expanded to include other data types -- pictures, sound, ..]
The text of a note can have any length. Each note has a unique ID, which is a set of 16 alphanumeric characters. The ID can be thought of as the note's address in the graph. Note IDs are usually provided between ":" marks, so they look something like this: :axMIDS0EmKQXqMnm:. In addition to text content and ID, notes have other properties, described later.
There is (currently) only one kind of relationship. Each relationship starts at one note and ends at another. If there is a relationship from x to y, we say that x is the parent of y, and y is the child of x.
Children tend to be "about" their parents, but you can arrange them however you want. Two notes can both be each others' parent, and a note can be its own parent. Each note can be a child of any of the other notes. A note can be its own child. A note can have many parents and many children.
The parental relationship naturally gives rise to "trees". If there are children, then there are grandchildren, and great-grandchildren, etc. For instance, one note might say things to do. One of its children might be things to do on the computer, another things to do on Tuesday. We say that both of those children are "under" the "parent" things to do. The children of things to do on the computer might include email my state representative and look for musical instruments on Craigslist. Those two children of things to do on the computer are "grandchildren" of things to do.
In a traditional table of contents or filesystem, there is also a useful "tree" concept. However, in contrast to those, the graph allows multiple, overlapping trees to coexist. By having multiple parents, a note in the graph can effectively "be" in more than one "place" at once. Whereas in a traditional filesystem, files can become so far apart that they get lost, in a graph, any two things that should be neighbors can be neighbors, forever and ever, simply by adding a relationship from one to the other. There is no red shift, no rule of entropy, no universal expansion ripping the data apart.
Here is an example of a shortcut in Emacs: C-x u. That can be read as saying "press Ctrl-x, then press u". The two modifiers are written C (for Ctrl) and M (for Alt).
At least, it's that easy in Linux. On Windows or Mac, the C and M modifier keys might be different.
Emacs starts with one window. (It lets you create more, as described in a later section.) A window in Emacs provides a view of a "buffer". A window only views one buffer at a time. There can be many open buffers even when there is only one window.
A buffer in Emacs is a collection of text. A buffer can represent a file, or a folder in your hard drive, or a list of messages (e.g. warnings and errors) from Emacs to the user -- Emacs is flexible that way. Emacs also lets you keep the same buffer open in two separate windows, which is handy for comparing two distant parts of the same buffer.
Each view of the graph generated in smsn-mode is assigned its own buffer. If you view the buffer list (C-x C-b), it can look like you've got a lot of files open, but they're all just views onto the same graph. When you run a search in smsn, its search results are presented in a new buffer.
The two most commonly used views are forward-view and backward-view. Both of them presume some root note, which could be thought of as the view's focus, or center. In forward-view, the root's children are visible. The root is a note, and so are the children, but whereas the children are in the buffer, the root is only visible as the title of the buffer.
Backward-view displays the root's parents instead of its children. The root (and therefore the buffer title) remain the same.
You can view the forward-tree or the backward-tree to a depth between 1 and 7. A forward-view with a depth of 1 shows only children; depth 2 shows children and grandchildren; etc.
If a note is its own parent, then when it is the root of the view, it will be both the title of the view and one of the members of the view.
SmSn consists of two parts. The client or front end, Emacs in smsn-mode, is the part the user interacts with. The back end or server is the part that hosts the graph. The front end displays a window of text representing some portion of the graph, and the user can edit that stuff. However, edits do not immediately affect the graph. Rather, the user must choose to "push" them to the graph. To push to the graph is to save your changes. (We call it pushing to the graph instead of saving changes because that makes pulling from the graph easier to understand.)
You can have multiple buffers (buffers are like windows; read on for more details) open at once, with unsaved changes in each. When you push changes, you push only the changes made to the current buffer.
"Pulling" from the graph can be important. If you create a first buffer, then leaves it open and makes edits in a second buffer, the contents of the first buffer can become out of date. When you return to it, you can be sure you are looking at the latest data by pulling from the graph. (We could have called it "refreshing the view".) Note that any unsaved changes in the buffer will be lost when you pull from the graph.
If you want, you can avoid that problem entirely by only keeping one buffer open at a time.
A note in smsn-mode starts with a "bullet", which is either an elevated period (·) if it has no children, or a cross (+) if it does have children. The bullet is followed by a space, which is followed by the text of the note.
Together, the bullet and the space after it contain some hidden text, which specifies the note's ID. Recall that the ID is like the note's address in the graph. The ID is what lets Emacs know which note it is talking about. (The text content of the note is not enough information to do that, because two notes can say the same thing.) You can test this yourself: you might see a note that looks like · groceries, but if you paste it into another application, you will instead see something like · :UbllhFaDamiTeUcm: groceries.
You can cut or copy the note, by highlighting the bullet and the text. If you only highlight the text, you can copy it, but Emacs won't know which note it came from.
You can create a new note by starting it with a bullet (which can be any character; we usually use . but you could use x or 7 or whatever you find convenient), following that with a space, and following that with the text it should contain. When you push that to the graph, a new address will be created for it.
smsn-mode has two submodes: edit-mode (the default) and move-submode. Every shortcut available in edit-submode is available in move-submode. Move-submode provides a few additional ones, for speed. You will know which submode you are in by the color of the cursor: It is black in edit-submode, and green in move-submode. Toggle between them with C-c m.
This guide will describe only the most commonly used commands. (These are the ones I use at least 99.9% of the time.) For a complete list of edit-submode commands, see SmSn-mode Command Reference.
Move-submode is fast because it uses single-key commands, but that makes it impossible to type many words. For instance f in move-submode switches to forward view, so you cannot type the letter f while in move-submode. Edit mode is the mode to use when you want to write text.
Edit-submode shortcuts begin with C-c, and are always available. If a command involves a modifier key (C or M) and does not start with C-c, then it is built into Emacs, and works both in smsn-mode and in other modes. If a shortcut does not involve a modifier key, it is only available while in move-submode.
Use C-c n to create a new note. This will create a new buffer in forward-view centered on the new note, which will be given the title life, the universe and everything, visible in the buffer's title bar (which is below the buffer, not above). The new note has no children yet, so the buffer is empty.
Undo with C-x u, or simply u in move-submode.
Push to the graph with C-c p. Pull with C-c u (it stands for "update").
Move the cursor with the arrow keys, or in move-submode with the letters i,j,k and l.
Visit a note with n or t. This creates a new buffer, showing a forward-view of the note's children. n closes the old buffer; t leaves it open.
Switch to forward view with f, and to backward view with b. Both of these commands pull from the graph, so any unsaved changes will be lost.
Change the height of the tree with h [number], where number is between 1 and 7. This controls how many generations of the arrow relationship are shown; for instance, in backward-view, a height of two shows parents and grandparents.
Close a buffer with q.
Toggle line-wrap with ;. This controls whether long lines spill over the right side or wrap back around on the left.
Start the highlight with z. Cut the highlight with x, copy it with c, paste it with v. There is also a way to copy a note without highlighting it: C-c r. Similarly, to copy only the text of the note, not its address, use C-c v (it stands for "value").
Search for text with C-c s. If you then type the word "cat" and press enter, every note containing the word "cat" will appear. Search for "cat*" and every word that begins with "cat", like "catch" or "category", will appear. There are more tricks like that; for details, check out the Apache Lucene query syntax.
Search results are presented in a clever order. Notes with short text passages rank high in the search results. Notes with high priority or weight properties also rank high. We'll talk about properties soon.
We discussed two properties already: address and text. Those are mandatory. Notes also have a time of creation. Address and time of creation are immutable -- the user does not choose them, and the user cannot change them.
A note can have an alias, or URL, associated with it. From such a note in SmSn, you can open the alias in your browser by pressing C-c C-a C-t b. Moreover, if you have the SmSn Chrome Plugin installed, from a page in Chrome you can create a note formatted for SmSn, with an alias and a human-readable text field.
A note also has weight, priority and sharability levels. Each of those varies from 0 to 1. When you create a note, it is assigned default levels for all of them, which you can change.
Priority defaults to 0. A nonzero priority causes a note to display with some amount of underlining, and causes it to rank higher in the search results.
Weight defaults to 0.5. A weight above 0.5 causes the note to appear more bold, and to rank higher in search results. A lower weight has the opposite effect. Text with a weight of 0 is invisible (and silly).
Sharability defaults to the same value as the root of the current view -- that is, of the first parent. Sharing in SmSn is pretty cool, and will be described in its own section, soon.
One way to change the weight of a note is to insert a line after it that looks like " @weight 0.75". There must be some leading space, and the number can be anything from 0 to 1 (inclusive). Sharability and priority can be changed similarly.
Move-submode provides a faster way to change those three properties: Press s for sharability, p for priority, or w for weight, and then press 0 for 0, 1 for 0.25, 2 for 0.5, 3 for 0.75, or 4 for 1.0. (In fact you can use z for 0, a for 1, s for 2, d for 3 and f for 4; it's a little faster.)
The model will be expanded, but currently a note's sharability comes in four flavors. Sharability of 0.25 is called "private", and causes the note to appear red. Sharability of 0.5 is called "personal", and appears yellow. 0.75, "public", is green. 1.00, "universal", is blue.
If you are in a public place and don't want your private notes visible, you can set a minimum sharability level (C-c C-s C-m [number]). (The minimum sharability must be at least the sharability of the root of the current view, though; otherwise you would not be permitting yourself to see anything.)
If you are sharing a graph with someone else, their personal and private notes are invisible to you, and vice-versa. (Actually you could share the personal ones too; it depends how you set up your git repositories. See git-smsn.) If a public note has a private note as a child, that private note will be invisible to everyone except its owner. However, non-owners will still see an empty line in its place, indicating that something is there.
git-smsn provides a collection of Git scripts for sharing a knowledge base. Each sharability level corresponds to its own repository.
In Emacs a frame is something that holds windows. When you start Emacs, you see a single frame, with a single window. You can divide the frame into more windows, and you can create more frames.
A window can be split horizontally with C-x 2, or vertically with C-x 3. That can be repeated. To make the current window occupy the entire frame, use C-x 1. To switch between windows in a frame, use C-x o, or in move-submode, simply o.
A new frame can be created with C-x 5 2. To close it, or to switch between frames, do whatever your operating system requires.
Within a window, one way to change which buffer is being viewed is to press C-x b. The menu bar will ask for the name of the buffer to switch to. Tab completion is available.
If you can't remember the name (my usual state), you can show all the open buffers by pressing C-x C-b. This opens a second window, the Buffer List, with its own associated mode, Buffer menu mode. When the cursor is in the Buffer List, pressing o opens the buffer at point in the other window. ("At point" means "under the cursor" in Emacs-speak.) Buffer menu mode has all sorts of cool shortcuts, and the built-in Emacs documentation is outstanding; to learn about it, put the cursor in the buffer menu and press ?.