minor doc updates, use wrongdoc

Switch documentation over to wrongdoc, no more JavaScript!
Our documentation still sucks.

9 files changed, 52 insertions, 184 deletions

diff --git a/.document b/.document
index 5b24ce0..50ea20c 100644
--- a/.document
+++ b/.document
@@ -5,5 +5,6 @@ NEWS
 ChangeLog
 lib
 ext/sleepy_penguin/init.c
+ext/sleepy_penguin/epoll.c
 ext/sleepy_penguin/eventfd.c
 ext/sleepy_penguin/timerfd.c
diff --git a/.gitignore b/.gitignore
index 88d1bfe..77c63dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,4 @@ pkg/
 /man
 tags
 TAGS
+/LATEST
diff --git a/.wrongdoc.yml b/.wrongdoc.yml
new file mode 100644
index 0000000..2ac3b1d
--- /dev/null
+++ b/.wrongdoc.yml
@@ -0,0 +1,4 @@
+---
+cgit_url: http://git.bogomips.org/cgit/sleepy_penguin.git
+git_url: git://git.bogomips.org/sleepy_penguin.git
+rdoc_url: http://bogomips.org/sleepy_penguin/
diff --git a/GNUmakefile b/GNUmakefile
index 8e3bfe3..14595f1 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -3,7 +3,6 @@ all::
 RUBY = ruby
 RAKE = rake
 RSYNC = rsync
-GIT_URL = git://git.bogomips.org/sleepy_penguin.git
 
 GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
         @./GIT-VERSION-GEN
@@ -28,60 +27,27 @@ install:
 setup_rb_files := .config InstalledFiles
 prep_setup_rb := @-$(RM) $(setup_rb_files);$(MAKE) -C $(ext) clean
 
+extdir := ext/sleepy_penguin
 clean:
-        -$(MAKE) -C ext/sleepy_penguin clean
-        $(RM) $(setup_rb_files) ext/sleepy_penguin/Makefile
-
-pkg_extra := GIT-VERSION-FILE NEWS ChangeLog
-manifest: $(pkg_extra)
-        $(RM) .manifest
-        $(MAKE) .manifest
-
-.manifest:
-        (git ls-files && \
-         for i in $@ $(pkg_extra); \
-         do echo $$i; done) | LC_ALL=C sort > $@+
-        cmp $@+ $@ || mv $@+ $@
-        $(RM) $@+
+        -$(MAKE) -C $(extdir) clean
+        $(RM) $(setup_rb_files) $(extdir)/Makefile
 
-NEWS: GIT-VERSION-FILE
-        $(RAKE) -s news_rdoc > $@+
-        mv $@+ $@
-
-latest: NEWS
-        @awk 'BEGIN{RS="=== ";ORS=""}NR==2{sub(/\n$$/,"");print RS""$$0 }' $<
+pkg_extra := GIT-VERSION-FILE NEWS ChangeLog LATEST
+ChangeLog: GIT-VERSION-FILE .wrongdoc.yml
+        wrongdoc prepare
 
-SINCE =
-ChangeLog: LOG_VERSION = \
-  $(shell git rev-parse -q "$(GIT_VERSION)" >/dev/null 2>&1 && \
-          echo $(GIT_VERSION) || git describe)
-ifneq ($(SINCE),)
-ChangeLog: log_range = v$(SINCE)..$(LOG_VERSION)
-endif
-ChangeLog: GIT-VERSION-FILE
-        @echo "ChangeLog from $(GIT_URL) ($(log_range))" > $@+
-        @echo >> $@+
-        git log $(log_range) | sed -e 's/^/    /' >> $@+
-        mv $@+ $@
-
-news_atom := http://bogomips.org/sleepy_penguin/NEWS.atom.xml
-cgit_atom := http://git.bogomips.org/cgit/sleepy_penguin.git/atom/?h=master
-atom = <link rel="alternate" title="Atom feed" href="$(1)" \
-             type="application/atom+xml"/>
+.manifest: ChangeLog
+        (git ls-files && for i in $@ $(pkg_extra); do echo $$i; done) | \
+                LC_ALL=C sort > $@+
+        cmp $@+ $@ || mv $@+ $@
+        $(RM) $@+
 
