rote 0.2.2 → 0.2.4

data/README

@@ -71,7 +71,12 @@ With that done, you should be able to run
 	
 to verify that the command-line wrapper is working. You should of course see
 the version number of your Rote installation.
- 
+
+*NOTE* Windows users - you may experience problems at this point, with Rote
+complaining that 'rake' is an invalid command. To fix this, simply set an
+environment variable, RAKE_CMD, with the command to execute for rake
+(e.g. rake.bat).
+
 == How do I use it?
 
 Please see the user guide for usage information. The latest version can be
@@ -101,8 +106,9 @@ packages from escaping into the wild.
 
 === Further information
 
-Rote is developed by Ross Bamford (ross <at> roscopeco.co.uk). Flame him if
-it breaks your day ;P
+Rote is developed by Ross Bamford (rosco <at> roscopeco.co.uk), with help from
+the developers listed in CONTRIBUTORS. Any bugs are probably down to Ross, 
+though, so flame him if it breaks your day ;P
 
 * Homepage - http://rote.rubyforge.org/
 * Project - http://rubyforge.org/projects/rote
@@ -111,3 +117,9 @@ it breaks your day ;P
 
 As you may have guessed, Rote's hosting and development services are provided
 by http://RubyForge.org .
+
+Thanks to Yukihiro Matsumoto for a remarkable platform, Masatoshi Seki for 
+embedding it in text, Jim Weirich for an elegant build tool, and Dean Allen 
+for making markup easy in Ruby. Thanks too to the many people who've contributed
+and improved these things over the years - as ever, we stand on the shoulders
+of giants.

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.10 2005/12/02 20:07:16 roscopeco Exp $
+# $Id: Rakefile,v 1.11 2005/12/05 14:45:15 roscopeco Exp $
 #
 
 begin
@@ -141,6 +141,7 @@ PKG_FILES = FileList[
   'bin/**/*', 
   'lib/**/*.rb', 
   'lib/rote/builtin.rf', 
+  'lib/rote/project/**/*',
   'test/**/*',
   'doc/**/*'
 ]
@@ -289,6 +290,57 @@ task :rubyfiles do
   puts Dir['bin/*'].reject { |fn| fn =~ /CVS|(~$)|(\.rb$)/ }
 end
 
+desc "Show deprecation notes"
+task :deprecated do
+  Dir['lib/**/*.r?'].each do |fn|
+    File.open(fn) do |f| 
+      [*f].each_with_index do |line,i| 
+        if line =~ /#(.*)vv([0-9\.]+)(?:[\s\t]*)v-([0-9\.]+)/
+          cmnt = $~[1].strip
+          cmnt = '<No comment>' if (cmnt.nil? or cmnt.empty?)          
+          printf "%s:%d\n%-60s    %5s    %5s\n\n", fn, i+1, cmnt, $~[2].strip, $~[3].strip
+        end #if splits okay
+      end #each_w_idx
+    end #fopen
+  end #dir
+end
+
+desc "Find features deprecated at VER"
+task :deprecated_by do
+  fail "\nYou must specify the version to check (VER=x.y.z)\n\n" unless ver = ENV['VER']
+  Dir['lib/**/*.r?'].each do |fn|
+    File.open(fn) do |f| 
+      [*f].each_with_index do |line,i| 
+        if line =~ /vv#{ver}/
+          if line =~ /#(.*)vv([0-9\.]+)(?:[\s\t]*)v-([0-9\.]+)/
+            cmnt = $~[1].strip
+            cmnt = '<No comment>' if (cmnt.nil? or cmnt.empty?)          
+            printf "%s:%d\n%-60s    %5s    %5s\n\n", fn, i+1, cmnt, $~[2].strip, $~[3].strip
+          end #if splits okay
+        end #if line is dep remove
+      end #each_w_idx
+    end #fopen
+  end #dir
+end
+
+desc "Find deprecated features to be removed by VER"
+task :deprecated_due do
+  fail "\nYou must specify the version to check (VER=x.y.z)\n\n" unless ver = ENV['VER']
+  Dir['lib/**/*.r?'].each do |fn|
+    File.open(fn) do |f| 
+      [*f].each_with_index do |line,i| 
+        if line =~ /v-#{ver}/
+          if line =~ /#(.*)vv([0-9\.]+)(?:[\s\t]*)v-([0-9\.]+)/
+            cmnt = $~[1].strip
+            cmnt = '<No comment>' if (cmnt.nil? or cmnt.empty?)          
+            printf "%s:%d\n%-60s    %5s    %5s\n\n", fn, i+1, cmnt, $~[2].strip, $~[3].strip
+          end #if splits okay
+        end #if line is dep remove
+      end #each_w_idx
+    end #fopen
+  end #dir
+end
+
 # --------------------------------------------------------------------
 # Creating a release
 

