hoe-manualgen 0.0.1

data/.autotest

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+# Autotest.add_hook :initialize do |at|
+#   at.extra_files << "../some/external/dependency.rb"
+#
+#   at.libs << ":../some/external"
+#
+#   at.add_exception 'vendor'
+#
+#   at.add_mapping(/dependency.rb/) do |f, _|
+#     at.files_matching(/test_.*rb$/)
+#   end
+#
+#   %w(TestA TestB).each do |klass|
+#     at.extra_class_map[klass] = "test/test_misc.rb"
+#   end
+# end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/History.md

@@ -0,0 +1,4 @@
+## 0.0.1 [2011-01-31] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/README.md

@@ -0,0 +1,72 @@
+# hoe-manualgen
+
+* http://deveiate.org/hoe-manualgen.html
+
+## Description
+
+A manual-generation plugin for Hoe.
+
+This is a plugin for [Hoe][hoe] that adds tasks and resources for
+generating a manual or cookbook.
+
+It's self-documenting, so for more, see [the latest manual for hoe-manualgen itself][hoe-manualgen-manual].
+
+
+## Installation
+
+    gem install hoe-manualgen
+
+
+## Contributing
+
+You can check out the current development source with Mercurial like so:
+
+	hg clone http://bitbucket.org/ged/hoe-manualgen
+
+Or if you prefer Git, via its Github mirror:
+
+	https://github.com/ged/hoe-manualgen
+
+After checking out the source, run:
+
+	$ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+## License
+
+Copyright (c) 2010, 2011, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+[hoe]:http://seattlerb.rubyforge.org/hoe/
+[hoe-manualgen-manual]:http://deveiate.org/code/hoe-manualgen/
+
+

data/Rakefile

@@ -0,0 +1,85 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	$stderr.puts "This Rakefile requires Hoe (gem install hoe)"
+end
+
+require 'rake/clean'
+
+Hoe.add_include_dirs 'lib'
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :manualgen
+
+Hoe.plugins.delete :rubyforge
+
+hoespec = Hoe.spec 'hoe-manualgen' do
+	self.readme_file = 'README.md'
+	self.history_file = 'History.md'
+
+	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
+
+	self.extra_deps.push *{
+		'RedCloth'   => '~> 4.2.3',
+		'rcodetools' => '~> 0.8.5.0',
+	}
+	self.extra_dev_deps.push *{
+		'rspec'    => '~> 2.4.0',
+		'tidy-ext' => '~> 0.1.10',
+	}
+
+	self.spec_extras[:licenses] = ["BSD"]
+	self.spec_extras[:signing_key] = '/Volumes/Keys/ged-private_gem_key.pem'
+
+	self.require_ruby_version( '>=1.8.7' )
+
+	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
+
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+begin
+	include Hoe::MercurialHelpers
+
+	### Task: prerelease
+	desc "Append the package build number to package versions"
+	task :pre do
+		rev = get_numeric_rev()
+		trace "Current rev is: %p" % [ rev ]
+		hoespec.spec.version.version << "pre#{rev}"
+		Rake::Task[:gem].clear
+
+		Gem::PackageTask.new( hoespec.spec ) do |pkg|
+			pkg.need_zip = true
+			pkg.need_tar = true
+		end
+	end
+
+	### Make the ChangeLog update if the repo has changed since it was last built
+	file '.hg/branch'
+	file 'ChangeLog' => '.hg/branch' do |task|
+		$stderr.puts "Updating the changelog..."
+		content = make_changelog()
+		File.open( task.name, 'w', 0644 ) do |fh|
+			fh.print( content )
+		end
+	end
+
+	# Rebuild the ChangeLog immediately before release
+	task :prerelease => 'ChangeLog'
+
+rescue NameError => err
+	task :no_hg_helpers do
+		fail "Couldn't define the :pre task: %s: %s" % [ err.class.name, err.message ]
+	end
+
+	task :pre => :no_hg_helpers
+	task 'ChangeLog' => :no_hg_helpers
+
+end
+