-# using rdoc 2.5.x
-doc: .document NEWS ChangeLog
-        rdoc -t "$(shell sed -ne '1s/^= //p' README)"
+doc: .document .wrongdoc.yml
+        find lib ext -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/
-        $(RUBY) -i -p -e \
-          '$$_.gsub!("</title>",%q{\&$(call atom,$(cgit_atom))})' \
-          doc/ChangeLog.html
-        $(RUBY) -i -p -e \
-          '$$_.gsub!("</title>",%q{\&$(call atom,$(news_atom))})' \
-          doc/NEWS.html doc/README.html
-        $(RAKE) -s news_atom > doc/NEWS.atom.xml
-        cd doc && ln README.html tmp && mv tmp index.html
 
 ifneq ($(VERSION),)
 rfproject := rainbows
@@ -94,10 +60,10 @@ release_changes := release_changes-$(VERSION)
 release-notes: $(release_notes)
 release-changes: $(release_changes)
 $(release_changes):
-        $(RAKE) -s release_changes > $@+
+        wrongdoc release_changes > $@+
         $(VISUAL) $@+ && test -s $@+ && mv $@+ $@
 $(release_notes):
-        GIT_URL=$(GIT_URL) $(RAKE) -s release_notes > $@+
+        wrongdoc release_notes > $@+
         $(VISUAL) $@+ && test -s $@+ && mv $@+ $@
 
 # ensures we're actually on the tagged $(VERSION), only used for release
@@ -128,8 +94,8 @@ $(pkgtgz): manifest fix-perms
         @test -n "$(distdir)"
         $(RM) -r $(distdir)
         mkdir -p $(distdir)
-        tar c `cat .manifest` | (cd $(distdir) && tar x)
-        cd pkg && tar c $(basename $(@F)) | gzip -9 > $(@F)+
+        tar cf - `cat .manifest` | (cd $(distdir) && tar xf -)
+        cd pkg && tar cf - $(basename $(@F)) | gzip -9 > $(@F)+
         mv $@+ $@
 
 package: $(pkgtgz) $(pkggem)
@@ -139,7 +105,7 @@ release: verify package $(release_notes) $(release_changes)
         # make tgz release on RubyForge
         rubyforge add_release -f -n $(release_notes) -a $(release_changes) \
           $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz)
-        # push gem to Gemcutter
+        # push gem to RubyGems.org
         gem push $(pkggem)
         # in case of gem downloads from RubyForge releases page
         -rubyforge add_file \
@@ -151,12 +117,12 @@ gem install-gem: GIT-VERSION-FILE
         $(MAKE) $@ VERSION=$(GIT_VERSION)
 endif
 
-extdir := ext/sleepy_penguin
 ext := $(extdir)/sleepy_penguin_ext.$(DLEXT)
 $(extdir)/Makefile: $(extdir)/extconf.rb
         cd $(@D) && $(RUBY) extconf.rb
 
-$(ext): $(wildcard $(extdir)/*.c) $(wildcard $(extdir)/*.h) $(extdir)/Makefile
+c_files := $(wildcard $(extdir)/*.[ch] $(extdir)/*/*.h)
+$(ext): $(c_files) $(extdir)/Makefile
         $(MAKE) -C $(@D)
 
 all:: test
@@ -171,11 +137,9 @@ $(test_units): build
 # this requires GNU coreutils variants
 publish_doc:
         -git set-file-times
-        $(RM) -r doc ChangeLog NEWS
-        $(MAKE) doc LOG_VERSION=$(shell git tag -l | tail -1)
-        $(MAKE) -s latest > doc/LATEST
-        find doc/images doc/js -type f | \
-                TZ=UTC xargs touch -d '1970-01-01 00:00:00' doc/rdoc.css
+        $(MAKE) doc
+        find doc/images -type f | \
+                TZ=UTC xargs touch -d '1970-01-01 00:00:06' doc/rdoc.css
         $(MAKE) doc_gz
         chmod 644 $$(find doc -type f)
         $(RSYNC) -av doc/ bogomips.org:/srv/bogomips/sleepy_penguin/
@@ -185,8 +149,7 @@ publish_doc:
 # "gzip_static on" can serve the gzipped versions directly.
 doc_gz: docs = $(shell find doc -type f ! -regex '^.*\.\(gif\|jpg\|png\|gz\)$$')
 doc_gz:
-        touch doc/NEWS.atom.xml -d "$$(awk 'NR==1{print $$4,$$5,$$6}' NEWS)"
         for i in $(docs); do \
           gzip --rsyncable -9 < $$i > $$i.gz; touch -r $$i $$i.gz; done
 
