rote 0.3.2 → 0.3.2.2

data/README

@@ -5,7 +5,7 @@
 Rote is a simple page-based template system that was written to make it
 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, 
+build for your pages, with page rendering (optionally supporting Textile, RDoc, 
 Markdown, and embedded Ruby code with RedCloth [http://redcloth.rubyforge.org/]
 and ERB [http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html]), 
 layout, and general documentation / website build tasks.
@@ -120,7 +120,7 @@ though, so flame him if it breaks your day ;P
 * Homepage - http://rote.rubyforge.org/
 * Project - http://rubyforge.org/projects/rote
 * Issues - http://rubyforge.org/tracker/?group_id=1120
-* List - rote-devel@rubyforge.org
+* Lists - rote-users@rubyforge.org, rote-devel@rubyforge.org (http://rubyforge.org/mail/?group_id=1120)
 
 As you may have guessed, Rote's hosting and development services are provided
 by http://RubyForge.org .

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 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: Rakefile 171 2006-01-12 00:16:17 +0000 (Thu, 12 Jan 2006) roscopeco $
 #
 
 begin
@@ -151,6 +151,20 @@ ws = Rote::DocTask.new(:doc) { |site|
 # add rdoc dep to doc task
 task :doc => [:rdoc]
 
+desc "Publish the documentation and web site"
+task :doc_upload => [ :doc ] do
+  if acct = ENV['RUBYFORGE_ACCT']
+    require 'rake/contrib/sshpublisher'
+    Rake::SshDirPublisher.new(
+      "#{acct}@rubyforge.org",
+      "/var/www/gforge-projects/rote",
+      "html"
+    ).upload
+  else
+    raise "Skipping documentation upload - Need to set RUBYFORGE_ACCT to your rubyforge.org user name"
+  end
+end
+
 # ====================================================================
 # Create a task that will package the Rote software into distributable
 # tar, zip and gem files.
@@ -370,7 +384,8 @@ task :release => [
   :alltests,
   :update_version,
   :package,
-  :tag] do
+  :tag,
+  :doc_upload] do
   
   announce 
   announce "**************************************************************"
@@ -405,9 +420,9 @@ task :prerelease do
     announce "Release Task Testing, skipping checked-in file test"
   else
     announce "Checking for unchecked-in files..."
-    data = `cvs -q update`
+    data = `svn status`
     unless data =~ /^$/
-      fail "CVS update is not clean ... do you have unchecked-in files?"
+      fail "SVN status is not clean ... do you have unchecked-in files?"
     end
     announce "No outstanding checkins found ... OK"
   end
@@ -433,20 +448,32 @@ task :update_version => [:prerelease] do
     if ENV['RELTEST']
       announce "Release Task Testing, skipping commiting of new version"
     else
-      sh %{cvs commit -m "Updated to version #{PKG_VERSION}" lib/rote.rb}
+      sh %{svn commit -m "Updated to version #{PKG_VERSION}" lib/rote.rb}
     end
   end
 end
 
-desc "Tag all the CVS files with the latest release number (REL=x.y.z)"
+desc "Create a new SVN tag with the latest release number (REL=x.y.z)"
 task :tag => [:prerelease] do
   reltag = "REL_#{PKG_VERSION.gsub(/\./, '_')}"
   reltag << ENV['REUSE'].gsub(/\./, '_') if ENV['REUSE']
   announce "Tagging CVS with [#{reltag}]"
   if ENV['RELTEST']
-    announce "Release Task Testing, skipping CVS tagging"
+    announce "Release Task Testing, skipping SVN tagging"
   else
-    sh %{cvs tag #{reltag}}
+    # need to get current base URL
+    s = `svn info`
+    if s =~ /URL:\s*([^\n]*)\n/
+      svnroot = $1
+      if svnroot =~ /^(.*)\/trunk/
+        svnbase = $1
+        sh %{svn cp #{svnroot} #{svnbase}/tags/#{reltag} -m "Release #{PKG_VERSION}"}
+      else
+        fail "Please merge to trunk before making a release"
+      end
+    else 
+      fail "Unable to determine repository URL from 'svn info' - is this a working copy?"
+    end  
   end
 end
 

data/doc/pages/guide/index.html

@@ -2,10 +2,6 @@
 
 p{color:red}. *The guide is still under construction*
 
-p. It has not yet been fully updated to cover all new features in 0.3.x. 
-Although most features are mentioned, in some cases the documentation consists 
-soley of a link to the relevant "RDoc":<%= link_rel '/rdoc/index.html' %>
-
 <a name='top'></a>
 
 It is assumed that you have installed Rote already. If not, please
@@ -167,43 +163,91 @@ though ruby source is implicitly excluded). The directory layout beneath the
 page root is retained when transforming pages, and is also used to provide
 hierarchical structure to the common page code.
 
-The default behaviour is to transform all matched pages with ERB, and 
+The default behaviour is to transform all matched 
+<%= section_link 'template code and erb', 'templates' %> pages with ERB, and 
 optionally apply a second render pass with a <%= section_link 'layout' %>,
 before writing to the same base filename beneath the output directory.
 You can customise this behaviour by specifying 
 <%= section_link 'extension mappings' %> for specific file extensions - 
 see the <%= section_link 'Rake task configuration' %> section for details.
 
+Each page and layout template used by Rote may have associated with it an 
+optional Ruby source file, allowing variables to be defined for use in ERB
+code, and supporting interaction with Rote via the methods of the 
+"@Rote::Page@":<%= link_rel '/rdoc/classes/Rote/Page.html' %> class. Page
+and layout code is loaded from a @rb@ file alongside the template itself.
+Code can also be applied across multiple pages based on filesystem hierarchy
+by placing it in @COMMON.rb@ files in the *pages* tree. The order of evaluation
+of these files travels down from the most remote COMMON.rb to the page code
+itself, and this provides a simple yet fairly powerful way to apply various
+configuration options, filtering, and user variables across your pages.
+See <%= section_link 'template code and erb' %> for more information on the
+search path and evaluation order for page code.
+
+Rote additionally allows a variety of formatting and postprocessing options
+thanks to it's support for <%= section_link 'filters' %> - little bits of Ruby 
+that perform some text transformation, macro expansion, or postprocessing 
+during page rendering. Rote provides standard filters to support Textile 
+and Markdown formatting, syntax highlighting, processing with HTMLTidy, and
+more. 
+
 <%= section 4, 'Template code and ERB' %>
 
 All templates may contain embedded Ruby code (ERB), delimited by the standard
 &lt;&#37; ... &#37;&gt; (for executed code) and &lt;&#37;= ... &#37;&gt; (for 
 output) tags. Any (valid) Ruby code may be placed in the templates, and 
 variables may be defined to allow information to be passed into templates.
-There are five places where you might define such variables. The following 
+There are four places where you might define such variables. The following 
 is in order of evaluation:
 
 * A block supplied to the <%= section_link 'extension mappings', 'extension mapping' %>
   that matched this page (if any).
 * Any COMMON.rb files from the filesystem root down to this directory.
-* This page's ruby code, _basename_.rb
-* In the template itself
+* This page's ruby code, _basename_.rb.
+* In the template itself (via ERB).
 
 When a @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.
 
+Additionally, when <%= section_link 'layout' %> is used the following evaluation 
+takes place *after rendering the template text* and can be used to make variables 
+available for the layout pass(es):
+
+* This layout's ruby code, _layout_basename_.rb.
+* In the layout itself (again, with ERB).
+
 Template code is used to support a great deal of flexibility in Rote, from 
 selecting layouts to mixing in format helpers to controlling the filter chain.
 You can find details of the methods available in the 
 "@Rote::Page@ RDoc":<%= link_rel '/rdoc/classes/Rote/Page.html' %>
 
-<%= section 4, 'Layout' %>
+<%= section 4, 'Plaintext Formatting' %>
+
+If you are using Rote to generate HTML, you'll probably want to utilise some
+kind of _plain-text formatting_. Rote has out-of-the-box support for
+Textile, Markdown, and RDoc formatting, which can be applied to any page using 
+standard <%= section_link 'filters' %>. 
+
+These filters can be applied to any page directly from page or common code,
+and if you are using the built-in Rakefile (either using the @rote@ command to
+build, or with a @rake@ build created with the @rote create@ command) then
+the following extension mappings are defined by default, allowing the filters
+to be applied without resorting to page code:
+
+  .mhtml or .markdown      => Markdown formatting, .html output
+  .thtml or .textile       => Textile formatting, .html output
+  .rdhtml or .rdoc         => RDoc formatting, .html output
+  
+Each of these filters is covered (along with further usage instructions) in
+the <%= section_link 'filters' %> section.   
 
-_Layouts_ do exactly what you'd expect - they allow common template to be
-applied across several pages. This is handled via multiple render passes,
+<%= section 4, 'Layout' %>
 
+_Layouts_ allow common template to be applied across several pages.
+This is handled via multiple render passes, with each layout responsible
+for including the previously rendered content (via ERB).
 
 Layouts are stored under the @doc/layouts@ directory (by default). They may
 be organised into subdirectories, but this hierarchy is not connected to
@@ -217,7 +261,7 @@ specified, then the same extension as the page itself is assumed. Examples:
   * layout 'dark.txt'
   * &lt;&#37; layout 'my' &#37;&gt;
   
-_*Note* the absence of the = sign   in the ERB tag in the last example,_
+_*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._
 
@@ -250,6 +294,13 @@ in a further render pass. In all respects this is no different from the
 initial layout pass - layout code is executed, and rendering performed.
 Obviously, this may result in additional layouts being applied to the page.
 
+<div class='note'>
+Layouts can only be nested by calling @layout@ again from *layout code* 
+(or ERB in the layout template itself). Multiple calls to @layout@ from
+@COMMON.rb@ or page code will result in consistent page code behaviour,
+i.e. any previously-specified layout will be overriden.
+</div>
+
 There are no special requirements for layouts that are used in this way -
 from the user point of view a layout simply needs to include the 
 <code>@content_for_layout</code> where appropriate.
@@ -265,9 +316,10 @@ Along with this ability, a number of filters are provided as standard:
 For example If you're generating HTML, you'll probably want to use some plaintext 
 formatting, rather than writing HTML by hand. Rote directly supports this
 (thanks to "RedCloth":http://whytheluckystiff.net/ruby/redcloth and 
-"BlueCloth":http://www.deveiate.org/projects/BlueCloth) via _filters_, with both
-Textile and Markdown support out of the box (assuming those libraries are 
-available on your machine).
+"BlueCloth":http://www.deveiate.org/projects/BlueCloth) via _filters_, with
+Textile, RDoc and Markdown support out of the box (assuming those libraries are 
+available on your machine). See the <%= section_link 'plaintext formatting' %>
+for more details on this.
 
 h5. Filter chaining
 
@@ -381,11 +433,11 @@ This is a macro filter, and should be applied in the _page filter chain_:
 
 This filter uses the "Syntax":http://syntax.rubyforge.org/ library, passing the
 macro argument as the language ('ruby', 'xml' and 'yaml' are supported out of the 
-box). The output is wrapped in <pre class='[language]'><code> ... </code></pre> 
+box). The output is wrapped in 
+&lt;pre class='[language]'&gt;&lt;code&gt; ... &lt;/code&gt;&lt;/pre&gt;
 for output, with highlighting handled by <span> tags, allowing syntax colours and 
 styles to be applied via CSS. You can find a full list of the Ruby highlight classes
-in the
-"Syntax documentation":http://syntax.rubyforge.org/chapter-2.html
+in the "Syntax documentation":http://syntax.rubyforge.org/chapter-2.html
 but you will need to experiment with the highlighter to find the XML and YAML 
 classes.
 
@@ -396,13 +448,13 @@ Code to be highlighted is inserted into pages like so:
     def amethod
       "some code"		
     end	
-  # :code#
+  #:code
 #:code#
 
 <div class='note'>
-*Note* that in the above example, the end tag has an extra whitespace to work around
-a limitation of the Syntax plugin (and macros in general) - a macro cannot contain
-it's own end tag!
+Note that the closing tag in the above example is missing a closing '#' - this works
+around a limitation of the current Syntax filter (and macro implementation in general),
+which means that a macro cannot contain it's own end-tag.
 </div>
 
 Since macros are rendered separately from the page text, you don't have to worry much
@@ -778,12 +830,34 @@ from any Ruby code, by calling methods on the @Rake@ module.
 *Note* that this extension is intended, and tested, for Rote - it is not designed
 to be a general extension (though one could easily be extracted from it). In 
 particular it takes advantage of other extended functionality provided by Rote,
-and takes no account, for example, or parallel task execution. 
+and takes no account, for example, of parallel task execution. 
 
 By default, the cache is maintained in the project root, in a directory named
 @.rake_cache@. This is managed by Rote, so for the most part can be ignored, 
 though you can of course supply an alternate path if you wish (via @Rake.cache_dir=@).
 
+h6. Caching and clean builds
+
+When performing a clean build, the cache will also be removed (as part of the 
+@clobber@ task), and all dependencies will be re-evaluated and cached afresh.
+Caching exists only to allow accurate dependency resolution during incremental
+builds.
+
+h6. Disabling the cache
+
+There may be occasions when you want to disable use of the cache (for example when
+diagnosing unexpected dependency chains). This can be accomplished by setting
+an environment variable, NO_RAKE_CACHE prior to invoking Rote (or Rake). For a
+single invocation, the easiest way to do this is from the command-line:
+
+<pre><code>
+	rake clobber doc NO_RAKE_CACHE=true
+</code></pre>
+
+Specifying this option (or setting the variable) will completely disable use of
+the cache, causing any existing cache to be ignored and all dependencies determined
+during the run to be discarded.
+
 h5. Dependency-based block memoize
 
 Somewhat related to dependency caching, Rote also provides the ability to memoize
@@ -807,13 +881,6 @@ The following (OSX-specific) example illustrates usage of this feature:
   end
 #:code#
 
-h6. Caching and clean builds
-
-When performing a clean build, the cache will also be removed (as part of the 
-@clobber@ task), and all dependencies will be re-evaluated and cached afresh.
-Caching exists only to allow accurate dependency resolution during incremental
-builds.
-
 <%= section 3, 'Final notes' %>
 
 Rake is a *very* flexible tool, and supports a wide variety of configuration

data/doc/pages/index.html

@@ -14,18 +14,20 @@ Rote offers the following major features:
 	* Simple set-up based on page templates and sections.
 	* 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.
+	* Apply arbitrary Ruby code across all documentation, a subset, or individual pages.
 	* 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, integration with CSS builder etc. hoped for).
+	  common formats.
+	* Flexible filtering with several standard filters and the ability to
+	  implement your own in a few lines of Ruby.
+	* Low-overhead monitoring functionality allows documentation to be automatically
+	  re-rendered, and custom processing done, whenever the source changes.
 
-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 and general textual templating).
+Rote is somewhat similar to "WebGen":http://webgen.rubyforge.org in intent, though the two
+are quite different in implementation. WebGen provides a richer environment geared more 
+toward end-user websites and content publishing, whereas Rote's implementation as an 
+extension to Rake reflects a bias toward software documentation and general textual templating.
 
 See the "User guide":<%= link_rel '/guide' %> and "RDoc":<%= link_rel '/rdoc' %> for usage information.
 