data/TODO

@@ -1,16 +1,20 @@
 = Rote project -- Todo list
 
 Most of the following ideas will probably be implemented at some point.
-Send any suggestions (or test-driven patches) to:
+Send any suggestions or patches (preferably as/with tests) to:
 
   rosco <at> roscopeco <dot> co <dot> uk
 
 * More flexible markup rendering
 * Nested layouts
+* Better COMMON.rb handling
 * 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.
+* Auto-link within section
 * Index and glossary support
 * statistics
 * (maybe?) Automatic navigation / TOC
 * (maybe?) Rant integration
+* Ability to define rules for input.ext -> output.ext
+* Support ruby source templates (.rbt, auto rename to .rb on output).

data/doc/layouts/page.html

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='utf-8'?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/xhtml1-strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html>
 
 <head>

data/doc/pages/guide/COMMON.rb

@@ -1,7 +1,18 @@
-# This is a hack that exists currently to inherit COMMON.rb
-# from above. Of course, we can still define extra stuff
-# here. 
-#
-# This will be made implicit soon.
-
+# inherit common.rb from above
 inherit_common
+
+def section_anchor(name)
+  name.downcase.gsub(/\s/,'_')
+end
+
+def section_link(name, text = name)
+  %Q{"#{text}":\##{section_anchor(name)}}
+end
+
+def section(level, name, toplink = true)
+%Q{
+#{"[#{section_link('Top')}]" if toplink}
+<a name='#{section_anchor(name)}'></a>
+h#{level}. #{name}
+}
+end

data/doc/pages/guide/index.html

@@ -6,25 +6,26 @@ It is assumed that you have installed Rote already. If not, please
 consult the <a href="<%= link_rel '/rdoc/files/README.html' %>">README</a> 
 for installation instructions.
 
-<a name='top'/>
+<a name='top'></a>
 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
-  ** "Basics":#create_templates_basics
-  ** "Formatting":#create_templates_formatting
-  ** "Template code & ERB":#create_templates_erb
-  ** "Applying layout":#create_templates_layout
-  * "Resources":#resources
-  * "Source monitoring":#monitor
-  * "Publishing":#publishing
+  * <%= section_link 'Conventions' %>
+  * <%= section_link 'Starting out with Rote' %>
+  ** <%= section_link 'Creating a project' %>
+  ** <%= section_link 'From the command-line' %>
+  ** <%= section_link 'From your Rakefile' %>
+  * <%= section_link 'Creating templates' %>
+  ** <%= section_link 'Basics' %>
+  ** <%= section_link 'Formatting' %>
+  ** <%= section_link 'Template code and ERB' %>
+  ** <%= section_link 'Applying layout' %>
+  * <%= section_link 'Resources' %>
+  * <%= section_link 'Source monitoring' %>
+  ** <%= section_link 'Auto-refresh Task' %>
+  * <%= section_link 'Definining additional tasks' %>
+  * <%= section_link 'Publishing' %>  
   
-<a name='conventions'/>
-h3. Conventions used in this document
+<%= section 3, 'Conventions', false %>
 
 *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
@@ -32,40 +33,38 @@ 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
+<%= section 3, 'Starting out with Rote' %>
 
-<a name='getting_started_source_layout'/>
-h4. Documentation source layout
+<%= section 4, 'Creating a project', false %>
 
-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:
+To get started quickly, we'll use the built-in project template, which provides
+a standard Rote directory tree with a single page, and Rakefile ready for
+customisation. The template gives a convenient way to get started on a new
+Rote project. To invoke it, just type:
+
+<p><pre><code>        rote create someproject</code></pre></p>
+
+If all goes well, you should see a single line (@cp_r ...@) indicating that
+Rote copied the template to your specified directory (@someproject@ in this
+case). This directory will have the following layout:
 
 <p><code><pre>  
-  project_root ( <- root, this can be called whatever you like)
+  someproject
   |
-  |--> [publish.rf]
+  |--> Rakefile 
   |
   |--> doc
-  |    |--> [COMMON.rb]
-  |    |
   |    |--> res
-  |    |    |--> (resources)
+  |    |    |--> images
+  |    |    |--> rote-tiny.png
   |    |
   |    |--> layouts
-  |    |    |--> one.txt
-  |    |    |--> two.html
+  |    |    |--> normal.html
   |    | 
   |    |--> pages
-  |    |    |--> [COMMON.rb]
-  |    |    |--> apage.txt
-  |    |    |--> [apage.rb]
-  |    |    |--> adir
-  |    |    |    |--> [COMMON.rb]
-  |    |    |    |--> bpage.html
-  |    |    |    |--> [bpage.rb]   
+  |         |--> COMMON.rb
+  |         |--> index.html
+  |         |--> index.rb
 			  
 </pre></code></p>
 
@@ -75,17 +74,18 @@ See the section on Layouts below for details on layout name resolution.
 
 Ruby source is optional, and allows you to define instance variables and 
 methods on a Page instance. COMMON.rb is applied to all pages in a given
-directory. See "the section on templates":#create_templates for more
-information on the specifics.
+directory. See <%= section_link 'creating templates', 'the section on 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
-site).
+To build the sample page, simply type @rote@ or @rake@ from the top-level
+directory. This will start the default @doc@ task to transform all 
+modified pages / resources (everything, in this case).
 
