rote 0.1.0

data/doc/pages/index.html

@@ -0,0 +1,66 @@
+h2. Rote - A static website build tool for Ruby
+
+*Rote is a simple page-based template system for your static website 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 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.
+
+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.
+	* 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
+	  as a custom task library.
+	* Supports any (text-based) format, while providing utilities and helpers for
+	  common formats (HTML at present).
+
+h3. So where is it?
+
+The first release of Rote can be downloaded from "Our FRS on RubyForge":http://rubyforge.org/frs/?group_id=1120 .
+It should be also available as a RubyGem (rote-0.1.0) in the usual way.
+The "README":rdoc/files/README.html has the most comprehensive user guide at the moment.  Obviously, this
+site is still under construction too.
+
+You can also grab the latest code from "CVS":http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote. 
+
+Please note that Rote is still pretty new, and while this first release is 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. Check out the "Project page on Rubyforge":http://rubyforge.org/projects/rote 
+for everything you need to get going with the CVS version.
+
+h3. Licence
+
+<ul>
+<pre>
+<code>
+Copyright (c) 2005 Ross Bamford (and contributors)
+
+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 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+</code>
+</pre>
+</ul>

data/doc/pages/index.rb

@@ -0,0 +1,4 @@
+# the default
+#layout 'page'
+
+@page_title = 'Welcome!'

data/doc/res/stylesheets/normal.css

@@ -0,0 +1,141 @@
+/*
+ * (c)2005 Ross Bamford.
+ *
+ * rosco at roscopeco dot co dot uk
+ */
+body {
+	background: #ffffff;
+	color: #000000;
+	font-family: arial, helvetica, sans-serif;
+	font-size: 10pt;
+	padding: 0px;
+	margin: 0px 0px 0px 0px;
+}
+
+a:link {
+	color: #cc3030;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #df3b3b;
+	text-decoration: underline;
+}
+
+a:active {
+	color: #df3b3b;
+	text-decoration: underline;
+}
+
+a:visited {
+	color: #b02424;
+	text-decoration: none;
+}
+
+a#nav:link {
+	color: #cc3030;
+	text-decoration: none;
+	font-weight: bold;
+	background: auto;
+}
+
+a#nav:hover {
+	color: #df3b3b;
+	text-decoration: underline;
+	font-weight: bold;
+	background: #c3c3c3;
+}
+
+a#nav:active {
+	color: #df3b3b;
+	text-decoration: underline;
+	font-weight: bold;
+	background: #c3c3c3;
+}
+
+a#nav:visited {
+	color: #b02424;
+	text-decoration: none;
+	font-weight: bold;
+	background: auto;
+}
+
+/* outer div top bar on pages */
+table.topbar {
+	background: #f5f5f5;
+	color: #000000;
+	width: 100%;
+	border: white thin none;
+}
+
+tr.topnav {
+	background: #ebebeb;
+	text-align: center;
+	padding: 5px;
+}
+
+td.toplogo {
+	text-align: left;
+}
+
+td.toprpotlogo {
+	text-align: right;
+}
+
+td.navicon {
+	width: 22px;
+}
+
+img.navicon {
+	border: white thin none;
+	width: 22px;
+	height: 22px;
+}
+
+/* ***************** */
+
+div.frontcopyright {
+	/* Copyright bit on front page */
+	color: #909090;
+	position: absolute;
+	bottom: 2%;
+	right: 2%;
+	text-align: right;
+	font-size: 8pt;
+}
+
+div.copyright {
+	/* Copyright bit on pages */
+	color: #909090;
+	position: relative;	
+	top: 5em;
+	right: 2%;
+	text-align: right;
+	font-size: 8pt;	
+}
+
+div.main {
+	/* main div on front page */
+	width: 90%;
+	margin: 2% 2% 2% 2%;
+}
+
+img.smallrpotlogo {
+	width: 210px;
+	height: 47px;
+}
+
+img.biglogo {
+	width: 294px;
+	height: 135px;
+}
+
+img.medlogo {
+	width: 221px;
+	height: 101px;
+}
+
+img.smalllogo {
+	width: 147px;
+	height: 68px;
+}

data/install.rb

