ron 0.1

data/COPYING

@@ -0,0 +1,21 @@
+       Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+
+Permission  is  hereby granted, free of charge, to any person ob-
+taining a copy of  this  software  and  associated  documentation
+files  (the "Software"), to deal in the Software without restric-
+tion, including without limitation the rights to use, copy, modi-
+fy, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is  fur-
+nished 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  NONIN-
+FRINGEMENT. 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.

data/README

@@ -0,0 +1,145 @@
+         ron -- the opposite of roff
+
+Ron is a humane text format and toolchain for
+creating UNIX man pages -- and things that
+appear as man pages from a distance. Use it
+to build and install standard UNIX roff man
+pages or to generate nicely formatted HTML
+manual pages for the web.
+
+The ron file format is based on Markdown. In
+fact, ron files are 100% Markdown compatible
+but have a more rigidly defined structure and
+extend Markdown in some ways to provide
+features commonly found in man pages (e.g.,
+definition lists). The ron(5) manual page
+included with this distribution defines the
+format in more detail.
+
+INSTALL
+-------
+
+The easiest way to install ron is with
+rubygems:
+
+    $ [sudo] gem install ron -s gems.gemcutter.org
+
+Or, clone the git repository and install from
+source:
+
+    $ git clone git://github.com/rtomayko/ron.git
+    $ cd ron
+    $ rake install
+
+EXAMPLES
+--------
+
+The .ron files located under the repository's
+./man directory show off a wide range of ron
+capabilities. The HTML versions of these
+files are available at:
+
+    http://rtomayko.github.com/ron/ron.1.html
+    http://rtomayko.github.com/ron/ron.5.html
+    http://rtomayko.github.com/ron/markdown.5.html
+
+BASIC USAGE
+-----------
+
+To generate a roff man page from the included
+markdown.5.ron file and open it in man(1):
+
+    $ ron -b man/markdown.5.ron
+    building: man/markdown.5
+    $ man man/markdown.5
+
+To generate a standalone HTML version:
+
+    $ ron -b --html man/markdown.5.ron
+    building: man/markdown.5.html
+    $ open man/markdown.5.html
+
+To build roff and HTML versions of all ron
+files:
+
+    $ ron -b --roff --html man/*.ron
+
+If you just want to view a ron file as if it
+were a man page without building any
+intermediate files:
+
+    $ ron -m man/markdown.5.ron
+
+The ron(1) manual page included with this
+distribution includes full documentation on
+ron command line options.
+
+RATIONALE
+---------
+
+Some people think UNIX manual pages are a
+poor and outdated form of documentation. I
+disagree.
+
+- Man pages typically follow a well defined
+  structure that's immediately familiar and
+  provides a useful starting point for
+  developers documenting new tools,
+  libraries, and formats.
+
+- Man pages get to the point. Because they're
+  written in an inverted style, with a
+  SYNOPSIS section followed by additional
+  detail, prose, and finally references to
+  other sources of information, man pages
+  provide the best of both cheat sheet and
+  reference style documentation.
+
+- Man pages have very limited text formatting
+  capabilities. This is a feature. You get
+  bold and underline, basically, and they're
+  typically applied consistently across man
+  pages.
+
+- Most man pages use only a single level of
+  section hierarchy (although two levels are
+  technically supported). Hierarchy destroys
+  otherwise good documentation by adding
+  unnecessary complexity. Feynman described
+  the whole of quantum electro dynamics with
+  only two levels of hierarchy. How can you
+  possibly need more? Man pages force you to
+  keep it simple.
+
+- Man pages have a simple referencing syntax;
+  e.g., sh(1), fork(2), markdown(5).  HTML
+  versions can use this to generate links
+  between pages.
+
+- The classical terminal man page display is
+  typographically well thought out. Big bold
+  section headings, justified monospaced
+  text, nicely indented paragraphs,
+  intelligently aligned definition lists, and
+  an informational header and footer.
+
+All that being said, trying to figure out how
+to create a man page can be a really tedious
+process. The roff/man macro languages are
+highly extensible, fractured between multiple
+dialects, and include a bunch of stuff that's
+entirely irrelevant to modern man page
+creation. It's also horribly ugly compared to
+today's humane text formats or even HTML
+(just sayin').
+
+Ron aims to address many of the issues with
+man page creation while preserving the things
+that makes man pages a great form of
+documentation.
+
+COPYRIGHT
+---------
+
+Ron is Copyright (C) 2009 Ryan Tomayko
+See the file COPYING for more information.

data/Rakefile

@@ -0,0 +1,73 @@
+require 'rake/clean'
+require 'rake/testtask'
+
+task :default => :test
+task :spec => :test
+
+# SPECS ===============================================================
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ['-rubygems'] if defined? Gem
+end
+
+# PACKAGING ============================================================
+
+require 'rubygems/specification'
+$spec = eval(File.read('ron.gemspec'))
+
+def package(ext='')
+  "pkg/ron-#{$spec.version}" + ext
+end
+
+desc 'Build packages'
+task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
+
+desc 'Build and install as local gem'
+task :install => package('.gem') do
+  sh "gem install #{package('.gem')}"
+end
+
+directory 'pkg/'
+CLOBBER.include('pkg')
+
+file package('.gem') => %w[pkg/ ron.gemspec] + $spec.files do |f|
+  sh "gem build ron.gemspec"
+  mv File.basename(f.name), f.name
+end
+
+file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
+  sh <<-SH
+    git archive --prefix=ron-#{source_version}/ --format=tar HEAD |
+    gzip > #{f.name}
+  SH
+end
+
+# Gemspec Helpers ====================================================
+
+def source_version
+  line = File.read('lib/ron.rb')[/^\s*VERSION = .*/]
+  line.match(/.*VERSION = '(.*)'/)[1]
+end
+
+file 'ron.gemspec' => FileList['{lib,test}/**','Rakefile'] do |f|
+  # read spec file and split out manifest section
+  spec = File.read(f.name)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+  # replace version and date
+  head.sub!(/\.version = '.*'/, ".version = '#{source_version}'")
+  head.sub!(/\.date = '.*'/, ".date = '#{Date.today.to_s}'")
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject{ |file| file =~ /^\./ }.
+    reject { |file| file =~ /^doc/ }.
+    map{ |file| "    #{file}" }.
+    join("\n")
+  # piece file back together and write...
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head,manifest,tail].join("  # = MANIFEST =\n")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "updated #{f.name}"
+end