-.PHONY: .FORCE-GIT-VERSION-FILE doc manifest man test $(test_units)
+.PHONY: .FORCE-GIT-VERSION-FILE doc manifest test $(test_units)
diff --git a/Rakefile b/Rakefile
index 3ac6130..017d3ec 100644
--- a/Rakefile
+++ b/Rakefile
@@ -1,106 +1,8 @@
 # -*- encoding: binary -*-
-# most tasks are in the GNUmakefile which offers better parallelism
-def tags
-  timefmt = '%Y-%m-%dT%H:%M:%SZ'
-  @tags ||= `git tag -l`.split(/\n/).map do |tag|
-    if %r{\Av[\d\.]+\z} =~ 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.strftime(timefmt),
-        :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 => body,
-      }
-    end
-  end.compact.sort { |a,b| b[:time] <=> a[:time] }
-end
-
 cgit_url = "http://git.bogomips.org/cgit/sleepy_penguin.git"
-git_url = ENV['GIT_URL'] || 'git://git.bogomips.org/sleepy_penguin.git'
-web_url = "http://bogomips.org/sleepy_penguin"
-
-desc 'prints news as an Atom feed'
-task :news_atom do
-  require 'nokogiri'
-  new_tags = tags[0,10]
-  puts(Nokogiri::XML::Builder.new do
-    feed :xmlns => "http://www.w3.org/2005/Atom" do
-      id! "#{web_url}NEWS.atom.xml"
-      title "sleepy_penguin news"
-      subtitle "epoll"
-      link! :rel => "alternate", :type => "text/html",
-            :href => "#{web_url}NEWS.html"
-      updated(new_tags.empty? ? "1970-01-01T00:00:00Z" : new_tags.first[:time])
-      new_tags.each do |tag|
-        entry do
-          title tag[:subject]
-          updated tag[:time]
-          published tag[:time]
-          author {
-            name tag[:tagger_name]
-            email tag[:tagger_email]
-          }
-          url = "#{cgit_url}/tag/?id=#{tag[:tag]}"
-          link! :rel => "alternate", :type => "text/html", :href =>url
-          id! url
-          message_only = tag[:body].split(/\n.+\(\d+\):\n {6}/s).first.strip
-          content({:type =>:text}, message_only)
-          content(:type =>:xhtml) { pre tag[:body] }
-        end
-      end
-    end
-  end.to_xml)
-end
-
-desc 'prints RDoc-formatted news'
-task :news_rdoc do
-  tags.each do |tag|
-    time = tag[:time].tr!('T', ' ').gsub!(/:\d\dZ/, ' UTC')
-    puts "=== #{tag[:tag].sub(/^v/, '')} / #{time}"
-    puts ""
-
-    body = tag[:body]
-    puts tag[:body].gsub(/^/sm, "  ").gsub(/[ \t]+$/sm, "")
-    puts ""
-  end
-end
-
-desc "print release changelog for Rubyforge"
-task :release_changes do
-  version = ENV['VERSION'] or abort "VERSION= needed"
-  version = "v#{version}"
-  vtags = tags.map { |tag| tag[:tag] =~ /\Av/ and tag[:tag] }.sort
-  prev = vtags[vtags.index(version) - 1]
-  if prev
-    system('git', 'diff', '--stat', prev, version) or abort $?
-    puts ""
-    system('git', 'log', "#{prev}..#{version}") or abort $?
-  else
-    system('git', 'log', version) or abort $?
-  end
-end
-
-desc "print release notes for Rubyforge"
-task :release_notes do
-  spec = Gem::Specification.load('sleepy_penguin.gemspec')
-  puts spec.description.strip
-  puts ""
-  puts "* #{spec.homepage}"
-  puts "* #{spec.email}"
-  puts "* #{git_url}"
-
-  _, _, body = `git cat-file tag v#{spec.version}`.split(/\n\n/, 3)
-  print "\nChanges:\n\n"
-  puts body
-end
+git_url = 'git://git.bogomips.org/sleepy_penguin.git'
 
-desc "read news article from STDIN and post to rubyforge"
+desc "post news article to rubyforge"
 task :publish_news do
   require 'rubyforge'
   spec = Gem::Specification.load('sleepy_penguin.gemspec')
diff --git a/ext/sleepy_penguin/epoll.c b/ext/sleepy_penguin/epoll.c
index 6db69d4..06788ec 100644
--- a/ext/sleepy_penguin/epoll.c
+++ b/ext/sleepy_penguin/epoll.c
@@ -375,6 +375,13 @@ static VALUE real_epwait(struct rb_epoll *ep)
 }
 #endif /* 1.8 Green thread compatibility code */
 
