Added usage documentation to script/debug_storage

script/debug_storage

@@ -1,5 +1,56 @@
 #!/usr/bin/ruby
 
+=begin
+The purpose of this script is to help people poke around in the Madeleine storage. 
+
+Two caveats:
+1. You MUST be a reasonably good Ruby programmer to use it successfully for anything non-trivial.
+2. It's very easy to screw up something by poking in the storage internals. If you do, please 
+   undo your changes by deleting the most recent snapshot(s) and don't ask for help.
+
+Usage example:
+
+E:\eclipse\workspace\instiki\script>irb
+irb(main):001:0> load 'debug_storage'
+Enter path to storage [E:/eclipse/workspace/instiki/storage/2500]:
+Loading storage from the default storage path (E:/eclipse/workspace/instiki/storage/2500)
+Instiki storage from E:/eclipse/workspace/instiki/storage/2500 is loaded.
+Access it via global variable $wiki.
+Happy poking!
+=> true
+irb(main):003:0> $wiki.system
+=> {"password"=>"foo"}
+irb(main):005:0> $wiki.system['password'] = 'bar'
+=> "bar"
+irb(main):006:0> $wiki.webs.keys
+=> ["wiki1", "wiki2"]
+irb(main):007:0> $wiki.webs['wiki1'].password = 'the_password'
+=> "the_password"
+irb(main):008:0> WikiService::snapshot
+=> []
+
+
+Things that are possible:
+
+# cleaning old revisions
+$wiki.webs['wiki'].pages['HomePage'].revisions = $wiki.webs['wiki'].pages['HomePage'].revisions[-1..-1]
+
+# Changing contents of a revision
+$wiki.webs['wiki'].pages['HomePage'].revisions[-1] = 'new content'
+
+# Checking that all pages can be rendered by the markup engine
+$wiki.webs['wiki'].pages.each_pair do |name, page|
+  page.revisions.each_with_index do |revision, i|
+    begin
+      revision.display_content
+    rescue =>
+      puts "Error when rendering revision ##{i} of page #{name.inspect}:"
+      puts e.message
+      puts e.backtrace.join("\n")
+    end
+end
+=end
+
 require 'fileutils'
 require 'optparse'
 require 'webrick'
@@ -41,6 +92,6 @@ require 'wiki_service'
 WikiService.storage_path = storage_path
 $wiki = WikiService.instance
 puts "Instiki storage from #{storage_path} is loaded."
-puts 'Access it a global variable $wiki.'
+puts 'Access it via global variable $wiki.'
 puts 'Happy poking!'
 nil