-["top":#top]
+The README included with the project template has further information
+about build options and available tasks, as well as pointers to possible
+next steps.
 
-<a name='getting_started_command_line'/>
-h4. From the command-line
+<%= section 4, 'From the command-line' %>
 
 If you are generating a standalone documentation set (i.e. not as part of 
 some wider build) then you don't need to worry about writing a @Rakefile@ -
@@ -107,7 +107,7 @@ individual file task for each page in your doc set. For example, running
 the 'rote' command again with no options will cause it to exit almost
 immediately, since all output is up to date. If you change a file, and run
 rote again, then just that file will be updated. There are a few caveats
-with this (see "the notes section":#final_notes).
+with this (see <%= section_link 'Final notes', 'the notes section' %>).
 
 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)
@@ -128,13 +128,10 @@ Further command-line usage information is available with:
 	
 <p><pre><code>        rote --usage</code></pre></p>
 	
-and Unix installations performed with =install.rb= should also make a
+and Unix installations performed with @install.rb@ should also make a
 manpage available for the @rote@ command.
 
-["top":#top]
-
-<a name='getting_started_rakefile'/>
-h4. From your @Rakefile@
+<%= section 4, 'From your Rakefile' %>
 
 If you are wanting to build documentation as part of a larger build process, or
 commandline setup, then you'll want to get started on integrating Rote with 
@@ -146,7 +143,7 @@ something like:
 	require 'rote'
 	
 	ws = Rote::DocTask.new(:doc) { |site| 
-	  site.site_dir = 'html'
+	  site.output_dir = 'html'
 	  site.layout_dir = 'doc/layouts'
 	
 	  site.pages.dir = 'doc/pages'
@@ -157,8 +154,7 @@ something like:
 	  site.res.include('**/*.gif')
 	  site.res.include('**/*.jpg')
 	  site.res.include('**/*.css')
-	}
-	
+	}	
 </code></pre>
 	
 Save this as @Rakefile@, and fire up:
@@ -168,16 +164,12 @@ Save this as @Rakefile@, and fire up:
 If all goes well, you should see each command and transformation output to your
 console as Rote runs. 
 
-*Note* that it's safe to include '**/*' in the @pages@ list, since @rb@ 
-files are implicitly excluded.
-
-["top":#top]
+*Note* that it's safe to include all files in the @pages@ list, since @rb@ 
+files are implicitly excluded (as page code).
 
-<a name='create_templates'/>
-h3. Creating templates
+<%= section 3, 'Creating templates' %>
 
-<a name='create_templates_basics'/>
-h4. The basics
+<%= section 4, 'The Basics', false %>
 
 As mentioned, templates are simply text files in the @doc/pages@ directory. The
 layout below that directory is retained when transforming pages, and is
@@ -187,10 +179,7 @@ By default, any file with an extension other than @rb@ will be processed
 as a page template (with it's associated ruby source). The output will have
 the same filename and path, relative to the output directory.
 
-["top":#top]
-
-<a name='create_templates_formatting'/>
-h4. Applying formatting
+<%= section 4, 'Applying formatting' %>
 
 If you're generating HTML, you'll probably want to use some plaintext 
 formatting, rather than writing HTML by hand. Rote directly supports
@@ -202,10 +191,10 @@ appropriate symbols to the array, for example in page code or COMMON.rb:
 <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
-on adding code to your templates. Obviously you don't have to use all three, 
-and order isn't significant - formatting is applied as Textile, then Markdown,
-then Rdoc.
+See <%= section_link 'template code and erb', 'the section on template code' %> 
+for more information on adding code to your templates. Obviously you don't have 
+to use all three, and order isn't significant - formatting is applied as Textile, 
+then Markdown, then Rdoc.
 	
 *Some additional notes on formatting*
 
@@ -215,22 +204,22 @@ then Rdoc.
     being ignored. Always use the << :opt syntax.
     
   * Note that *Formatting is applied _after_ any ERB has been evaluated.*
+    This allows you to output formatting from your code and have it rendered
+   	properly.
 
   * that the options you supply are passed directly to RedCloth, so you can
     exercise much more control over the formatting by using the feature-specific
     symbols defined by RedCloth, rather than the blanket :textile and :markdown
     symbols.
 
-["top":#top]
-
-<a name='create_templates_erb'/>
-h4. Template code and ERB
+<%= section 4, 'Template code and ERB' %>
 
 All templates may contain embedded Ruby code (ERB), delimited by the standard
-&lt;% ... %&gt; (for executed code) and &lt;%= ... %&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 four places where 
-you might define such variables. The following is in order of evaluation:
+&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 four places where you might define such variables. The following 
+is in order of evaluation:
 
 * This directory's COMMON.rb, or the parent directory's COMMON.rb if
   @inherit_common@ is used.
@@ -243,10 +232,7 @@ 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.
 
-["top":#top]
-
-<a name='create_templates_layout'/>
-h4. Layout
+<%= section 4, 'Layout' %>
 
 Layouts are stored under the @doc/layouts@ directory (by default). They may
 be organised into subdirectories, but this hierarchy is not connected to
@@ -258,7 +244,7 @@ specified, then the same extension as the page itself is assumed. Examples:
   * layout 'one'
   * layout 'main/wide'
   * layout 'dark.txt'
-  * <&#37; layout 'my' &#37;>
+  * &lt;&#37; layout 'my' &#37;&gt;
   
 _*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_
@@ -270,16 +256,13 @@ the layout (in which textile is currently not supported). The layout is
 responsible for inserting the rendered template where appropriate, with
 e.g.:
 
-  * <&#37;= @content_for_layout &#37;>
+  * &lt;&#37;= @content_for_layout &#37;&gt;
 
 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
 be templated and laid out.
 
-["top":#top]
-
-<a name='resources'/>
-h3. Resources
+<%= section 3, '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
@@ -291,10 +274,7 @@ 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
+<%= section 3, '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
@@ -330,8 +310,38 @@ 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
+<%= section 4, 'Auto-refresh task' %>
+
+When using Source monitoring, it's often handy to be able to inform some other
+program that something has changed. For example, you may want to automatically
+refresh your browser after changed HTML is rendered. Rote supports this via
+the @doc_refresh@ task, which is triggered whenever @doc_monitor@ finds changes
+in your source set (_after_ rendering, of course).
+
+The following (Mac) example uses OSA script to refresh the Safari browser when
+your rendered documentation changes:
+<pre><code>
+	require 'osx/aeosa'
+	
+	task :doc_refresh do 
+		OSX.do_osascript('tell application "Safari" to do javascript "window.location.reload();" in document 1')	
+	end
+</code></pre>
+
+As with all rake tasks, multiple actions can be associated, and you can of course
+add prerequisites to the @refresh@ task as with any other Rake task.
+
+<%= section 3, 'Defining additional tasks' %>
+
+The command-line build will automatically look for a file in the top-level
+directory (above @doc@) named @local.rf@. If found, this file will be 
+evaluated by Rake, making any tasks defined within it available to your
+build. This can be used to define an <%= section_link 'auto-refresh task' %>
+for the <%= section_link 'source monitoring', 'monitor' %> feature, for example,
+or to define tasks to publish your site (most likely using one of Rake's 
+directory publishers).
+
+<%= section 3, '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
@@ -339,29 +349,20 @@ 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 
-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.
-
-["top":#top]
-
-<a name='final_notes'/>
-h3. Final notes
+<%= section 3, 'Final notes' %>
 
 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:
+what to update. If you change common or page code you'll need to run:
 	
 <p><pre><code>        rote clobber</code></pre></p>
 		
-to make sure everything gets updated. It's recommended to always run upload
-as:
-	
-<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.
-
-["top":#top]
+to make sure everything gets updated. This will also apply if you have
+interdependencies between pages and resources, but in that situation you
+_could_ work around it if you wished by manually (!) specifying the 
+appropriate resources as dependencies to the appropriate page task.
+Such configuration is beyond the scope of this manual - see 
+"Rake's Documentation":http://rake.rubyforge.org/ for information on
+dependency configuration and resolution in Rake.
+
+[<%= section_link 'Top' %>]

data/lib/rote.rb

@@ -1,5 +1,6 @@
 # rote.rb - main Rote module  
 # Copyright (c) 2005 Ross Bamford (and contributors)
+# $Id: rote.rb,v 1.18 2005/12/05 14:55:22 roscopeco Exp $
 #
 # 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,23 +42,29 @@ require 'net/ftp'
 require 'rake'
 
 # Master Rote version. Manage this from the Rake release support.
-ROTEVERSION = '0.2.2'
+ROTEVERSION = '0.2.4'
 
 #####
-## *Rote* is a Rake (http://rake.rubyforge.org) based build tool for page-based
-## static websites that enables layout, textile formatting, and ERB to be used
-## to automatically generate your site, and can handle uploading the site 
-## to your (host's) server.
+## *Rote* is a Rake (http://rake.rubyforge.org) based build tool for static
+## page-based documentation, websites, and general textual templates.
+## It enables embedded Ruby code, layout, and optionally plain-text formatting
+## (HTML-only at present) to be used to automatically generate output in any
+## (textual) format from a directory tree containing template files.
 ##
-## Rote was created for my personal site, but is general enough to be applied
-## to many different types of website, including basic blog-plus sites,
-## slower-moving news and information sites, and software documentation.
+## Rote was created for my personal website, but has become a fairly flexible
+## tool, general enough to be applied to many different types of templating.
+## Rote can handle your software documentation, blog-plus sites,
+## and even (slower-moving) news and information sites.
 ##
-## See +README+ for general usage information. +Rote::DocTask+ documents the
-## Rake task integration, while +Rote::Page+ has information useful to template
+## Rote can be used from the command-line, or in your own +Rakefile+. It
+## supports both manual and automatic rendering of modified resources, and
+## can be configured to monitor your source tree for changes.
+##
+## See +README+ for general usage information. Rote::DocTask documents the
+## Rake task integration, while Rote::Page has information useful to template
 ## writers.
 ##
-## Rote is (c)2005 Ross Bamford. See +LICENSE+ for details.
+## Rote is (c)2005 Ross Bamford (and contributors). See +LICENSE+ for details.
 module Rote
 
   # this space intentionally left blank

data/lib/rote/app.rb

@@ -1,3 +1,8 @@
+# Rote application class
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: app.rb,v 1.4 2005/12/05 14:44:32 roscopeco Exp $
 require 'getoptlong'
 
 module Rote
@@ -30,7 +35,7 @@ module Rote
       raise "Missing builtin.rf (expected at '#{@rakefile}')!" unless File.exists?(@rakefile)
       
       @rakeopts = ENV['RAKE_OPTS'] || ''
-      @rake = ENV['RAKE_CMD'] || 'rake'
+      @rake = ENV['RAKE_CMD'] || (PLATFORM =~ /mswin/ ? 'rake.bat' : 'rake')
       
       process_args
       
@@ -98,11 +103,14 @@ Recognised options are:
   --help      -h     Synonym for --usage
   --version   -V     Display Rote's version and quit
 
-The 'rote' command is implemented as a wrapper around Rake, and 
-requires the 'rake' command be in your path. You can circumvent this
-by setting the RAKE_CMD environment variable appropriately.
-Additional options can be passed to Rake via the RAKE_OPTS variable.
-  
+In addition to the standard doc_XXX tasks and those provided by any
+local configuration, the following 'special' tasks are recognised:
+
+  create <project>   Create a blank project from the built-in template.
+   
+Note that these 'special' tasks are implemented as part of the command-
+line wrapper for Rote, and will not be available from custom Rakefiles.
+
 In non-standard environments, it may be necessary to set the ROTE_LIB 
 variable to point to the location of Rote's libraries.
   

data/lib/rote/builtin.rf

@@ -1,35 +1,84 @@
+# Built-in Rote rakefile
 #
-# Built-in Rakefile for Rote, (c)2005 Ross Bamford
-
+# This is effectively a copy of the template rakefile, 
+# but with extra tasks for the command-line wrapper.
+#
+# (c)2005 Ross Bamford (and contributors)
+# 
+begin 
+  require 'rubygems'
+rescue LoadError
+  nil # optional
+end
 require 'rake'
 require 'rake/clean'
 require 'rote'
 
-# Create tasks to build the doc tree
-# 
-# Creates the following tasks
+# Create a set of tasks with the prefix 'doc' to  build the
+# documentation set. The directory layout is as for the
+# command-line wrapper (but can be changed of course).
+#
+# This 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
+#   * doc           - transform/copy all modified pages / resources
+#   * doc_pages     - transform all modified pages
+#   * doc_res       - copy all modified resources
+#   * doc_monitor   - Start monitor mode, transform changed files automatically
 #
+#   * [html/**/*]   - Transform single page / resource unconditionally
+#
+#   * clobber_doc   - Remove output (hooks into main 'clobber' task)
+#
+# In addition to these tasks, you may also wish to define a 'doc_refresh' task
+# to be run whenever modified resources are processed in monitor mode.
 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.include('**/*.png')