+/*
+ * Calls epoll_wait(2) and yields
+ *
+ * :call-seq:
+ *
+ *        epoll.wait(64, 1000) { |flags, obj| ... }
+ */
 static VALUE epwait(int argc, VALUE *argv, VALUE self)
 {
         VALUE timeout, maxevents;
@@ -529,7 +536,7 @@ void sleepy_penguin_init_epoll(void)
 {
         VALUE mSleepyPenguin, cEpoll;
 
-        mSleepyPenguin = rb_const_get(rb_cObject, rb_intern("SleepyPenguin"));
+        mSleepyPenguin = rb_define_module("SleepyPenguin");
         cEpoll = rb_define_class_under(mSleepyPenguin, "Epoll", rb_cObject);
         cEpoll_IO = rb_define_class_under(cEpoll, "IO", rb_cIO);
         rb_define_method(cEpoll, "initialize", init, -1);
diff --git a/ext/sleepy_penguin/eventfd.c b/ext/sleepy_penguin/eventfd.c
index e0a295c..1a2792b 100644
--- a/ext/sleepy_penguin/eventfd.c
+++ b/ext/sleepy_penguin/eventfd.c
@@ -156,7 +156,7 @@ void sleepy_penguin_init_eventfd(void)
 {
         VALUE mSleepyPenguin, cEventFD;
 
-        mSleepyPenguin = rb_const_get(rb_cObject, rb_intern("SleepyPenguin"));
+        mSleepyPenguin = rb_define_module("SleepyPenguin");
         cEventFD = rb_define_class_under(mSleepyPenguin, "EventFD", rb_cIO);
         rb_define_singleton_method(cEventFD, "new", create, -1);
 #ifdef EFD_NONBLOCK
diff --git a/ext/sleepy_penguin/timerfd.c b/ext/sleepy_penguin/timerfd.c
index 89ee774..ff717cf 100644
--- a/ext/sleepy_penguin/timerfd.c
+++ b/ext/sleepy_penguin/timerfd.c
@@ -107,7 +107,7 @@ void sleepy_penguin_init_timerfd(void)
 {
         VALUE mSleepyPenguin, cTimerFD;
 
-        mSleepyPenguin = rb_const_get(rb_cObject, rb_intern("SleepyPenguin"));
+        mSleepyPenguin = rb_define_module("SleepyPenguin");
         cTimerFD = rb_define_class_under(mSleepyPenguin, "TimerFD", rb_cIO);
         rb_define_singleton_method(cTimerFD, "create", create, -1);
         rb_define_singleton_method(cTimerFD, "new", create, -1);
diff --git a/sleepy_penguin.gemspec b/sleepy_penguin.gemspec
index 2fecd06..fee581e 100644
--- a/sleepy_penguin.gemspec
+++ b/sleepy_penguin.gemspec
@@ -1,36 +1,26 @@
 ENV["VERSION"] or abort "VERSION= must be specified"
 manifest = File.readlines('.manifest').map! { |x| x.chomp! }
-summary = File.readlines("README")[0].gsub(/\A=\s+\S+[^\w]+/, '').strip
-description = File.read("README").split(/\n\n/)[1].strip
+require 'wrongdoc'
+extend Wrongdoc::Gemspec
+name, summary, title = readme_metadata
 
 Gem::Specification.new do |s|
   s.name = %q{sleepy_penguin}
-  s.version = ENV["VERSION"]
-
+  s.version = ENV["VERSION"].dup
   s.homepage = 'http://bogomips.org/sleepy_penguin/'
-  s.authors = ["sleepy_penguin hackers"]
+  s.authors = ["#{name} hackers"]
   s.date = Time.now.utc.strftime('%Y-%m-%d')
   s.description = description
   s.email = %q{sleepy.penguin@librelist.com}
-
-  s.extra_rdoc_files = 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
-
+  s.extra_rdoc_files = extra_rdoc_files(manifest)
   s.files = manifest
-  s.rdoc_options = [ "-t", summary ]
+  s.rdoc_options = rdoc_options
   s.require_paths = %w(lib ext)
   s.rubyforge_project = %q{rainbows}
   s.summary = summary
   s.test_files = Dir['test/test_*.rb']
   s.extensions = %w(ext/sleepy_penguin/extconf.rb)
+  s.add_development_dependency('wrongdoc', '~> 1.3')
 
   # s.license = %w(LGPL) # disabled for compatibility with older RubyGems
 end