@@ -0,0 +1,96 @@
+puts <<-EOM
+NOT YET SUPPORTED
+
+Please copy 'bin' and 'lib' to a new directory, and set ROTE_HOME to 
+point there. Standard installation is not yet supported.
+EOM
+
+__END__
+require 'rbconfig'
+require 'find'
+require 'ftools'
+
+include Config
+
+$ruby = CONFIG['ruby_install_name']
+
+##
+# Install a binary file. We patch in on the way through to
+# insert a #! line. If this is a Unix install, we name
+# the command (for example) 'rake' and let the shebang line
+# handle running it. Under windows, we add a '.rb' extension
+# and let file associations to their stuff
+#
+
+def installBIN(from, opfile)
+
+  tmp_dir = nil
+  for t in [".", "/tmp", "c:/temp", $bindir]
+    stat = File.stat(t) rescue next
+    if stat.directory? and stat.writable?
+      tmp_dir = t
+      break
+    end
+  end
+
+  fail "Cannot find a temporary directory" unless tmp_dir
+  tmp_file = File.join(tmp_dir, "_tmp")
+    
+  File.open(from) do |ip|
+    File.open(tmp_file, "w") do |op|
+      ruby = File.join($realbindir, $ruby)
+      op.puts "#!#{ruby} -w"
+      op.write ip.read
+    end
+  end
+
+  opfile += ".rb" if CONFIG["target_os"] =~ /mswin/i
+  File::install(tmp_file, File.join($bindir, opfile), 0755, true)
+  File::unlink(tmp_file)
+end
+
+$sitedir = CONFIG["sitelibdir"]
+unless $sitedir
+  version = CONFIG["MAJOR"]+"."+CONFIG["MINOR"]
+  $libdir = File.join(CONFIG["libdir"], "ruby", version)
+  $sitedir = $:.find {|x| x =~ /site_ruby/}
+  if !$sitedir
+    $sitedir = File.join($libdir, "site_ruby")
+  elsif $sitedir !~ Regexp.quote(version)
+    $sitedir = File.join($sitedir, version)
+  end
+end
+
+$bindir =  CONFIG["bindir"]
+
+$realbindir = $bindir
+
+bindir = CONFIG["bindir"]
+if (destdir = ENV['DESTDIR'])
+  $bindir  = destdir + $bindir
+  $sitedir = destdir + $sitedir
+  
+  File::makedirs($bindir)
+  File::makedirs($sitedir)
+end
+
+rote_dest = File.join($sitedir, "rote")
+File::makedirs(rote_dest, true)
+File::chmod(0755, rote_dest)
+
+# The library files
+
+files = Dir.chdir('lib') { Dir['**/*.rb'] }
+
+for fn in files
+  fn_dir = File.dirname(fn)
+  target_dir = File.join($sitedir, fn_dir)
+  if ! File.exist?(target_dir)
+    File.makedirs(target_dir)
+  end
+  File::install(File.join('lib', fn), File.join($sitedir, fn), 0644, true)
+end
+
+# and the executable
+
+installBIN("bin/rote", "rote")

data/lib/rote/app.rb