data/data/hoe-manualgen/layouts/default.erb.erb

@@ -0,0 +1,87 @@
+<!DOCTYPE html>  
+<!--
+
+	Main Manual Layout
+	$Id: default.erb.erb,v 8077c9cdbac9 2011/01/26 02:15:09 ged $
+	
+	Author: Michael Granger <ged@FaerieMUD.org>
+	Two column fluid layout adapted from Matthew James Taylor's "Perfect 'Left Menu' 
+	2 Column Liquid Layout":
+	http://matthewjamestaylor.com/blog/perfect-2-column-left-menu.htm
+
+  -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+
+  <title><%= name %> Manual — <%%= page.config['title'] || "untitled" %></title>
+
+  <link rel="stylesheet" href="css/manual.css">
+
+  <script src="js/jquery-1.4.4.min.js"></script>
+  <script src="js/sh.js"></script>
+  <script src="js/manual.js"></script>
+
+</head>
+<body>
+<div id="page">
+
+	<header>
+		<hgroup>
+			<a href="/">
+				<h1><%= name %></h1>
+			</a>
+			<%% if metadata.version %><h2 class="version"><%%= metadata.version %></h2><%% end %>
+			<%% if page.config['tagline'] %><h2 class="tagline"><%%= page.config['tagline'] %></h2><%% end %>
+		</hgroup>
+	</header>
+
+	<div class="colmask leftmenu">
+		<div class="colleft">
+
+			<section id="content" class="col1">
+				<!-- Generated content -->
+				<%%= content %>
+				<!-- end of generated content -->
+			</section>
+
+			<aside id="sidebar" class="col2">
+				<nav>
+		<%%
+					@catalog.traverse_page_hierarchy( self ) do |type, title, path|
+						case type
+		  			when :section
+		%>
+						<div class="section">
+							<h3><a href="<%%= self.basepath + path %>/"><%%= title %></a></h3>
+							<ul class="index-section">
+		<%%  		when :current_section %>
+						<div class="section current-section">
+							<h3><a href="<%%= self.basepath + path %>/"><%%= title %></a></h3>
+							<ul class="index-section current-index-section">
+		<%%  		when :section_end, :current_section_end %>
+							</ul>
+						</div>
+		<%%  		when :entry %>
+							<li><a href="<%%= self.basepath + path %>.html"><%%= title %></a></li>
+		<%%  		when :current_entry %>
+							<li class="current-entry"><%%= title %></li>
+		<%% 			end
+					end
+		 %>
+				</nav>
+	</aside>
+
+		</div>
+	</div>
+ 
+	<footer>
+		<div class="copyright">Copyright &copy; 2008-<%%= Time.now.year %> <%= author.join(', ') %>.</div>
+		<div class="vcsrev">Rev: $Revision: 8077c9cdbac9 $</div>
+		<div class="timestamp">Built: <%%= Time.now.strftime("%Y%m%d %H:%M:%S %Z") %></div>
+	</footer>
+
+</body>
+</html>
+

data/data/hoe-manualgen/lib/api-filter.rb

@@ -0,0 +1,76 @@
+#!/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 "click here":Class::Name ?>
+### 
+class Hoe::ManualGen::APIFilter < Hoe::ManualGen::Page::Filter
+
+	# PI	   ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
+	ApiPI = %r{
+		<\?
+			api			# Instruction Target
+			\s+
+			(?:"					
+				(.*?)   # Optional link text [$1]
+			":)?
+			(.*?)	    # Class name [$2]
+			\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
+
+			self.generate_link( page, apipath, classname, link_text )
+		end
+	end
+
+
+	### Create an HTML link fragment from the parsed ApiPI.
+	###
+	def generate_link( current_page, apipath, classname, 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</a>} % [
+				classuri,
+				link_text || classname
+			]
+		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
+end
+

data/data/hoe-manualgen/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::Page::Filter
+	
+	# 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/data/hoe-manualgen/lib/examples-filter.rb

@@ -0,0 +1,238 @@
+#!/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::Page::Filter
+	
+	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
+