# SoyWiki

SoyWiki turns Vim into a powerful, lean, and fast wiki.  It's got all
the protein of a more conventional wiki, but a lot less of the fat and
cholesterol. 

A quick overview of its characteristics and features:

* flat text files
* maximum data portability
* high interoperability with Unix tools
* Vim text editing power
* super-efficient modes of wiki traversal 
* Git for versioning, distributed workflows, and blaming
* CamelCase wiki words
* namespaced wiki words
* autocompletion of wiki words
* automated global renaming of wiki words
* syntax colored wiki words
* outliner-like capability with expansion commands
* operates on all POSIX systems (e.g. OS X, Linux, FreeBSD)

SoyWiki builds on Vim's strengths as a text editor and interface to the
Unix operating system, SoyWiki makes it possible to create, navigate,
and refactor wiki content at the speed of thought. 

SoyWiki is good for tracking projects, contacts, ideas, and collecting
and organizing research. SoyWiki combines the affordances of notebooks,
index cards, and Post-it notes, and adds to them the power of hyperlinks
and automatic indexing.

SoyWiki makes a great writing aid, especially if you do your writing in
Vim. You can have SoyWiki open in multiple Vim windows, tabs, and
buffers, alongside any number of regular Vim windows. Throw in a bunch
of Vim abbreviations (`:help abbreviations`), a large monitor, and a
teapot, and you'll have your paper, essay, book, or screenplay written
in record time.

SoyWiki is free and open source.

[scriv]:http://www.literatureandlatte.com/scrivener.php

## Prerequisites

* a recent version of Vim (SoyWiki is developed against Vim 7.2 and 7.3)
* a recent version of Ruby: Ruby 1.9.2 is recommended
* RubyGems (if Ruby version is older than 1.9)
* a recent version of [Git][git] (1.7.0.4 or above to be safe)

[git]:http://git-scm.com/

The current version of SoyWiki assumes a Unix environment. 

To use SoyWiki you should be fairly good at using Vim. 

Most of SoyWiki's commands should work even if you don't have Git
installed. But the revision history commands will not.

## Installation

    gem install soywiki

Test your installation by typing `soywiki -h`. You should see SoyWiki's help.

On some systems you may run into a PATH issue, where the system can't find the
`soywiki` command after installation. Please report this if you encounter this
problem, and mention what system you're using. You might want to try 

    sudo gem install soywiki

If you ever want to uninstall SoyWiki from your system, execute this command:

    gem uninstall soywiki

... and all traces of SoyWiki will removed.

New and improved versions of SoyWiki will be released over time. To install the
latest version, just type `gem install soywiki` again.


## Starting SoyWiki

Before you start SoyWiki, create a directory that will hold your wiki
files and `cd` into it. Then you can start SoyWiki with

    soywiki

You can make as many SoyWiki wikis on your system as you want just by
creating directories for them. It's not a good idea however to nest
SoyWiki wiki directories within each other, for reasons that will become
clear below.

To use MacVim as your SoyWiki Vim engine, you can run soywiki like this

    SOYWIKI_VIM=mvim soywiki

or you can `export SOYWIKI_VIM=mvim` in your `~/.bash_profile` and then
just run `soywiki`.


## Basic usage

For basic use, SoyWiki works exactly like a typical wiki.

You write text, and when you want to create a new wiki page, you come up with a
WikiWord for it and format it in CamelCase. Whenever you type a valid WikiLink,
it will automatically be syntax-highlighted, and pressing ENTER on it will take
you to the new page. 

Creating WikiWords and pressing ENTER on them is how you create wiki pages and
link them together. You'll be surprised at how powerful this simple mechanism
is for organizing your notes. 

