rote 0.2.0 → 0.2.2

data/CONTRIBUTORS

@@ -0,0 +1,14 @@
+== The Contributors
+
+Many of Rote's best bits come from contributions made by other Rubyists,
+whether in the form of fully pegged-out features, patches, or suggestions.
+Without the help and guidance of these people, Rote would almost certainly 
+suck like a hoover.
+
+===== Jonathan Paisley <jp-www at dcs gla ac uk> 
+* Auto -run tasks
+* COMMON.rb inheritance (with BOC)
+* Rake magic
+* better resource management
+* Many other suggestions for improvements
+

data/README

@@ -15,17 +15,17 @@ layout, and general documentation / website build tasks.
 Rote uses the following (versions are as per my development environment,
 you may find you can use older versions, you may not).
 	
-* Ruby 1.8.3 ('yum install ruby' on Fedora 4)
+* Ruby 1.8.x 
 * Rake 0.6.2 ('gem install rake')
-* RedCloth 3.0.4 ('gem install RedCloth')
+* RedCloth 3.0.4 ('gem install RedCloth') (_Only required if :textile or :markdown formatting is used_)
 
 RubyGems [http://rubyforge.org/frs/?group_id=126] is *highly recommended*,
 and makes for not only an easier install but a cleaner library path.
 Rote is tested with Gems 0.8.11.
 
 Please note that Rote is written and tested on Linux - I have no facilities
-to test with, e.g. Windows, and would like to hear about any issues that affect
-usage with other OSes.
+to test with, e.g. Windows, and would like very much to hear about any issues 
+that affect usage with other OSes.
 
 == Installation ... 
 

data/Rakefile

@@ -6,7 +6,7 @@
 # This Rakefile is heavily based on Rake's own Rakefile.
 # Portions copyright (c)2003, 2004 Jim Weirich (jim <AT> weirichhouse.org)
 #
-# $Id: Rakefile,v 1.9 2005/12/01 11:06:40 roscopeco Exp $
+# $Id: Rakefile,v 1.10 2005/12/02 20:07:16 roscopeco Exp $
 #
 
 begin
@@ -108,7 +108,7 @@ rd = Rake::RDocTask.new("rdoc") { |rdoc|
   rdoc.template = 'doc/jamis.rb'
   rdoc.title    = "Rote"
   rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
-  rdoc.rdoc_files.include('README', 'LICENSE', 'TODO')
+  rdoc.rdoc_files.include('README', 'LICENSE', 'TODO', 'CONTRIBUTORS')
   rdoc.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc')
   rdoc.rdoc_files.exclude(/\bcontrib\b/)
 }
@@ -120,7 +120,7 @@ ws = Rote::DocTask.new(:doc) { |site|
   site.pages.dir = 'doc/pages'
   site.pages.include('**/*')  
   
-  site.res.dir = 'doc/res/'
+  site.res.dir = 'doc/res'
   site.res.include('**/*.png')
   site.res.include('**/*.gif')
   site.res.include('**/*.jpg')

data/TODO

@@ -7,9 +7,10 @@ Send any suggestions (or test-driven patches) to:
 
 * More flexible markup rendering
 * Nested layouts
-* Integration with test reports
-* Automatic navigation / TOC
+* Find and Integrate test run / coverage reports
 * Ability to have multiple views of a section, e.g. user guide (separate
   pages) and user guide (one page) generated from same source.
 * Index and glossary support
 * statistics
+* (maybe?) Automatic navigation / TOC
+* (maybe?) Rant integration

data/doc/layouts/page.html

@@ -40,7 +40,8 @@
 	
 	<div class='copyright'><strong>&copy; 2005 Ross Bamford</strong><br/>
 		Managed with <a href='http://ruby-lang.org'>Ruby</a> + <a href='http://rake.rubyforge.org'>Rake</a> + <a href='http://rote.rubyforge.org/'>Rote</a><br/>
-		Hosting &amp; development services provided by <a href='http://rubyforge.org/'>RubyForge.org</a>		
+		Hosting &amp; development services provided by <a href='http://rubyforge.org/'>RubyForge.org</a><br/>
+		[<a href='http://validator.w3.org/check?uri=referer'>Validate</a>]
 		<p/>&nbsp;
 	</div>			
 </body>

data/doc/pages/COMMON.rb

@@ -33,6 +33,6 @@ format_opts << :textile
 					 :url => 'http://rubyforge.org/projects/rote'},					 
 					{:title => 'Browse CVS',
 					 :url => 'http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote'},
-					{:title => 'License',
+					{:title => 'Licence',
 					 :url => '/license.html'}					 
 					]

data/doc/pages/guide/index.html

@@ -9,7 +9,9 @@ for installation instructions.
 <a name='top'/>
 h3. Contents
 
+  * "Conventions":#conventions
   * "Getting started with Rote":#getting_started
+  ** "Documentation source layout":#getting_started_source_layout
   ** "From the command-line":#getting_started_command_line
   ** "From your Rakefile":#getting_started_rakefile
   * "Creating templates":#create_templates
@@ -18,19 +20,30 @@ h3. Contents
   ** "Template code & ERB":#create_templates_erb
   ** "Applying layout":#create_templates_layout
   * "Resources":#resources
+  * "Source monitoring":#monitor
   * "Publishing":#publishing
   
+<a name='conventions'/>
+h3. Conventions used in this document
+
+*Task names* - Rote's standard tasks are always referred to with the base-name
+_doc_ , e.g. @doc_pages@, @doc_clean@, and just plain @doc@. This is the prefix
+used by the built-in Rakefile, but since it can be changed when using Rote in
+your own Rake builds you should of course substitute whatever is appropriate 
+if you have chosen to modify it.
+
 <a name='getting_started'/>
 h3. Getting started with Rote
 
-h4. Setting up a project
+<a name='getting_started_source_layout'/>
+h4. Documentation source layout
 
 To get started quickly, we'll use the standard Rote directory layout, which
 can be used immediately with the command-line wrapper, and fits well with
 Rakefile usage too. Basically, Rote expects your documentation source to
 be laid out as follows:
 
-<code><pre>  
+<p><code><pre>  
   project_root ( <- root, this can be called whatever you like)
   |
   |--> [publish.rf]
@@ -54,7 +67,7 @@ be laid out as follows:
   |    |    |    |--> bpage.html
   |    |    |    |--> [bpage.rb]   
 			  
-</code></pre>
+</pre></code></p>
 
 Template sources under the 'pages' directory may have any extension (except
 @rb@), and will be rendered to that same name under the output directory. 
@@ -66,7 +79,7 @@ directory. See "the section on templates":#create_templates for more
 information on the specifics.
 
 If you've downloaded Rote, then you can see the canonical example site by
-looking in the =doc/= directory (where you'll find the source for this
+looking in the @doc/@ directory (where you'll find the source for this
 site).
 
 ["top":#top]
@@ -83,7 +96,7 @@ setting up library dependencies and generation of appropriate tasks.
 The command-line wrapper expects the above layout, and requires no direct
 configuration. To generate an entire documentation set, simply run:
 
-<pre><code>        rote</code></pre>
+<p><pre><code>        rote</code></pre></p>
 	
 from the top-level directory (@project@ in the example above), you should get
 a 'html' directory created with the (transformed) templates, and any 
@@ -100,20 +113,20 @@ The file tasks are named for the target files, so for example to generate
 just the top-level index.html (regardless of whether it's been modified)
 you'd run:
 
-<pre><code>        rote html/index.html</code></pre>
+<p><pre><code>        rote html/index.html</code></pre></p>
 
-The @clean@ task supports deleting all output files to start from scratch:
+The @clobber@ task supports deleting all output files to start from scratch:
 
-<pre><code>        rote clean</code></pre>
+<p><pre><code>        rote clobber</code></pre></p>
 
 Of course, multiple file or task names (or a mixture) can be specified.
 You can get a list of valid tasks in the current context with:
 
-<pre><code>        rote --tasks</code></pre>
+<p><pre><code>        rote --tasks</code></pre></p>
 	
 Further command-line usage information is available with:
 	
-<pre><code>        rote --usage</code></pre>
+<p><pre><code>        rote --usage</code></pre></p>
 	
 and Unix installations performed with =install.rb= should also make a
 manpage available for the @rote@ command.
@@ -166,7 +179,7 @@ h3. Creating templates
 <a name='create_templates_basics'/>
 h4. The basics
 
-As mentioned, templates are simply text files in the =doc/pages= directory. The
+As mentioned, templates are simply text files in the @doc/pages@ directory. The
 layout below that directory is retained when transforming pages, and is
 also used to provide simple hierarchical structure to the common page code.
 
@@ -186,7 +199,7 @@ The formatting applied to a given page is controlled by that page's @format_opts
 array. All three are disabled by default - to enable formatting you must add
 appropriate symbols to the array, for example in page code or COMMON.rb:
 
-<pre><code>        format_opts << :textile << :markdown << :rdoc</code></pre>
+<p><pre><code>        format_opts << :textile << :markdown << :rdoc</code></pre></p>
 
 This can be done in page code, COMMON.rb, or even inside the template itself.
 See "the section on template code":#create_templates_erb for more information
@@ -196,9 +209,10 @@ then Rdoc.
 	
 *Some additional notes on formatting*
 
-  * Although you can directly assign to @format_opts@, this isn't recommended 
-    since Ruby often interprets it as a local variable set rather than method call, 
-    resulting in much head scratching as to why your options are being ignored.
+  * You cannot directly assign to @format_opts@, from page code since Ruby 
+    interprets assignments with no receiver as local variable sets rather than
+    method calls, resulting in much head scratching as to why your options are 
+    being ignored. Always use the << :opt syntax.
     
   * Note that *Formatting is applied _after_ any ERB has been evaluated.*
 
@@ -224,7 +238,7 @@ you might define such variables. The following is in order of evaluation:
 * In a block passed to Page.new
 * In the template itself
 
-When a =Rote::Page= instance is created, Rote looks for these, and if found
+When a @Rote::Page@ instance is created, Rote looks for these, and if found
 evaluates them, in order, in the same binding as the template is later rendered
 in (i.e. the @Page@ instance binding). Therefore, you can define
 instance variables to pass data around, or even helper methods if you wish.
@@ -234,27 +248,29 @@ instance variables to pass data around, or even helper methods if you wish.
 <a name='create_templates_layout'/>
 h4. Layout
 
-Layouts are stored under the =doc/layouts= directory (by default). They may
+Layouts are stored under the @doc/layouts@ directory (by default). They may
 be organised into subdirectories, but this hierarchy is not connected to
 the hierarchy in @pages@. To apply a layout to a page, simply call the
-=Rote::Page.layout= method from code applied to that page, passing the
+@Rote::Page.layout@ method from code applied to that page, passing the
 base-name (and path, relative to @layouts@, if used). If no extension is
 specified, then the same extension as the page itself is assumed. Examples:
 
-<pre>
-	layout 'one'
-	layout 'main/wide'
-	layout 'dark.txt'
-	&lt;% layout 'my' %&gt;
-</pre>	
+  * layout 'one'
+  * layout 'main/wide'
+  * layout 'dark.txt'
+  * <&#37; layout 'my' &#37;>
+  
+_*Note* the absence of the = sign   in the ERB tag in the last example,_
+_indicating that this is code to be executed rather than code that should_
+_generate output._
 
 With that done, Rote would first render the template text (including textile)
-and set the Page instance variable =@content_for_layout= before rendering 
+and set the Page instance variable @\@content_for_layout@ before rendering 
 the layout (in which textile is currently not supported). The layout is
 responsible for inserting the rendered template where appropriate, with
 e.g.:
 
-<pre>        &lt;%= @content_for_layout %&gt;</pre>
+  * <&#37;= @content_for_layout &#37;>
 
 This pattern shouldn't be unfamiliar. Again, note that Rote doesn't mandate 
 HTML, despite the appearance from the ERB tags - any (textual) format can
@@ -267,26 +283,64 @@ h3. Resources
 
 Of course, you're likely to have resources for your site (images, sounds, etc)
 and you'll need to copy them over to the target too. Such resources should be
-placed under 'res' (with the commandline setup) or in your specified @res@
-directory, and will be copied directly to the output directory after page
-rendering.
+placed under @doc/res@ (with the commandline setup) or in your specified @res@
+directory (from a Rakefile).
 
 As you'd expect, the directory layout beneath @res@ should mirror that of the 
-output, and will be preserved during the copy.
+output, and will be preserved during the copy. Resources are copied only if
+necessary (determined by existence and last-modified timestamp), in a similar
+way to pages.
 
 ["top":#top]
 
+<a name='monitor'/>
+h3. Source monitoring
+
+When making changes to a documentation set, you frequently need to render out
+your changes to check formatting or ensure something works correctly. In this
+situation it's inconvenient to keep dropping out to your shell to run @rote@
+(or @rake@) manually, particularly when making a lot of incremental changes.
+
+Fortunately, Rote provides a simple mechanism for monitoring your documentation
+source and automatically performing updates as needed. Simply specify the 
+@doc_monitor@ task and Rote will go into a loop, periodically running the
+top-level _doc_ task which will transform / copy any pages or resources that
+have been modified. It will of course take notice of any custom file or directory
+dependencies you add to the doc task (e.g. to generate RDoc as part of a
+website), and in turn monitor their dependent files too (for example rebuilding
+the RDoc if you modify a source file). It does *not* however attempt to track
+format-specific dependencies _between_ resources (such as which pages use which
+CSS), since this would imply some knowledge of the format in use. In practice
+this means that you may need to trigger a clean build after updating such
+resources, although it is actually fairly easy to set up this kind of 
+relationship by specifying that certain file-tasks relating to pages depend 
+on the appropriate file-tasks representing the resources (for instance).
+
+By default, @monitor@ checks for updates approximately once
+per second, but you can specify a custom value _when using a Rakefile_ by
+setting @monitor_interval@ in the block passed to @DocTask.new@.
+
+*Note* that the monitor functionality is deliberately kept simple with respect
+to IO and concurrency, reflecting the fact that output files are rarely
+anything more than that - it would be almost pointless to complicate the
+way monitoring works with any kind of semaphore or file-locking scheme.
+Of course if this does cause problems in your particular scenario, let me know
+because it just might make me reconsider.
+
+When you're done with Rote simply hit CTRL-C (or use @kill@) to stop monitoring
+and exit.
+
 <a name='publishing'/>
 h3. Publishing
 
 Rote does not provide any direct support for publishing your site at present,
 relying on you to configure an appropriate publish task if required, using
-the publishers supplied with Rake (in =rake/contrib=), or your own. This 
+the publishers supplied with Rake (in @rake/contrib@), or your own. This 
 allows maximum flexibility, and allows Rote to concentrate on creating your 
 documents.
 
 The command-line build will automatically look for a file in the top-level
-directory (above @doc@) named =publish.rf=. If found, this file will be 
+directory (above @doc@) named @publish.rf@. If found, this file will be 
 evaluated by Rake, making any tasks defined within it available to your
 build. The most likely use case is to define a task that uses an SSH directory
 publisher to publish via SCP.
@@ -300,12 +354,12 @@ Currently, there isn't enough checking involved on source resources when
 building pages - Basically, only templates are considered when Rake decides
 what to update. If you change layouts, code or resources you'll need to run:
 	
-<pre><code>        rote clean</code></pre>
+<p><pre><code>        rote clobber</code></pre></p>
 		
 to make sure everything gets updated. It's recommended to always run upload
 as:
 	
-<pre><code>        rote clean upload</code></pre>
+<p><pre><code>        rote clobber upload</code></pre></p>
 	
 Please note that this isn't Rake's limitation - it's mine. It will be fixed
 in a later version of Rote.

data/doc/pages/index.html

@@ -2,7 +2,7 @@
 easier to author and maintain non-dynamic websites and 
 offline documentation.* Rote provides a simple commandline or 
 "Rake":http://rake.rubyforge.org based build for your pages, with page 
-rendering (optionally supporting Textile and Markdown with 
+rendering (optionally supporting RDoc formatting, Textile and Markdown with 
 "RedCloth":http://redcloth.rubyforge.org/ and ruby code with
 "ERB":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html), layout,
 and general documentation / website build tasks.
@@ -12,20 +12,20 @@ h3. Features
 Rote offers the following major features:
 
 	* Simple set-up based on page templates and sections.
-	* ERB, Textile, and Markdown supported out of the box.
+	* ERB, Textile, Markdown and RDoc supported out of the box.
 	* Multiple configurable layouts apply boilerplate to your pages.
 	* 'Scoped' Ruby code support allows fine-grained control of data available across 
 	  all documentation, a subset, or individual pages.
-	* Can be used standalone (from the command-line) or from within "Rake":http://rake.rubyforge.org
+	* Can be used standalone (from the command-line) or within "Rake":http://rake.rubyforge.org
 	  as a custom task library.
 	* Supports any (text-based) format, while providing utilities and helpers for
-	  common formats (HTML at present).
+	  common formats (HTML at present, integration with CSS builder etc. hoped for).
 
 Rote is somewhat similar to (though simpler than) 
 "WebGen":http://webgen.rubyforge.org , which provides a richer environment
 geared more toward websites and content publishing (whereas Rote's
 implementation as an extension to Rake reflects a bias toward software 
-documentation).
+documentation and general textual templating).
 
 See the "User guide":<%= link_rel '/guide' %> and "RDoc":<%= link_rel '/rdoc' %> for usage information.
 
@@ -35,17 +35,17 @@ You can get Rote via "RubyGems":http://rubyforge.org/projects/rubygems if you ha
 
 	* <strong><code>gem install -r rote</code></strong>
 
-Alternatively, you can download tarball / zip packages from: 
+Alternatively, you can download tarball / zip packages if you don't: 
 
   * <strong>"http://rubyforge.org/frs/?group_id=1120":http://rubyforge.org/frs/?group_id=1120</strong>
 
-You can also grab the latest code from "CVS":http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote. 
+You can also grab the latest code from "CVS":http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote.
 
 h4. From CVS 
 
 A link to the latest stable release can be found from the "project page":http://rubyforge.org/projects/rote .
 
-Please note that Rote is still pretty new, and while currently fairly functional, it's
-also still shiny and new, and liable to break down, destroy data, and run away with your spouse if
-given half a chance. Sound like fun? Then check out the "Project page on Rubyforge":http://rubyforge.org/projects/rote 
-for everything you need to get going with the CVS version!
+Please note that Rote is still fairly new, and though it's so far not shown itself to be particularly
+anti-social, it's by no means a complete piece of kit. If that's okay with you (maybe you're 
+pretty happy-go-lucky in general...) then see the "Project page on Rubyforge":http://rubyforge.org/projects/rote 
+for everything you need to get going with the CVS version.

data/doc/res/stylesheets/normal.css

@@ -116,8 +116,8 @@ div.copyright {
 
 div.main {
 	/* main div on front page */
-	width: 90%;
-	margin: 2% 2% 2% 2%;
+	width: 70%;
+	margin: 50px 12% 50px 8%;
 }
 
 img.smallrpotlogo {
@@ -138,4 +138,12 @@ img.medlogo {
 img.smalllogo {
 	width: 147px;
 	height: 68px;
-}
+}
+
+h3 {
+	border-bottom: thin #959595 solid;
+}
+
+h4 {
+	border-bottom: thin #b8c8c8 solid;
+}

data/lib/rote.rb

@@ -41,7 +41,7 @@ require 'net/ftp'
 require 'rake'
 
 # Master Rote version. Manage this from the Rake release support.
-ROTEVERSION = '0.2.0'
+ROTEVERSION = '0.2.2'
 
 #####
 ## *Rote* is a Rake (http://rake.rubyforge.org) based build tool for page-based

data/lib/rote/builtin.rf

@@ -5,17 +5,25 @@ require 'rake'
 require 'rake/clean'
 require 'rote'
 
-CLEAN.include('html')
-
-# Create a task build the website / docs
-ws = Rote::DocTask.new("doc") { |site| 
+# Create tasks to build the doc tree
+# 
+# Creates the following tasks
+#
+#		doc                        - Everything
+#   doc-pages                  - Transform all modified pages
+#		doc-res                    - Copy all resources
+#		doc-clean                  - Remove generated documentation
+#		html/[filename]            - Transform single [filename] unconditionally
+#		doc-monitor								 - Start monitor mode on doc source
+#
+ws = Rote::DocTask.new(:doc) { |site| 
   site.output_dir = 'html'
   site.layout_dir = 'doc/layouts'
 
   site.pages.dir = 'doc/pages'
   site.pages.include('**/*')  
   
-  site.res.dir = 'doc/res/'
+  site.res.dir = 'doc/res'
   site.res.include('**/*.png')
   site.res.include('**/*.gif')
   site.res.include('**/*.jpg')

data/lib/rote/page.rb

@@ -31,10 +31,12 @@ module Rote
     # when (if) the page source calls layout(basename).
     attr_reader :layout_text
     
-    # Formatting options passed to RedCloth. This is an array of the
-    # option symbols defined by RedCloth.
-    # The most common are :textile and :markdown. See RedCloth
-    # documentation for full details of supported options.
+    # Formatting options for this page. This is an array of the
+    # option symbols, as defined by RedCloth, with a further +:rdoc+ 
+    # symbol that selects RDoc formatting. The most common are 
+    # :textile. :markdown, and :rdoc, but additional options are
+    # supported by RedCloth - see it's documentation for full details
+    # of supported option symbols and their effect.
     # 
     # The default is [], which means 'No formatting'. This setting
     # does not affect ERB rendering (which is always performed, before
@@ -77,8 +79,8 @@ module Rote
       # get script filenames, and eval them if found
       src_rb = template_fn.sub(/\..*$/,'') + '.rb'            
       section_rb = @fixme_dir + '/COMMON.rb'
-      instance_eval(File.read(section_rb)) if File.exists?(section_rb)     
-      instance_eval(File.read(src_rb)) if File.exists?(src_rb)    
+      instance_eval(File.read(section_rb),section_rb) if File.exists?(section_rb)     
+      instance_eval(File.read(src_rb),src_rb) if File.exists?(src_rb)    
       
       # Allow block to have the final say
       yield self if block_given?  
@@ -208,10 +210,12 @@ module Rote
       end
     end
     
-    # FIXME NASTY HACK II: relative links (doesn't work)
+    # FIXME NASTY HACK II: relative links (kinda works, but simply. Handy when
+    # you do both local preview from some deep directory, and remote deployment
+    # to a root)
     def link_rel(href) 
       thr = href
-      if thr.is_a?(String) && href[0,1] == '/'
+      if thr.is_a?(String) && href[0,1] == '/'    # only interested in absolute
         thr = href[1..href.length]     
         count = @fixme_dir.split('/').length - 2
         if count > 0 then count.times {
@@ -222,4 +226,4 @@ module Rote
     end
     
   end #class  
-end #module
+end #module

data/lib/rote/rotetasks.rb

@@ -63,7 +63,7 @@ module Rote
   class DocTask < Rake::TaskLib
     # Default exclusion patterns for the page sources. These are
     # applied along with the defaults from +FileList+. 
-    DEFAULT_SRC_EXCLUDES = [ /\.rb$/ ]
+    DEFAULT_SRC_EXCLUDES = [ /\.rb$/, /\.rf$/ ]
     
     # The base-name for tasks created by this instance, supplied at 
     # instantiation.
@@ -82,12 +82,25 @@ module Rote
     # Globs for the +FileList+ that supplies the resources to copy. You 
     # should configure the +layout_dir+ and +include+ at least one entry
     # here (you may add +exclude+ strings or regexps, too).
+    #
+    # This is *not* a +FileList+ - the patterns supplied to this are used
+    # with the base-directory specified to construct an appropriate
+    # +FileList+.
     attr_reader :res
     
     # If +show_page_tasks+ is +true+, then the file tasks created for each
     # source page will be shown in the Rake task listing from the command line.
-    attr_accessor :show_page_tasks         
-    alias :show_page_tasks? :show_page_tasks
+    attr_accessor :show_file_tasks         
+    alias :show_file_tasks? :show_file_tasks
+    alias :show_file_tasks= :show_file_tasks=
+    
+    # *Deprecated* alias for +show_file_tasks+. It will be removed.
+    alias :show_page_tasks? :show_file_tasks      # vv0.3.0 v-0.5
+    alias :show_page_tasks= :show_file_tasks=
+    
+    # The approximate number of seconds between update checks when running
+    # monitor mode (Default: 1)
+    attr_accessor :monitor_interval    
     
     # Create a new DocTask, using the supplied block for configuration,
     # and define tasks with the specified base-name within Rake.
@@ -96,6 +109,7 @@ module Rote
       @output_dir = '.'      
       @pages = FilePatterns.new('.')
       @res = FilePatterns.new('.')
+      @monitor_interval = 1
       DEFAULT_SRC_EXCLUDES.each { |excl| @pages.exclude(excl) }
       
       @show_page_tasks = false
@@ -114,55 +128,90 @@ module Rote
       nil
     end
     
+    # define a task for each resource, and 'all resources' task
     def define_res_tasks
       res_fl = res.to_filelist
+      tasks = res_fl.select { |fn| not File.directory?(fn) }.map do |fn|
+        tfn = fn.sub(/^#{res.dir}/, output_dir)
+        desc "#{fn} => #{tfn}" if show_file_tasks?
+        file tfn => [fn] do
+          dn = File.dirname(tfn)
+          mkdir_p dn unless File.exists?(dn)
+          cp fn, tfn
+        end
+        tfn
+      end
       
-      desc "Copy documentation resources"
-      task "#{name}-res" do
-        res_fl.each { |fn|           
-          unless File.directory?(fn)    # make dirs only as needed
-            tfn = fn.sub(/#{res.dir}/, output_dir)
-            dn = File.dirname(tfn)
-            mkdir_p dn unless File.exists?(dn)            
-            cp fn, tfn
-          end        
-        }
-      end #task
+      desc "Copy new/changed resources"
+      task "#{name}_res" => tasks     
     end
 
+    # define a task for each page, and 'all pages' task
     def define_page_tasks
-      # make file list
-      pages_fl = pages.to_filelist
-    
-      # define a task for each page
-      realpages = FileList[]
-      pages_fl.each { |fn| 
-        unless File.directory?(fn)    # make dirs only as needed
-          realpages << fn
-          tfn = fn.sub(/^#{pages.dir}/, output_dir)
-          
-          desc "#{fn} => #{tfn}" if show_page_tasks?
-          file tfn => [fn] do
-            dn = File.dirname(tfn)
-            mkdir_p dn unless File.exists?(dn)
-            File.open(tfn, 'w+') { |f|
-              puts "tr #{fn} => #{tfn}"
-              f << Page.new(fn,layout_dir).render
-            }
-          end
+      pages_fl = pages.to_filelist    
+      tasks = pages_fl.select { |fn| not File.directory?(fn) }.map do |fn| 
+        tfn = fn.sub(/^#{pages.dir}/, output_dir)          
+        desc "#{fn} => #{tfn}" if show_file_tasks?
+        file tfn => [fn] do
+          dn = File.dirname(tfn)
+          mkdir_p dn unless File.exists?(dn)
+          File.open(tfn, 'w+') do |f|
+            puts "tr #{fn} => #{tfn}"
+            f << Page.new(fn,layout_dir).render
+          end          
         end
-      }
+        tfn
+      end
       
-      # this is pretty convenient ;]
-      desc "Render all documentation pages"
-      task "#{name}-pages" => realpages.sub(/#{pages.dir}/, output_dir)
+      desc "Render new/changed documentation pages"
+      task "#{name}_pages" => tasks
     end
     
     def define_main_tasks
       desc "Build the documentation"
-      task name => ["#{name}-pages", "#{name}-res"]
+      task name => ["#{name}_pages", "#{name}_res"]
+
+      task :clobber => [ "clobber_#{name}" ]
+      desc "Remove the generated documentation"
+      task "clobber_#{name}" do
+        rm_rf output_dir
+      end    
+      
+      # thanks to Jonathan Paisley for this :)    
+      # Relies on Rake mods made below.
+      desc "Monitor and automatically rebuild the documentation"
+      task "#{name}_monitor" do
+        loop do
+          Rake::Task::tasks.each { |t| t.reset }
+          Rake::Task[name].invoke
+          if Rake::Task::tasks.grep(Rake::FileTask).detect { |t| t.executed? } then
+            Rake::Task["#{name}_refresh"].invoke if Rake::Task.task_defined?("#{name}_refresh")
+          end
+          sleep monitor_interval
+        end
+      end        
+      
     end
     
   end #class  
   
-end #module
+end #module
+
+## The -run task requires a few mods to Rake to let us fire
+## and reset task invocations in a loop.
+module Rake
+  class Task
+    def reset
+      @already_invoked = false
+      @executed = false
+    end
+    def executed?
+      @executed
+    end
+    alias :pre_rote_execute :execute
+    def execute
+      @executed = true
+      pre_rote_execute
+    end
+  end
+end       

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: rote
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2005-12-01 00:00:00 +00:00
+  version: 0.2.2
+date: 2005-12-03 00:00:00 +00:00
 summary: Adds template-based doc support to Rake.
 require_paths: 
 - lib
@@ -33,6 +33,7 @@ files:
 - README
 - TODO
 - LICENSE
+- CONTRIBUTORS
 - bin/rote
 - lib/rote.rb
 - lib/rote/rotetasks.rb
@@ -102,6 +103,7 @@ extra_rdoc_files:
 - README
 - LICENSE
 - TODO
+- CONTRIBUTORS
 executables: 
 - rote
 extensions: []