@@ -0,0 +1,112 @@
+require 'getoptlong'
+
+module Rote
+
+  # Command-line launcher for Rote.
+  class Application
+    attr_accessor :rote_bin
+    attr_accessor :rote_lib
+    attr_accessor :debug
+    attr_accessor :tasks
+    attr_accessor :trace
+    attr_accessor :usage
+    attr_accessor :version
+    attr_accessor :rake
+    attr_accessor :rakefile
+    attr_accessor :rakeopts
+    
+    # Create a new Application instance, processing command-line arguments,
+    # optionally passing +self+ to the supplied block for further 
+    # configuration.
+    def initialize(rote_bin, rote_lib) # :yield: self if block_given?
+      # init vars
+      @rote_bin = rote_bin
+      @rote_lib = rote_lib || rote_bin
+      @debug = false
+      @tasks = false
+      @trace = false
+      @usage = false
+      @version = false    
+      
+      @rakefile = File.exists?('Rakefile') ? 'Rakefile' : "#{rote_lib}/builtin.rf"
+      @rakeopts = ENV['RAKE_OPTS'] || ''
+      @rake = ENV['RAKE_CMD'] || 'rake'
+      
+      process_args
+      
+      yield self if block_given?
+    end
+      
+    # Run the application with the current options.
+    def run            
+      if @version
+        print "rote, version #{ROTEVERSION}\n"
+       
+      elsif @tasks
+        print `#{rake} --rakefile=#{rakefile} --libdir=#{rote_lib} --tasks`.gsub(/^rake /,'rote ')
+      
+      elsif @usage
+        show_usage()
+      
+      else
+        if @trace
+          rakeopts << ' --trace'
+        elsif @debug
+          rakeopts << '--verbose'
+        end
+      
+        exec("#{rake} --rakefile=#{rakefile} --libdir=#{rote_lib} #{rakeopts} #{$*.join(' ')}")
+      end
+    end
+    
+    private
+    
+    # Display help text
+    def show_usage
+      print <<-EOM
+      Usage: rote [options] [task1] .. [taskN]
+    
+      Where [taskN] is a valid task or target name for the current project. 
+      Rite generates targets for each page source, and also defines a number
+      of top-level tasks for various things. Use the '--tasks' option to get
+      a list of valid tasks.
+    
+      Recognised options are:
+    
+        --tasks     -T     Display a list of tasks in this project.
+        --debug     -d     Enable debugging information.
+        --trace     -t     Enables verbose debugging information.    
+        --usage     -u     Display this help message and quit
+        --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.
+      
+      Depending on your environment, you may need to set ROTE_HOME to point
+      to the installation directory. 
+      EOM
+    end
+    
+    # Process commandline
+    def process_args
+      GetoptLong.new(
+        [ "--debug",   "-d", GetoptLong::NO_ARGUMENT ],
+        [ "--tasks",   "-T", GetoptLong::NO_ARGUMENT ],
+        [ "--trace",   "-x", GetoptLong::NO_ARGUMENT ],
+        [ "--usage",   "-u", GetoptLong::NO_ARGUMENT ],
+        [ "--help",    "-h", GetoptLong::NO_ARGUMENT ],
+        [ "--version", "-v", GetoptLong::NO_ARGUMENT ]
+      ).each { |opt,arg|
+        @debug = true if opt == '--debug'
+        @trace = true if opt == '--trace'
+        @tasks = true if opt == '--tasks'
+        @usage = true if opt == '--usage' || opt == '--help'
+        @version = true if opt == '--version'
+      }    
+    end
+    
+  end # Application
+end # Rote

data/lib/rote/dirfilelist.rb