-  site.res.include('**/*.gif')
-  site.res.include('**/*.jpg')
-  site.res.include('**/*.css')
+  site.res.include('**/*')
 }
 
 task :default => [:doc]
 
+#################### CREATE NEW PROJECT FROM TEMPLATE ###############
+#
+# This works in a slightly odd way. The 'create' task simply sets up
+# a rule that catches anything. This rule will then be triggered by
+# the task that follows on the command-line, and taken as the 
+# target directory name.
+# 
+# So instead of 'rote create NAME=foo' we have 'rote create foo'
+#
+# Note that this does preclude having other tasks on the same 
+# invocation (after the create at least) but does also allow
+# multiple projects to be created at once. 
+#
+# Also need a way to display error message if the rule isn't 
+# invoked at least once...
+task :create do
+	rule '' do |t|
+		fail "'#{t.name}' already exists" if File.exists?(t.name)
+	
+		src = 'rote/project'
+	  src_dir = $:.detect { |it| File.exists?(File.join(it,src)) }
+  	fail "Cannot locate project template" unless src_dir
+  
+	  # For now, just copy. Later, maybe we'll do some transformation on the
+  	# sources as they're copied.
+	  cp_r File.join(src_dir, src), t.name
+	end
+end
+
+# import user-level tasks
+import "#{ENV['HOME']}/.rotetasks.rf" if File.exists?("#{ENV['HOME']}/.rotetasks.rf")
+import 'local.rf' if File.exists?('local.rf')
+
+# DEPRECATED - publish.rf will be unsupported. 			vv0.2.3		v-0.5   1
 import 'publish.rf' if File.exists?('publish.rf')
