wrongdoc 1.0.0

data/Documentation/.gitignore

@@ -0,0 +1,4 @@
+*.html_fragment
+*.1
+*.5
+*.html

data/Documentation/GNUmakefile

@@ -0,0 +1,32 @@
+all::
+
+RONN = ronn
+ronn_man = $(RONN) -r
+ronn_html = $(RONN) -f
+
+man1 := $(addsuffix .1,wrongdoc)
+html1 := $(addsuffix .html_fragment,$(man1))
+man5 := $(addsuffix .5,dotwrongdoc)
+html5 := $(addsuffix .html_fragment,$(man5))
+man := $(man1) $(man5)
+html := $(html1) $(html5)
+
+all:: html man
+
+html: $(html)
+man: $(man)
+	mkdir -p ../man/man1 ../man/man5
+	install -m 644 $(man1) ../man/man1
+	install -m 644 $(man5) ../man/man5
+
+%.1: %.1.ronn
+	$(ronn_man) $<
+%.5: %.5.ronn
+	$(ronn_man) $<
+%.1.html_fragment: %.1.ronn
+	$(ronn_html) $<
+%.5.html_fragment: %.5.ronn
+	$(ronn_html) $<
+
+clean::
+	$(RM) $(man) $(html)

data/Documentation/dotwrongdoc.5.ronn

@@ -0,0 +1,23 @@
+dotwrongdoc(5) -- wrongdoc config file format
+=============================================
+
+## SYNOPSIS
+
+A YAML file in the top-level project directory named ".wrongdoc.yml"
+
+## DESCRIPTION
+
+As wrongdoc favors consistency over configuration, there is minimal
+configuration to deal with.
+
+## KEYS
+
+`rdoc_url`, `cgit_url` should be obvious
+
+`merge_html` is a key-value mapping of (empty) RDoc source files to an
+HTML file that will be merged into RDoc after-the-fact.  It is useful
+for merging non-RDoc generated HTML into the project.
+
+## SEE ALSO
+
+wrongdoc(1)

data/Documentation/wrongdoc.1.ronn

@@ -0,0 +1,17 @@
+wrongdoc(1) -- removes JavaScript from RDoc
+===========================================
+
+## SYNOPSIS
+`wrongdoc` prepare
+
+`wrongdoc`
+
+## DESCRIPTION
+
+**Wrongdoc** does horrible things to your RDoc project.  It's own
+documentation sucks, but it'll help to make your documentation
+JavaScript-free and therefore suck less :)
+
+## SEE ALSO
+
+dotwrongdoc(5)

data/GIT-VERSION-FILE

@@ -0,0 +1 @@
+GIT_VERSION = 1.0.0

data/GIT-VERSION-GEN

@@ -0,0 +1,40 @@
+#!/bin/sh
+
+GVF=GIT-VERSION-FILE
+DEF_VER=v1.0.0.GIT
+
+LF='
+'
+
+# First see if there is a version file (included in release tarballs),
+# then try git-describe, then default.
+if test -f version
+then
+	VN=$(cat version) || VN="$DEF_VER"
+elif test -d .git -o -f .git &&
+	VN=$(git describe --abbrev=4 HEAD 2>/dev/null) &&
+	case "$VN" in
+	*$LF*) (exit 1) ;;
+	v[0-9]*)
+		git update-index -q --refresh
+		test -z "$(git diff-index --name-only HEAD --)" ||
+		VN="$VN-dirty" ;;
+	esac
+then
+	VN=$(echo "$VN" | sed -e 's/-/./g');
+else
+	VN="$DEF_VER"
+fi
+
+VN=$(expr "$VN" : v*'\(.*\)')
+
+if test -r $GVF
+then
+	VC=$(sed -e 's/^GIT_VERSION = //' <$GVF)
+else
+	VC=unset
+fi
+test "$VN" = "$VC" || {
+	echo >&2 "GIT_VERSION = $VN"
+	echo "GIT_VERSION = $VN" >$GVF
+}