@@ -39,13 +41,15 @@ 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 "SVN":http://rubyforge.org/plugins/scmsvn/viewcvs.php/?root=rote
 
-h4. From CVS 
+h4. From Subversion
 
 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 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.
+You can also grab the latest code from Subversion . The trunk always has the most up to date development code 
+while the latest release, while can be found on the appropriate tag for that version. Although every effort 
+is made to ensure that this development code works, it cannot of course be guaranteed to be complete or bug 
+free. If that’s okay with you (maybe you’re pretty happy-go-lucky in general…) then see our 
+"SCM page":http://rubyforge.org/scm/?group_id=1120 at Rubyforge for everything you need to get going with 
+the SVN version.

data/lib/rote.rb

@@ -1,6 +1,6 @@
 # rote.rb - main Rote module  
 # Copyright (c) 2005 Ross Bamford (and contributors)
-# $Id: rote.rb 145 2005-12-14 19:19:58 +0000 (Wed, 14 Dec 2005) roscopeco $
+# $Id: rote.rb 172 2006-01-12 00:21:40 +0000 (Thu, 12 Jan 2006) roscopeco $
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in 
@@ -41,7 +41,7 @@ end
 require 'rake'
 
 # Master Rote version. Manage this from the Rake release support.
-ROTEVERSION = '0.3.2'
+ROTEVERSION = '0.3.2.2'
 
 #####
 ## *Rote* is a Rake (http://rake.rubyforge.org) based build tool for static

