hoe-manns 1.0.0

data/manual/lib/editorial-filter.rb

@@ -0,0 +1,59 @@
+#!/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

@@ -0,0 +1,230 @@
+#!/usr/bin/ruby
+#encoding: utf-8
+#
+# 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 )
+		require 'pathname'
+		require 'strscan'
+		require 'yaml'
+		require 'rcodetools/xmpfilter'
+		require 'digest/md5'
+		require 'tmpdir'
+		require 'erb'
+	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

@@ -0,0 +1,111 @@
+#!/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
+
+
+
+
+