data/GNUmakefile

@@ -0,0 +1,114 @@
+# use GNU Make to run tests in parallel, and without depending on RubyGems
+all::
+MRI = ruby
+RUBY = ruby
+RAKE = rake
+RSYNC = rsync
+WRONGDOC := $(RUBY) -I lib bin/wrongdoc
+
+GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
+	@./GIT-VERSION-GEN
+-include GIT-VERSION-FILE
+-include local.mk
+
+man1_paths := $(addprefix man/man1/, wrongdoc.1)
+man5_paths := $(addprefix man/man5/, dotwrongdoc.5)
+manpages := $(man1_paths) $(man5_paths)
+
+clean:
+	-$(MAKE) -C Documentation clean
+
+man html:
+	$(MAKE) -C Documentation $@
+
+$(manpages): man
+pkg_extra := GIT-VERSION-FILE ChangeLog LATEST NEWS $(manpages)
+
+ChangeLog: GIT-VERSION-FILE .wrongdoc.yml
+	$(WRONGDOC) prepare
+
+.manifest: ChangeLog
+	(git ls-files && for i in $@ $(pkg_extra); do echo $$i; done) | \
+	  LC_ALL=C sort > $@+
+	mv $@+ $@
+
+doc: .document .wrongdoc.yml man html
+	find bin lib -type f -name '*.rbc' -exec rm -f '{}' ';'
+	$(RM) -r doc
+	$(WRONGDOC) all
+	install -m644 COPYING doc/COPYING
+	install -m644 $(shell grep '^[A-Z]' .document) doc/
+	tar cf - man | (cd doc && tar xf -)
+
+publish_doc:
+	-git set-file-times
+	$(MAKE) doc
+	-find doc/images -type f | \
+		TZ=UTC xargs touch -d '1970-01-01 00:00:01' doc/rdoc.css
+	chmod 644 $$(find doc -type f)
+	$(RSYNC) -av doc/ bogomips.org:/srv/bogomips/wrongdoc/
+	git ls-files | xargs touch
+
+ifneq ($(VERSION),)
+rfproject := rainbows
+rfpackage := wrongdoc
+pkggem := pkg/$(rfpackage)-$(VERSION).gem
+pkgtgz := pkg/$(rfpackage)-$(VERSION).tgz
+release_notes := release_notes-$(VERSION)
+release_changes := release_changes-$(VERSION)
+
+release-notes: $(release_notes)
+release-changes: $(release_changes)
+$(release_changes):
+	$(WRONGDOC) release_changes > $@+
+	$(VISUAL) $@+ && test -s $@+ && mv $@+ $@
+$(release_notes):
+	$(WRONGDOC) release_notes > $@+
+	$(VISUAL) $@+ && test -s $@+ && mv $@+ $@
+
+# ensures we're actually on the tagged $(VERSION), only used for release
+verify:
+	test x"$(shell umask)" = x0022
+	git rev-parse --verify refs/tags/v$(VERSION)^{}
+	git diff-index --quiet HEAD^0
+	test `git rev-parse --verify HEAD^0` = \
+	     `git rev-parse --verify refs/tags/v$(VERSION)^{}`
+
+fix-perms:
+	-git ls-tree -r HEAD | awk '/^100644 / {print $$NF}' | xargs chmod 644
+	-git ls-tree -r HEAD | awk '/^100755 / {print $$NF}' | xargs chmod 755
+
+gem: $(pkggem)
+
+install-gem: $(pkggem)
+	gem install $(CURDIR)/$<
+
+$(pkggem): .manifest fix-perms
+	gem build $(rfpackage).gemspec
+	mkdir -p pkg
+	mv $(@F) $@
+
+$(pkgtgz): distdir = $(basename $@)
+$(pkgtgz): HEAD = v$(VERSION)
+$(pkgtgz): .manifest fix-perms
+	@test -n "$(distdir)"
+	$(RM) -r $(distdir)
+	mkdir -p $(distdir)
+	tar cf - `cat .manifest` | (cd $(distdir) && tar xf -)
+	cd pkg && tar cf - $(basename $(@F)) | gzip -9 > $(@F)+
+	mv $@+ $@
+
+package: $(pkgtgz) $(pkggem)
+
+release: verify package $(release_notes) $(release_changes)
+	rubyforge add_release -f -n $(release_notes) -a $(release_changes) \
+	  $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz)
+	gem push $(pkggem)
+	-rubyforge add_file \
+	  $(rfproject) $(rfpackage) $(VERSION) $(pkggem)
+else
+gem install-gem: GIT-VERSION-FILE
+	$(MAKE) $@ VERSION=$(GIT_VERSION)
+endif
+
+.PHONY: .FORCE-GIT-VERSION-FILE doc manifest man test