+
+
+

data/lib/rote/page.rb

@@ -1,3 +1,8 @@
+# Rote page class
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: page.rb,v 1.9 2005/12/05 14:44:32 roscopeco Exp $
 require 'erb'
 require 'rdoc/markup/simple_markup'
 require 'rdoc/markup/simple_markup/to_html'
@@ -12,9 +17,9 @@ end
 module Rote
 
   #####
-  ## A +Page+ object represents an individual page, taking input from a
-  ## template and (optionally) some ruby code, and producing rendered
-  ## ('merged') output as a +String+.
+  ## A +Page+ object represents an individual template source file, taking
+  ## input from that file and (optionally) some ruby code, and producing 
+  ## rendered (or 'merged') output as a +String+.
   ## When a page is created, ruby source will be found alongside the 
   ## file, with same basename and an '.rb' extension. If found it will
   ## run through +instance_eval+. That source can call methods

data/lib/rote/project/README

@@ -0,0 +1,49 @@
+This is the auto-generated Rote documentation source.
+
+To render it using Rote's command-line wrapper (ignoring the included
+Rakefile), type:
+
+  rote doc
+
+from the top-level directory (this one).
+
+To render using the included Rakefile (the result is the same in either
+case) type instead:
+
+  rake doc
+  
+If you prefer, you can omit the 'doc' task, since it is configured
+as the default.  
+
+In either case, you should see some output as the pages are rendered 
+and resources copied, and get output in a (created) 'html' directory.
+Once you have rendered the site, running the command again will appear
+to do nothing, because only changed resources are re-rendered. To 
+start over:
+
+  (rote|rake) clobber
+
+Alternatively, modify the page or resource files, and rerun the first
+command to transform only the modified resource.
+
+WHAT NEXT?
+
+	+ See what else you can do by typing:
+	
+			  (rote|rake) --tasks
+			  
+			  rote --usage		( with the command-line wrapper )
+			  
+  + Modify the included page template and layout to suit your needs. 
+
+  + Edit the included Rakefile to add or change tasks, or delete it
+    if you're sticking with the command-line wrapper.
+
+  + Add more pages and layouts.
+
+  + Start Rote in monitor mode, and have your changes rendered as
+    you work:
+
+        (rote|rake) monitor
+
+