In SoyWiki, a wiki page is a simple text file that has a WikiWord title
on the first line (don't alter this line) and any text your want to
insert below that. SoyWiki will create stub WikiPages for you
automatically as you traverse WikiLinks that don't yet reference any
content.

That's all you need to know to get started. 

## Namespaced WikiWords

Every WikiWord in SoyWiki is implicitly or explicitly namespaced.

An explicitly namespaced WikiWord looks like this:

    recipes.SoyRaspberrySmoothie

The implicitly namespaced form looks just like a conventional WikiWord:

    SoyRaspberrySmoothie

A namespace must start with a lower-case letter and consist only of letters,
numbers, and underscore characters. 

Within a WikiWord namespace you can use unqualified WikiWords to link pages
within that namespace together. For example, if you are editing a page called
`recipes.SoyMacaroni` and you want to link to a page called
`recipes.SoyRaspberrySmoothie`, you can type a link called
`SoyRaspberrySmoothie`. SoyWiki will treat this link as an implicitly
namespaced link to another page in the `recipes` namespace. 

You can't chain namespace words together. The maximum nesting level is 1.  More
nesting would imply hierarchical relationships, and permitting hierarchical
nesting goes against the grain of what a wiki is, which is an [undirected
graph][graph].  SoyWiki namespaces are not supposed to represent hierarchies,
but domains (e.g., personal, work, project1, project2, etc.).  You can easily
represent hierarchical relationships _within_ a wiki page. See "Expanding a
wiki page" below to see how you can use SoyWiki like an outliner program.

[graph]:http://en.wikipedia.org/wiki/Graph_theory

SoyWiki's namespaced WikiWords help organize your wiki space conceptually.
They also help reduce clutter in your wiki directory.

When you start SoyWiki for the first time, the active namespace is the default
namespace `main`. `main.HomePage` is the first page you will see.

## Wiki navigation 

You can navigate a SoyWiki wiki very quickly with the following
commands: 

* `CTRL-k` and `CTRL-j` move the cursor directly to the next or previous WikiLink on the page
* `ENTER` follows the WikiLink under the cursor
* `,f` follows the first WikiLink after the cursor
* `CTRL-l` opens a WikiLink in a vertical split window; press `CTRL-l` again
while the cursor is on the top line to close the new window 
* `CTRL-h` does the same, but in a regular split window
* `q` closes a split window 

These key mappings may not be very mnemonic, but they are easy to
memorize through muscle memory and were chosen to keep the hands
stationary and the fingers near home position on a QWERTY keyboard while
navigating the wiki.

You can also use Vim's jump motions `CTRL-o` and `CTRL-i` to move back
and forth in your jump history. See `:help jump-motions` for more on
this. You can press `CTRL-^` to toggle between the current page and the
last page you looked at.

You can view all the pages in your wiki, most recently modified first,
by pressing `,m`. This opens both a page list and autocompletion window.
You can use the standard Vim autocompletion commands here to find the
page you want and call it up.  See Vim's `:help ins-completion-menu` for
further instructions.

When you're on a wiki page and you want to see all the other wiki pages
that link in to it, press `,M`. If there is only one page that links in,
you'll be taken there automatically.

`,o` opens the first normal web hyperlink -- the ones that begin with http://
or https:// -- on or after the cursor in your default web browser.

Under the covers, SoyWiki uses the command `gnome-open` or `open` to
launch your web browser. This should cover Linux Gnome desktop and OS X
users. You can change the command SoyWiki uses to open a hyperlink by
adding this to your `~/.vimrc`:

    let g:SoyWiki#browser_command = "your browser command here"

If your Vim has `netrw`, you can open a hyperlink directly in same Vim
window by putting the cursor at the beginning of a hyperlink and typing
`gf`, or `C-w f` if you want to open the webpage in a split window.  See
`:help netrw` for more information.

## WikiLink autocompletion

When you're writing a wiki page and you want to link to another page,
SoyWiki can help you autocomplete your WikiLink. Press `CTRL-x CTRL-u`
in Vim insert mode to invoke it.


## Wiki refactoring

You can delete the current page with `:SWDelete` (shortcut: `:SWD`).

`:SWRenameTo [new name]` renames the current page. Make sure the new name
is valid CamelCase. You can put a namespace in front of the new name
as `namespace.` or `namespace/`. If you omit the namespace, the current
namespace is assumed.

When you rename a page, SoyWiki will update all the links on other pages
in your wiki that need to be updated in light of the change. (You'll see
the other links that were updated in the output.)

To create a wiki page directly, without first typing a WikiWord and
traversing it, type `:SWCreate` followed by the full path to the new
page. The form of the argument here should be `namespace/WikiWord`. You
may use command line file path autocomplete to fill out the namespace
subdirectory if it already exists.

Beyond the standard cut and paste, SoyWiki gives you four fast ways of
shuttling text from one wiki page to another.

First, highlight the text you want to move with Vim's visual mode. (See
`:help visual-mode` for more info) 

