magmasource: add documentation

README.rst

@@ -1377,8 +1377,6 @@ For exemple, to grow 40 plump helmet spawn:
 
     growcrops plump 40
 
-This is a ruby script and needs the ruby plugin.
-
 
 removebadthoughts
 =================
@@ -1396,8 +1394,6 @@ you unpause.
 With the optional ``-v`` parameter, the script will dump the negative thoughts
 it removed.
 
-This is a ruby script and needs the ruby plugin.
-
 
 slayrace
 ========
@@ -1418,3 +1414,23 @@ after selecting the unit with the 'v' cursor:
 :: 
     rb_eval df.unit_find.body.blood_count = 0
 
+
+magmasource
+===========
+Create an infinite magma source on a tile.
+
+This script registers a map tile as a magma source, and every 12 game ticks
+that tile receives 1 new unit of flowing magma.
+
+Place the game cursor where you want to create the source (must be a
+flow-passable tile, and not too high in the sky) and call
+:: 
+    magmasource here
+
+To add more than 1 unit everytime, call the command again.
+
+To delete one source, place the cursor over its tile and use ``delete-here``.
+To remove all placed sources, call ``magmasource stop``.
+
+With no argument, this command shows an help message and list existing sources.
+

scripts/magmasource.rb

@@ -1,11 +1,11 @@
 # create an infinite magma source at the cursor
 
 $magma_sources ||= []
-$magma_onupdate ||= nil
 
 case $script_args[0]
 when 'here'
     $magma_onupdate ||= df.onupdate_register(12) {
+        # called every 12 game ticks (100x a dwarf day)
         if $magma_sources.empty?
             df.onupdate_unregister($magma_onupdate)
             $magma_onupdate = nil
@@ -52,14 +52,15 @@ when 'stop'
 else
     puts <<EOS
 Creates a new infinite magma source at the cursor.
+
 Arguments:
  here - create a new source at the current cursor position
-        call multiple times for higher flow
+        (call multiple times for higher flow)
  delete-here - delete the source under the cursor
  stop - delete all created magma sources
 EOS
 
     if $magma_sources.first
-        puts "Current magma sources:", $magma_sources.map { |s| " #{s.inspect}" }
+        puts '', 'Current magma sources:', $magma_sources.map { |s| " #{s.inspect}" }
     end
 end