soywiki 0.0.9 → 0.1.1

data/.gitignore

@@ -8,3 +8,4 @@ pkg/
 notes.txt
 *buffer
 wiki/
+soywiki.html

data/README.markdown

@@ -44,12 +44,17 @@ SoyWiki is free and open source.
 * a recent version of Vim (SoyWiki is developed against Vim 7.2 and 7.3)
 * a recent version of Ruby (SoyWiki is developed using Ruby 1.9.2)
 * RubyGems (if Ruby version is older than 1.9)
-* a recent version of Git (1.7.0.4 or above to be safe)
+* 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
@@ -96,28 +101,37 @@ just run `soywiki`.
 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. The WikiLink you
-just typed 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 the main way of linking wiki pages together. You'll be
+with a WikiWord for it and format it in CamelCase. The WikiLink you just
+typed 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. 
 
 ## Wiki navigation 
 
-Because SoyWiki is not just wiki but also a Vim program, it lets you
-work a lot faster and with more economy than browser-based wikis. 
-
 You can navigate a SoyWiki wiki very quickly with the following
-commands. 
+commands: 
 
-* `CTRL-n` and `CTRL-p` move the cursor directly to the next or previous WikiLink on the page
+* `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
-* `,-` opens a WikiLink in a split window
-* `,|` does the same, but in a vertical split window
+* `CTRL-l` opens a WikiLink in a split window
+* `CTRL-n` does the same, but in a vertical split window
+* Both `q` and `CTRL-h` close 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
@@ -158,12 +172,22 @@ in Vim insert mode to invoke it.
 
 ## Wiki refactoring
 
-You can rename a wiki page with`,r`. You'll see a prompt asking
-you for the new name. Make sure it is valid CamelCase. After you press
-ENTER, SoyWiki will rename the page and update all the links on other
-pages in your wiki that need updating because of the change.
+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.)
 
-You can delete a page with `,#`. 
+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.
@@ -190,27 +214,36 @@ You can use these shortcuts:
 * `:SWInsert` → `:SWI`
 * `:SWAppend` → `:SWA`
 
-With `:SWLinkInsert` and `:SWLinkAppend` you can use tab-autocompletion
-to avoid typing out the whole command name.
+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
 
 To search your SoyWiki wiki, type `:SWSearch [search term]`. 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.  See `:help quickfix`
-for more QuickFix commands. 
+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. 
 
-Searches are case-insensitve by default. To do a case-sensitive search,
-add a `\C` to your search string, e.g.:
+Searches are case-sensitve by default. To do a case-insensitive search,
+add a `\c` to your search string, e.g.:
 
-    :SWSearch Gnu\C
+    :SWSearch Gnu\c
 
 Again, you can use `:SWS` as a shortcut.
 
 Under the hood, `:SWSearch` is just a thin wrapper around the `:vimgrep`
 command.
 
+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
 
