pluginfactory 1.0.3 → 1.0.4

data/rake/191_compat.rb

@@ -0,0 +1,26 @@
+# 1.9.1 fixes
+
+
+# Make Pathname compatible with 1.8.7 Pathname.
+unless Pathname.instance_methods.include?( :=~ )
+	class Pathname
+		def self::glob( *args ) # :yield: p
+			args = args.collect {|p| p.to_s }
+			if block_given?
+				Dir.glob(*args) {|f| yield self.new(f) }
+			else
+				Dir.glob(*args).map {|f| self.new(f) }
+			end
+		end
+
+		def =~( other )
+			self.to_s =~ other
+		end
+
+		def to_str
+			self.to_s
+		end
+	end
+end
+
+

data/rake/dependencies.rb

@@ -1,6 +1,6 @@
 # 
 # Dependency-checking and Installation Rake Tasks
-# $Id: dependencies.rb 10 2008-07-18 15:52:48Z deveiant $
+# $Id: dependencies.rb 43 2008-09-05 18:19:16Z deveiant $
 # 
 
 require 'rubygems/dependency_installer'
@@ -9,8 +9,7 @@ require 'rubygems/requirement'
 require 'rubygems/doc_manager'
 
 ### Install the specified +gems+ if they aren't already installed.
-def install_gems( *gems )
-	gems.flatten!
+def install_gems( gems )
 	
 	defaults = Gem::DependencyInstaller::DEFAULT_OPTIONS.merge({
 		:generate_rdoc     => true,
@@ -28,20 +27,28 @@ def install_gems( *gems )
 
 	gemindex = Gem::SourceIndex.from_installed_gems
 
-	gems.each do |gemname|
-		if (( specs = gemindex.search(gemname) )) && ! specs.empty?
-			log "Version %s of %s is already installed; skipping..." % 
-				[ specs.first.version, specs.first.name ]
+	gems.each do |gemname, reqstring|
+		requirement = Gem::Requirement.new( reqstring )
+		trace "requirement is: %p" % [ requirement ]
+		
+		trace "Searching for an installed #{gemname}..."
+		specs = gemindex.find_name( gemname )
+		trace "...found %d specs: %s" %
+			[ specs.length, specs.collect {|s| "%s %s" % [s.name, s.version] }.join(', ') ]
+		
+		if spec = specs.find {|spec| requirement.satisfied_by?(spec.version) }
+			log "Version %s of %s is already installed (needs %s); skipping..." % 
+				[ spec.version, spec.name, requirement ]
 			next
 		end
 
 		rgv = Gem::Version.new( Gem::RubyGemsVersion )
 		installer = nil
 		
-		log "Trying to install #{gemname.inspect}..."
+		log "Trying to install #{gemname.inspect} #{requirement}..."
 		if rgv >= Gem::Version.new( '1.1.1' )
 			installer = Gem::DependencyInstaller.new
-			installer.install( gemname )
+			installer.install( gemname, requirement )
 		else
 			installer = Gem::DependencyInstaller.new( gemname )
 			installer.install
@@ -55,8 +62,15 @@ def install_gems( *gems )
 end
 
 
-### Task: install gems for development tasks
+### Task: install runtime dependencies
+desc "Install runtime dependencies as gems"
 task :install_dependencies do
-	install_gems( DEPENDENCIES.keys )
+	install_gems( DEPENDENCIES )
+end
+
+### Task: install gems for development tasks
+desc "Install development dependencies as gems"
+task :install_dev_dependencies do
+	install_gems( DEVELOPMENT_DEPENDENCIES )
 end
 

data/rake/helpers.rb

@@ -1,9 +1,21 @@
+# encoding: utf-8
 #####################################################################
 ###	G L O B A L   H E L P E R   F U N C T I O N S
 #####################################################################
 
+
 require 'pathname'
-require 'readline'
+
+begin
+	require 'readline'
+	include Readline
+rescue LoadError
+	# Fall back to a plain prompt
+	def readline( text )
+		$stderr.print( text.chomp )
+		return $stdin.gets
+	end
+end
 
 # Set some ANSI escape code constants (Shamelessly stolen from Perl's
 # Term::ANSIColor by Russ Allbery <rra@stanford.edu> and Zenin <zenin@best.com>
@@ -42,7 +54,7 @@ CLEAR_CURRENT_LINE = "\e[2K"
 ### Output a logging message
 def log( *msg )
 	output = colorize( msg.flatten.join(' '), 'cyan' )
-	$deferr.puts( output )
+	$stderr.puts( output )
 end
 
 
@@ -50,7 +62,7 @@ end
 def trace( *msg )
 	return unless $trace
 	output = colorize( msg.flatten.join(' '), 'yellow' )
-	$deferr.puts( output )
+	$stderr.puts( output )
 end
 
 
@@ -59,9 +71,14 @@ end
 def run( *cmd )
 	cmd.flatten!
 
-	log( cmd.collect {|part| part =~ /\s/ ? part.inspect : part} ) 
+	if cmd.length > 1
+		trace( cmd.collect {|part| part =~ /\s/ ? part.inspect : part} ) 
+	else
+		trace( cmd )
+	end
+	
 	if $dryrun
-		$deferr.puts "(dry run mode)"
+		$stderr.puts "(dry run mode)"
 	else
 		system( *cmd )
 		unless $?.success?
@@ -71,6 +88,14 @@ def run( *cmd )
 end
 
 
+### Run a subordinate Rake process with the same options and the specified +targets+.
+def rake( *targets )
+	opts = ARGV.select {|arg| arg[0,1] == '-' }
+	args = opts + targets.map {|t| t.to_s }
+	run 'rake', '-N', *args
+end
+
+
 ### Open a pipe to a process running the given +cmd+ and call the given block with it.
 def pipeto( *cmd )
 	$DEBUG = true
@@ -78,7 +103,7 @@ def pipeto( *cmd )
 	cmd.flatten!
 	log( "Opening a pipe to: ", cmd.collect {|part| part =~ /\s/ ? part.inspect : part} ) 
 	if $dryrun
-		$deferr.puts "(dry run mode)"
+		$stderr.puts "(dry run mode)"
 	else
 		open( '|-', 'w+' ) do |io|
 		
@@ -108,7 +133,7 @@ def download( sourceuri, targetfile=nil )
 	log "Downloading %s to %s" % [sourceuri, targetfile]
 	targetpath.open( File::WRONLY|File::TRUNC|File::CREAT, 0644 ) do |ofh|
 	
-		url = sourceuri.is_a?( URI ) ? sourceuri : URI.parse( sourceuri )
+		url = sourceuri.is_a?( URI ) ? sourceuri : URI( sourceuri )
 		downloaded = false
 		limit = 5
 		
@@ -126,7 +151,7 @@ def download( sourceuri, targetfile=nil )
 						puts "done."
 		
 					elsif res.is_a?( Net::HTTPRedirection )
-						url = URI.parse( res['location'] )
+						url = URI( res['location'] )
 						log "...following redirection to: %s" % [ url ]
 						limit -= 1
 						sleep 0.2
@@ -159,12 +184,12 @@ end
 def ansi_code( *attributes )
 	attributes.flatten!
 	attributes.collect! {|at| at.to_s }
-	# $deferr.puts "Returning ansicode for TERM = %p: %p" %
+	# $stderr.puts "Returning ansicode for TERM = %p: %p" %
 	# 	[ ENV['TERM'], attributes ]
 	return '' unless /(?:vt10[03]|xterm(?:-color)?|linux|screen)/i =~ ENV['TERM']
 	attributes = ANSI_ATTRIBUTES.values_at( *attributes ).compact.join(';')
 
-	# $deferr.puts "  attr is: %p" % [attributes]
+	# $stderr.puts "  attr is: %p" % [attributes]
 	if attributes.empty? 
 		return ''
 	else
@@ -194,7 +219,7 @@ end
 ### Output the specified <tt>msg</tt> as an ANSI-colored error message
 ### (white on red).
 def error_message( msg, details='' )
-	$deferr.puts colorize( 'bold', 'white', 'on_red' ) { msg } + details
+	$stderr.puts colorize( 'bold', 'white', 'on_red' ) { msg } + details
 end
 alias :error :error_message
 
@@ -216,7 +241,7 @@ def prompt( prompt_string, failure_msg="Try again." ) # :yields: response
 
 	begin
 		prompt = make_prompt_string( prompt_string )
-		response = Readline.readline( prompt ) || ''
+		response = readline( prompt ) || ''
 		response.strip!
 		if block_given? && ! yield( response ) 
 			error_message( failure_msg + "\n\n" )
@@ -240,7 +265,7 @@ def prompt_with_default( prompt_string, default, failure_msg="Try again." )
 		response = prompt( "%s [%s]" % [ prompt_string, default ] )
 		response = default.to_s if !response.nil? && response.empty? 
 
-		trace "Validating reponse %p" % [ response ]
+		trace "Validating response %p" % [ response ]
 
 		# the block is a validator.  We need to make sure that the user didn't
 		# enter '~', because if they did, it's nil and we should move on.  If
@@ -267,7 +292,7 @@ def prompt_for_multiple_values( label, default=nil )
     result = nil
     
     begin
-        result = Readline.readline( make_prompt_string("> ") )
+        result = readline( make_prompt_string("> ") )
 		if result.nil? || result.empty?
 			results << default if default && results.empty?
 		else
@@ -279,8 +304,7 @@ def prompt_for_multiple_values( label, default=nil )
 end
 
 
-### Turn echo and masking of input on/off. Based on similar code in
-### Ruby-Password by Ian Macdonald <ian@caliban.org>.
+### Turn echo and masking of input on/off. 
 def noecho( masked=false )
 	require 'termios'
 
@@ -288,13 +312,15 @@ def noecho( masked=false )
 	term = Termios.getattr( $stdin )
 
 	begin
-		term.c_lflag &= ~Termios::ECHO
-		term.c_lflag &= ~Termios::ICANON if masked
+		newt = term.dup
+		newt.c_lflag &= ~Termios::ECHO
+		newt.c_lflag &= ~Termios::ICANON if masked
+
+		Termios.tcsetattr( $stdin, Termios::TCSANOW, newt )
 
 		rval = yield
 	ensure
-		term.c_lflag |= ( Termios::ECHO | Termios::ICANON )
-		Termios.setattr( $stdin, Termios::TCSANOW, term )
+		Termios.tcsetattr( $stdin, Termios::TCSANOW, term )
 	end
 	
 	return rval
@@ -313,22 +339,25 @@ end
 
 ### Display a description of a potentially-dangerous task, and prompt
 ### for confirmation. If the user answers with anything that begins
-### with 'y', yield to the block, else raise with an error.
-def ask_for_confirmation( description )
+### with 'y', yield to the block. If +abort_on_decline+ is +true+,
+### any non-'y' answer will fail with an error message.
+def ask_for_confirmation( description, abort_on_decline=true )
 	puts description
 
 	answer = prompt_with_default( "Continue?", 'n' ) do |input|
 		input =~ /^[yn]/i
 	end
 
-	case answer
-	when /^y/i
-		yield
-	else
+	if answer =~ /^y/i
+		return yield
+	elsif abort_on_decline
 		error "Aborted."
 		fail
 	end
+
+	return false
 end
+alias :prompt_for_confirmation :ask_for_confirmation
 
 
 ### Search line-by-line in the specified +file+ for the given +regexp+, returning the
@@ -348,19 +377,6 @@ def find_pattern_in_file( regexp, file )
 end
 
 
-### Get a list of the file or files to run rspec on.
-def rspec_files
-	if ENV['class']
-		classname = ENV['class']
-		spec_file = SPECSDIR + "#{classname}_spec.rb"
-		raise "Can't find the spec file for the class '#{classname}'" unless spec_file.exist?
-		return [ spec_file ]
-	else
-		return SPEC_FILES
-	end
-end
-
-
 ### Invoke the user's editor on the given +filename+ and return the exit code
 ### from doing so.
 def edit( filename )
@@ -374,9 +390,18 @@ end
 
 ### Extract all the non Rake-target arguments from ARGV and return them.
 def get_target_args
-	args = ARGV.reject {|arg| Rake::Task.task_defined?(arg) }
+	args = ARGV.reject {|arg| arg =~ /^-/ || Rake::Task.task_defined?(arg) }
 	return args
 end
 
 
+### Log a subdirectory change, execute a block, and exit the subdirectory
+def in_subdirectory( subdir )
+	block = Proc.new
+	
+	log "Entering #{subdir}"
+	Dir.chdir( subdir, &block )
+	log "Leaving #{subdir}"
+end
+	
 

data/rake/manual.rb

@@ -1,8 +1,10 @@
 # 
 # Manual-generation Rake tasks and classes
-# $Id: manual.rb 10 2008-07-18 15:52:48Z deveiant $
+# $Id: manual.rb 84 2009-02-10 07:38:42Z deveiant $
 # 
-# Author: Michael Granger <ged@FaerieMUD.org>
+# Authors:
+# * Michael Granger <ged@FaerieMUD.org>
+# * Mahlon E. Smith <mahlon@martini.nu>
 # 
 # This was born out of a frustration with other static HTML generation modules
 # and systems. I've tried webby, webgen, rote, staticweb, staticmatic, and
@@ -49,18 +51,25 @@ module Manual
 			end
 
 
+			### Export any static resources required by this filter to the given +output_dir+.
+			def export_resources( output_dir )
+				# No-op by default
+			end
+			
+
 			### Process the +page+'s source with the filter and return the altered content.
 			def process( source, page, metadata )
 				raise NotImplementedError,
 					"%s does not implement the #process method" % [ self.class.name ]
 			end
-		end
+		end # class Filter
 
 
 		### The default page configuration if none is specified.
 		DEFAULT_CONFIG = {
-			'filters' => [ 'textile', 'erb' ],
+			'filters' => [ 'erb', 'links', 'textile' ],
 			'layout'  => 'default.page',
+			'cleanup' => true,
 		  }.freeze
 
 		# Pattern to match a source page with a YAML header
@@ -74,24 +83,30 @@ module Manual
 		# Options to pass to libtidy
 		TIDY_OPTIONS = {
 			:show_warnings     => true,
-			:indent            => false,
+			:indent            => true,
 			:indent_attributes => false,
 			:indent_spaces     => 4,
 			:vertical_space    => true,
 			:tab_size          => 4,
 			:wrap_attributes   => true,
 			:wrap              => 100,
+			:char_encoding     => 'utf8'
 		  }
 
 
 		### Create a new page-generator for the given +sourcefile+, which will use
-		### ones of the templates in +layouts_dir+ as a wrapper.
-		def initialize( sourcefile, layouts_dir )
-			@sourcefile = Pathname.new( sourcefile )
+		### ones of the templates in +layouts_dir+ as a wrapper. The +basepath+ 
+		### is the path to the base output directory, and the +catalog+ is the
+		### Manual::PageCatalog to which the page belongs.
+		def initialize( catalog, sourcefile, layouts_dir, basepath='.' )
+			@catalog     = catalog
+			@sourcefile  = Pathname.new( sourcefile )
 			@layouts_dir = Pathname.new( layouts_dir )
+			@basepath    = basepath
 
 			rawsource = @sourcefile.read
 			@config, @source = self.read_page_config( rawsource )
+
 			# $stderr.puts "Config is: %p" % [@config],
 			# 	"Source is: %p" % [ @source[0,100] ]
 			@filters = self.load_filters( @config['filters'] )
@@ -104,6 +119,12 @@ module Manual
 		public
 		######
 		
+		# The Manual::PageCatalog to which the page belongs
+		attr_reader :catalog
+		
+		# The relative path to the base directory, for prepending to page paths
+		attr_reader :basepath
+		
 		# The Pathname object that specifys the page source file
 		attr_reader :sourcefile
 		
@@ -124,18 +145,28 @@ module Manual
 		def generate( metadata )
 			content = self.generate_content( @source, metadata )
 
-			# :TODO: Read config from page for layout, filters, etc.
-			templatepath = @layouts_dir + 'default.page'
+			layout = self.config['layout'].sub( /\.page$/, '' )
+			templatepath = @layouts_dir + "#{layout}.page"
 			template = ERB.new( templatepath.read )
 			page = self
 
 			html = template.result( binding() )
 
-			# return self.cleanup( html )
+			# Use Tidy to clean up the html if 'cleanup' is turned on, but remove the Tidy
+			# meta-generator propaganda/advertising.
+			html = self.cleanup( html ).sub( %r:<meta name="generator"[^>]*tidy[^>]*/>:im, '' ) if
+				self.config['cleanup']
+				
 			return html
 		end
 
 
+		### Return the page title as specified in the YAML options
+		def title
+			return self.config['title'] || self.sourcefile.basename
+		end
+		
+		
 		### Run the various filters on the given input and return the transformed
 		### content.
 		def generate_content( input, metadata )
@@ -168,8 +199,9 @@ module Manual
 				tidy.options.output_xhtml = true
 
 				xml = tidy.clean( source )
-				puts tidy.errors
-				puts tidy.diagnostics
+				errors = tidy.errors
+				error_message( errors.join ) unless errors.empty?
+				trace tidy.diagnostics
 				return xml
 			end
 		rescue LoadError => err
@@ -187,6 +219,239 @@ module Manual
 			end
 		end
 
+
+		### Build the index relative to the receiving page and return it as a String
+		def make_index_html
+			items = [ '<div class="index">' ]
+
+			@catalog.traverse_page_hierarchy( self ) do |type, title, path|
+				case type
+				when :section
+					items << %Q{<div class="section">}
+					items << %Q{<h2><a href="#{self.basepath + path}/">#{title}</a></h2>}
+					items << '<ul class="index-section">'
+					
+				when :current_section
+					items << %Q{<div class="section current-section">}
+					items << %Q{<h2><a href="#{self.basepath + path}/">#{title}</a></h2>}
+					items << '<ul class="index-section current-index-section">'
+
+				when :section_end, :current_section_end
+					items << '</ul></div>'
+
+				when :entry
+					items << %Q{<li><a href="#{self.basepath + path}.html">#{title}</a></li>}
+
+				when :current_entry
+					items << %Q{<li class="current-entry">#{title}</li>}
+
+				else
+					raise "Unknown index entry type %p" % [ type ]
+				end
+
+			end
+
+			items << '</div>'
+
+			return items.join("\n")
+		end
+
+	end
+
+
+	### A catalog of Manual::Page objects that can be referenced by various criteria.
+	class PageCatalog
+
+		### Create a new PageCatalog that will load Manual::Page objects for .page files 
+		### in the specified +sourcedir+.
+		def initialize( sourcedir, layoutsdir )			
+			@sourcedir = sourcedir
+			@layoutsdir = layoutsdir
+			
+			@pages       = []
+			@path_index  = {}
+			@uri_index   = {}
+			@title_index = {}
+			@hierarchy   = {}
+			
+			self.find_and_load_pages
+		end
+		
+		
+		######
+		public
+		######
+
+		# An index of the pages in the catalog by Pathname
+		attr_reader :path_index
+		
+		# An index of the pages in the catalog by title
+		attr_reader :title_index
+		
+		# An index of the pages in the catalog by the URI of their source relative to the source 
+		# directory
+		attr_reader :uri_index
+		
+		# The hierarchy of pages in the catalog, suitable for generating an on-page index
+		attr_reader :hierarchy
+		
+		# An Array of all Manual::Page objects found
+		attr_reader :pages
+
+		# The Pathname location of the .page files.
+		attr_reader :sourcedir
+		
+		# The Pathname location of look and feel templates.
+		attr_reader :layoutsdir
+
+		
+		### Traverse the catalog's #hierarchy, yielding to the given +builder+
+		### block for each entry, as well as each time a sub-hash is entered or
+		### exited, setting the +type+ appropriately. Valid values for +type+ are:
+		###	 
+		###		:entry, :section, :section_end
+		###
+		### If the optional +from+ value is given, it should be the Manual::Page object
+		### which is considered "current"; if the +from+ object is the same as the 
+		### hierarchy entry being yielded, it will be yielded with the +type+ set to 
+		### one of:
+		### 
+		###     :current_entry, :current_section, :current_section_end
+		###
+		### each of which correspond to the like-named type from above.
+		def traverse_page_hierarchy( from=nil, &builder ) # :yields: type, title, path
+			raise LocalJumpError, "no block given" unless builder
+			self.traverse_hierarchy( Pathname.new(''), self.hierarchy, from, &builder )
+		end
+
+
+		#########
+		protected
+		#########
+
+		### Sort and traverse the specified +hash+ recursively, yielding for each entry.
+		def traverse_hierarchy( path, hash, from=nil, &builder )
+			# Now generate the index in the sorted order
+			sort_hierarchy( hash ).each do |subpath, page_or_section|
+				if page_or_section.is_a?( Hash )
+					self.handle_section_callback( path + subpath, page_or_section, from, &builder )
+				else
+					next if subpath == INDEX_PATH
+					self.handle_page_callback( path + subpath, page_or_section, from, &builder )
+				end
+			end
+		end
+
+
+		### Return the specified hierarchy of pages as a sorted Array of tuples. 
+		### Sort the hierarchy using the 'index' config value of either the
+		### page, or the directory's index page if it's a directory.
+		def sort_hierarchy( hierarchy )
+			hierarchy.sort_by do |subpath, page_or_section|
+
+				# Directory
+				if page_or_section.is_a?( Hash )
+
+					# Use the index of the index page if it exists
+					if page_or_section[INDEX_PATH]
+						idx = page_or_section[INDEX_PATH].config['index']
+						trace "Index page's index for directory '%s' is: %p" % [ subpath, idx ]
+						idx.to_s || subpath.to_s
+					else
+						trace "Using the path for the sort of directory %p" % [ subpath ]
+						subpath.to_s
+					end
+					
+				# Page
+				else
+					if subpath == INDEX_PATH
+						trace "Sort index for index page %p is 0" % [ subpath ]
+						'0'
+					else
+						idx = page_or_section.config['index']
+						trace "Sort index for page %p is: %p" % [ subpath, idx ]
+						idx.to_s || subpath.to_s
+					end
+				end
+
+			end # sort_by
+		end
+		
+
+		INDEX_PATH = Pathname.new('index')
+
+		### Build up the data structures necessary for calling the +builder+ callback
+		### for an index section and call it, then recurse into the section contents.
+		def handle_section_callback( path, section, from=nil, &builder )
+			from_current = false
+			trace "Section handler: path=%p, section keys=%p, from=%s" %
+				[ path, section.keys, from.sourcefile ]
+			
+			# Call the callback with :section -- determine the section title from
+			# the 'index.page' file underneath it, or the directory name if no 
+			# index.page exists.
+			if section.key?( INDEX_PATH )
+				if section[INDEX_PATH].sourcefile.dirname == from.sourcefile.dirname
+					from_current = true
+					builder.call( :current_section, section[INDEX_PATH].title, path )
+				else
+					builder.call( :section, section[INDEX_PATH].title, path )
+				end
+			else
+				title = File.dirname( path ).gsub( /_/, ' ' )
+				builder.call( :section, title, path )
+			end
+			
+			# Recurse
+			self.traverse_hierarchy( path, section, from, &builder )
+			
+			# Call the callback with :section_end
+			if from_current
+				builder.call( :current_section_end, '', path )
+			else
+				builder.call( :section_end, '', path )
+			end
+		end
+		
+		
+		### Yield the specified +page+ to the builder
+		def handle_page_callback( path, page, from=nil )
+			if from == page
+				yield( :current_entry, page.title, path )
+			else
+				yield( :entry, page.title, path )
+			end
+		end
+		
+
+		### Find and store
+		
+		### Find all .page files under the configured +sourcedir+ and create a new
+		### Manual::Page object for each one.
+		def find_and_load_pages
+			Pathname.glob( @sourcedir + '**/*.page' ).each do |pagefile|
+				path_to_base = @sourcedir.relative_path_from( pagefile.dirname )
+
+				page = Manual::Page.new( self, pagefile, @layoutsdir, path_to_base )
+				hierpath = pagefile.relative_path_from( @sourcedir )
+
+				@pages << page
+				@path_index[ pagefile ]     = page
+				@title_index[ page.title ]  = page
+				@uri_index[ hierpath.to_s ] = page
+				
+				# Place the page in the page hierarchy by using inject to find and/or create the 
+				# necessary subhashes. The last run of inject will return the leaf hash in which
+				# the page will live
+				section = hierpath.dirname.split[1..-1].inject( @hierarchy ) do |hier, component|
+					hier[ component ] ||= {}
+					hier[ component ]
+				end
+
+				section[ pagefile.basename('.page') ] = page
+			end
+		end
+		
 	end
 
 
@@ -203,7 +468,10 @@ module Manual
 		### Process the given +source+ as Textile and return the resulting HTML
 		### fragment.
 		def process( source, *ignored )
-			return RedCloth.new( source ).to_html
+			formatter = RedCloth::TextileDoc.new( source )
+			formatter.hard_breaks = false
+			formatter.no_span_caps = true
+			return formatter.to_html
 		end
 
 	end
@@ -268,6 +536,70 @@ module Manual
 
 		attr_reader :name
 
+
+		### Set up the tasks for building the manual
+		def define
+
+			# Set up a description if the caller hasn't already defined one
+			unless Rake.application.last_comment
+				desc "Generate the manual"
+			end
+
+			# Make Pathnames of the directories relative to the base_dir
+			basedir     = Pathname.new( @base_dir )
+			sourcedir   = basedir + @source_dir
+			layoutsdir  = basedir + @layouts_dir
+			outputdir   = @output_dir
+			resourcedir = basedir + @resource_dir
+			libdir      = basedir + @lib_dir
+
+			load_filter_libraries( libdir )
+			catalog = Manual::PageCatalog.new( sourcedir, layoutsdir )
+			
+			# Declare the tasks outside the namespace that point in
+			task @name => "#@name:build"
+			task "clobber_#@name" => "#@name:clobber"
+
+			namespace( self.name ) do
+				setup_resource_copy_tasks( resourcedir, outputdir )
+				manual_pages = setup_page_conversion_tasks( sourcedir, outputdir, catalog )
+				
+				desc "Build the manual"
+				task :build => [ :rdoc, :copy_resources, :copy_apidocs, :generate_pages ]
+				
+				task :clobber do
+					RakeFileUtils.verbose( $verbose ) do
+						rm_f manual_pages.to_a
+					end
+					remove_dir( outputdir ) if ( outputdir + '.buildtime' ).exist?
+				end
+				
+				desc "Remove any previously-generated parts of the manual and rebuild it"
+				task :rebuild => [ :clobber, self.name ]
+				
+				desc "Watch for changes to the source files and rebuild when they change"
+				task :autobuild do
+					scope = [ self.name ]
+					loop do
+						t = Rake.application.lookup( :build, scope )
+						t.reenable
+						t.prerequisites.each do |pt|
+							if task = Rake.application.lookup( pt, scope )
+								task.reenable
+							else
+								trace "Hmmm... no %p task in scope %p?" % [ pt, scope ]
+							end
+						end
+						t.invoke
+						sleep 2
+						trace "  waking up..."
+					end
+				end
+	        end
+
+		end # def define
+		
+		
 		### Load the filter libraries provided in the given +libdir+
 		def load_filter_libraries( libdir )
 			Pathname.glob( libdir + '*.rb' ) do |filterlib|
@@ -279,12 +611,11 @@ module Manual
 
 		### Set up the main HTML-generation task that will convert files in the given +sourcedir+ to
 		### HTML in the +outputdir+
-		def setup_page_conversion_tasks( sourcedir, outputdir, layoutsdir )
-			source_glob = sourcedir + '**/*.page'
-			trace "Looking for sources that match: %s" % [ source_glob ]
+		def setup_page_conversion_tasks( sourcedir, outputdir, catalog )
 
-			# Find the list of source .page files
-			manual_sources = FileList[ source_glob ]
+			# we need to figure out what HTML pages need to be generated so we can set up the
+			# dependency that causes the rule to be fired for each one when the task is invoked.
+			manual_sources = FileList[ catalog.path_index.keys.map {|pn| pn.to_s} ]
 			trace "   found %d source files" % [ manual_sources.length ]
 			
 			# Map .page files to their equivalent .html output
@@ -306,11 +637,12 @@ module Manual
 					outputdir.to_s
 			 	]) do |task|
 			
-				source = Pathname.new( task.source ).relative_path_from( Pathname.getwd )
-				target = Pathname.new( task.name ).relative_path_from( Pathname.getwd )
+				source = Pathname.new( task.source )
+				target = Pathname.new( task.name )
 				log "  #{ source } -> #{ target }"
 					
-				page = Manual::Page.new( source, layoutsdir )
+				page = catalog.path_index[ source ]
+				#trace "  page object is: %p" % [ page ]
 					
 				target.dirname.mkpath
 				target.open( File::WRONLY|File::CREAT|File::TRUNC ) do |io|
@@ -318,67 +650,135 @@ module Manual
 				end
 			end
 			
+			# Group all the manual page output files targets into a containing task
+			desc "Generate any pages of the manual that have changed"
+			task :generate_pages => manual_pages
 			return manual_pages
 		end
 		
 		
+		### Copy method for resources -- passed as a block to the various file tasks that copy
+		### resources to the output directory.
+		def copy_resource( task )
+			source = task.prerequisites[ 1 ]
+			target = task.name
+			
+			when_writing do
+				trace "  #{source} -> #{target}"
+				mkpath File.dirname( target ), :verbose => $trace unless
+					File.directory?( File.dirname(target) )
+				install source, target, :mode => 0644, :verbose => $trace
+			end
+		end
+			
+		
 		### Set up a rule for copying files from the resources directory to the output dir.
 		def setup_resource_copy_tasks( resourcedir, outputdir )
+			resources = FileList[ resourcedir + '**/*.{js,css,png,gif,jpg,html}' ]
+			resources.exclude( /\.svn/ )
+			target_pathmap = "%%{%s,%s}p" % [ resourcedir, outputdir ]
+			targets = resources.pathmap( target_pathmap )
+			copier = self.method( :copy_resource ).to_proc
 			
-			task :copy_resources => [ outputdir.to_s ] do
-				when_writing( "Copying resources" ) do
-					verbose do
-						files = FileList[ resourcedir + '*' ]
-						files.exclude( /\.svn/ )
-						unless files.empty?
-							trace "  Copying resource files: #{files}"
-							cp_r files, outputdir, :verbose => true
-						end
-					end
-				end
+			# Create a file task to copy each file to the output directory
+			resources.each_with_index do |resource, i|
+				file( targets[i] => [ outputdir.to_s, resource ], &copier )
+			end
+
+			desc "Copy API documentation to the manual output directory"
+			task :copy_apidocs => :rdoc do
+				cp_r( RDOCDIR, outputdir )
+			end
+
+			# Now group all the resource file tasks into a containing task
+			desc "Copy manual resources to the output directory"
+			task :copy_resources => targets do
+				log "Copying manual resources"
 			end
 		end
 		
+	end # class Manual::GenTask
+	
+end
 
-		### Set up the tasks for building the manual
-		def define
 
-			# Set up a description if the caller hasn't already defined one
-			unless Rake.application.last_comment
-				desc "Generate the manual"
-			end
 
-			# Make Pathnames of the directories relative to the base_dir
-			basedir     = Pathname.new( @base_dir )
-			sourcedir   = basedir + @source_dir
-			layoutsdir  = basedir + @layouts_dir
-			outputdir   = basedir + @output_dir
-			resourcedir = basedir + @resource_dir
-			libdir      = basedir + @lib_dir
+### Task: manual generation
+if MANUALDIR.exist?
+	MANUALOUTPUTDIR = MANUALDIR + 'output'
+	trace "Manual will be generated in: #{MANUALOUTPUTDIR}"
+	
+	begin
+		directory MANUALOUTPUTDIR.to_s
+
+		Manual::GenTask.new do |manual|
+			manual.metadata.version = PKG_VERSION
+			manual.metadata.api_dir = RDOCDIR
+			manual.output_dir = MANUALOUTPUTDIR
+			manual.base_dir = MANUALDIR
+			manual.source_dir = 'src'
+		end
 
-			load_filter_libraries( libdir )
+		task :clobber_manual do
+			rmtree( MANUALOUTPUTDIR, :verbose => true )
+		end
 
-			# Declare the tasks outside the namespace that point in
-			task @name => "#@name:build"
-			task "clobber_#@name" => "#@name:clobber"
+	rescue LoadError => err
+		task :no_manual do
+			$stderr.puts "Manual-generation tasks not defined: %s" % [ err.message ]
+		end
 
-			namespace( self.name ) do
-				setup_resource_copy_tasks( resourcedir, outputdir )
-				manual_pages = setup_page_conversion_tasks( sourcedir, outputdir, layoutsdir )
+		task :manual => :no_manual
+		task :clobber_manual => :no_manual
+	end
+
+else
+	TEMPLATEDIR = RAKE_TASKDIR + 'manualdir'
+
+	if TEMPLATEDIR.exist?
+
+		desc "Create a manual for this project from a template"
+		task :manual do
+			log "No manual directory (#{MANUALDIR}) currently exists."
+			ask_for_confirmation( "Create a new manual directory tree from a template?" ) do
+				MANUALDIR.mkpath
 				
-				task :build => [ :copy_resources, *manual_pages ]
+				%w[layouts lib output resources src].each do |dir|
+					FileUtils.mkpath( MANUALDIR + dir, :mode => 0755, :verbose => true, :noop => $dryrun )
+				end
 				
-				task :clobber do
-					RakeFileUtils.verbose( $verbose ) do
-						rm_f manual_pages.to_a
+				Pathname.glob( TEMPLATEDIR + '**/*.{rb,css,png,js,erb,page}' ).each do |tmplfile|
+					trace "extname is: #{tmplfile.extname}"
+					
+					# Render ERB files
+					if tmplfile.extname == '.erb'
+						rname = tmplfile.basename( '.erb' )
+						target = MANUALDIR + tmplfile.dirname.relative_path_from( TEMPLATEDIR ) + rname
+						template = ERB.new( tmplfile.read, nil, '<>' )
+
+						target.dirname.mkpath( :mode => 0755, :verbose => true, :noop => $dryrun ) unless
+						 	target.dirname.directory?
+						html = template.result( binding() )
+						log "generating #{target}: html => #{html[0,20]}"
+
+						target.open( File::WRONLY|File::CREAT|File::EXCL, 0644 ) do |fh|
+							fh.print( html )
+						end
+					
+					# Just copy anything else
+					else
+						target = MANUALDIR + tmplfile.relative_path_from( TEMPLATEDIR )
+						FileUtils.mkpath target.dirname,
+							:mode => 0755, :verbose => true, :noop => $dryrun unless target.dirname.directory?
+						FileUtils.install tmplfile, target,
+							:mode => 0644, :verbose => true, :noop => $dryrun
 					end
-					remove_dir( outputdir ) if ( outputdir + '.buildtime' ).exist?
 				end
-				task :rebuild => [ :clobber, :build ]
-	        end
+			end
 
-		end # def define
-		
-	end # class Manual::GenTask
-	
+		end # task :manual
+
+	end
 end
+
+