olddoc 1.0.0

data/Documentation/.gitignore

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

data/Documentation/GNUmakefile

@@ -0,0 +1,53 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+all::
+
+INSTALL = install
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+pandoc_html = $(pandoc) --toc -t html --no-wrap
+
+
+man1 := olddoc.1
+man5 := olddoc.5
+man7 :=
+
+html1 := $(addsuffix .html, $(man1))
+html5 := $(addsuffix .html, $(man5))
+html7 := $(addsuffix .html, $(man7))
+
+all:: man
+
+man: $(man1) $(man5) $(man7)
+html: $(html1) $(html5) $(html7)
+
+prefix ?= $(HOME)
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man5dir = $(mandir)/man5
+man7dir = $(mandir)/man7
+
+gem-man: man
+	$(INSTALL) -d -m 755 ../man
+	test -z "$(man1)" || $(INSTALL) -m 644 $(man1) ../man
+	test -z "$(man5)" || $(INSTALL) -m 644 $(man5) ../man
+	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) ../man
+
+install-man: man
+	$(INSTALL) -d -m 755 $(DESTDIR)$(mandir)
+	test -z "$(man1)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+	test -z "$(man5)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+	test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
+	test -z "$(man1)" || $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+	test -z "$(man5)" || $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
+	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
+
+%: %.txt
+	$(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+%.html : %.txt
+	$(pandoc_html) < $< > $@+ && mv $@+ $@
+
+clean::
+	$(RM) $(man1) $(man5) $(man7) $(html1) $(html5) $(html7)

data/Documentation/olddoc.1.txt

@@ -0,0 +1,21 @@
+% olddoc(1) olddoc user manual
+
+# NAME
+
+olddoc - old-fashioned RDoc HTML generator
+
+# SYNOPSIS
+
+`olddoc` prepare
+
+`rdoc` -f oldweb
+
+# DESCRIPTION
+
+olddoc features oldweb, and old-fashioned RDoc HTML generator.
+You can also use "olddoc prepare" to generate NEWS files from
+git tags.
+
+# SEE ALSO
+
+olddoc(5)

data/Documentation/olddoc.5.txt

@@ -0,0 +1,26 @@
+% olddoc(1) olddoc user manual
+
+# NAME
+
+.olddoc.yml - olddoc config file format
+
+# SYNOPSIS
+
+A YAML file in the top-level project directory named ".olddoc.yml"
+
+# DESCRIPTION
+
+As olddoc 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
+
+olddoc(1)

data/GNUmakefile

@@ -0,0 +1,59 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+all::
+pkg = olddoc
+RUBY = ruby
+VERSION := $(shell $(RUBY) -Ilib -rolddoc -e 'puts Olddoc::VERSION')
+
+check-warnings:
+	@(for i in $$(git ls-files '*.rb'| grep -v '^setup\.rb$$'); \
+	  do $(RUBY) -d -W2 -c $$i; done) | grep -v '^Syntax OK$$' || :
+
+pkggem := pkg/$(pkg)-$(VERSION).gem
+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-man:
+	$(MAKE) -C Documentation/ gem-man
+
+pkg_extra := NEWS
+
+.manifest: fix-perms
+	$(RUBY) -I lib bin/olddoc prepare
+	rm -rf man
+	(git ls-files; \
+	 for i in $(pkg_extra); do echo $$i; done) | \
+	 LC_ALL=C sort > $@+
+	cmp $@+ $@ || mv $@+ $@; rm -f $@+
+
+placeholders := olddoc_5 olddoc_1
+
+$(placeholders):
+	echo olddoc_placeholder > $@
+
+.gem-manifest: .manifest gem-man $(placeholders)
+	(ls man/*.?; cat .manifest) | LC_ALL=C sort > $@+
+	cmp $@+ $@ || mv $@+ $@; rm -f $@+
+
+doc: $(placeholders)
+	$(MAKE) -C Documentation html
+	rm -rf doc
+	olddoc prepare
+	rdoc --debug -f oldweb
+	olddoc merge
+	ln NEWS.atom.xml doc/
+
+gem: $(pkggem)
+
+install-gem: $(pkggem)
+	gem install $(CURDIR)/$<
+
+$(pkggem): fix-perms .gem-manifest
+	VERSION=$(VERSION) gem build $(pkg).gemspec
+	mkdir -p pkg
+	mv $(@F) $@
+
+package: $(pkggem)
+
+.PHONY: all .FORCE-GIT-VERSION-FILE NEWS
+.PHONY: check-warnings fix-perms doc

data/INSTALL

@@ -0,0 +1,9 @@
+= olddoc installation
+
+olddoc requires Ruby 1.9.3 (or later) and rdoc 4.2 or later to install.
+Once you have Ruby installed, installation via RubyGems should take care
+of the dependency for you:
+
+	gem install olddoc
+
+See README for usage instructions.

data/README

@@ -0,0 +1,89 @@
+= olddoc - old-fashioned Ruby documentation generator
+
+olddoc contains old-fashioned document generators for those who do not
+wish to impose bloated, new-fangled web cruft on their readers.
+
+olddoc contains oldweb, an HTML generator without any images, frames,
+CSS, or JavaScript.  It is designed for users of text-based browsers
+and/or low-bandwidth connections.  oldweb focuses on text as it is
+the lowest common denominator for accessibility and compatibility
+with people and hardware.
+
+== Reasons
+
+* No CSS.  Encouraging users to use CSS leads to problems like
+  copy-paste hijacking: http://thejh.net/misc/website-terminal-copy-paste
+  External CSS also increases page load time as it often blocks page
+  rendering.  Asynchronous loading of CSS also causes accessibility
+  problems as links/buttons may move as a user attempts to click.
+
+* No JavaScript.  There is a constant barrage of security and
+  client-side performance problems associated with it.  It's also
+  unreasonable to expect users to rely on LibreJS and inspect every
+  piece of JS they run.
+
+* No frames.  Frames are an accessibility hassle and unfriendly
+  to users of tiny screens on mobile devices and text-based browsers.
+
+* No images.  Not everyone can view or afford bandwidth to load images.
+  This also reduces the potential for security vulnerabilities as less
+  code gets run.  Furthermore, loading the wrong image in a public
+  place can get you arrested (or worse).
+
+Encourage readers to simplify and speed up their browsing experience.
+They can disable CSS, JavaScript, and images in their browser without
+missing out!
+
+== Usage
+
+	gem install olddoc
+	cd $ANY_RDOC_USING_RUBY_PROJECT
+	rdoc -f oldweb
+
+You can also use olddoc to generate NEWS entries
+assuming you have git tags, a README file and .olddoc.yml
+
+	olddoc prepare
+
+And "olddoc merge" to merge instances of "olddoc_placeholder" in
+an HTML file with HTML fragments generated with other tools
+such as pandoc(1).  This requries an appropriately configured
+.olddoc.yml with a "merge_html" section see olddoc(5)
+
+== Source code
+
+	git clone git://80x24.org/olddoc
+
+Please use git-format-patch(1) and git-send-email(1) distributed with
+the git(7) suite for generating and sending patches.  Please format
+pull requests with the git-request-pull(1) script (also distributed
+with git(7)) and send them via email to <olddoc-public@80x24.org>
+
+== Contact
+
+All feedback (comments, results, feature requests, bug reports, patches,
+pull-requests) via plain-text mail to the mailing list is very much
+appreciated.
+
+Please send plain-text mail to the list at <olddoc-public@80x24.org>
+HTML will not be read.  olddoc is for GUI-phobes, by GUI-phobes.
+Mailing list archives available at http://80x24.org/olddoc-public/
+No subscription is necessary to post to the mailing list.
+
+== License
+
+olddoc is copyrighted Free Software by all contributors, see logs
+in revision control for names and email addresses of all of them.
+
+olddoc 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 of the License, or (at your
+option) any later version.
+
+olddoc 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 General Public License along
+with this program; if not, see https://www.gnu.org/licenses/gpl-3.0.txt

data/Rakefile

@@ -0,0 +1,31 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'tempfile'
+include Rake::DSL
+task :rsync_docs do
+  dest = ENV["RSYNC_DEST"] || "80x24.org:/srv/80x24/olddoc/"
+  top = %w(INSTALL README COPYING)
+
+  # git-set-file-times is distributed with rsync,
+  # Also available at: http://yhbt.net/git-set-file-times
+  # on Debian systems: /usr/share/doc/rsync/scripts/git-set-file-times.gz
+  sh("git", "set-file-times", 'Documentation', *top)
+
+  do_gzip = lambda do |txt|
+    gz = "#{txt}.gz"
+    tmp = "#{gz}.#$$"
+    sh("gzip --rsyncable -9 < #{txt} > #{tmp}")
+    st = File.stat(txt)
+    File.utime(st.atime, st.mtime, tmp) # make nginx gzip_static happy
+    File.rename(tmp, gz)
+    gz
+  end
+
+  files = `git ls-files Documentation/*.txt`.split(/\n/)
+  files.concat(top)
+  files.concat(%w(NEWS))
+  files.concat(Dir["doc/*.html"].to_a)
+  gzfiles = files.map { |txt| do_gzip.call(txt) }
+  files.concat(gzfiles)
+  sh("rsync --chmod=Fugo=r -av #{files.join(' ')} #{dest}")
+end

data/TODO

@@ -0,0 +1 @@
+* manpage generator

data/bin/olddoc

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+$stderr.sync = $stdout.sync = true
+tasks = %w(prepare merge)
+usage = "Usage: #{File.basename($0)} [#{tasks.join('|')}]"
+require 'olddoc'
+opts = Olddoc.config
+case ARGV[0]
+when "prepare"
+  Olddoc::Prepare.new(opts).run
+when "merge"
+  Olddoc::Merge.new(opts).run
+else
+  warn "#{$0.inspect} #{ARGV.inspect} not understood"
+  abort usage
+end

data/lib/olddoc.rb

@@ -0,0 +1,20 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+module Olddoc
+  VERSION = '1.0.0'
+
+  autoload :Gemspec, 'olddoc/gemspec'
+  autoload :History, 'olddoc/history'
+  autoload :Merge, 'olddoc/merge'
+  autoload :NewsAtom, 'olddoc/news_atom'
+  autoload :NewsRdoc, 'olddoc/news_rdoc'
+  autoload :Prepare, 'olddoc/prepare'
+  autoload :Readme, 'olddoc/readme'
+
+  def self.config(path = ".olddoc.yml")
+    File.readable?(path) and return YAML.load(File.read(path))
+    warn "#{path} not found in current directory"
+    {}
+  end
+end
+require_relative 'oldweb'

data/lib/olddoc/gemspec.rb

@@ -0,0 +1,17 @@
+# helper methods for gemspecs
+module Olddoc::Gemspec
+  include Olddoc::Readme
+
+  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/olddoc/history.rb

@@ -0,0 +1,57 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'uri'
+
+module Olddoc::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
+
+  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
+        type = `git cat-file -t #{tag}`.chomp
+        user_type = { "tag" => "tagger", "commit" => "committer" }[type]
+        user_type or abort "unable to determine what to do with #{type}=#{tag}"
+        header, subject, body = `git cat-file #{type} #{tag}`.split(/\n\n/, 3)
+        body ||= "initial" unless old_summaries.include?(tag)
+        header = header.split(/\n/)
+
+        tagger = header.grep(/\A#{user_type} /).first
+        time = Time.at(tagger.split(/ /)[-2].to_i).utc
+        {
+          :time => time.strftime(timefmt),
+          :ruby_time => time,
+          :tagger_name => %r{^#{user_type} ([^<]+)}.match(tagger)[1].strip,
+          :tagger_email => %r{<([^>]+)>}.match(tagger)[1].strip,
+          :id => `git rev-parse refs/tags/#{tag}`.chomp!,
+          :tag => tag,
+          :subject => subject.strip,
+          :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/olddoc/merge.rb

@@ -0,0 +1,26 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+class Olddoc::Merge
+  def initialize(opts)
+    @merge_html = opts["merge_html"] || {}
+  end
+
+  # FIXME: generate manpages directly from rdoc instead of relying on
+  # pandoc to do it via markdown.
+  def run
+    @merge_html.each do |file, source|
+      rdoc_html = "doc/#{file}.html"
+      fragment = File.read(source)
+      File.open(rdoc_html, "a+") { |fp|
+        html = fp.read
+        if html.sub!(%r{\s*<p>\s*olddoc_placeholder\s*</p>\s*}sm, fragment)
+          fp.truncate(0)
+          fp.write(html)
+        else
+          warn "olddoc_placeholder not found in #{rdoc_html}"
+        end
+      }
+    end
+  end
+end