rote 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c)2005 Ross Bamford (and contributors). All rights reserved.
+
+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.
+

data/README

@@ -0,0 +1,293 @@
+= ROTE - A static website build tool for Ruby
+
+== What is this?
+
+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.
+
+== Should I download it?
+
+I don't know. 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).
+	  
+So, should you?
+  
+== Why 'Rote'
+
+The name? I tried to come up with a combination of 'Ruby Site', but couldn't
+get past 'Rite' (it's already taken ;)). So, I changed a letter. I'm short on
+imagination you know. Oh, you mean why the system? Well, to make it easier 
+for me to manage roscopeco.co.uk now that I've dumped all the dynamic (JEE) 
+stuff and gone back to good old Apache sans CGI. I want something that lets 
+me do the disconnected page rendering and some of the 'dynamic' stuff, 
+without the dynamic stuff.
+
+If you really need a better explanation for the name, I've come up with these
+alternatives:
+
+* Something about 'the docs I rote'
+* 'Rake-Oriented Template Extensions'
+* 'Rote Only Talks Erb'
+* 'Really? Ordinary Template Enhancements?'
+
+== What else do I need?
+
+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)
+* RubyGems 0.8.11 (http://rubyforge.org/frs/?group_id=126)
+* Rake 0.6.2 ('gem install rake')
+* RedCloth 3.0.4 ('gem install RedCloth')
+
+== How do I install it?
+
+Set it up somewhere warm. At the moment, the standard install.rb is broken,
+and so disabled - you will need to install Rote into it's own directory
+(I know, I know). DONT modify your path - it's what symlinks are for.
+If you use a symlink you'll probaby need to point ROTE_HOME to the install
+directory as well. With that done, you should be able to run 
+
+	rote --version
+	
+to verify that the command-line wrapper is working. If you wish to use the 
+tasks in your own Rakefiles, you will need to modify the library load path. 
+This can be done using the --libdir option to Rake, or alternatively by adding
+something like the following _before_ the +require+ '+rote+' line:
+
+	$: << "#{ENV['ROTE_HOME']}/lib"
+	
+This line does of course place restrictions on the build environment, in that
+Rote will have to be properly installed and configured with the ROTE_HOME
+environment variable.
+
+Obviously once we get into releases, Rote will of course be distributed via
+RubyGems, allowing much of this to be transparent for the user if you have
+Gems. Fixing the proper installation is a priority, and will come soon. 
+
+*Note*: Currently, the +rote+ script supports usage with custom Rakefiles as
+well as the built-in command-line setup. If +rote+ is run from a directory 
+that contains an existing Rakefile, it will use that instead of the built-in
+one. It will *not* search parent directories for a Rakefile.
+
+This feature exists to support custom Rakefiles without libpath twiddling,
+but should be considered a hack that will probably disappear from a (not
+too distant) future version.
+ 
+== How do I use it?
+
+=== 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+ -
+you can use the built-in build via the +rote+ command. This works with
+a standard directory layout, and wraps invocation of +rake+ to handle
+setting up library dependencies and generation of appropriate tasks.
+
+You'll need something like the following directory layout:
+  
+  somesite ( <- root, this can be called whatever you like)
+  |--> [publish.rf]
+  |
+  |--> doc
+  |    |--> [COMMON.rb]
+  |    |
+  |    |--> res
+  |    |    |--> (resources)
+  |    |
+  |    |--> layouts
+  |    |    |--> one.rhtml
+  |    |    |--> two.rhtml
+  |    | 
+  |    |--> pages
+  |    |    |--> [COMMON.rb]
+  |    |    |--> apage.txt
+  |    |    |--> [apage.rb]
+  |    |    |--> adir
+  |    |    |    |--> [COMMON.rb]
+  |    |    |    |--> bpage.html
+  |    |    |    |--> [bpage.rb]   
+
+Template sources under the 'pages' directory may have any extension (except
++rb+), and will be rendered to that same name under the output directory. 
+See the section on Layouts below for details on layout name resolution.
+Set up a simple test site following the above layout, and then run:
+
+	rote
+	
+from the top-level directory (+somesite+), you should get a 'target' directory
+created with the (transformed) templates.
+
+Now try:
+
+	rote --tasks
+	
+to get a list of valid tasks, or 
+	
+	rote --usage
+	
+for further option information.
+
+=== 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 
+your own (existing) +Rakefile+. Fortunately, this is very easy to do. Try 
+something like:
+
+	# Rakefile
+	include 'rote'
+	
+	ws = Rote::DocTask.new(:doc) { |site| 
+	  site.site_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')
+	}
+	
+Save this as +Rakefile+, and fire up:
+
+	rake --libdir=$ROTE_HOME/lib doc
+
+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.
+
+== Creating templates
+
+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.
+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.
+
+=== Template code and ERB
+
+All templates may contain embedded Ruby code (ERB), delimited by the standard
+<% ... %> (for executed code) and <%= ... %> (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.
+* This page's ruby code, _basename_.rb
+* In a block passed to Page.new
+* In the template itself
+
+When a Rote::Page instance is created, Rote looks for these, and 
+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.
+
+=== Text to HTML formatting
+
+Rote uses RedCloth (http://redcloth.rubyforge.org) to provide text to HTML 
+formatting, supporting both Textile and Markdown. The formatting applied to a
+given page is controlled by that page's +format_opts+ array. Both are disabled
+by default - to enable formatting you must add something like the following
+somewhere appropriate:
+
+	format_opts << :textile << :markdown
+	
+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.
+
+Formatting is applied _after_	any ERB has been evaluated.
+
+*Note* 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.
+
+=== Layout
+
+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
+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:
+
+	layout 'one'
+	layout 'main/wide'
+	layout 'dark.txt'
+	<% layout 'my' %>
+	
+With that done, Rote would first render the template text (including textile)
+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.:
+
+	<%= @content_for_layout %>
+	
+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.
+
+== 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.
+
+Of course, the directory layout beneath +res+ should mirror that of the 
+output, and will be preserved during the copy.
+
+== 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). 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 task that uses an SSH directory
+publisher to publish via SCP.
+
+== A final note about command-line mode
+
+Currently, there isn't enough checking involved on source resources when
+building pages from the command-line wrapper - Basically, only templates are
+considered when Rake decides what to update. If you change layouts, code or 
+resources you'll need to run:
+	
+	rote clean
+		
+to make sure everything gets updated. It's recommended to always run upload
+as:
+	
+	rote clean upload
+		
+Please note that this isn't Rake's limitation - it's mine.	

data/Rakefile

@@ -0,0 +1,369 @@
+# Rote Rakefile (run with 'rake' command)
+#
+# Copyright 2005 Ross Bamford (and contributors). All rights reserved.
+# Rote is distributed under an MIT style license.  See LICENSE for details.
+#
+# 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.3 2005/11/25 01:24:39 roscopeco Exp $
+#
+
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+$: << 'lib'
+require 'rote'
+
+CLEAN.include('testdata')
+CLOBBER.include('TAGS')
+
+def announce(msg='')
+  STDERR.puts msg
+end
+
+# Determine the current version of the software
+
+if `ruby -Ilib ./bin/rote --version` =~ /\S+$/
+  CURRENT_VERSION = $&
+else
+  CURRENT_VERSION = "0.0.0"
+end
+
+if ENV['REL']
+  PKG_VERSION = ENV['REL']
+else
+  PKG_VERSION = CURRENT_VERSION
+end
+
+
+SRC_RB = FileList['lib/**/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task (All tests)"
+task :default => :alltests
+
+# Test Tasks ---------------------------------------------------------
+
+task :ta => :alltests
+#task :tf => :funtests
+task :tu => :unittests
+task :test => :unittests
+
+Rake::TestTask.new(:alltests) do |t|
+  t.test_files = FileList[
+    'test/test*.rb',
+    'test/contrib/test*.rb',
+    'test/fun*.rb'
+  ]
+  t.warning = true
+  t.verbose = true
+end
+
+Rake::TestTask.new(:unittests) do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.warning = true
+  t.verbose = false
+end
+
+# Rake::TestTask.new(:funtests) do |t|
+#   t.test_files = FileList['test/fun*.rb']
+#   t.warning = true
+#   t.warning = true
+# end
+
+directory 'testdata'
+[:alltests, :unittests].each do |t|
+  task t => ['testdata']
+end
+
+# CVS Tasks ----------------------------------------------------------
+
+# Install rote using the standard install.rb script.
+desc "Install the application"
+task :install do
+  ruby "install.rb"
+end
+
+# Website / Doc tasks ------------------------------------------------
+
+# Create a task to build the RDOC documentation tree.
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html/rdoc'
+#  rdoc.template = 'kilmer'
+#  rdoc.template = 'css2'
+  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('lib/**/*.rb', 'doc/**/*.rdoc')
+  rdoc.rdoc_files.exclude(/\bcontrib\b/)
+}
+
+# Create a task build the website / docs
+CLOBBER.include('html')
+
+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')
+}
+
+# add rdoc dep to doc task
+task :doc => [:rdoc]
+
+# ====================================================================
+# Create a task that will package the Rote software into distributable
+# tar, zip and gem files.
+
+PKG_FILES = FileList[
+  'install.rb',
+  '[A-Z]*',
+  'bin/**/*', 
+  'lib/**/*.rb', 
+  'test/**/*.rb',
+  'test/**/*.rf',
+  'test/**/*.mf',
+  'test/**/Rakefile',
+  'doc/**/*'
+]
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'rote'
+    s.version = PKG_VERSION
+    s.summary = "Adds template-based doc support to Rake."
+    s.description = <<-EOF
+      Rote is a set of Rake task libraries and utilities that
+      enable easy rendering of textual documentation formats
+      (like HTML) for websites and offline documentation.
+    EOF
+
+    #### Dependencies and requirements.
+
+    #s.add_dependency('log4r', '> 1.0.4')
+    #s.requirements << ""
+
+    #### Which files are to be included in this gem?  Everything!  (Except CVS directories.)
+
+    s.files = PKG_FILES.to_a
+
+    #### C code extensions.
+
+    #s.extensions << "ext/rmagic/extconf.rb"
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'                         # Use these for libraries.
+
+    s.bindir = "bin"                               # Use these for applications.
+    s.executables = ["rote"]
+    s.default_executable = "rote"
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    s.rdoc_options <<
+      '--title' <<  'Rote -- Template-based doc support for Rake' <<
+      '--main' << 'README' <<
+      '--line-numbers' << 
+      '-o' << 'html/rdoc'
+
+    #### Author and project details.
+
+    s.author = "Ross Bamford"
+    s.email = "ross@roscopeco.co.uk"
+    s.homepage = "http://rote.rubyforge.org"
+    s.rubyforge_project = "rote"
+#     if ENV['CERT_DIR']
+#       s.signing_key = File.join(ENV['CERT_DIR'], 'gem-private_key.pem')
+#       s.cert_chain  = [File.join(ENV['CERT_DIR'], 'gem-public_cert.pem')]
+#     end
+  end
+
+  package_task = Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar_gz = true
+    pkg.package_dir = 'pkg'    
+  end
+end
+
+# Misc tasks =========================================================
+
+def count_lines(filename)
+  lines = 0
+  codelines = 0
+  open(filename) { |f|
+    f.each do |line|
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+  }
+  [lines, codelines]
+end
+
+def show_line(msg, lines, loc)
+  printf "%6s %6s   %s\n", lines.to_s, loc.to_s, msg
+end
+
+desc "Count total lines in source"
+task :lines do
+  total_lines = 0
+  total_code = 0
+  show_line("File Name", "LINES", "LOC")
+  SRC_RB.each do |fn|
+    lines, codelines = count_lines(fn)
+    show_line(fn, lines, codelines)
+    total_lines += lines
+    total_code  += codelines
+  end
+  show_line("TOTAL", total_lines, total_code)
+end
+
+ARCHIVEDIR = '/mnt/usb'
+
+task :archive => [:package] do
+  cp FileList["pkg/*.tar.gz", "pkg/*.zip", "pkg/*.gem"], ARCHIVEDIR
+end
+
+# Define an optional publish target in an external file.  If the
+# publish.rf file is not found, the publish targets won't be defined.
+
+load "publish.rf" if File.exist? "publish.rf"
+
+# Support Tasks ------------------------------------------------------
+
+desc "Look for TODO and FIXME tags in the code"
+task :todo do
+  FileList['**/*.rb'].egrep /#.*(FIXME|TODO|TBD)/
+end
+
+desc "Look for Debugging print lines"
+task :dbg do
+  FileList['**/*.rb'].egrep /\bDBG|\bbreakpoint\b/
+end
+
+desc "List all ruby files"
+task :rubyfiles do 
+  puts Dir['**/*.rb'].reject { |fn| fn =~ /^pkg/ }
+  puts Dir['bin/*'].reject { |fn| fn =~ /CVS|(~$)|(\.rb$)/ }
+end
+
+# --------------------------------------------------------------------
+# Creating a release
+
+desc "Make a new release"
+task :release => [
+  :prerelease,
+  :clobber,
+  :alltests,
+  :update_version,
+  :package,
+  :tag] do
+  
+  announce 
+  announce "**************************************************************"
+  announce "* Release #{PKG_VERSION} Complete."
+  announce "* Packages ready to upload."
+  announce "**************************************************************"
+  announce 
+end
+
+# Validate that everything is ready to go for a release.
+task :prerelease do
+  announce 
+  announce "**************************************************************"
+  announce "* Making RubyGem Release #{PKG_VERSION}"
+  announce "* (current version #{CURRENT_VERSION})"
+  announce "**************************************************************"
+  announce  
+
+  # Is a release number supplied?
+  unless ENV['REL']
+    fail "Usage: rake release REL=x.y.z [REUSE=tag_suffix]"
+  end
+
+  # Is the release different than the current release.
+  # (or is REUSE set?)
+  if PKG_VERSION == CURRENT_VERSION && ! ENV['REUSE']
+    fail "Current version is #{PKG_VERSION}, must specify REUSE=tag_suffix to reuse version"
+  end
+
+  # Are all source files checked in?
+  if ENV['RELTEST']
+    announce "Release Task Testing, skipping checked-in file test"
+  else
+    announce "Checking for unchecked-in files..."
+    data = `cvs -q update`
+    unless data =~ /^$/
+      fail "CVS update is not clean ... do you have unchecked-in files?"
+    end
+    announce "No outstanding checkins found ... OK"
+  end
+end
+
+task :update_version => [:prerelease] do
+  if PKG_VERSION == CURRENT_VERSION
+    announce "No version change ... skipping version update"
+  else
+    announce "Updating Rote version to #{PKG_VERSION}"
+    open("lib/rote.rb") do |rakein|
+      open("lib/rote.rb.new", "w") do |rakeout|
+	rakein.each do |line|
+	  if line =~ /^ROTEVERSION\s*=\s*/
+	    rakeout.puts "ROTEVERSION = '#{PKG_VERSION}'"
+	  else
+	    rakeout.puts line
+	  end
+	end
+      end
+    end
+    mv "lib/rote.rb.new", "lib/rote.rb"
+    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}
+    end
+  end
+end
+
+desc "Tag all the CVS files 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"
+  else
+    sh %{cvs tag #{reltag}}
+  end
+end
+
+# Require experimental XForge/Metaproject support.
+# load 'xforge.rf' if File.exist?('xforge.rf')
+

data/TODO

@@ -0,0 +1,12 @@
+= Rote project -- Todo list
+
+Most of the following ideas will probably be implemented at some point.
+Send any suggestions (or test-driven patches) to:
+
+  rosco <at> roscopeco <dot> co <dot> uk
+
+* More flexible markup rendering
+* Integration with test reports
+* Automatic navigation / TOC
+* Index and glossary support
+* statistics