data/LATEST

@@ -0,0 +1,4 @@
+=== wrongdoc 1.0.0 - initial release / 
+
+  Welcome to hell
+

data/LICENSE

@@ -0,0 +1,17 @@
+wrongdoc is copyrighted Free Software by all contributors, see logs in
+revision control for names and email addresses of all of them.
+
+This library is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version
+{3}[http://www.gnu.org/licenses/gpl-3.0.txt] of the License, or (at
+your option) any later version.
+
+wrongdoc is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
+License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with wrongdoc; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301

data/NEWS

@@ -0,0 +1,4 @@
+=== wrongdoc 1.0.0 - initial release / 2010-12-24 01:07 UTC
+
+  Welcome to hell
+

data/README

@@ -0,0 +1,40 @@
+= wrongdoc - RDoc done right (IMNSHO)
+
+wrongdoc mangles an existing RDoc directory and makes any changes we
+feel like.  It mainly removes JavaScript from Darkfish and adds links to
+a {cgit}[http://hjemli.net/git/cgit/] instance.  It is a bikeshed
+project and *entirely* subject to the whims of its creator, so it is
+likely the wrong solution for anybody else.
+
+wrongdoc is tightly integrated with git and cgit, and capable of of
+automatically generating NEWS and ChangeLog files in RDoc format based
+on git history and tags.
+
+== Usage
+
+First, prepare a .wrongdoc.yml in the top-level directory of your project,
+then run the following command to generate your RDoc:
+
+    $ wrongdoc
+
+== Future Plans
+
+* Remove images/icons from Darkfish without breaking text alignment.
+
+* Optimize for small screens at the expense of large ones.
+
+* gitweb support (preserving cgit support)
+
+* ASCII-art unicorns and rainbows! (maybe)
+
+== Feedback
+
+It's Free Software, fork it and hack it to your heart's content, just
+do not expect the original author(s) to support anything they disagree
+with.  Remember, this is a bikeshed project!
+
+Help with CSS for removing image/icon cruft and making better use of
+small screen real-estate would be greatly appreciated.
+
+The original authors may be contacted through the mailing list:
+{wrongdoc@librelist.org}[mailto:wrongdoc@librelist.org].

data/bin/wrongdoc

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+usage = "Usage: #{File.basename($0)} [prepare]"
+$stderr.sync = $stdout.sync = true
+require 'wrongdoc'
+opts = Wrongdoc.config
+case ARGV[0]
+when "prepare"
+  Wrongdoc::Prepare.new(opts).run
+when "release_notes"
+  Wrongdoc::Release.notes($stdout, opts)
+when "release_changes"
+  Wrongdoc::Release.changes($stdout)
+when "all"
+  Wrongdoc::Prepare.new(opts).run
+  Wrongdoc::Rdoc.new(opts).run
+  Wrongdoc::Merge.new(opts).run
+  Wrongdoc::Final.new(opts, ARGV[1]).run
+else
+  abort "#{$0.inspect} #{ARGV.inspect} not understood"
+end

data/lib/wrongdoc/changelog.rb

@@ -0,0 +1,25 @@
+# helper method for generating the ChangeLog in RDoc format atomically
+module Wrongdoc::Changelog
+  include Wrongdoc::History
+
+  def changelog
+    fp = Tempfile.new('ChangeLog', '.')
+    fp.write "ChangeLog from #@cgit_uri"
+    cmd = %w(git log)
+    if @changelog_start && tags[0]
+      range = "#@changelog_start..#{tags[0][:tag]}"
+      fp.write(" (#{range})")
+      cmd << range
+    end
+    fp.write("\n\n")
+    prefix = "   "
+    IO.popen(cmd.join(' ')) do |io|
+      io.each { |line|
+        fp.write prefix
+        fp.write line
+      }
+    end
+    File.rename(fp.path, 'ChangeLog')
+    fp.close!
+  end
+end

data/lib/wrongdoc/final.rb

@@ -0,0 +1,105 @@
+require 'find'
+require 'fileutils'
+
+class Wrongdoc::Final
+  include Wrongdoc::ParseXML
+  include Wrongdoc::NewsAtom
+
+  def run
+    Find.find('doc') { |path| /\.html\z/ =~ path and fix(path) }
+    FileUtils.rm_rf('doc/js')
+    news_atom
+  end
+
+  def initialize(opts, git_tag = nil)
+    @cgit_uri = URI.parse(opts[:cgit_url])
+    @rdoc_uri = URI.parse(opts[:rdoc_url])
+    @git_tag = git_tag
+  end
+
+  # returns a cgit URI for the given +path+ and +lineno+
+  def path_uri(path, lineno)
+    uri = @cgit_uri.dup
+    uri.path += "/tree/#{URI.escape(path)}"
+    uri.fragment = "n#{lineno}"
+    uri.query = "id=#{URI.escape(@git_tag)}" if @git_tag
+    uri
+  end
+
+  # delete all the stuff that offends us
+  def killkillkill!(doc)
+    unlink = proc { |node| node.unlink }
+
+    # JavaScript is dangerous
+    doc.search("script").each(&unlink)
+
+    # if your project's big enough to need JS search, it's too bloated
+    doc.search('span.search-toggle').each(&unlink)
+    doc.search('form').each(&unlink)
+
+    # remove W3C validator link, we use tidy instead
+    doc.search('div#validator-badges p').each { |x|
+      /Validate/i =~ x.content and x.unlink
+    }
+  end
+
+  # since we killed off JavaScript, viewing source isn't possible with
+  # RDoc anymore, so link people to the web source viewer
+  def source_linkify!(doc)
+    doc.search('div.method-detail').each { |mdetail|
+      path = lineno = nil
+      mdetail.search('div.method-source-code').each { |src|
+        src.search('span.ruby-comment').each { |x|
+          if x.content =~ /File\s+(\S+),\s+line\s+(\d+)/s
+            path, lineno = $1, $2
+          end
+        }
+        src.unlink if path && lineno
+      }
+      if path && lineno
+        mdetail.search('span.method-click-advice').each { |x|
+          x.content = ''
+          a = Nokogiri::XML::Node.new('a', doc)
+          a['href'] = path_uri(path, lineno).to_s
+          a.content = 'view method source'
+          x.add_child(a)
+        }
+      end
+    }
+  end
+
+  # Don't give the original Darkfish a bad name, and advertise ourselves :)
+  def advertise!(doc)
+    doc.search('div#validator-badges p small').each { |x|
+      if /\AGenerated/ =~ x.content
+        first = x.children.first
+        first.content = first.content.gsub /\AG/, "Originally g"
+        last = x.children.last
+        last.content = "#{last.content}, modified by "
+
+        a = Nokogiri::XML::Node.new('a', doc)
+        a["href"] = "http://bogomips.org/wrongdoc/"
+        a.content = "wrongdoc"
+        last.add_next_sibling(a)
+      end
+    }
+  end
+
+  def fix(file)
+    File.open(file, "a+") do |fp|
+      buf = process(fp.read)
+      fp.truncate 0
+      fp.write buf
+    end
+  end
+
+  # the main entry point, this does all the require processing on any
+  # given String buffer.
+  def process(str)
+    doc = parse_xml(str)
+    killkillkill!(doc)
+    source_linkify!(doc)
+    advertise!(doc)
+    doc.to_xhtml(:indent => 0)
+  end
+end

data/lib/wrongdoc/gemspec.rb

@@ -0,0 +1,18 @@
+# helper methods for gemspecs
+module Wrongdoc::Gemspec
+  include Wrongdoc::Readme
+  include Wrongdoc::RdocOptions
+
+  def extra_rdoc_files(manifest)
+    File.readlines('.document').map! do |x|
+      x.chomp!
+      if File.directory?(x)
+        manifest.grep(%r{\A#{x}/})
+      elsif File.file?(x)
+        x
+      else
+        nil
+      end
+    end.flatten.compact
+  end
+end

data/lib/wrongdoc/history.rb

@@ -0,0 +1,50 @@
+module Wrongdoc::History
+  def initialize_history
+    @tags = @old_summaries = nil
+  end
+
+  # returns a cgit URI for a given +tag_name+
+  def tag_uri(tag_name)
+    uri = @cgit_uri.dup
+    uri.path = "/tag/"
+    uri.query = "id=#{tag_name}"
+    uri
+  end
+
+  # TODO: investigate Ruby git libraries
+  def tags
+    timefmt = '%Y-%m-%dT%H:%M:%SZ'
+    @tags ||= `git tag -l`.split(/\n/).map do |tag|
+      next if tag == "v0.0.0"
+      if %r{\Av[\d\.]+} =~ tag
+        header, subject, body = `git cat-file tag #{tag}`.split(/\n\n/, 3)
+        header = header.split(/\n/)
+        tagger = header.grep(/\Atagger /).first
+        body ||= "initial"
+        time = Time.at(tagger.split(/ /)[-2].to_i).utc
+        {
+          :time => time.strftime(timefmt),
+          :ruby_time => time,
+          :tagger_name => %r{^tagger ([^<]+)}.match(tagger)[1].strip,
+          :tagger_email => %r{<([^>]+)>}.match(tagger)[1].strip,
+          :id => `git rev-parse refs/tags/#{tag}`.chomp!,
+          :tag => tag,
+          :subject => subject,
+          :body => (old = old_summaries[tag]) ? "#{old}\n#{body}" : body,
+        }
+      end
+    end.compact.sort { |a,b| b[:time] <=> a[:time] }
+  end
+
+  def old_summaries
+    @old_summaries ||= if File.exist?(".CHANGELOG.old")
+      File.readlines(".CHANGELOG.old").inject({}) do |hash, line|
+        version, summary = line.split(/ - /, 2)
+        hash[version] = summary
+        hash
+      end
+    else
+      {}
+    end
+  end
+end

data/lib/wrongdoc/merge.rb

@@ -0,0 +1,20 @@
+class Wrongdoc::Merge
+  include Wrongdoc::ParseXML
+
+  def initialize(opts)
+    @merge_html = opts[:merge_html]
+  end
+
+  def run
+    @merge_html.each do |file, source|
+      rdoc_html = "doc/#{file}.html"
+      src = Nokogiri::XML(File.read(source))
+      File.open(rdoc_html, "a+") { |fp|
+        doc = parse_xml(fp.read)
+        doc.search("div#documentation")[0].add_child(src.root)
+        fp.truncate 0
+        fp.write doc.to_xhtml
+      }
+    end
+  end
+end

data/lib/wrongdoc/news_atom.rb

@@ -0,0 +1,46 @@
+module Wrongdoc::NewsAtom
+  include Wrongdoc::History
+  include Wrongdoc::Readme
+
+  # generates an Atom feed based on git tags in the document directory
+  def news_atom
+    project_name, short_desc, _ = x = readme_metadata
+    new_tags = tags[0,10]
+    atom_uri = @rdoc_uri.dup
+    atom_uri.path += "NEWS.atom.xml"
+    news_uri = @rdoc_uri.dup
+    news_uri.path += "NEWS.html"
+    doc = Nokogiri::XML::Builder.new {
+      feed :xmlns => "http://www.w3.org/2005/Atom" do
+        id! atom_uri.to_s
+        title "#{project_name} news"
+        subtitle short_desc
+        link! :rel => 'alternate', :type => 'text/html', :href => news_uri.to_s
+        updated new_tags.empty? ? '1970-01-01:00:00:00Z' : new_tags[0][:time]
+        new_tags.each do |tag|
+          entry {
+            title tag[:subject]
+            updated tag[:time]
+            published tag[:time]
+            author {
+              name tag[:tagger_name]
+              email tag[:tagger_email]
+            }
+            uri = tag_uri(tag[:tag]).to_s
+            link! :rel => "alternate", :type => "text/html", :href => uri
+            id! uri
+            message_only = tag[:body].split(/\n.+\(\d+\):\n {6}/s)[0].strip
+            content({:type =>:text}, message_only)
+            content(:type =>:xhtml) { pre tag[:body] }
+          }
+        end
+      end
+    }
+    fpath = "doc/NEWS.atom.xml"
+    File.open(fpath, "w") { |fp| fp.write doc.to_xml(:indent => 0) }
+    unless new_tags.empty?
+      time = new_tags[0][:ruby_time]
+      File.utime(time, time, fpath)
+    end
+  end
+end

data/lib/wrongdoc/news_rdoc.rb

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+module Wrongdoc::NewsRdoc
+  include Wrongdoc::History
+
+  def puts_tag(fp, tag)
+    time = tag[:time].tr!('T', ' ').gsub!(/:\d\dZ/, ' UTC')
+    fp.puts "=== #{tag[:subject]} / #{time}"
+    fp.puts ""
+
+    body = tag[:body]
+    fp.puts tag[:body].gsub(/^/smu, "  ").gsub(/[ \t]+$/smu, "")
+    fp.puts ""
+  end
+
+  # generates a NEWS file in the top-level directory based on git tags
+  def news_rdoc
+    news = Tempfile.new('NEWS', '.')
+    tags.each { |tag| puts_tag(news, tag) }
+    File.open("LATEST", "wb") { |latest|
+      if tags.empty?
+        latest.puts "Currently unreleased"
+        news.puts "No news yet."
+      else
+        puts_tag(latest, tags[0])
+      end
+    }
+    File.rename(news.path, 'NEWS')
+    news.close!
+  end
+end

data/lib/wrongdoc/parse_xml.rb

@@ -0,0 +1,11 @@
+module Wrongdoc::ParseXML
+  def parse_xml(str)
+    opts = {
+      :input_encoding => 'utf8',
+      :output_encoding => 'utf8',
+      :wrap => 0,
+      :tidy_mark => false,
+    }
+    Nokogiri::XML(TidyFFI::Tidy.new(str, opts).clean)
+  end
+end

data/lib/wrongdoc/prepare.rb

@@ -0,0 +1,17 @@
+class Wrongdoc::Prepare
+  include Wrongdoc::NewsRdoc
+  include Wrongdoc::Changelog
+  include Wrongdoc::Readme
+
+  def initialize(opts)
+    @rdoc_uri = URI.parse(opts[:rdoc_url])
+    @cgit_uri = URI.parse(opts[:cgit_url])
+    @changelog_start = opts[:changelog_start]
+    @name, @short_desc = readme_metadata
+  end
+
+  def run
+    news_rdoc
+    changelog
+  end
+end