mizuho 0.9.8 → 0.9.9

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Hongli Lai
+Copyright (c) 2008-2012 Hongli Lai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.markdown

@@ -4,29 +4,23 @@ Mizuho is a documentation formatting tool, best suited for small to
 medium-sized documentation. One writes documentation in plain text
 files, which Mizuho then converts to nicely formatted HTML.
 
-Mizuho supports input files in [Asciidoc](http://www.methods.co.nz/asciidoc/)
-format. Asciidoc is a text formatting tool, used by e.g. Git for its
-documentation. Thanks to Asciidoc, Mizuho supports a large number of formatting
-options.
+Mizuho wraps [Asciidoc](http://www.methods.co.nz/asciidoc/), the text
+formatting tool used by e.g. Git and Phusion Passenger for its manuals.
+Mizuho adds the following functionality on top of Asciidoc:
 
-### Under the hood
+ * Commenting via [Juvia](https://github.com/FooBarWidget/juvia).
 
-Mizuho is actually a wrapper around Asciidoc. Asciidoc itself can only
-generate single-page XHTML output. Mizuho extends Asciidoc by providing
-multi-page XHTML output support and support for multiple templates.
-
-## Features and highlights
-
- * You can output the documentation in a single XHTML file, or in multiple
-   XHTML files (one per chapter).
- * Output is fully customizable via ERB templates.
- * Based on Asciidoc and supports all Asciidoc formatting commands.
- * Comes bundled with Asciidoc so you don't have to install it yourself. Mizuho
-   Just Works(tm) out-of-the-box.
+Mizuho bundles Asciidoc so you don't have to install it yourself. Mizuho
+should Just Work(tm) out-of-the-box. Asciidoc uses GNU source-highlight
+for highlighting source code. GNU source-highlight depends on Boost and
+so is notorious for being difficult to install on systems without a
+decent package manager (e.g. OS X). Mizuho comes prebundled with an OS
+X binary for GNU source-highlight so that you don't have to worry about
+that.
 
 ## Requirements
 
- * hpricot (`gem install hpricot`)
+ * Nokogiri (`gem install nokogiri`)
  * Python (because Asciidoc is written in Python)
  * [GNU Source-highlight](http://www.gnu.org/software/src-highlite/), if you
    want syntax highlighting support. If you're on OS X then it's not necessary
@@ -46,17 +40,12 @@ http://www.methods.co.nz/asciidoc/userguide.html
 
 Next, write an input file and save it in a .txt file.
 
-Finally, convert the .txt file to a single XHTML file with Mizuho, with the
+Finally, convert the .txt file to a single HTML file with Mizuho, with the
 default template:
 
     mizuho input.txt
 
-This will generate 'input.html'. Or, you can convert it to multiple XHTML files
-that also have a different look:
-
-    mizuho input.txt --template manualsonrails --multi-page
-
-Take a look at the 'templates' directory for available templates.
+This will generate 'input.html'.
 
 ## Credits
 

data/asciidoc/stylesheets/flask.css

@@ -1,13 +1,3 @@
-/*
- * AsciiDoc 'flask' theme for xhtml11 and html5 backends. A shameless knock-off
- * of the Flask website styling (http://flask.pocoo.org/docs/).
- *
- * The implementation is straight-forward, consisting of the asciidoc.css file
- * followed by theme specific overrides.
- *
- * */
-
-
 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
 
 /* Default font. */
@@ -92,6 +82,7 @@ ul > li > * { color: black; }
 pre {
   padding: 0;
   margin: 0;
+  overflow: auto;
 }
 
 #author {
@@ -518,6 +509,29 @@ th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 }
 
 
+/*
+ * manpage specific
+ *
+ * */
+
+body.manpage h1 {
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+  border-top: 2px solid silver;
+  border-bottom: 2px solid silver;
+}
+body.manpage h2 {
+  border-style: none;
+}
+body.manpage div.sectionbody {
+  margin-left: 3em;
+}
+
+@media print {
+  body.manpage div#toc { display: none; }
+}
+
+
 /*
  * Theme specific overrides of the preceding (asciidoc.css) CSS.
  *
@@ -544,7 +558,7 @@ h1 { font-size: 240%; }
 h2 { font-size: 180%; }
 h3 { font-size: 150%; }
 h4 { font-size: 130%; }
-h5 { font-size: 100%; }
+h5 { font-size: 115%; }
 h6 { font-size: 100%; }
 #header h1 { margin-top: 0; }
 #toc {

data/bin/mizuho

@@ -1,24 +1,40 @@
 #!/usr/bin/env ruby
 require File.expand_path(File.dirname(__FILE__) + "/../lib/mizuho")
 require 'optparse'
+require 'rubygems'
 require 'mizuho/generator'
 
 $KCODE = 'UTF-8'
-options = {}
+options = { :topbar => true }
 parser = OptionParser.new do |opts|
+	nl = "\n" + ' ' * 37
 	opts.banner = "Usage: mizuho [options] INPUT"
 	opts.separator ""
 	
 	opts.separator "Options:"
-	opts.on("-t", "--template FILE", String, "Specify a template file to use.") do |value|
-		options[:template] = value
+	opts.on("-c", "--comments SYSTEM",
+	        "Use a commenting system. The only#{nl}" +
+	        "supported commenting system right now is#{nl}" +
+	        "'juvia'.") do |value|
+		if value != 'juvia'
+			abort "The only supported commenting system right now is 'juvia'."
+		end
+		options[:commenting_system] = value
 	end
-	opts.on("-m", "--multi-page", "Generate one file per chapter.") do |value|
-		options[:multi_page] = value
+	opts.on("--juvia-url URL", "When using Juvia as the commenting system,#{nl}" +
+	        "specify the Juvia base URL here.") do |value|
+		options[:juvia_url] = value
 	end
-	opts.on("--icons-dir DIR", "Specify the directory in which icons\n" <<
-		"#{' ' * 37}should be searched. Defaults to\n" <<
-		"#{' ' * 37}'images/icons'.") do |value|
+	opts.on("--juvia-site-key KEY", "When using Juvia as the commenting system,#{nl}" +
+	        "specify the Juvia site key here.") do |value|
+		options[:juvia_site_key] = value
+	end
+	#opts.on("-m", "--multi-page", "Generate one file per chapter.") do |value|
+	#	options[:multi_page] = value
+	#end
+	opts.on("--icons-dir DIR", "Specify the directory in which icons#{nl}" <<
+		"should be searched. Defaults to#{nl}" <<
+		"'images/icons'.") do |value|
 		options[:icons_dir] = value
 	end
 	opts.on("-o", "--output FILE", String, "Specify the output filename.") do |value|
@@ -28,9 +44,9 @@ end
 begin
 	parser.parse!
 rescue OptionParser::ParseError => e
-	puts e
-	puts
-	puts "Please see '--help' for valid options."
+	STDERR.puts e
+	STDERR.puts
+	STDERR.puts "Please see '--help' for valid options."
 	exit 1
 end
 

data/lib/mizuho.rb

@@ -1,9 +1,30 @@
+# Copyright (c) 2008-2012 Hongli Lai
+#
+# 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.
+
 module Mizuho
-	SOURCE_ROOT = File.expand_path(File.dirname(__FILE__) + "/..")
-	LIBDIR      = "#{SOURCE_ROOT}/lib"
-	ASCIIDOC    = "#{SOURCE_ROOT}/asciidoc/asciidoc.py"
+	SOURCE_ROOT   = File.expand_path(File.dirname(__FILE__) + "/..")
+	LIBDIR        = "#{SOURCE_ROOT}/lib"
+	TEMPLATES_DIR = "#{SOURCE_ROOT}/templates"
+	ASCIIDOC      = "#{SOURCE_ROOT}/asciidoc/asciidoc.py"
 	
-	VERSION_STRING = "0.9.8"
+	VERSION_STRING = "0.9.9"
 	
 	if $LOAD_PATH.first != LIBDIR
 		$LOAD_PATH.unshift(LIBDIR)

data/lib/mizuho/fuzzystringmatch.rb

@@ -0,0 +1,100 @@
+# Extracted from https://github.com/kiyoka/fuzzy-string-match
+
+#
+#                            Fuzzy String Match 
+#
+#   Copyright 2010 Kiyoka Nishiyama
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module Mizuho
+  class JaroWinklerPure
+    THRESHOLD = 0.7
+
+    def getDistance( s1, s2 )
+      a1 = s1.split( // )
+      a2 = s2.split( // )
+      
+      if s1.size > s2.size
+        (max,min) = a1,a2
+      else
+        (max,min) = a2,a1
+      end
+
+      range = [ (max.size / 2 - 1), 0 ].max
+      indexes = Array.new( min.size, -1 )
+      flags   = Array.new( max.size, false )
+
+      matches = 0;
+      (0 ... min.size).each { |mi|
+        c1 = min[mi]
+        xi = [mi - range, 0].max
+        xn = [mi + range + 1, max.size].min
+        
+        (xi ... xn).each { |i|
+          if (not flags[i]) && ( c1 == max[i] )
+            indexes[mi] = i
+            flags[i] = true
+            matches += 1
+            break
+          end
+        }
+      }
+
+      ms1 = Array.new( matches, nil )
+      ms2 = Array.new( matches, nil )
+
+      si = 0
+      (0 ... min.size).each { |i|
+        if (indexes[i] != -1)
+          ms1[si] = min[i]
+          si += 1
+        end
+      }
+
+      si = 0
+      (0 ... max.size).each { |i|
+        if flags[i]
+          ms2[si] = max[i]
+          si += 1
+        end
+      }
+      
+      transpositions = 0
+      (0 ... ms1.size).each { |mi|
+        if ms1[mi] != ms2[mi]
+          transpositions += 1
+        end
+      }
+
+      prefix = 0
+      (0 ... min.size).each { |mi|
+        if s1[mi] == s2[mi]
+          prefix += 1
+        else
+          break
+        end
+      }
+
+      if 0 == matches
+        0.0
+      else
+        m = matches.to_f
+        t = (transpositions/ 2)
+        j = ((m / s1.size) + (m / s2.size) + ((m - t) / m)) / 3.0;
+        return j < THRESHOLD ? j : j + [0.1, 1.0 / max.size].min * prefix * (1 - j)
+      end
+    end
+  end
+end

data/lib/mizuho/generator.rb

@@ -1,9 +1,27 @@
-require 'optparse'
-require 'digest/sha1'
+# Copyright (c) 2008-2012 Hongli Lai
+#
+# 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.
+
+require 'nokogiri'
 require 'mizuho'
-require 'mizuho/parser'
-require 'mizuho/template'
 require 'mizuho/source_highlight'
+require 'mizuho/id_map'
 
 module Mizuho
 
@@ -12,24 +30,52 @@ end
 
 class Generator
 	def initialize(input, options = {})
-		@input_file = input
-		@output_name = options[:output]
-		@template = locate_template_file(options[:template])
-		@multi_page = options[:multi_page]
-		@icons_dir = options[:icons_dir]
-		@conf_file = options[:conf_file]
+		@options     = options
+		@input_file  = input
+		@output_file = options[:output] || default_output_filename(input)
+		@id_map_file = options[:id_map] || default_id_map_filename(input)
+		@icons_dir   = options[:icons_dir]
+		@conf_file   = options[:conf_file]
+		@enable_topbar     = options[:topbar]
+		@commenting_system = options[:commenting_system]
+		if @commenting_system == 'juvia'
+			require_options(options, :juvia_url, :juvia_site_key)
+		end
 	end
 	
 	def start
-		output_filename = determine_output_filename(@input_file, @output_name)
-		self.class.run_asciidoc(@input_file, output_filename, @icons_dir, @conf_file)
-		if @template
-			apply_template(output_filename, @input_file, @output_name, @template, @multi_page)
+		if @commenting_system
+			@id_map = IdMap.new
+			if File.exist?(@id_map_file)
+				@id_map.load(@id_map_file)
+			else
+				warn "No ID map file, generating one (#{@id_map_file})..."
+			end
+		end
+		self.class.run_asciidoc(@input_file, @output_file, @icons_dir, @conf_file)
+		transform(@output_file)
+		if @commenting_system
+			@id_map.save(@id_map_file)
+			stats = @id_map.stats
+			if stats[:fuzzy] > 0
+				warn "Warning: #{stats[:fuzzy]} fuzzy ID(s)"
+			end
+			if stats[:orphaned] > 0
+				warn "Warning: #{stats[:orphaned]} unused ID(s)"
+			end
 		end
 	end
 	
 	def self.run_asciidoc(input, output, icons_dir = nil, conf_file = nil)
-		args = ["python", ASCIIDOC, "-a", "toc", "-a", "icons"]
+		args = [
+			"python", ASCIIDOC,
+			"-b", "html5",
+			"-a", "toc",
+			"-a", "theme=flask",
+			"-a", "toclevels=3",
+			"-a", "icons",
+			"-n"
+		]
 		if icons_dir
 			args << "-a"
 			args << "iconsdir=#{icons_dir}"
@@ -41,93 +87,149 @@ class Generator
 				args << cf
 			end
 		end
-		args += ["-n", "-o", output, input]
+		args += ["-o", output, input]
 		if !system(*args)
 			raise GenerationError, "Asciidoc failed."
 		end
 	end
 
 private
-	def locate_template_file(template_name)
-		if template_name.nil?
-			return "#{SOURCE_ROOT}/templates/asciidoc.html.erb"
-		elsif template_name =~ %r{[/.]}
-			# Looks like a filename.
-			return template_name
-		else
-			return "#{SOURCE_ROOT}/templates/#{template_name}.html.erb"
-		end
+	def default_output_filename(input)
+		return File.dirname(input) +
+			"/" +
+			File.basename(input, File.extname(input)) +
+			".html"
 	end
 	
-	def determine_output_filename(input, output = nil, chapter_id = nil)
-		if chapter_id
-			if output
-				dirname = File.dirname(output)
-				extname = File.extname(output)
-				basename = File.basename(output, extname)
-				filename = File.join(dirname, "#{basename}-#{chapter_id}#{extname}")
-			else
-				dirname = File.dirname(input)
-				basename = File.basename(input, File.extname(input))
-				filename = File.join(dirname, "#{basename}-#{chapter_id}.html")
+	def default_id_map_filename(input)
+		return File.dirname(input) +
+			"/" +
+			File.basename(input, File.extname(input)) +
+			".idmap.txt"
+	end
+	
+	def warn(message)
+		STDERR.puts(message)
+	end
+	
+	def transform(filename)
+		File.open(filename, 'r+') do |f|
+			doc = Nokogiri.HTML(f)
+			head = (doc / "head")[0]
+			body = (doc / "body")[0]
+			title = (doc / "title")[0].text
+			preamble = (doc / "#preamble")[0]
+			toctitle = (doc / "#toctitle")[0]
+			
+			head.add_child(stylesheet_tag)
+			
+			if @commenting_system
+				headers = (doc / "#content h2, #content h3, #content h4")
+				headers.each do |header|
+					header['data-comment-topic'] = @id_map.associate(header.text)
+					header.add_previous_sibling(create_comment_balloon)
+				end
 			end
-		else
-			if output
-				filename = output
-			else
-				dirname = File.dirname(input)
-				basename = File.basename(input, File.extname(input))
-				filename = File.join(dirname, "#{basename}.html")
+			
+			if @enable_topbar
+				body.children.first.add_previous_sibling(topbar(title))
+			end
+			body.add_child(javascript_tag)
+			
+			if preamble
+				preamble.remove
+				preamble_copy = (doc / "#header > h1")[0].add_next_sibling(preamble.to_s)[0]
+				preamble_copy['id'] = 'preamble'
 			end
+			
+			toctitle.add_previous_sibling(create_comment_balloon)
+			
+			f.rewind
+			f.truncate(0)
+			f.puts(doc.to_html)
 		end
-		return File.expand_path(filename)
 	end
 	
-	def apply_template(asciidoc_file, input_file, output_name, template_file, multi_page)
-		parser = Parser.new(asciidoc_file)
-		if multi_page
-			File.unlink(asciidoc_file)
-			assign_chapter_filenames_and_heading_basenames(parser.chapters, input_file, output_name)
-			parser.chapters.each_with_index do |chapter, i|
-				template = Template.new(template_file,
-					:multi_page? => true,
-					:title => parser.title,
-					:table_of_contents => parser.table_of_contents,
-					:contents => chapter.contents,
-					:is_preamble? => chapter.heading.nil?,
-					:chapters => parser.chapters,
-					:prev_chapter => (i <= 1) ? nil : parser.chapters[i - 1],
-					:current_chapter => chapter,
-					:next_chapter => parser.chapters[i + 1])
-				template.save(chapter.filename)
+	def stylesheet_tag
+		content = %Q{<style type="text/css">\n}
+		
+		css = File.read("#{TEMPLATES_DIR}/mizuho.css")
+		css.gsub!(/url\('(.*?)\.png'\)/) do
+			data = File.open("#{TEMPLATES_DIR}/#{$1}.png", "rb") do |f|
+				f.read
 			end
-		else
-			template = Template.new(template_file,
-				:multi_page? => false,
-				:title => parser.title,
-				:table_of_contents => parser.table_of_contents,
-				:contents => parser.contents)
-			template.save(asciidoc_file)
+			data = [data].pack('m')
+			data.gsub!("\n", "")
+			"url('data:image/png;base64,#{data}')"
 		end
-	rescue Template::Error => e
-		STDERR.puts("*** #{template_file}:\n#{e}")
-		exit 1
+		content << css << "\n"
+		
+		if @enable_topbar
+			content << File.read("#{TEMPLATES_DIR}/topbar.css") << "\n"
+		end
+		
+		if @commenting_system == 'disqus'
+			content << File.read("#{TEMPLATES_DIR}/disqus.css") << "\n"
+		elsif @commenting_system == 'intensedebate'
+			content << File.read("#{TEMPLATES_DIR}/intensedebate.css") << "\n"
+		end
+		
+		content << %Q{</style>\n}
+		return content
 	end
 	
-	def assign_chapter_filenames_and_heading_basenames(chapters, input_file, output_name)
-		chapters.each_with_index do |chapter, i|
-			if chapter.is_preamble?
-				chapter.filename = determine_output_filename(input_file, output_name)
-			else
-				title_sha1 = Digest::SHA1.hexdigest(chapter.title_without_numbers)
-				chapter.filename = determine_output_filename(input_file,
-					output_name, title_sha1.slice(0..7))
-				chapter.heading.basename = File.basename(chapter.filename)
-				chapter.heading.each_descendant do |h|
-					h.basename = File.basename(chapter.filename)
-				end
+	def topbar(title)
+		content = render_template("topbar.html")
+		content.gsub!(/\{TITLE\}/, title)
+		return content
+	end
+	
+	def javascript_tag
+		content = %Q{<script>}
+		content << File.read("#{TEMPLATES_DIR}/jquery-1.7.1.min.js") << "\n"
+		content << File.read("#{TEMPLATES_DIR}/jquery.hashchange-1.0.0.js") << "\n"
+		content << File.read("#{TEMPLATES_DIR}/mizuho.js") << "\n"
+		if @enable_topbar
+			content << File.read("#{TEMPLATES_DIR}/topbar.js") << "\n"
+		end
+		if @commenting_system == 'juvia'
+			content << %Q{
+				var JUVIA_URL = '#{@options[:juvia_url]}';
+				var JUVIA_SITE_KEY = '#{@options[:juvia_site_key]}';
+			}
+			content << File.read("#{TEMPLATES_DIR}/juvia.js") << "\n"
+		end
+		content << %Q{</script>}
+		return content
+	end
+	
+	def create_comment_balloon
+		return %Q{<a href="javascript:void(0)" class="comments empty" title="Add a comment"><span class="count"></span></a>}
+	end
+	
+	def render_template(name)
+		content = File.read("#{TEMPLATES_DIR}/#{name}")
+		content.gsub!(/\{INLINE_IMAGE:(.*?)\.png\}/) do
+			data = File.open("#{TEMPLATES_DIR}/#{$1}.png", "rb") do |f|
+				f.read
+			end
+			data = [data].pack('m')
+			data.gsub!("\n", "")
+			"data:image/png;base64,#{data}"
+		end
+		return content
+	end
+
+	def require_options(options, *required_keys)
+		fail = false
+		required_keys.each do |key|
+			if !options.has_key?(key)
+				fail = true
+				argument_name = '--' + key.to_s.gsub('_', '-')
+				STDERR.puts "You must also specify #{argument_name}!"
 			end
 		end
+		exit 1 if fail
 	end
 end