@@ -237,6 +270,14 @@ the general instructions [here][git-sync].
 
 [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.
+
 
 ## Namespaced WikiWords
 
@@ -306,6 +347,18 @@ other wiki pages that include the real content. And since expansion is
 recursive, you can effectively nest outlines within outlines, like
 dreams within dreams.  
 
+
+## 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.

data/bin/soywiki-expand

@@ -3,14 +3,17 @@ require 'soywiki'
 
 # Takes any wiki link that stands alone on a line and expands it
 
-WIKI_LINK_PATTERN =  /^\s*(([a-z]\w+\.)?[A-Z][a-z]+[A-Z]\w*|\.[A-Z][a-z]+[A-Z]\w*)\s*$/
+# this is different from Soywiki::WIKI_WORD in that it requires ^\s* before the
+# first letter
+
+WIKI_LINK_PATTERN =  /^\s*([a-z]\w+\.)?[A-Z][a-z]+[A-Z]\w*/
 
 PROCESSED_FILES = []
 
 def indent(text, level, mode)
   return text if mode == 'seamless'
   return text if level == 0
-  (': ' * level) +  text
+  (':' * level) + ' ' +  text
 
 end
 

data/bin/soywiki-ls-t

@@ -1,10 +1,12 @@
 #!/usr/bin/env ruby
 require 'soywiki'
 
-xs = Dir.glob(File.join('**', '*')).select {|x|
-  File.file?(x) && 
-    x.gsub('/', '.') =~ Soywiki::WIKI_WORD
-}.sort_by {|x|
-  File.stat(x).mtime
-}.reverse.map {|x| x.to_page_title}
+# this emulates ls -t in unix, but searches subdirs and returns a flat list of
+# files
+
+xs = Dir.glob('*/*').
+    select {|x| File.file?(x) && x.gsub('/', '.') =~ Soywiki::WIKI_WORD }.
+    sort_by {|x| File.stat(x).mtime }.
+    reverse.map {|x| x.to_page_title }
+
 puts xs.join("\n")

data/bin/soywiki-pages-linking-in

@@ -2,29 +2,25 @@
 # encoding: utf-8
 require 'soywiki'
 
-def inbound_links_to?(file, page_title)
+def contains_links_to?(file, page_title)
   return false unless File.file?(file)
   return false if (file =~ /(\.swo|\.swp)$/ || file =~ /^\./)
   body =   File.read(file)
+  # '.' must be escaped in the regular expression to match literal
   body =~ /[\A\s\n\b]#{page_title.gsub(".", "\.")}\b/
 end
 
-target_page = ARGV.first
+target_page = ARGV.first.dup
+# make sure this is a title, not a path
+target_page.gsub!("/", ".")
 
-if target_page.namespaced?
-  namespace, page = *target_page.split(".")
-  # find all files in this namespace
-  xs = Dir.glob(File.join("#{namespace}", "*")).select do |file|
-    inbound_links_to?(file, target_page) || inbound_links_to?(file, ".#{page}")
-  end
-  ys = Dir.glob(File.join("**", '*')).select do |file|
-    inbound_links_to?(file, target_page) 
-  end
-  (xs + ys).uniq.sort.
-    each {|x| puts x.to_page_title}
-else
-  Dir.glob(File.join("**", '*')).select do |file|
-    inbound_links_to?(file, target_page)
-  end.
-    each {|file| puts file.to_page_title}
+
+# find all files in this namespace
+xs = Dir.glob("#{target_page.namespace}/*").select do |file|
+  contains_links_to?(file, target_page) || contains_links_to?(file, target_page.short_page_title)
+end
+ys = Dir.glob('*/*').select do |file|
+  contains_links_to?(file, target_page) 
 end
+(xs + ys).uniq.sort.each {|x| puts x.to_page_title}
+

data/bin/soywiki-rename

@@ -3,7 +3,6 @@ require 'soywiki'
 
 oldname, newname = *ARGV
 
-
 MEMO = ["Updating inbound and outbound links..."]
 
 def report(file, oldname, newname)
@@ -15,78 +14,69 @@ def change_all_absolute_links(oldname, newname)
   target_files = `grep -rlF '#{oldname.to_page_title}' *`.strip.split(/\n/)
   target_files.each do |file|
     text = File.read(file)
-    text.gsub!(/\b#{oldname.to_page_title}\b/, newname.to_page_title)
+    regex = /\b#{oldname.to_page_title}\b/
+    matches = text.scan(regex)
+    text.gsub!(regex, newname.to_page_title)
     File.open(file, 'w') {|f| f.puts text}
     report file, oldname.to_page_title, newname.to_page_title
   end
 end
 
-# Three other cases to cover, involving namespaces:
-#
-# Case 1: Oldname is namespaced, and Newname is in same namespace
-#
-# In the directory for OldName's namespace, change all referenecs to
-# .OldName to .NewName
-
-if oldname.namespaced? && (oldname.namespace == newname.namespace)
-  MEMO << "- Updating relative links in same namespace"
-  target_files = `grep -rlF '#{oldname.short_page_title}' #{oldname.namespace}/*`.strip.split(/\n/)
-  target_files.each do |file|
-    text = File.read(file)
-    text.gsub!(/([\b\s\n]\.)(#{oldname.short_page_title})\b/, '\1' + newname.short_page_title)
-    File.open(file, 'w') {|f| f.puts text}
-    report file, oldname.short_page_title, newname.short_page_title
-  end
-end
-
-# newname can be absolutized or top level or relative
-def change_relative_inbound_links(oldname, newname)
-  MEMO << "- Updating relative inbound links"
-  target_files = `grep -rlF '#{oldname.to_page_title}' #{oldname.namespace}/*`.strip.split(/\n/)
+def change_unqualified_inbound_links_in_same_namespace(oldname, newname)
+  MEMO << "- Updating unqualified inbound links"
+  target_files = `grep -rlF '[^.]#{oldname.short_page_title}' #{oldname.namespace}/*`.strip.split(/\n/)
   target_files.each do |file|
     text = File.read(file)
-    text.gsub!(/[\b\s\n]\.(#{oldname.short_page_title})\b/, "." + newname)
+    text.gsub!(/(\A|\s)#{oldname.short_page_title}\b/, "." + newname)
     File.open(file, 'w') {|f| f.puts text}
     report file, oldname.short_page_title, newname
   end
 end
 
-RELATIVE_LINK_REGEX =/([\A\s\n\b])\.([A-Z][a-z]+[A-Z]\w*)/
+RELATIVE_LINK_REGEX =/(\A\s)([A-Z][a-z]+[A-Z]\w*)/
 
-def absolutize_relative_outbound_links(oldname, newname)
-  MEMO << "Absolutizing relative inbound links"
-  if File.exist?(newname.to_file_path)
-    text = File.read(newname.to_file_path)
+def absolutize_unqualified_outbound_links(oldname, newname)
+  MEMO << "Absolutizing unqualified inbound links"
+  target_file = newname.to_file_path
+  if File.exist?(target_file)
+    text = File.read(target_file)
     matches = text.scan(RELATIVE_LINK_REGEX)
-    text.gsub!(RELATIVE_LINK_REGEX, '\1' + oldname.namespace + '.\2')
-    File.open(newname.to_file_path, 'w') {|f| f.puts text}
-    MEMO <<  "  - In file #{file}: Absolutized these relative links: #{matches.inspect}"
+    text.gsub!(RELATIVE_LINK_REGEX, oldname.namespace + '.\1')
+    File.open(target_file, 'w') {|f| f.puts text}
+    MEMO <<  "  - In file #{target_file}: Absolutized these unqualified links: #{matches.inspect}"
   end
 end
 
 
-# Case 2: Oldname is namespaced, and Newname is in different namespace
-if oldname.namespaced? && newname.namespaced? && (oldname.namespace != newname.namespace)
-  # In the directory for OldName's namespace, change all references to
-  # .OldName to newnamespace.NewName (i.e. NewName).
-  change_relative_inbound_links(oldname, newname)
-  # And in the renamed file, change all relative references to
-  # .PageName to oldnamespace.PageName
-  absolutize_relative_outbound_links(oldname, newname)
+# Three other cases to cover, involving namespaces:
+#
+# Case 1: newname is in same namespace as oldname
+#
+# In the directory for OldName's namespace, change all unqualified referenecs to
+# OldName to NewName
+
+if oldname.namespace == newname.namespace
+  MEMO << "- Updating unqualified links in same namespace"
+  target_files = `grep -rlF '#{oldname.short_page_title}' #{oldname.namespace}/*`.strip.split(/\n/)
+  target_files.each do |file|
+    text = File.read(file)
+    text.gsub!(/(\A\s)(#{oldname.short_page_title})\b/, newname.short_page_title)
+    File.open(file, 'w') {|f| f.puts text}
+    report file, oldname.short_page_title, newname.short_page_title
+  end
 end
 
-# Case 3: Oldname is namespaced, and Newname is top level
-if oldname.namespaced? && !newname.namespaced? 
-  # In the directory for OldName's namespace, change all references to
-  # .OldName to TopLevelNewName (i.e. NewName)
-  change_relative_inbound_links(oldname, newname)
-  # And in the renamed file, change all relative references to
-  # .PageName to oldnamespace.PageName
-  absolutize_relative_outbound_links(oldname, newname)
+# Case 2: newname is in different namespace from oldname
+if oldname.namespace != newname.namespace
+  # In the directory for OldName's namespace, change all unqualified references to
+  # OldName to newnamespace.NewName (i.e. NewName).
+  change_unqualified_inbound_links_in_same_namespace(oldname, newname)
+  # And in the renamed file, change all unqualified references to
+  # PageName to oldnamespace.PageName
+  absolutize_unqualified_outbound_links(oldname, newname)
 end
 
 # Finally,
-
 change_all_absolute_links oldname, newname
 
 puts MEMO.join("\n")

data/lib/soywiki.rb

@@ -1,11 +1,5 @@
 
 class String
-  def is_namespaced?
-    self.split(/\.|\//).size == 2
-  end
-
-  alias :namespaced? :is_namespaced?
-
   # TODO change this to a Windows compatible approach
   def to_file_path
     self.gsub(".", "/")
@@ -20,15 +14,14 @@ class String
   end
 
   def namespace
-    return nil unless self.namespaced?
     self.to_page_title.split('.')[0]
   end
 end
 
 
 module Soywiki
-  VERSION = '0.0.9'
-  WIKI_WORD = /\b([a-z][\w_]+\.)?[A-Z][a-z]+[A-Z]\w*\b|\.[A-Z][a-z]+[A-Z]\w*\b/
+  VERSION = '0.1.1'
+  WIKI_WORD = /\b([a-z][\w_]+\.)?[A-Z][a-z]+[A-Z]\w*\b/
 
   def self.run
     if %W( -v --version -h --help).include?(ARGV.first)