Skip to content
Newer
Older
100644 512 lines (355 sloc) 20 KB
b754435 @danchoi writing up the README
authored Feb 8, 2011
1 # SoyWiki
2
736ba32 @danchoi README edits
authored Feb 14, 2011
3 SoyWiki turns Vim into a powerful, lean, and fast wiki. It's got all the
74c7e8c @danchoi edits
authored Feb 14, 2011
4 protein of a more conventional wiki, but less saturated fat and no
5 cholesterol.
06b23b2 @danchoi README edits
authored Feb 12, 2011
6
8688bd1 @danchoi change in website build process
authored Feb 22, 2011
7 [screenshots]
8
5c2fac6 @danchoi edits
authored Feb 14, 2011
9 A quick overview of SoyWiki's characteristics and features:
2a49365 @danchoi edits
authored Feb 8, 2011
10
11 * flat text files
ae9e1fc @danchoi readme
authored Feb 8, 2011
12 * maximum data portability
13 * high interoperability with Unix tools
14 * Vim text editing power
15 * super-efficient modes of wiki traversal
2a49365 @danchoi edits
authored Feb 8, 2011
16 * Git for versioning, distributed workflows, and blaming
17 * CamelCase wiki words
18 * namespaced wiki words
19 * autocompletion of wiki words
20 * automated global renaming of wiki words
b4f22e8 @danchoi edit
authored Feb 8, 2011
21 * syntax colored wiki words
ecde51e @danchoi edit
authored Feb 18, 2011
22 * can open web hyperlinks in external browser or inside Vim
667e261 @danchoi readme edit
authored Feb 9, 2011
23 * outliner-like capability with expansion commands
ae9e1fc @danchoi readme
authored Feb 8, 2011
24 * operates on all POSIX systems (e.g. OS X, Linux, FreeBSD)
25
e33009f @danchoi edit readme
authored Feb 9, 2011
26 SoyWiki builds on Vim's strengths as a text editor and interface to the
560924d @danchoi edit
authored Feb 14, 2011
27 Unix operating system, SoyWiki's primary goal is to make it possible to
28 create, navigate, and refactor wiki content at the speed of thought.
716cdad @danchoi edit
authored Feb 9, 2011
29
30 SoyWiki is good for tracking projects, contacts, ideas, and collecting
0ef3c1c @danchoi edit readme
authored Feb 9, 2011
31 and organizing research. SoyWiki combines the affordances of notebooks,
6298282 @danchoi edits
authored Feb 14, 2011
32 index cards, and Post-it notes, and adds to them the power of
64760b4 @danchoi edit
authored Feb 14, 2011
33 hyperlinks, search, revision history, automated refactoring, and more.
2ab1acb @danchoi edit readme
authored Feb 8, 2011
34
65a7493 @danchoi Tone it down
authored Feb 14, 2011
35 SoyWiki makes a good writing aid, especially if you do your writing in
8a06af3 @danchoi working on extraction commands
authored Feb 9, 2011
36 Vim. You can have SoyWiki open in multiple Vim windows, tabs, and
ac4cb1f @danchoi readme edit
authored Feb 9, 2011
37 buffers, alongside any number of regular Vim windows. Throw in a bunch
38 of Vim abbreviations (`:help abbreviations`), a large monitor, and a
439703a @danchoi edits
authored Feb 14, 2011
39 teapot, and you'll have a powerful toolkit for writing your paper, essay,
40 book, or screenplay.
2874fd8 @danchoi edit readme
authored Feb 9, 2011
41
b2ce5c9 @danchoi edit readme
authored Feb 9, 2011
42 SoyWiki is free and open source.
21bae34 @danchoi edit readme
authored Feb 9, 2011
43
44 [scriv]:http://www.literatureandlatte.com/scrivener.php
2ab1acb @danchoi edit readme
authored Feb 8, 2011
45
b754435 @danchoi writing up the README
authored Feb 8, 2011
46 ## Prerequisites
47
735e09d @danchoi readme edits
authored Feb 8, 2011
48 * a recent version of Vim (SoyWiki is developed against Vim 7.2 and 7.3)
551fc6b @danchoi some tweaks
authored Feb 14, 2011
49 * a recent version of Ruby: Ruby 1.9.2 is recommended
b754435 @danchoi writing up the README
authored Feb 8, 2011
50 * RubyGems (if Ruby version is older than 1.9)
52c824c @danchoi edit readme; git link
authored Feb 10, 2011
51 * a recent version of [Git][git] (1.7.0.4 or above to be safe)
52
53 [git]:http://git-scm.com/
b754435 @danchoi writing up the README
authored Feb 8, 2011
54
735e09d @danchoi readme edits
authored Feb 8, 2011
55 The current version of SoyWiki assumes a Unix environment.
b754435 @danchoi writing up the README
authored Feb 8, 2011
56
13e694f @danchoi readme edit
authored Feb 9, 2011
57 To use SoyWiki you should be fairly good at using Vim.
8dcc6f2 @danchoi edit
authored Feb 8, 2011
58
137695c @danchoi edits
authored Feb 16, 2011
59 To install Ruby 1.9.2, I recommend using the [RVM Version Manager][rvm].
60
61 [rvm]:http://rvm.beginrescueend.com
62
3461e72 @danchoi readme; git not strictly required
authored Feb 10, 2011
63 Most of SoyWiki's commands should work even if you don't have Git
64 installed. But the revision history commands will not.
65
b754435 @danchoi writing up the README
authored Feb 8, 2011
66 ## Installation
67
68 gem install soywiki
69
735e09d @danchoi readme edits
authored Feb 8, 2011
70 Test your installation by typing `soywiki -h`. You should see SoyWiki's help.
b754435 @danchoi writing up the README
authored Feb 8, 2011
71
9f691d2 @danchoi edits
authored Feb 16, 2011
72 If you run into any PATH errors, try the following: Install the RVM
73 Version Manager, then install Ruby 1.9.2 through RVM, and then run `gem
74 install soywiki`. This should solve any installation issues.
137695c @danchoi edits
authored Feb 17, 2011
75
735e09d @danchoi readme edits
authored Feb 8, 2011
76 If you ever want to uninstall SoyWiki from your system, execute this command:
b754435 @danchoi writing up the README
authored Feb 8, 2011
77
78 gem uninstall soywiki
79
735e09d @danchoi readme edits
authored Feb 8, 2011
80 ... and all traces of SoyWiki will removed.
b754435 @danchoi writing up the README
authored Feb 8, 2011
81
18be96f @danchoi doc edits
authored Feb 9, 2011
82 New and improved versions of SoyWiki will be released over time. To install the
83 latest version, just type `gem install soywiki` again.
84
85
735e09d @danchoi readme edits
authored Feb 8, 2011
86 ## Starting SoyWiki
b754435 @danchoi writing up the README
authored Feb 8, 2011
87
46b92a7 @danchoi edit readme
authored Feb 9, 2011
88 Before you start SoyWiki, create a directory that will hold your wiki
89 files and `cd` into it. Then you can start SoyWiki with
b754435 @danchoi writing up the README
authored Feb 8, 2011
90
91 soywiki
92
46b92a7 @danchoi edit readme
authored Feb 9, 2011
93 You can make as many SoyWiki wikis on your system as you want just by
94 creating directories for them. It's not a good idea however to nest
95 SoyWiki wiki directories within each other, for reasons that will become
96 clear below.
97
18be96f @danchoi doc edits
authored Feb 9, 2011
98 To use MacVim as your SoyWiki Vim engine, you can run soywiki like this
99
100 SOYWIKI_VIM=mvim soywiki
101
e6b57f8 @danchoi readme edit
authored Feb 9, 2011
102 or you can `export SOYWIKI_VIM=mvim` in your `~/.bash_profile` and then
103 just run `soywiki`.
18be96f @danchoi doc edits
authored Feb 9, 2011
104
ca3bbbd @danchoi README edits
authored Feb 14, 2011
105
d7d5e1a @danchoi Readme for :Soywiki command
authored Feb 18, 2011
106 You can start SoyWiki from within a running Vim session. To set this up,
f0b70af @danchoi edit
authored Feb 18, 2011
107 first install or update SoyWiki, and then run
d7d5e1a @danchoi Readme for :Soywiki command
authored Feb 18, 2011
108
109 soywiki --install-plugin
110
f0b70af @danchoi edit
authored Feb 18, 2011
111 Please note that you will need to run this command after each time you update
112 SoyWiki to a newer version.
d7d5e1a @danchoi Readme for :Soywiki command
authored Feb 18, 2011
113
8f98231 @danchoi typo
authored Feb 18, 2011
114 Assuming the plugin is installed, you can start SoyWiki from within a
d7d5e1a @danchoi Readme for :Soywiki command
authored Feb 18, 2011
115 running Vim session by typing the command
116
117 :Soywiki
118
119 Make sure when you do this that Vim's working directory is the root of
120 your wiki directory. You can change the working directory for the
121 current Vim window with `:lcd`. See `:help lcd` for more info.
122
123
667e261 @danchoi readme edit
authored Feb 9, 2011
124 ## Basic usage
46b92a7 @danchoi edit readme
authored Feb 9, 2011
125
126 For basic use, SoyWiki works exactly like a typical wiki.
127
ca3bbbd @danchoi README edits
authored Feb 14, 2011
128 You write text, and when you want to create a new wiki page, you come up with a
129 WikiWord for it and format it in CamelCase. Whenever you type a valid WikiLink,
130 it will automatically be syntax-highlighted, and pressing ENTER on it will take
131 you to the new page.
132
133 Creating WikiWords and pressing ENTER on them is how you create wiki pages and
134 link them together. You'll be surprised at how powerful this simple mechanism
135 is for organizing your notes.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
136
2ffa361 @danchoi readme edit
authored Feb 10, 2011
137 In SoyWiki, a wiki page is a simple text file that has a WikiWord title
af20374 @danchoi typo
authored Feb 18, 2011
138 on the first line. Beyond that, you can append any text you want. (You
139 may alter the title line at the top, but it helps you see what wiki page
27da460 @danchoi edits
authored Feb 14, 2011
140 you're on.) SoyWiki will create stub WikiPages for you automatically as
141 you traverse WikiLinks that don't yet reference any content.
25ebed9 @danchoi readme edit
authored Feb 10, 2011
142
46b92a7 @danchoi edit readme
authored Feb 9, 2011
143 That's all you need to know to get started.
144
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
145 ## Namespaced WikiWords
146
e6c2adf @danchoi readme edits
authored Feb 13, 2011
147 Every WikiWord in SoyWiki is implicitly or explicitly namespaced.
8b3f417 @danchoi edits
authored Feb 14, 2011
148 SoyWiki's namespaced WikiWords help organize your wiki space
149 conceptually. They also help reduce clutter in your wiki directory.
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
150
e6c2adf @danchoi readme edits
authored Feb 13, 2011
151 An explicitly namespaced WikiWord looks like this:
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
152
e6c2adf @danchoi readme edits
authored Feb 13, 2011
153 recipes.SoyRaspberrySmoothie
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
154
e6c2adf @danchoi readme edits
authored Feb 13, 2011
155 The implicitly namespaced form looks just like a conventional WikiWord:
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
156
e6c2adf @danchoi readme edits
authored Feb 13, 2011
157 SoyRaspberrySmoothie
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
158
e6c2adf @danchoi readme edits
authored Feb 13, 2011
159 A namespace must start with a lower-case letter and consist only of letters,
160 numbers, and underscore characters.
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
161
5ff2aa8 @danchoi edits
authored Feb 14, 2011
162 Within a WikiWord namespace you can use unqualified WikiWords to link
163 pages within that namespace together. For example, if you are editing a
164 page called `recipes.SoyMacaroni` and you want to link to a page called
e6c2adf @danchoi readme edits
authored Feb 13, 2011
165 `recipes.SoyRaspberrySmoothie`, you can type a link called
166 `SoyRaspberrySmoothie`. SoyWiki will treat this link as an implicitly
167 namespaced link to another page in the `recipes` namespace.
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
168
2aa93f7 @danchoi edits
authored Feb 14, 2011
169 SoyWiki wiki pages are stored as text files named by WikiWord within
170 subdirectories named after their namespace. So
ba9460b @danchoi typo
authored Feb 14, 2011
171 `recipes.SoyRaspberrySmoothie` would be written to
2aa93f7 @danchoi edits
authored Feb 14, 2011
172 `recipes/SoyRaspberrySmoothie`.
5ff2aa8 @danchoi edits
authored Feb 14, 2011
173
e6c2adf @danchoi readme edits
authored Feb 13, 2011
174 You can't chain namespace words together. The maximum nesting level is 1. More
175 nesting would imply hierarchical relationships, and permitting hierarchical
176 nesting goes against the grain of what a wiki is, which is an [undirected
177 graph][graph]. SoyWiki namespaces are not supposed to represent hierarchies,
a2cd819 @danchoi readme edits
authored Feb 13, 2011
178 but domains (e.g., personal, work, project1, project2, etc.). You can easily
179 represent hierarchical relationships _within_ a wiki page. See "Expanding a
180 wiki page" below to see how you can use SoyWiki like an outliner program.
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
181
e6c2adf @danchoi readme edits
authored Feb 13, 2011
182 [graph]:http://en.wikipedia.org/wiki/Graph_theory
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
183
e6c2adf @danchoi readme edits
authored Feb 13, 2011
184
185 When you start SoyWiki for the first time, the active namespace is the default
186 namespace `main`. `main.HomePage` is the first page you will see.
d48f6fe @danchoi update namespace instructions
authored Feb 12, 2011
187
7133f48 @danchoi edit readme
authored Feb 9, 2011
188 ## Wiki navigation
46b92a7 @danchoi edit readme
authored Feb 9, 2011
189
190 You can navigate a SoyWiki wiki very quickly with the following
25ebed9 @danchoi readme edit
authored Feb 10, 2011
191 commands:
46b92a7 @danchoi edit readme
authored Feb 9, 2011
192
4d87447 @danchoi edit
authored Feb 14, 2011
193 * `CTRL-j` and `CTRL-k` move the cursor directly to the next or previous WikiLink on the page
59f9b51 @danchoi edits
authored Feb 15, 2011
194 * `ENTER` follows the WikiLink under the cursor
ad07a4c @danchoi readme edit; wiki-links to WikiLinks
authored Feb 9, 2011
195 * `,f` follows the first WikiLink after the cursor
52be3e4 @danchoi edit
authored Feb 12, 2011
196 * `CTRL-l` opens a WikiLink in a vertical split window; press `CTRL-l` again
241e9be @danchoi readme edit
authored Feb 12, 2011
197 while the cursor is on the top line to close the new window
d557aa4 @danchoi Better keybinding: C-l second time closes new split window
authored Feb 12, 2011
198 * `CTRL-h` does the same, but in a regular split window
199 * `q` closes a split window
bb1e7f6 @danchoi remapping things around
authored Feb 20, 2011
200 * `,h` takes you to the `HomePage` of the current namespace
201 * `,H` takes you to `main.HomePage`
d557aa4 @danchoi Better keybinding: C-l second time closes new split window
authored Feb 13, 2011
202
d10a31e @danchoi edits
authored Feb 10, 2011
203 These key mappings may not be very mnemonic, but they are easy to
204 memorize through muscle memory and were chosen to keep the hands
205 stationary and the fingers near home position on a QWERTY keyboard while
206 navigating the wiki.
70afcf0 @danchoi more ergonomic key mappings for jumping to next link
authored Feb 10, 2011
207
46b92a7 @danchoi edit readme
authored Feb 9, 2011
208 You can also use Vim's jump motions `CTRL-o` and `CTRL-i` to move back
209 and forth in your jump history. See `:help jump-motions` for more on
210 this. You can press `CTRL-^` to toggle between the current page and the
211 last page you looked at.
212
2d02020 @danchoi edits
authored Feb 14, 2011
213 * `,m` opens the page list
1e03e37 @danchoi ,n opens namespace selection list
authored Feb 18, 2011
214 * `,n` opens the namespace list
2d02020 @danchoi edits
authored Feb 14, 2011
215 * `,M` opens the inbound links page list
216
46b92a7 @danchoi edit readme
authored Feb 9, 2011
217 You can view all the pages in your wiki, most recently modified first,
e6c2adf @danchoi readme edits
authored Feb 13, 2011
218 by pressing `,m`. This opens both a page list and autocompletion window.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
219 You can use the standard Vim autocompletion commands here to find the
220 page you want and call it up. See Vim's `:help ins-completion-menu` for
221 further instructions.
222
223 When you're on a wiki page and you want to see all the other wiki pages
224 that link in to it, press `,M`. If there is only one page that links in,
225 you'll be taken there automatically.
226
1e03e37 @danchoi ,n opens namespace selection list
authored Feb 18, 2011
227 `,n` lets you select from your namespaces. Choosing one will take you to
228 the `HomePage` of that namespace.
229
1aae84b @danchoi new heading
authored Feb 18, 2011
230
231 ## Opening web hyperlinks
232
68c17d0 @danchoi edits
authored Feb 15, 2011
233 * `,o` opens the first web hyperlink under or after the cursor in the default external web browser
234 * `ENTER` opens the web hyperlink under the cursor in the default external web browser
1890bb9 @danchoi edits
authored Feb 15, 2011
235 * `,O` opens the web hyperlink under the cursor in a vertical split window
236 * `CTRL-w f` opens the web hyperlink under the cursor in a normal split window
2572f50 @danchoi edits
authored Feb 15, 2011
237 * `gf` opens the web hyperlink under the cursor in the same Vim window
2d02020 @danchoi edits
authored Feb 14, 2011
238
2572f50 @danchoi edits
authored Feb 16, 2011
239 `,o` opens the next web hyperlink on or after the cursor in your default
240 external web browser. Web hyperlinks are the URLs that begin with
241 http:// or https://. You can also use `ENTER` when the cursor is over a
242 web hyperlink.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
243
244 Under the covers, SoyWiki uses the command `gnome-open` or `open` to
c03a5b9 @danchoi fix typo in markup
authored Feb 15, 2011
245 launch your external web browser. This should cover Linux Gnome desktop
246 and OS X users. You can change the command SoyWiki uses to open a
247 hyperlink by adding this to your `~/.vimrc`:
46b92a7 @danchoi edit readme
authored Feb 9, 2011
248
249 let g:SoyWiki#browser_command = "your browser command here"
250
f0fde16 @danchoi Wrap netrw open webpage command in ,O
authored Feb 15, 2011
251 If your Vim has `netrw` installed, you can open a hyperlink directly in
c03a5b9 @danchoi fix typo in markup
authored Feb 16, 2011
252 Vim by putting the cursor on a web hyperlink and typing `gf`, `CTRL-W f`
2572f50 @danchoi edits
authored Feb 16, 2011
253 or `,O` (capital O). All these commands open the webpage inside your Vim
254 session using `elinks` or whatever browser you set as your
255 `g:netrw_http_cmd`. See `:help netrw` for more information.
26ab69b @danchoi edits
authored Feb 14, 2011
256
475ae45 @danchoi edits
authored Feb 16, 2011
257 TIP: I personally prefer using `netrw` (configured to use elinks) to
5f5eec0 @danchoi edits
authored Feb 15, 2011
258 launching URLs in an external web browser. This lets me keep all my URL
83e0e54 @danchoi edits
authored Feb 15, 2011
259 bookmarks in regular text files and open, clip, and annotate them all in
260 SoyWiki and Vim. Using `netrw` helps your text editor rather than your
475ae45 @danchoi edits
authored Feb 16, 2011
261 web browser dominate your workflow. And you tend to stay focused on
85d234c @danchoi typo
authored Feb 18, 2011
262 your task rather than going down the rabbit hole of internet
475ae45 @danchoi edits
authored Feb 16, 2011
263 distractions.
26ab69b @danchoi edits
authored Feb 14, 2011
264
46b92a7 @danchoi edit readme
authored Feb 9, 2011
265
ad07a4c @danchoi readme edit; wiki-links to WikiLinks
authored Feb 10, 2011
266 ## WikiLink autocompletion
3eaf3eb @danchoi edit readme
authored Feb 9, 2011
267
268 When you're writing a wiki page and you want to link to another page,
ad07a4c @danchoi readme edit; wiki-links to WikiLinks
authored Feb 10, 2011
269 SoyWiki can help you autocomplete your WikiLink. Press `CTRL-x CTRL-u`
3eaf3eb @danchoi edit readme
authored Feb 9, 2011
270 in Vim insert mode to invoke it.
271
8a06af3 @danchoi working on extraction commands
authored Feb 9, 2011
272
7133f48 @danchoi edit readme
authored Feb 9, 2011
273 ## Wiki refactoring
46b92a7 @danchoi edit readme
authored Feb 9, 2011
274
e30e471 @danchoi More shortcuts
authored Feb 14, 2011
275 You can delete the current page with `:SWDelete`.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
276
e0961ea @danchoi rename changes
authored Feb 12, 2011
277 `:SWRenameTo [new name]` renames the current page. Make sure the new name
7dbc086 @danchoi lots of changes, mainly to use new namespaces
authored Feb 10, 2011
278 is valid CamelCase. You can put a namespace in front of the new name
279 as `namespace.` or `namespace/`. If you omit the namespace, the current
280 namespace is assumed.
281
282 When you rename a page, SoyWiki will update all the links on other pages
283 in your wiki that need to be updated in light of the change. (You'll see
284 the other links that were updated in the output.)
46b92a7 @danchoi edit readme
authored Feb 9, 2011
285
843cb98 @danchoi Use SWCreate instead of ,c to create a page
authored Feb 10, 2011
286 To create a wiki page directly, without first typing a WikiWord and
287 traversing it, type `:SWCreate` followed by the full path to the new
288 page. The form of the argument here should be `namespace/WikiWord`. You
289 may use command line file path autocomplete to fill out the namespace
290 subdirectory if it already exists.
b6caa87 @danchoi readme update; ,c
authored Feb 10, 2011
291
475ae45 @danchoi edits
authored Feb 16, 2011
292 TIP: I recommend not using :SWCreate to create wiki pages. Prefer the
2c3ec09 @danchoi edits
authored Feb 15, 2011
293 method of writing a WikiLink and then traversing it. This will make your
294 wiki more interlinked, better organized, and easier to traverse in an
295 organic way.
296
18be96f @danchoi doc edits
authored Feb 9, 2011
297 Beyond the standard cut and paste, SoyWiki gives you four fast ways of
d2e13ef @danchoi remove SWDI SWDA for now
authored Feb 9, 2011
298 shuttling text from one wiki page to another.
b05dbc6 @danchoi change SW prefix to SY
authored Feb 9, 2011
299
300 First, highlight the text you want to move with Vim's visual mode. (See
301 `:help visual-mode` for more info)
302
303 Then, type
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
304
dc23b48 @danchoi extrace and replace done
authored Feb 9, 2011
305 * `:SWInsert [target]` to move the text to the top of target page
306 * `:SWAppend [target]` to move the text to the bottom of the target page
18be96f @danchoi doc edits
authored Feb 9, 2011
307 * `:SWLinkInsert [target]` performs `:SWInsert` and replaces the text with a WikiWord link
308 * `:SWLinkAppend [target]` performs `:SWAppend` and replaces the text with a WikiWord link
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
309
b05dbc6 @danchoi change SW prefix to SY
authored Feb 9, 2011
310 `[target]` is the name of the file that contains the wiki page you're
6894d11 @danchoi edits
authored Feb 14, 2011
311 targeting, e.g. `recipes/SoyRaspberrySmoothie`. Press `TAB` for
312 autocompletion help.
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
313
6894d11 @danchoi edits
authored Feb 14, 2011
314 These four commands will open the target page (if it isn't open already)
315 in a split window and insert or append the selected text into it. If
316 the target page doesn't exist, it will be created.
8437eef @danchoi edit readme
authored Feb 9, 2011
317
18be96f @danchoi doc edits
authored Feb 9, 2011
318 You can use these shortcuts:
46b2257 @danchoi check for wikiword; replace extracted text with WikiWord
authored Feb 9, 2011
319
e30e471 @danchoi More shortcuts
authored Feb 15, 2011
320 * `:SWDelete` → `:SWD`
321 * `:SWRename` → `:SWR`
322 * `:SWCreate` → `:SWC`
18be96f @danchoi doc edits
authored Feb 9, 2011
323 * `:SWInsert` → `:SWI`
324 * `:SWAppend` → `:SWA`
8437eef @danchoi edit readme
authored Feb 9, 2011
325
d993849 @danchoi readme: note about command line history
authored Feb 10, 2011
326 With `:SWLinkInsert` and `:SWLinkAppend` you can use Vim's command line
327 completion (`:help cmdline-completion`) to avoid typing out the whole command name.
328
329 Also, you can use Vim's command line history (`:help cmdline-history`)
330 and command line window (`:help cmdline-window`) to save keystrokes when
331 you want to repeatedly execute an insert or append command targeting the
332 same wiki page.
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
333
334
d3bbe93 @danchoi search feature; extract deletes selection in original
authored Feb 9, 2011
335 ## Search
336
bf73fa7 @danchoi edits; corrections
authored Feb 14, 2011
337 * `:SWSearch [term]`
338 * `:SWNamespaceSearch [term]`
d3bbe93 @danchoi search feature; extract deletes selection in original
authored Feb 9, 2011
339
9335ac7 @danchoi edits
authored Feb 12, 2011
340 These commands search your SoyWiki wiki. `:SWNamespaceSearch` confines
341 your search to the current namespace.
342
343 Vim will load any matches in the quickfix list window. If there are
344 matches, you can use `:cn` and `:cp` to go from match to match, `:cl` to
345 list the matches, and `:cc [item number]` to see a particular match ln
0f0501f @danchoi typo fix
authored May 9, 2011
346 the list. See `:help quickfix` or more QuickFix commands.
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
347
fd74c62 @danchoi SWNamespaced Search; search case-insensitive
authored Feb 12, 2011
348 Examples:
46b92a7 @danchoi edit readme
authored Feb 9, 2011
349
61a3f63 @danchoi edits
authored Feb 14, 2011
350 :SWSearch gnu
351 :SWNamespaceSearch gnu
fd74c62 @danchoi SWNamespaced Search; search case-insensitive
authored Feb 13, 2011
352
353 You can use `:SWS` as a shortcut for `:SWSearch`. You can also
bf73fa7 @danchoi edits; corrections
authored Feb 15, 2011
354 tab-complete `:SWN` to `:SWNamespaceSearch`.
fd74c62 @danchoi SWNamespaced Search; search case-insensitive
authored Feb 13, 2011
355
356 Searches are case-insensitve.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
357
d3bbe93 @danchoi search feature; extract deletes selection in original
authored Feb 9, 2011
358 Under the hood, `:SWSearch` is just a thin wrapper around the `:vimgrep`
fd74c62 @danchoi SWNamespaced Search; search case-insensitive
authored Feb 13, 2011
359 command. Use `:vimgrep` directly if you want to do anything more
360 specific.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
361
475ae45 @danchoi edits
authored Feb 16, 2011
362 TIP: You can flag important notes in your wiki content by typing flags
1398bdc @danchoi edits
authored Feb 15, 2011
363 like TODO or IMPORTANT! on the same line, and then use `:SWSearch` and
3461e72 @danchoi readme; git not strictly required
authored Feb 10, 2011
364 `:cl` to see all instances of them across your entire wiki.
d7c14b5 @danchoi readme edit
authored Feb 9, 2011
365
46b92a7 @danchoi edit readme
authored Feb 9, 2011
366 ## Revision history and distributed workflows
367
368 SoyWiki delegates revision-tracking, syncing, and collaboration
23d026b @danchoi edit readme
authored Feb 9, 2011
369 workflows to Git. SoyWiki automatically creates a Git repository in
46b92a7 @danchoi edit readme
authored Feb 9, 2011
370 your wiki directory and automatically commits all the edits you make to
371 it. You can sync a SoyWiki wiki between two computers using the
23d026b @danchoi edit readme
authored Feb 9, 2011
372 standard Git push and pull commands. Collaborators can also edit a
46b92a7 @danchoi edit readme
authored Feb 9, 2011
373 common wiki this way, in peer to peer fashion.
374
375 SoyWiki provides a few convenient key mappings to view the revision
376 history of a wiki page:
377
55f0cbb @danchoi Don't use color-words diff, new bindings
authored Feb 16, 2011
378 * `,lp` shows a `git-log -p` view of the revision history of the current page
379 * `,ls` shows a `git log --stat` view of the current page's revision history
46b92a7 @danchoi edit readme
authored Feb 9, 2011
380 * `,b` shows a `git-blame` view of the current page, which shows when each line was added and by whom.
381
23d026b @danchoi edit readme
authored Feb 9, 2011
382 You can always bypass Vim and SoyWiki altogether and use Git directly to
383 inspect your revision history. The Git repo for your SoyWiki wiki will
384 be located in the same directory as your wiki files.
385
ad815fa @danchoi edits
authored Feb 14, 2011
386 To sync your SoyWiki wiki between two personal computers, you can follow
387 the instructions [here][git-sync] and set up an bare Git repository on
388 some server for all your computers to push to and pull from.
46b92a7 @danchoi edit readme
authored Feb 9, 2011
389
390 [git-sync]:http://www-cs-students.stanford.edu/~blynn/gitmagic/ch03.html
391
1aa2497 @danchoi edits
authored Feb 15, 2011
392 If you want something simpler, you could also try keeping your wiki
393 folder in a [Dropbox][dropbox] folder.
394
395 [dropbox]:http://stevelosh.com/projects/t/#it-does-the-simplest-thing-that-could-possibly-work
a8486b6 @danchoi readme edits
authored Feb 13, 2011
396
364dce3 @danchoi note on distributed collaboration w git
authored Feb 10, 2011
397 If you want to edit a common SoyWiki with many other people, it's
9924efb @danchoi edits
authored Feb 14, 2011
398 probably best to set up a common upstream Git repository (e.g. on
399 GitHub, if the wiki content is for public consumption). This process
400 may be intimidating for non-programmers, so a future version of SoyWiki
401 may provide a more user-friendly interface for distributed collaboration
402 workflows.
364dce3 @danchoi note on distributed collaboration w git
authored Feb 10, 2011
403
d7c14b5 @danchoi readme edit
authored Feb 9, 2011
404
405
632796c @danchoi readme edit
authored Feb 9, 2011
406 ## Expanding a wiki page
66c5cfa @danchoi readme
authored Feb 9, 2011
407
526b48f @danchoi readme edit
authored Feb 9, 2011
408 SoyWiki lets you "expand" a wiki page. What this does is expand all the
c9c2b6b @danchoi readme edit
authored Feb 9, 2011
409 wiki links in the page that appear alone on a line. Each of these links
410 is replaced by the content of the wiki page the link points to. This
411 expansion works recursively on all the expanded content. Don't worry.
412 It can't fall into an infinite recursive loop because it will only
632796c @danchoi readme edit
authored Feb 10, 2011
413 expand each WikiWord it encounters once, leaving all subsequent
c9c2b6b @danchoi readme edit
authored Feb 10, 2011
414 references to the same WikiWord unexpanded.
526b48f @danchoi readme edit
authored Feb 10, 2011
415
632796c @danchoi readme edit
authored Feb 10, 2011
416 The expanded version of the page will appear in a new Vim scratch buffer.
526b48f @danchoi readme edit
authored Feb 10, 2011
417 From there you can write it out to a new text file, pipe it to `lpr` to
418 print it, or whatever you like.
19bcc8e @danchoi change unfurl to expand; expand command
authored Feb 9, 2011
419
e6b57f8 @danchoi readme edit
authored Feb 9, 2011
420 There are two forms of expansion: seamful and seamless. Seamful
421 expansion expands wiki links into wiki pages and clearly marks where
422 this has happened by including markers along with the WikiWord that was
423 expanded. Seamless expansion does not mark a point of expansion with
19bcc8e @danchoi change unfurl to expand; expand command
authored Feb 9, 2011
424 anything, and it erases the WikiWord that got expanded.
425
0ba083a @danchoi change keybindings to be more ergo
authored Feb 12, 2011
426 * `,x` expands a wiki page seamfully and opens on a vertical split
427 * `,X` expands a wiki page seamlessly and opens on a vertical split
bb1e7f6 @danchoi remapping things around
authored Feb 20, 2011
428 * `,xx` expands a wiki page seamfully and opens on normal split
429 * `,XX` expands a wiki page seamlessly and opens on a normal split
0ba083a @danchoi change keybindings to be more ergo
authored Feb 12, 2011
430 * `q` closes the expanded view window
19bcc8e @danchoi change unfurl to expand; expand command
authored Feb 9, 2011
431
432 Both modes of expansion are useful when you want to assemble a long
6b9d669 @danchoi readme edit
authored Feb 9, 2011
433 piece of writing by using one page as a master outline that links to
434 other wiki pages that include the real content. And since expansion is
435 recursive, you can effectively nest outlines within outlines, like
436 dreams within dreams.
66c5cfa @danchoi readme
authored Feb 9, 2011
437
8eb801e @danchoi extra mappings for format, date, line
authored Feb 10, 2011
438
fdfd642 @danchoi readme edit
authored Feb 13, 2011
439 ## Exporting to HTML
440
424d3fe @danchoi edits
authored Feb 15, 2011
441 * `soywiki --html`
c341d3d @danchoi update readme
authored Feb 26, 2011
442 * `soywiki --html --markdown`
424d3fe @danchoi edits
authored Feb 15, 2011
443
444 Want to share your wiki with non-Vim-users? You can export your wiki
445 into a directory of HTML pages. Type `soywiki --html` from the root
446 directory of your wiki.
33a16a0 @danchoi edits
authored Feb 15, 2011
447
448 Aside from WikiWords, SoyWiki uses no markup system whatsoever. You can
449 write your content in whatever markup system you want, or no markup
c341d3d @danchoi update readme
authored Feb 26, 2011
450 system at all.
33a16a0 @danchoi edits
authored Feb 15, 2011
451
51acc48 @danchoi remove dependency on rdiscount to enable using on more minimal system
authored Jul 5, 2011
452 Please note that you need `haml` and `rdiscount` install on your system to
453 export to HTML.
c341d3d @danchoi update readme
authored Feb 26, 2011
454 By default, the HTML export feature just wraps your content in
455 <pre> tags after turning your WikiWords into hyperlinks.
33a16a0 @danchoi edits
authored Feb 15, 2011
456
c341d3d @danchoi update readme
authored Feb 26, 2011
457 If instead you want to write your pages using Markdown, you can process
458 Markdown by adding the `--markdown` flag.
fdfd642 @danchoi readme edit
authored Feb 13, 2011
459
460
8eb801e @danchoi extra mappings for format, date, line
authored Feb 10, 2011
461 ## Extra macros
462
1ceaca2 @danchoi edit
authored Feb 14, 2011
463 SoyWiki adds a few convenient Vim macros.
8eb801e @danchoi extra mappings for format, date, line
authored Feb 10, 2011
464
77f6dd5 @danchoi try to make extra macros local mappings
authored Feb 14, 2011
465 * `\` in normal mode reformats the current paragraph. It is equivalent to
19d09f6 @danchoi Switch from gwap to gqap
authored Feb 16, 2011
466 `gqap`. (`:help formatting`)
8eb801e @danchoi extra mappings for format, date, line
authored Feb 10, 2011
467 * `,-` inserts a long dashed line
35ebf7e @danchoi ,@ mapping is too close to ,#; use ,d
authored Feb 10, 2011
468 * `,d` inserts the current date and time
efb86eb @danchoi New macro ,D
authored Feb 18, 2011
469 * `,D` inserts a long dashed line, followed by the current date and time
8eb801e @danchoi extra mappings for format, date, line
authored Feb 10, 2011
470
471
2fa06a7 @danchoi show help mapping ,?
authored Feb 9, 2011
472 ## Getting help
473
c9c2b6b @danchoi readme edit
authored Feb 10, 2011
474 Typing `,?` will open the help webpage in a browser.
2fa06a7 @danchoi show help mapping ,?
authored Feb 10, 2011
475
66c5cfa @danchoi readme
authored Feb 9, 2011
476
353ddb2 @danchoi edit
authored Feb 18, 2011
477 ## CamelCase WikiLinks rule!
46b92a7 @danchoi edit readme
authored Feb 9, 2011
478
136bdda @danchoi edit readme
authored Feb 9, 2011
479 Some people don't like the CamelCase (a.k.a. WikiCase) wiki link
8546b5c @danchoi edit
authored Feb 18, 2011
480 pattern. But SoyWiki stands with CamelCase.
3eaf3eb @danchoi edit readme
authored Feb 9, 2011
481
48b655c @danchoi fix typo
authored Feb 14, 2011
482 * Besides being the original, CamelCase is the most elegantly minimalist approach to linking wiki pages together -- "with no additional markup whatsoever," [as Ward Cunningham put it][ward].
5fa64ba @danchoi readme edit
authored Feb 9, 2011
483 * It encourages you more than other wiki link patterns to create wiki pages with succinctly descriptive names that are easy to remember.
e8b8341 @danchoi edits
authored Feb 15, 2011
484 * Because the link pattern is so minimal and succinct, writing wiki links interrupts your flow of thought less than other wiki link patterns.
818b580 @danchoi edits
authored Feb 15, 2011
485 * CamelCase wiki links are less noisy than other link patterns in raw plain text form. This also contributes to flow.
1fbacec @danchoi edits
authored Feb 15, 2011
486 * The CamelCase link pattern 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 or munging.
136bdda @danchoi edit readme
authored Feb 9, 2011
487
488 [ward]:http://c2.com/cgi/wiki?WikiCase
489
b4c9c73 @danchoi edit
authored Feb 18, 2011
490 No wiki link pattern is perfect! All involve trade-offs. The CamelCase
d67ca14 @danchoi edit
authored Feb 18, 2011
491 pattern gives you a lot in return for its particular compromises.
8546b5c @danchoi edit
authored Feb 18, 2011
492
493
33a16a0 @danchoi edits
authored Feb 15, 2011
494 ## Bug reports and feature requests
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
495
ca3bbbd @danchoi README edits
authored Feb 14, 2011
496 SoyWiki is very new, so there are kinks and bugs to iron out and lot of
497 desirable features to add. If you have a bug to report or a good feature to
498 suggest, please file it on the [issue tracker][1]. That will help a lot.
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
499
500 [1]:https://github.com/danchoi/soywiki/issues
501
33a16a0 @danchoi edits
authored Feb 15, 2011
502 You can also join the [Google Group][group] and comment there.
503
504 [group]:http://groups.google.com/group/soywiki-users?msg=new&lnk=gcis
505
506 ## How to contact the developer
507
508 My name is Daniel Choi. I am based in Cambridge, Massachusetts, USA, and you
509 can email me at dhchoi {at} gmail.com.
510
0a128d8 @danchoi working on extraction commands
authored Feb 9, 2011
511
Something went wrong with that request. Please try again.