data/lib/rote/app.rb

@@ -2,7 +2,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: app.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: app.rb 121 2005-12-11 06:18:12 +0000 (Sun, 11 Dec 2005) roscopeco $
 require 'getoptlong'
 
 module Rote

data/lib/rote/cache.rb

@@ -4,7 +4,7 @@
 # (c)2005, 2006 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: cache.rb 150 2006-01-02 00:39:41 +0000 (Mon, 02 Jan 2006) roscopeco $
+# $Id: cache.rb 170 2006-01-11 23:38:51 +0000 (Wed, 11 Jan 2006) roscopeco $
 #++
 # This file adds dynamic dependency tracking and caching for 
 # incremental builds, by adding methods to the Rake module 
@@ -23,6 +23,7 @@ require 'pathname'
 require 'rake'
 
 module Rake
+  
   class << self
     # Directory for storing Rake dependency cache
     def cache_dir=(val); @cache_dir = val; end
@@ -33,15 +34,27 @@ module Rake
     # Array representing current tasks being executed
     def task_stack; @tasks ||= []; end
     # Reference to current task being executed
-    def current_task; task_stack.last; end
+    def current_task; task_stack.last; end    
+    # Determine whether dependency caching is enabled
+    def cache_enabled?
+      if @cache_enabled.nil?
+        @cache_enabled = !ENV['NO_RAKE_CACHE']
+      else 
+        @cache_enabled
+      end
+    end
+    
+    # Enable or disable dependency caching.
+    def cache_enabled=(b); @cache_enabled = b; end
 
     # Use this method to dynamically register one or more files