data/lib/rote/project/Rakefile

@@ -0,0 +1,51 @@
+# Standard Rakefile for custom Rote build
+#
+# Generated from:
+# $Id: Rakefile,v 1.1 2005/12/05 14:43:22 roscopeco Exp $
+# 
+begin 
+  require 'rubygems'
+rescue LoadError
+  nil # optional
+end
+require 'rake'
+require 'rake/clean'
+require 'rote'
+
+# Create a set of tasks with the prefix 'doc' to  build the
+# documentation set. The directory layout is as for the
+# command-line wrapper (but can be changed of course).
+#
+# This creates the following tasks:
+#
+#   * doc           - transform/copy all modified pages / resources
+#   * doc_pages     - transform all modified pages
+#   * doc_res       - copy all modified resources
+#   * doc_monitor   - Start monitor mode, transform changed files automatically
+#
+#   * [html/**/*]   - Transform single page / resource unconditionally
+#
+#   * clobber_doc   - Remove output (hooks into main 'clobber' task)
+#
+# In addition to these tasks, you may also wish to define a 'doc_refresh' task
+# to be run whenever modified resources are processed in monitor mode.
+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.include('**/*')
+}
+
+task :default => [:doc]
+
+# import user-level tasks
+import "#{ENV['HOME']}/.rotetasks.rf" if File.exists?("#{ENV['HOME']}/.rotetasks.rf")
+import 'local.rf' if File.exists?('local.rf')
+
+# TODO Define your custom tasks here
+
+