data/bin/ron

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+## Usage: ron [ OPTIONS ] [ FILE ... ]
+##        ron --build FILE ...
+##        ron --install FILE ...
+##        ron --man FILE
+## Convert ron file to roff or html.
+##
+## Options
+##   -b, --build             write output to files instead of to stdout
+##   -i, --install           write manpage to MAN_HOME or system man path
+##   -m, --man               show man page like man(1)
+##
+##       --roff              generate roff/man text; this is the default behavior
+##   -5, --html              generate HTML
+##
+##       --help              show this help message
+##
+## See the ron(2)
+require 'optparse'
+
+formats = []
+build = false
+install = false
+man = false
+groff = "groff -Wall -mtty-char -mandoc -Tascii"
+pager = ENV['MANPAGER'] || ENV['PAGER'] || 'more'
+
+def info(message, *args)
+  STDERR.puts message % args
+end
+
+def usage
+  puts File.read(__FILE__).
+    grep(/^##.*/).
+    map { |line| line.chomp[3..-1] }.
+    join("\n")
+end
+
+# parse command line options
+ARGV.options do |option|
+  option.on("--roff") { formats << 'roff' }
+  option.on("-5", "--html") { formats << 'html' }
+  option.on("-b", "--build") { build = true }
+  option.on("-i", "--install") { install = true }
+  option.on("-m", "--man") { man = true }
+
+  option.on_tail("--help") { usage ; exit }
+  option.parse!
+end
+
+if ARGV.empty? && STDIN.tty?
+  usage
+  exit
+elsif ARGV.empty?
+  ARGV.push '-'
+end
+
+formats = ['roff'] if formats.empty?
+pid = nil
+
+require 'ron'
+wr = STDOUT
+ARGV.each do |file|
+  doc = Ron.new(file) { file == '-' ? STDIN.read : File.read(file) }
+
+  # setup the man pipeline if the --man option was specified
+  if man && !build
+    rd, wr = IO.pipe
+    if pid = fork
+      rd.close
+    else
+      wr.close
+      STDIN.reopen rd
+      exec "#{groff} | #{pager}"
+    end
+  end
+
+  # write output for each format
+  formats.each do |format|
+    output = doc.convert(format)
+    if build
+      path = doc.path(format)
+      info "building: #{path}"
+      File.open(path, 'wb') { |f| f.write(output) }
+    else
+      wr.write(output)
+    end
+  end
+
+  if pid
+    wr.close
+    Process.wait
+  end
+end

data/lib/ron.rb

@@ -0,0 +1,15 @@
+# Ron is a humane text format and toolchain for authoring manpages (and
+# things that appear as manpages from a distance). Use it to build /
+# install standard UNIX roff(7) formatted manpages or to generate
+# beautiful HTML manpages.
+module Ron
+  VERSION = '0.1'
+
+  require 'ron/document'
+  require 'ron/roff'
+
+  # Create a new Ron::Document for the given ron file.
+  def self.new(filename, &block)
+    Document.new(filename, &block)
+  end
+end

data/lib/ron/document.rb

@@ -0,0 +1,117 @@
+require 'nokogiri'
+require 'rdiscount'
+require 'ron/roff'
+
+module Ron
+  class Document
+    VERSION = '0.1'
+    attr_reader :filename, :data, :basename, :name, :section, :tagline
+
+    def initialize(filename, &block)
+      @filename = filename
+      @reader = block || Proc.new { |f| File.read(f) }
+      @data = @reader.call(filename)
+
+      @basename = File.basename(filename)
+      @name, @section =
+        if @basename =~ /(\w+)\.(\d\w*)\.ron/
+          [$1, $2]
+        else
+          [@basename[/\w+/], nil]
+        end
+    end
+
+    # Construct a path to a file near the input file.
+    def path(extension=nil)
+      extension = nil if ['', 'roff'].include?(extension.to_s)
+      name = "#{@name}.#{section}"
+      name = "#{name}.#{extension}" if extension
+      File.join(File.dirname(filename), name)
+    end
+
+    # Convert the document to :roff or :html
+    def convert(format)
+      send "to_#{format}"
+    end
+
+    # Convert the document to roff.
+    def to_roff
+      RoffFilter.new(
+        to_html_fragment,
+        name,
+        section,
+        tagline
+      ).to_s
+    end
+
+    # Convert the document to HTML and return result
+    # as a string.
+    def to_html
+      layout_filter(to_html_fragment)
+    end
+
+    # Convert the document to HTML and return result
+    # as a string. The HTML does not include <html>, <head>,
+    # or <style> tags.
+    def to_html_fragment
+      definition_list_filter(markdown_filter(data))
+    end
+
+    # Apply the standard HTML layout template.
+    def layout_filter(html)
+      template_file = File.dirname(__FILE__) + "/layout.html"
+      template = File.read(template_file)
+      eval("%Q{#{template}}", binding, template_file)
+    end
+
+    # Run markdown on the data and extract name, section, and
+    # tagline.
+    def markdown_filter(data)
+      html = Markdown.new(data).to_html
+      @tagline, html = html.split("</h1>\n", 2)
+      @tagline.sub!('<h1>', '')
+
+      # grab name and section from title
+      if @tagline =~ /([\w_:-]+)\((\d\w*)\) -- (.*)/
+        @name, @section = $1, $2
+        @tagline = $3
+      end
+
+      "<h2 id='NAME'>NAME</h2>\n" +
+      "<p><code>#{@name}</code> -- #{@tagline}</p>\n" +
+      html
+    end
+
+    # Convert special format unordered lists to definition lists.
+    def definition_list_filter(html)
+      doc = Nokogiri::HTML(html)
+
+      # process all unordered lists depth-first
+      doc.xpath('//ul').to_a.reverse.each do |ul|
+        items = ul.xpath('li')
+        next if items.any? { |item| item.text.split("\n", 2).first !~ /:$/ }
+
+        ul.name = 'dl'
+        items.each do |item|
+          if item.child.name == 'p'
+            wrap = '<p></p>'
+            container = item.child
+          else
+            wrap = '<dd></dd>'
+            container = item
+          end
+          term, definition = container.inner_html.split(":\n", 2)
+
+          dt = item.before("<dt>#{term}</dt>").previous_sibling
+          dt['class'] = 'flush' if dt.content.length <= 10
+
+          item.name = 'dd'
+          container.swap(wrap.sub(/></, ">#{definition}<"))
+        end
+      end
+
+      doc.css('html > body').inner_html
+    end
+
+  end
+end