inversion 0.0.3 → 0.0.4

data/manual/lib/api-filter.rb

@@ -1,96 +0,0 @@
-#!/usr/bin/ruby 
-#
-# A manual filter to generate links from the Darkfish API.
-#
-# Authors:
-# * Michael Granger <ged@FaerieMUD.org>
-# * Mahlon E. Smith <mahlon@martini.nu>
-#
-
-
-### A filter for generating links from the generated API documentation. This allows you to refer
-### to class documentation by simply referencing a class name.
-###
-### Links are XML processing instructions. Pages can be referenced as such:
-###
-###   <?api Class::Name ?>
-###   <?api Class::Name#instance_method ?>
-###   <?api Class::Name.class_method ?>
-###
-### Link text can be overridden, too:
-###
-###   <?api "click here":Class::Name ?>
-###   <?api "click here":Class::Name#instance_method ?>
-###
-class Hoe::ManualGen::APIFilter < Hoe::ManualGen::PageFilter
-
-	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
-	ApiPI = %r{
-		<\?
-			api			# Instruction Target
-			\s+
-			(?:"					
-				(.*?)   # Optional link text [$1]
-			":)?
-			(.*?)	    # Class name [$2]
-			([\.#].*?)? # Method anchor [$3]
-			\s+
-		\?>
-	  }x
-
-
-	######
-	public
-	######
-
-	### Process the given +source+ for <?api ... ?> processing-instructions, calling out
-	def process( source, page, metadata )
-
-		apipath = metadata.api_dir or
-			raise "The API output directory is not defined in the manual task."
-
-		return source.gsub( ApiPI ) do |match|
-			# Grab the tag values
-			link_text  = $1
-			classname  = $2
-			methodname = $3
-
-			self.generate_link( page, apipath, classname, methodname, link_text )
-		end
-	end
-
-
-	### Create an HTML link fragment from the parsed ApiPI.
-	def generate_link( current_page, apipath, classname, methodname=nil, link_text=nil )
-
-		classpath = "%s.html" % [ classname.gsub('::', '/') ]
-		classfile = apipath + classpath
-		classuri  = current_page.basepath + 'api' + classpath
-
-		if classfile.exist?
-			return %{<a href="%s%s">%s</a>} % [
-				classuri,
-				make_anchor( methodname ),
-				link_text || (classname + methodname || '')
-			]
-		else
-			link_text ||= classname
-			error_message = "Could not find a link for class '%s'" % [ classname ]
-			$stderr.puts( error_message )
-			return %{<a href="#" title="#{error_message}" class="broken-link">#{link_text}</a>}
-		end
-	end
-
-
-	### Attach a method anchor.
-	def make_anchor( methodname )
-		return '' unless methodname
-
-		method_type = methodname[ 0, 1 ]
-		return "#method-%s-%s" % [
-			( method_type == '#' ? 'i' : 'c' ),
-			methodname[ 1..-1 ]
-		]
-	end
-end
-

data/manual/lib/editorial-filter.rb

@@ -1,59 +0,0 @@
-#!/usr/bin/ruby 
-# 
-# A manual filter to highlight content that needs editorial help.
-# 
-# Authors:
-# * Michael Granger <ged@FaerieMUD.org>
-# 
-# 
-
-
-
-### A filter for making editorial marks in manual content.
-### 
-### Editorial marks are XML processing instructions. There are several available types of
-### marks:
-###
-###   <?ed "This is an editor's note." ?>
-###   <?ed verify:"this content needs checking or verification" ?>
-### 
-class Hoe::ManualGen::EditorialFilter < Hoe::ManualGen::PageFilter
-	
-	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
-	LinkPI = %r{
-		<\?
-			ed					# Instruction Target
-			\s+
-			(\w+?)				# type of editorial mark [$1]
-			:?					# optional colon
-			"					
-				(.*?)           # content that should be edited [$2]
-			"
-			\s*
-		\?>
-	  }x
-	
-	
-	######
-	public
-	######
-
-	### Process the given +source+ for <?ed ... ?> processing-instructions
-	def process( source, page, metadata )
-		return source.gsub( LinkPI ) do |match|
-			# Grab the tag values
-			mark_type = $1
-			content   = $2
-			
-			self.generate_mark( page, mark_type, content )
-		end
-	end
-	
-	
-	### Create an HTML fragment from the parsed LinkPI.
-	def generate_mark( current_page, mark_type, content )
-		return "%%(editorial %s-mark)%s%%" % [ mark_type, content ]
-	end
-	
-	
-end

data/manual/lib/examples-filter.rb

@@ -1,238 +0,0 @@
-#!/usr/bin/ruby 
-# 
-# A collection of standard filters for the manual generation tasklib.
-# 
-# Authors:
-#   Michael Granger <ged@FaerieMUD.org>
-# 
-# 
-
-# Dependencies deferred until #initialize
-
-
-
-### A filter for inline example code or command-line sessions -- does
-### syntax-checking for some languages and captioning.
-### 
-### Examples are enclosed in XML processing instructions like so:
-###
-###   <?example {language: ruby, testable: true, caption: "A fine example"} ?>
-###      a = 1
-###      puts a
-###   <?end example ?>
-###
-### This will be pulled out into a preformatted section in the HTML,
-### highlighted as Ruby source, checked for valid syntax, and annotated with
-### the specified caption. Valid keys in the example PI are:
-### 
-### language::
-###   Specifies which (machine) language the example is in.
-### testable::
-###	  If set and there is a testing function for the given language, run it and append
-###	  any errors to the output.
-### caption::
-###   A small blurb to put below the pulled-out example in the HTML.
-class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
-	
-	DEFAULTS = {
-		:language     => :ruby,
-		:line_numbers => :inline,
-		:tab_width    => 4,
-		:hint         => :debug,
-		:testable     => false,
-	}
-
-	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
-	ExamplePI = %r{
-		<\?
-			example				# Instruction Target
-			(?:					# Optional instruction body
-			\s+
-			((?:				# [$1]
-				[^?]*			# Run of anything but a question mark
-				|				# -or-
-				\?(?!>)			# question mark not followed by a closing angle bracket
-			)*)
-			)?
-		\?>
-	  }x
-	
-	EndPI = %r{ <\? end (?: \s+ example )? \s* \?> }x
-
-
-	### Defer loading of dependenies until the filter is loaded
-	def initialize( *args )
-		begin
-			require 'pathname'
-			require 'strscan'
-			require 'yaml'
-			require 'rcodetools/xmpfilter'
-			require 'digest/md5'
-			require 'tmpdir'
-			require 'erb'
-		rescue LoadError => err
-			unless Object.const_defined?( :Gem )
-				require 'rubygems'
-				retry
-			end
-
-			raise
-		end
-	end
-	
-	
-	######
-	public
-	######
-
-	### Process the given +source+ for <?example ... ?> processing-instructions, calling out
-	def process( source, page, metadata )
-		scanner = StringScanner.new( source )
-		
-		buffer = ''
-		until scanner.eos?
-			startpos = scanner.pos
-			
-			# If we find an example
-			if scanner.skip_until( ExamplePI )
-				contents = ''
-				
-				# Append the interstitial content to the buffer
-				if ( scanner.pos - startpos > scanner.matched.length )
-					offset = scanner.pos - scanner.matched.length - 1
-					buffer << scanner.string[ startpos..offset ]
-				end
-
-				# Append everything up to it to the buffer and save the contents of
-				# the tag
-				params = scanner[1]
-				
-				# Now find the end of the example or complain
-				contentpos = scanner.pos
-				scanner.skip_until( EndPI ) or
-					raise "Unterminated example at line %d" % 
-						[ scanner.string[0..scanner.pos].count("\n") ]
-				
-				# Now build the example and append to the buffer
-				if ( scanner.pos - contentpos > scanner.matched.length )
-					offset = scanner.pos - scanner.matched.length - 1
-					contents = scanner.string[ contentpos..offset ]
-				end
-
-				trace "Processing with params: %p, contents: %p" % [ params, contents ]
-				buffer << self.process_example( params, contents, page )
-			else
-				break
-			end
-
-		end
-		buffer << scanner.rest
-		scanner.terminate
-		
-		return buffer
-	end
-	
-	
-	### Filter out 'example' macros, doing syntax highlighting, and running
-	### 'testable' examples through a validation process appropriate to the
-	### language the example is in.
-	def process_example( params, body, page )
-		options = self.parse_options( params )
-		caption = options.delete( :caption )
-		content = ''
-		lang = options.delete( :language ).to_s
-		
-		# Test it if it's testable
-		if options[:testable]
-			content = test_content( body, lang, page )
-		else
-			content = body
-		end
-
-		# Strip trailing blank lines and syntax-highlight
-		content = highlight( content.strip, options, lang )
-		caption = %{<div class="caption">} + caption.to_s + %{</div>} if caption
-
-		return %{<notextile><div class="example #{lang}-example">%s%s</div></notextile>} %
-		 	[content, caption || '']
-	end
-
-
-	### Parse an options hash for filtering from the given +args+, which can either 
-	### be a plain String, in which case it is assumed to be the name of the language the example 
-	### is in, or a Hash of configuration options.
-	def parse_options( args )
-		args = "{ #{args} }" unless args.strip[0] == ?{
-		args = YAML.load( args )
-
-		# Convert to Symbol keys and value
-		args.keys.each do |k|
-			newval = args.delete( k )
-			next if newval.nil? || (newval.respond_to?(:size) && newval.size == 0)
-			args[ k.to_sym ] = newval.respond_to?( :to_sym ) ? newval.to_sym : newval
-		end
-		return DEFAULTS.merge( args )
-	end
-	
-
-	### Test the given +content+ with a rule specific to the given +language+.
-	def test_content( body, language, page )
-		case language.to_sym
-		when :ruby
-			return self.test_ruby_content( body, page )
-
-		when :yaml
-			return self.test_yaml_content( body, page )
-
-		else
-			return body
-		end
-	end
-	
-		
-	### Test the specified Ruby content for valid syntax
-	def test_ruby_content( source, page )
-		# $stderr.puts "Testing ruby content..."
-		libdir = Pathname.new( __FILE__ ).dirname.parent.parent.parent + 'lib'
-		extdir = Pathname.new( __FILE__ ).dirname.parent.parent.parent + 'ext'
-
-		options = Rcodetools::XMPFilter::INITIALIZE_OPTS.dup
-		options[:include_paths] |= [ libdir.to_s, extdir.to_s ]
-		options[:width] = 60
-
-		if page.config['example_prelude']
-			prelude = page.config['example_prelude']
-			trace "  prepending prelude:\n#{prelude}"
-			source = prelude.strip + "\n" + source.strip
-		else
-			trace "  no prelude; page config is: %p" % [ page.config ]
-		end
-
-		rval = Rcodetools::XMPFilter.run( source, options )
-
-		trace "test output: ", rval
-		return rval.join
-	rescue Exception => err
-		return "%s while testing: %s\n  %s" %
-			[ err.class.name, err.message, err.backtrace.join("\n  ") ]
-	end
-	
-	
-	### Test the specified YAML content for valid syntax
-	def test_yaml_content( source, metadata )
-		YAML.load( source )
-	rescue YAML::Error => err
-		return "# Invalid YAML: " + err.message + "\n" + source
-	else
-		return source
-	end
-	
-	
-	### Highlights the given +content+ in language +lang+.
-	def highlight( content, options, lang )
-		source = ERB::Util.html_escape( content )
-		return %Q{\n\n<pre class="brush:#{lang}">#{source}</pre>\n\n}
-	end
-	
-end
-

data/manual/lib/links-filter.rb

@@ -1,111 +0,0 @@
-#!/usr/bin/ruby
-#
-# A manual filter to generate links from the page catalog.
-#
-# Authors:
-# * Michael Granger <ged@FaerieMUD.org>
-# * Mahlon E. Smith <mahlon@martini.nu>
-#
-#
-
-
-### A filter for generating links from the page catalog. This allows you to refer to other pages
-### in the source and have them automatically updated as the structure of the manual changes.
-###
-### Links are XML processing instructions. Pages can be referenced in one of several ways:
-###
-###   <?link Page Title ?>
-###   <?link "click here":Page Title ?>
-###   <?link Page Title #section_id ?>
-###   <?link "click here":Page Title#section_id ?>
-###
-### This first form links to a page by title. Link text defaults to the page title unless an
-### optional quoted string is prepended. If you want to link to an anchor inside the page, include
-### its ID with a hash mark after the title.
-###
-###   <?link path/to/Catalog.page ?>
-###   <?link "click here":path/to/Catalog.page ?>
-###   <?link path/to/Catalog.page#section_id ?>
-###   <?link "click here":path/to/Catalog.page#section_id ?>
-###
-### The second form links to a page by its path relative to the base manual source directory.
-### Again, the link text defaults to the page title, or can be overriden via a prepended string,
-### and you can link into a page with an appended ID.
-class Hoe::ManualGen::LinksFilter < Hoe::ManualGen::PageFilter
-
-	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
-	LinkPI = %r{
-		<\?
-			link				# Instruction Target
-			\s+
-			(?:"
-				(.*?)           # Optional link text [$1]
-			":)?
-			(.*?)				# Title or path [$2]
-			\s*
-			(\#[\-\w]+)?		# Fragment [$3]
-			\s+
-		\?>
-	  }x
-
-
-	######
-	public
-	######
-
-	### Process the given +source+ for <?link ... ?> processing-instructions, calling out
-	def process( source, page, metadata )
-		return source.gsub( LinkPI ) do |match|
-			# Grab the tag values
-			link_text = $1
-			reference = $2
-			fragment  = $3
-
-			self.generate_link( page, reference, link_text, fragment )
-		end
-	end
-
-
-	### Create an HTML link fragment from the parsed LinkPI.
-	def generate_link( current_page, reference, link_text=nil, fragment=nil )
-
-		if other_page = self.find_linked_page( current_page, reference )
-			href_path = other_page.sourcefile.relative_path_from( current_page.sourcefile.dirname )
-			href = href_path.to_s.gsub( '.page', '.html' )
-
-			if link_text
-				return %{<a href="#{href}#{fragment}">#{link_text}</a>}
-			else
-				return %{<a href="#{href}#{fragment}">#{other_page.title}</a>}
-			end
-		else
-			link_text ||= reference
-			error_message = "Could not find a link for reference '%s'" % [ reference ]
-			$stderr.puts( error_message )
-			return %{<a href="#" title="#{error_message}" class="broken-link">#{link_text}</a>}
-		end
-	end
-
-
-	### Lookup a page +reference+ in the catalog.  +reference+ can be either a
-	### path to the .page file, relative to the manual root path, or a page title.
-	### Returns a matching Page object, or nil if no match is found.
-	def find_linked_page( current_page, reference )
-
-		catalog = current_page.catalog
-
-		# Lookup by page path
-		if reference =~ /\.page$/
-			return catalog.uri_index[ reference ]
-
-		# Lookup by page title
-		else
-			return catalog.title_index[ reference ]
-		end
-	end
-end
-
-
-
-
-