Then, type

* `:SWInsert [target]` to move the text to the top of target page
* `:SWAppend [target]` to move the text to the bottom of the target page
* `:SWLinkInsert [target]` performs `:SWInsert` and replaces the text with a WikiWord link
* `:SWLinkAppend [target]` performs `:SWAppend` and replaces the text with a WikiWord link

`[target]` is the name of the file that contains the wiki page you're
targeting. Press `TAB` for autocompletion help.

These commands will open the target page (if it isn't open already) in a
split window and insert or append the selected text into it.  If the
target page doesn't exist, it will be created.

You can use these shortcuts:

* `:SWInsert` → `:SWI`
* `:SWAppend` → `:SWA`

With `:SWLinkInsert` and `:SWLinkAppend` you can use Vim's command line
completion (`:help cmdline-completion`) to avoid typing out the whole command name.

Also, you can use Vim's command line history (`:help cmdline-history`)
and command line window (`:help cmdline-window`) to save keystrokes when
you want to repeatedly execute an insert or append command targeting the
same wiki page.


## Search

* `:SWSearch` [term]
* `:SWNamespaceSearch` [term]

These commands search your SoyWiki wiki. `:SWNamespaceSearch` confines
your search to the current namespace.

Vim will load any matches in the quickfix list window.  If there are
matches, you can use `:cn` and `:cp` to go from match to match, `:cl` to
list the matches, and `:cc [item number]` to see a particular match ln
the list.  See `:help quickfix` to see the list of matches. for more
QuickFix commands. 

Examples:

    :SWSearch Gnu
    :SWNamespaceSearch Gnu

You can use `:SWS` as a shortcut for `:SWSearch`. You can also
tab-complete `:SWNS` to `:SWSNamespaceSearch`.

Searches are case-insensitve.  

Under the hood, `:SWSearch` is just a thin wrapper around the `:vimgrep`
command. Use `:vimgrep` directly if you want to do anything more
specific.

Tip: You can flag important notes in your wiki content by typing flags
like TODO or IMPORTANT on the same line, and then use `:SWSearch` and
`:cl` to see all instances of them across your entire wiki.

## Revision history and distributed workflows

SoyWiki delegates revision-tracking, syncing, and collaboration
workflows to Git.  SoyWiki automatically creates a Git repository in
your wiki directory and automatically commits all the edits you make to
it.  You can sync a SoyWiki wiki between two computers using the
standard Git push and pull commands.  Collaborators can also edit a
common wiki this way, in peer to peer fashion. 

SoyWiki provides a few convenient key mappings to view the revision
history of a wiki page: 

* `,l` shows a `git-log` view of the revision history of the current page
* `,b` shows a `git-blame` view of the current page, which shows when each line was added and by whom.
* `:SWLogStat` shows a `git log --stat` view of the current page's revision history

You can always bypass Vim and SoyWiki altogether and use Git directly to
inspect your revision history. The Git repo for your SoyWiki wiki will
be located in the same directory as your wiki files.

To sync your SoyWiki wiki between two personal computers, you can follow the
instructions [here][git-sync] or you can set up an bare Git repository
upstream on some server for all your computers to push to and pull from.

[git-sync]:http://www-cs-students.stanford.edu/~blynn/gitmagic/ch03.html


If you want to edit a common SoyWiki with many other people, it's
probably best to set up a common upstream Git repository and to work
locally on a development branch before pulling the HEAD of the master
branch from origin, merging your edits into it, and pushing the merged
result back to origin. This process may be intimidating for
non-programmers, so a future version of SoyWiki may provide a more
user-friendly interface for distributed collaboration workflows.



## Expanding a wiki page

SoyWiki lets you "expand" a wiki page.  What this does is expand all the
wiki links in the page that appear alone on a line.  Each of these links
is replaced by the content of the wiki page the link points to. This
expansion works recursively on all the expanded content.  Don't worry.
It can't fall into an infinite recursive loop because it will only
expand each WikiWord it encounters once, leaving all subsequent
references to the same WikiWord unexpanded.

The expanded version of the page will appear in a new Vim scratch buffer.
From there you can write it out to a new text file, pipe it to `lpr` to
print it, or whatever you like. 

There are two forms of expansion: seamful and seamless. Seamful
expansion expands wiki links into wiki pages and clearly marks where
this has happened by including markers along with the WikiWord that was
expanded. Seamless expansion does not mark a point of expansion with
anything, and it erases the WikiWord that got expanded. 

* `,x` expands a wiki page seamfully and opens on a vertical split
* `,X` expands a wiki page seamlessly and opens on a vertical split
* `,hx` expands a wiki page seamfully and opens on normal split
* `,hX` expands a wiki page seamlessly and opens on a normal split
* `q` closes the expanded view window

Both modes of expansion are useful when you want to assemble a long
piece of writing by using one page as a master outline that links to
other wiki pages that include the real content. And since expansion is
recursive, you can effectively nest outlines within outlines, like
dreams within dreams.  


## Exporting to HTML

Want to share your wiki with non-Vim-users?  You can export your wiki into a directory
of html pages. Type `soywiki --html` from the root directory of your wiki.


## Extra macros

SoyWiki adds a few convenient Vim macros that you can use anytime. 


* The `\` key in normal mode reformat the current paragraph. It is equivalent to
`gwap`. (`:help formatting`)
* `,-` inserts a long dashed line
* `,d` inserts the current date and time 
 

## Getting help

Typing `,?` will open the help webpage in a browser.


## Why CamelCase WikiLinks rule

Some people don't like the CamelCase (a.k.a. WikiCase) wiki link
pattern. But SoyWiki embraces it and wants everyone to adopt it, for the
following reasons:

* Besides being the original, CamelCase is the most elegantly minimalist approach to linking wiki pages together -- "with no additional markup whatsoever," [as Ward Cunninghamb put it][ward]. 
* It encourages you more than other wiki link patterns to create wiki pages with succinctly descriptive names that are easy to remember.
* Because the link pattern is so minimal and succinct, writing 
them interrupts your flow of thought a lot less than other wiki patterns.
* It is very conducive to storing
wiki pages in plain text files: the page names can map directly to Unix
file names without any awkward character escaping.

[ward]:http://c2.com/cgi/wiki?WikiCase



[soylink]:http://www.mayoclinic.com/health/soy/NS_patient-soy

## How to contact the developer

My name is Daniel Choi. I am based in Cambridge, Massachusetts, USA, and you
can email me at dhchoi {at} gmail.com.  

## How to support the SoyWiki project

SoyWiki is very new, so there are kinks and bugs to iron out and lot of
desirable features to add.  If you have a bug to report or a good feature to
suggest, please file it on the [issue tracker][1].  That will help a lot.

[1]:https://github.com/danchoi/soywiki/issues