data/lib/rote/project/doc/layouts/normal.html

@@ -0,0 +1,38 @@
+<% 
+  # This is the 'normal' layout. It can be selected with:
+  #
+  # layout 'normal'
+  #
+  # in page code. If the page itself doesn't have an '.html'
+  # extension, you will need to use:
+  #
+  #    layout 'normal.html'
+  #
+  #  instead.  
+  #
+  #  Here we just add basic HTML wrap-up, use the custom var
+  #  (@page_title) to get the title, and insert content where
+  #  we want it with @content_for_layout.  
+%>
+<html>
+  <head>
+    <%# Use our custom vars for the title %>
+    <title><%= @page_title + ' - ' + @site_title %></title>
+  </head>
+
+  <body>
+    <h1><%= @page_title %></h1>
+
+    <%# Insert page content #%>
+    <%= @content_for_layout %>
+
+    <p align='center'><hr width='80%'></p>
+    <p align='right'>
+    <span style='font-size: 8pt; color: #7c7c90'>Generated with</span><br/>
+
+      <%# use the link_rel helper to make absolute links relative to current page #%>
+      <a href='http://rote.rubyforge.org/' target='_blank'><img src='<%= link_rel '/images/rote-tiny.png' %>' alt='Rote'/></a>
+    </p>    
+  </body>
+</html>
+