-    # as dependencies of the currently executing task.
-    def register_dependency(deps, t = nil)
-      t = (current_task.name if current_task) unless t
-      if t then
-        file t => deps
-        (cached_dependencies[t] ||= []) << deps
+    # as dependencies of the currently executing task (or the
+    # specified task if non-nil).
+    def register_dependency(deps, task = nil)
+      task = (current_task.name if current_task) unless task
+      if task then
+        file task => deps
+        (cached_dependencies[task] ||= []) << deps
       end
     end
   end
@@ -53,17 +66,14 @@ module Rake
     # loaded, and handling the task stack. The argument controls
     # whether or not cached dependencies are loaded and should not
     # be set false except in testing.
-    def invoke(do_cache = true)
+    def invoke
       # Invoke patched to record task stack and
       # load cached dependencies on first go.
-      Rake.load_cached_dependencies if do_cache && !$CACHEDEPS_LOADED
+      Rake.load_cached_dependencies if Rake.cache_enabled?
       
       begin
-        Rake.task_stack << self
-        
-        # TODO what's going on here?
-        # Rake.cached_dependencies[name] = [] if Rake.cached_dependencies[name] 
-        
+        Rake.task_stack << self        
+        Rake.cached_dependencies[name] = [] if Rake.cached_dependencies[name]         
         pre_autodep_invoke
       ensure
         Rake.task_stack.pop
@@ -110,6 +120,8 @@ module Rake
   # An at_exit handler is installed to save the dependencies
   # when rake exits.
   def self.load_cached_dependencies
+    return if $CACHEDEPS_LOADED
+    
     at_exit { self.save_cached_dependencies }
 
     return unless File.exists?(dependencies_file)
@@ -123,7 +135,8 @@ module Rake
   end
   
   def self.save_cached_dependencies
-    return if cached_dependencies.empty?
+    return if cached_dependencies.empty? || !Rake.cache_enabled?
+    
     mkdir_p cache_dir unless File.exists?(cache_dir)
     deps = {}
     cached_dependencies.each do |k,v|