@@ -0,0 +1,42 @@
+module Rote
+
+  # An extension to the Rake +FileList+ class that allows a root
+  # directory to be specified.
+  class DirectoryFileList < FileList  
+  
+    # Create a +DirectoryFileList+ with optional root directory and
+    # patterns. You may also pass a block to perform additional
+    # configuration (e.g. if you have a lot of includes/excludes
+    # or just don't like arguments for whatever reason).
+    def initialize(basedir = '.', *patterns)
+      dir=(basedir)
+      super(*patterns)
+    end
+  
+    # The root directory from which this filelist matches. All patterns
+    # are considered relative to this directory.
+    attr_accessor :dir        
+    def dir=(newdir)
+      newdir = newdir.sub(/\/$/,'')
+      sub!(/^#{@dir}/,newdir)
+      @dir = newdir    
+    end
+   
+    # Adds the specified *shell glob* pattern(s) to the list of includes
+    # for this file list. The base directory is implied.
+    def include(*patterns)
+      super(*patterns.map { |it| "#{dir}/#{it}"})
+    end  
+
+    # Adds the specified *regexp or shell glob* pattern(s) to the list of
+    # excludes for this file list. The base directory is implied on 
+    # non-+Regexp+.arguments.
+    def exclude(*patterns)
+      # exclude takes regexps too, which we should leave alone.
+      super(*patterns.map { |it| 
+        it.is_a?(String) ? "#{dir}/#{it}" : it
+      })
+    end  
+  end
+  
+end

data/lib/rote/page.rb

@@ -0,0 +1,184 @@
+require 'erb'
+require 'rubygems'
+
+require_gem('RedCloth')
+
+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+.
+  ## 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
+  ## and set any instance variables, for use later in the template.
+  ##
+  ## Rendering happens only once for a given page object, when the 
+  ## to_html method is first called. Once a page has been rendered
+  ## it is frozen.
+  class Page  
+    # The text of the template to use for this page.
+    attr_reader :template_text
+
+    # The text of the layout to use for this page. This is read in
+    # 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.
+    # 
+    # The default is [], which means 'No formatting'. This setting
+    # does not affect ERB rendering (which is always performed, before
+    # any formatting).
+    attr_accessor :format_opts
+    def format_opts=(opts)
+      if !opts.nil? && opts.respond_to?(:to_ary)
+        @format_opts = opts
+      else
+        @format_opts = [opts]
+      end
+    end
+    
+    # Reads the template, and evaluates the global and page scripts, if 
+    # available, using the current binding. You may define any instance
+    # variables or methods you like in that code for use in the template,
+    # as well as accessing the predefined @template and @template_text
+    # variables.
+    #
+    # If specified, the layout path will be used to find layouts referenced
+    # from templates. 
+    #
+    # If a block is supplied, it is executed _after_ the global / page
+    # code, so you can locally override variables and so on. 
+    def initialize(template_fn, 
+                   layout_path = File.dirname(template_fn), 
+                   default_layout_ext = File.extname(template_fn)) # :yield: self if block_given?    
+      @template_text = nil
+      @layout_text = nil
+      @content_for_layout = nil
+      @result = nil
+      @format_opts = []
+      @layout_defext = default_layout_ext
+      @layout_path = layout_path
+      @fixme_dir = File.dirname(template_fn)
+      
+      # read in the template. Layout _may_ get configured later in page code
+      read_template(template_fn)
+      
+      # 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)    
+      
+      # Allow block to have the final say
+      yield self if block_given?  
+    end
+            
+    # Sets the layout from the specified file, or disables layout if
+    # +nil+ is passed in. The specified basename should be the name
+    # of the layout file relative to the +layout_dir+, with no extension.
+    #
+    # The layout is read by this method. An exception is
+    # thrown if the layout doesn't exist.
+    #
+    # This can only be called before the first call to +render+. After 
+    # that the instance is frozen.
+    def layout(basename)
+      if basename
+        fn = layout_fn(basename)
+        raise "Layout #{fn} not found" unless File.exists?(fn)
+        @layout_text = File.read(fn)
+      else
+        @layout_text = nil
+      end
+    end    
+    
+    # Render this page's textile and ERB, and apply layout.
+    # This is only done once - after that, it's cached for next time. You can
+    # also circumvent rendering by setting @result yourself in your page's ruby.
+    def render
+      @result or do_render!   # sets up result for next time...
+    end
+    
+    alias to_s render
+    
+    private
+        
+    # Sets the template from the specified file, or clears the template if
+    # +nil+ is passed in. The specified basename should be the name
+    # of the layout file relative to the +layout_dir+, with no extension.
+    def read_template(fn)
+      if fn
+        raise "Template #{fn} not found" unless File.exists?(fn)
+        @template_text = File.read(fn)
+      else
+        @template_text = nil
+      end
+    end  
+    
+    # render, set up @result for next time. Return result too.    
+    def do_render!
+      # Render the page content into the @content_for_layout
+      if !@template_text.nil?
+        ctl = ERB.new(@template_text).result(binding)
+        
+        @content_for_layout = 
+            if @format_opts && ((@format_opts.respond_to?(:to_ary) && (!@format_opts.empty?)) || @format_opts.is_a?(Symbol)) 
+              opts = @format_opts.respond_to?(:to_ary) ? @format_opts : [@format_opts]          
+              RedCloth.new(ctl).to_html(*opts) 
+            else
+              ctl
+            end
+      end
+      
+      # render into the layout if supplied.
+      @result = if !@layout_text.nil?
+        ERB.new(@layout_text).result(binding)   
+      else 
+        @content_for_layout
+      end 
+      
+      freeze
+      @result 
+    end
+        
+    # Get a full layout filename from a basename. If the basename has no extension,
+    # the default extension is added.
+    def layout_fn(basename) 
+      ext = File.extname(basename)
+      "#{@layout_path}/#{basename}#{@layout_defext if ext.empty?}"    
+    end
+    
+    # FIXME NASTY HACK: Allow templates to inherit COMMON.rb. This should be replaced
+    # with a proper search for inherited in Page.new. Call from your COMMON.rb to 
+    # inherit the COMMON.rb immediately above this. If none exists there, this doesn't go
+    # looking beyond that - it just returns false
+    def inherit_common
+      inh = "#{@fixme_dir}/../COMMON.rb"
+      if File.exists?(inh)
+        instance_eval(File.read(inh))
+        true              
+      else
+        false
+      end
+    end
+    
+    # FIXME NASTY HACK II: relative links (doesn't work)
+    def link_rel(href) 
+      thr = href
+      if thr.is_a?(String) && href[0,1] == '/'
+        thr = href[1..href.length]     
+        count = @fixme_dir.split('/').length - 2
+        if count > 0 then count.times {
+          thr = '../' + thr
+        } end      
+      end
+      thr
+    end
+    
+  end #class  
+end #module