data/lib/rote/project/doc/pages/COMMON.rb

@@ -0,0 +1,7 @@
+# Shared code for all pages in this directory.
+
+# This is executed for every file transformed, in the binding of 
+# the appropriate Rote::Page instance. Individual page sources
+# ([pagename].rb) override anything defined here.
+
+@site_title = "My site"

data/lib/rote/project/doc/pages/index.html

@@ -0,0 +1,12 @@
+This is a *sample* page. 
+
+<%# insert an image with relative path, using Textile !img! markup #%>
+It has a very small image:
+!<%= link_rel '/images/rote-tiny.png' %>!
+
+(Which is the same as the one at the bottom)
+
+* You should
+* Replace this
+* With your doc.
+

data/lib/rote/project/doc/pages/index.rb

@@ -0,0 +1,13 @@
+# Page code for the 'index' page. We call a few methods to
+# set layout and formatting, and then create a custom variable
+# for use in the layout.
+
+# This page uses Textile
+format_opts << :textile
+
+# Apply the 'normal' layout
+layout 'normal'
+
+# Set a custom var for use in our layout
+@page_title = 'A sample page'
+        

data/lib/rote/rotetasks.rb

@@ -1,3 +1,8 @@
+# Rake tasklib for Rote
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: rotetasks.rb,v 1.8 2005/12/05 14:44:32 roscopeco Exp $
 require 'rake'
 require 'rake/tasklib'
 
@@ -57,8 +62,10 @@ module Rote
   ## name you supply. The tasks defined are:
   ##
   ##   #{name}         - Transform all documentation, copy resources.
-  ##   #{name}-pages   - Transform all pages
-  ##   #{name}-res     - Copy resources
+  ##   #{name}_pages   - Transform all pages
+  ##   #{name}_res     - Copy resources
+  ##   #{name}_monitor - Start watching for changes
+  ##   #clobber_{name} - Remove output
   ##
   class DocTask < Rake::TaskLib
     # Default exclusion patterns for the page sources. These are
@@ -94,8 +101,8 @@ module Rote
     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
+    # *Deprecated* alias for +show_file_tasks+. vv0.2.2 v-0.5
+    alias :show_page_tasks? :show_file_tasks      
     alias :show_page_tasks= :show_file_tasks=
     
     # The approximate number of seconds between update checks when running

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: rote
 version: !ruby/object:Gem::Version 
-  version: 0.2.2
-date: 2005-12-03 00:00:00 +00:00
+  version: 0.2.4
+date: 2005-12-05 00:00:00 +00:00
 summary: Adds template-based doc support to Rake.
 require_paths: 
 - lib
@@ -39,7 +39,19 @@ files:
 - lib/rote/rotetasks.rb
 - lib/rote/page.rb
 - lib/rote/app.rb
+- lib/rote/project/doc/pages/COMMON.rb
+- lib/rote/project/doc/pages/index.rb
 - lib/rote/builtin.rf
+- lib/rote/project/Rakefile
+- lib/rote/project/doc
+- lib/rote/project/README
+- lib/rote/project/doc/res
+- lib/rote/project/doc/pages
+- lib/rote/project/doc/layouts
+- lib/rote/project/doc/res/images
+- lib/rote/project/doc/res/images/rote-tiny.png
+- lib/rote/project/doc/pages/index.html
+- lib/rote/project/doc/layouts/normal.html
 - test/test_page.rb
 - test/pages
 - test/layouts