ronn 0.4

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.md

@@ -0,0 +1,135 @@
+ronn -- the opposite of roff
+===========================
+
+## DESCRIPTION
+
+Ronn 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 Ronn file format is based on Markdown. In fact, Ronn files are a
+compatible subset of Markdown syntax but have a more rigid structure and
+extend Markdown in some ways to provide features commonly found in man
+pages (e.g., definition lists). The ronn(5) manual page defines the
+format in more detail.
+
+## DOCUMENTATION
+
+The `.ronn` files located under the `man/` directory show off a wide
+range of ronn capabilities and are the source of Ronn's own documentation.
+The source files and generated HTML / roff output files are available
+at:
+
+  * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html) -
+    build markdown based manual pages at the command line.  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1)
+
+  * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5.html) -
+    humane manual page authoring format syntax reference.  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5)
+
+  * [markdown(5)](http://rtomayko.github.com/ronn/markdown.5.html) -
+    humane text markup syntax (taken from
+    [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax),
+    John Gruber)  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/markdown.5.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/markdown.5)
+
+## INSTALL
+
+Install with Rubygems:
+
+    $ [sudo] gem install ronn
+    $ ronn --help
+
+Or, clone the git repository:
+
+    $ git clone git://github.com/rtomayko/ronn.git
+    $ PATH=ronn/bin:$PATH
+    $ ronn --help
+
+## BASIC USAGE
+
+To generate a roff man page from the included
+[`markdown.5.ronn`](man/markdown.5.ronn) file and open it with man(1):
+
+    $ ronn -b man/markdown.5.ronn
+    building: man/markdown.5
+    $ man man/markdown.5
+
+To generate a standalone HTML version:
+
+    $ ronn -b --html man/markdown.5.ronn
+    building: man/markdown.5.html
+    $ open man/markdown.5.html
+
+To build roff and HTML versions of all ronn files:
+
+    $ ronn -b --roff --html man/*.ronn
+
+If you just want to view a ronn file as if it were a man page without
+building intermediate files:
+
+    $ ronn -m man/markdown.5.ronn
+
+The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html) manual page
+includes comprehensive documentation on `ronn` command line options.
+
+## ABOUT
+
+Some people think UNIX manual pages are a poor and outdated style of
+documentation. I disagree:
+
+- Man pages 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 references to other sources of information, man pages
+  provide the best of both cheat sheet and reference style
+  documentation.
+
+- Man pages have extremely -- unbelievably -- limited text
+  formatting capabilities. You get a couple of headings, lists, bold,
+  underline and no more. This is a feature.
+
+- Although two levels of section hierarchy are technically
+  supported, most man pages use only a single level. Unwieldy
+  document hierarchies complicate otherwise good documentation.
+  Feynman covered all of physics -- heavenly bodies through QED --
+  with only two levels of document hierarchy (_The Feynman Lectures
+  on Physics_, 1970).
+
+- 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 monospace text,
+  nicely indented paragraphs, intelligently aligned definition
+  lists, and an informational header and footer.
+
+Unfortunately, trying to figure out how to create a man page is a
+fairly tedious process. The roff/man macro languages are highly
+extensible, fractured between multiple dialects, and include a bunch
+of device specific stuff that's entirely irrelevant to modern
+publishing tools.
+
+Ronn aims to address many of the issues with man page creation while
+preserving the things that makes man pages a great form of
+documentation.
+
+## COPYING
+
+Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
+See the file COPYING for information of licensing and distribution.
+
+## SEE ALSO
+
+[ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html),
+[ronn(5)](http://rtomayko.github.com/ronn/ronn.5.html),
+[markdown(5)](http://rtomayko.github.com/ronn/markdown.5.html)

data/Rakefile

@@ -0,0 +1,114 @@
+require 'rake/clean'
+
+task :default => :test
+
+ROOTDIR = File.expand_path('..', __FILE__).sub(/#{Dir.pwd}(?=\/)/, '.')
+LIBDIR  = "#{ROOTDIR}/lib"
+BINDIR  = "#{ROOTDIR}/bin"
+
+task :environment do
+  $LOAD_PATH.unshift ROOTDIR if !$:.include?(ROOTDIR)
+  $LOAD_PATH.unshift LIBDIR if !$:.include?(LIBDIR)
+  require_library 'hpricot'
+  require_library 'rdiscount'
+  ENV['RUBYLIB'] = $LOAD_PATH.join(':')
+  ENV['PATH'] = "#{BINDIR}:#{ENV['PATH']}"
+end
+
+desc 'Run tests'
+task :test => :environment do
+  require_library 'contest'
+  Dir['test/*_test.rb'].each { |test| require test }
+end
+
+desc 'Build the manual'
+task :man => :environment do
+  sh "ronn -br5 --manual='Ronn Manual' --organization='Ryan Tomayko' man/*.ronn"
+end
+
+# PACKAGING ============================================================
+
+if defined?(Gem)
+  $spec = eval(File.read('ronn.gemspec'))
+
+  def package(ext='')
+    "pkg/ronn-#{$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/ ronn.gemspec] + $spec.files do |f|
+    sh "gem build ronn.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file 'pkg/ron-0.4.gem' => %w[pkg/ ron.gemspec] do |f|
+    sh "gem build ron.gemspec"
+    mv 'ron-0.4.gem', f.name
+  end
+  task :package => 'pkg/ron-0.4.gem'
+
+  file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
+    sh <<-SH
+      git archive --prefix=ronn-#{source_version}/ --format=tar HEAD |
+      gzip > #{f.name}
+    SH
+  end
+end
+
+def source_version
+  line = File.read('lib/ronn.rb')[/^\s*VERSION = .*/]
+  line.match(/.*VERSION = '(.*)'/)[1]
+end
+
+file 'ronn.gemspec' => FileList['{lib,test,bin}/**','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
+
+# Misc ===============================================================
+
+def require_library(name)
+  require name
+rescue LoadError => boom
+  if !defined?(Gem)
+    warn "warn: #{boom}. trying again with rubygems."
+    require 'rubygems'
+    retry
+  end
+  abort "fatal: the '#{name}' library is required (gem install #{name})"
+end
+
+# make .wrong test files right
+task :right do
+  Dir['test/*.wrong'].each do |file|
+    dest = file.sub(/\.wrong$/, '')
+    mv file, dest
+  end
+end

data/bin/ron

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+exec File.dirname(__FILE__) + '/ronn', *ARGV

data/bin/ronn

@@ -0,0 +1,147 @@
+#!/usr/bin/env ruby
+## Usage: ronn [ OPTIONS ] [ FILE ]
+##        ronn --build FILE ...
+##        ronn --install FILE ...
+##        ronn --man FILE ...
+## Convert ronn FILE to roff man page or HTML and write to standard
+## output. With no FILE, ronn reads from standard input. The build,
+## install, and man forms accept multiple FILE arguments.
+##
+## Modes:
+##       --pipe                write to standard output (default behavior)
+##   -b, --build               write to files instead of standard output
+##   -i, --install             write to file in MAN_HOME or system man path
+##   -m, --man                 open man page like man(1)
+##
+## Formats:
+##   -r, --roff                generate roff/man text; this is the default behavior
+##   -5, --html                generate entire HTML page with layout
+##   -f, --fragment            generate HTML fragment instead of entire HTML page
+##
+## Document attributes:
+##       --date=DATE           published date in YYYY-MM-DD format;
+##                             displayed bottom-center in footer
+##       --manual=NAME         name of the manual this document belongs to;
+##                             displayed top-center in header
+##       --organization=NAME   publishing group, organization, or individual;
+##                             displayed bottom-left in footer
+##
+##       --help                show this help message
+##
+require 'date'
+require 'optparse'
+
+formats = []
+options = {}
+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.readlines(__FILE__).
+    grep(/^##.*/).
+    map { |line| line.chomp[3..-1] }.
+    join("\n")
+end
+
+# parse command line options
+ARGV.options do |option|
+  # modes
+  option.on("--pipe") { }
+  option.on("-b", "--build") { build = true }
+  option.on("-i", "--install") { install = true }
+  option.on("-m", "--man") { man = true }
+
+  # format options
+  option.on("-r", "--roff") { formats << 'roff' }
+  option.on("-5", "--html") { formats << 'html' }
+  option.on("-f", "--fragment") { formats << 'html_fragment' }
+
+  # manual attribute options
+  [:name, :section, :manual, :organization, :date].each do |option_attr|
+    option.on("--#{option_attr}=VALUE") { |val| options[option_attr] = val }
+  end
+
+  option.on_tail("--help") { usage ; exit }
+  option.parse!
+end
+
+if ARGV.empty? && STDIN.tty?
+  usage
+  exit
+elsif ARGV.empty?
+  ARGV.push '-'
+end
+
+# turn the --date arg into a real date object
+options[:date] &&= Date.strptime(options[:date], '%Y-%m-%d')
+
+formats = ['roff'] if formats.empty?
+formats.delete('html') if formats.include?('html_fragment')
+pid = nil
+
+begin
+  require 'hpricot'
+  require 'rdiscount'
+rescue LoadError
+  if !defined?(Gem)
+    warn "warn: #{$!.to_s}. trying again with rubygems."
+    require 'rubygems'
+    retry
+  end
+end
+
+begin
+  require 'ronn'
+rescue LoadError
+  raise if $!.to_s !~ /ronn/
+  libdir = File.expand_path("../../lib", __FILE__).sub(/^#{Dir.pwd}/, '.')
+  if !$:.include?(libdir)
+    warn "warn: #{$!.to_s}. trying again with #{libdir} on load path."
+    $:.unshift libdir
+    retry
+  end
+  raise
+end
+
+wr = STDOUT
+ARGV.each do |file|
+  doc = Ronn.new(file, options) { 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|
+    if build
+      path = doc.path_for(format)
+      info "building: #{path}" if build
+      output = doc.convert(format)
+      File.open(path, 'wb') { |f| f.puts(output) }
+      system "man #{path}" if man && format == 'roff'
+    else
+      output = doc.convert(format)
+      wr.puts(output)
+    end
+  end
+
+  if pid
+    wr.close
+    Process.wait
+  end
+end

data/lib/ronn.rb

@@ -0,0 +1,16 @@
+# Ronn 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 Ronn
+  VERSION = '0.4'
+
+  require 'ronn/document'
+  require 'ronn/roff'
+
+  # Create a new Ronn::Document for the given ronn file. See
+  # Ronn::Document.new for usage information.
+  def self.new(filename, attributes={}, &block)
+    Document.new(filename, attributes, &block)
+  end
+end

data/lib/ronn/document.rb

@@ -0,0 +1,288 @@
+require 'set'
+require 'hpricot'
+require 'rdiscount'
+require 'ronn/roff'
+
+module Ronn
+  # The Document class can be used to load and inspect a ronn document
+  # and to convert a ronn document into other formats, like roff or
+  # HTML.
+  #
+  # Ronn files may optionally follow the naming convention:
+  # "<name>.<section>.ronn". The <name> and <section> are used in
+  # generated documentation unless overridden by the information
+  # extracted from the document's name section.
+  class Document
+    attr_reader :path, :data
+
+    # The man pages name: usually a single word name of
+    # a program or filename; displayed along with the section in
+    # the left and right portions of the header as well as the bottom
+    # right section of the footer.
+    attr_accessor :name
+
+    # The man page's section: a string whose first character
+    # is numeric; displayed in parenthesis along with the name.
+    attr_accessor :section
+
+    # Single sentence description of the thing being described
+    # by this man page; displayed in the NAME section.
+    attr_accessor :tagline
+
+    # The manual this document belongs to; center displayed in
+    # the header.
+    attr_accessor :manual
+
+    # The name of the group, organization, or individual responsible
+    # for this document; displayed in the left portion of the footer.
+    attr_accessor :organization
+
+    # The date the document was published; center displayed in
+    # the document footer.
+    attr_accessor :date
+
+    # Create a Ronn::Document given a path or with the data returned by
+    # calling the block. The document is loaded and preprocessed before
+    # the intialize method returns. The attributes hash may contain values
+    # for any writeable attributes defined on this class.
+    def initialize(path=nil, attributes={}, &block)
+      @path = path
+      @basename = path.to_s =~ /^-?$/ ? nil : File.basename(path)
+      @reader = block || Proc.new { |f| File.read(f) }
+      @data = @reader.call(path)
+      @name, @section, @tagline = nil
+      @manual, @organization, @date = nil
+      @fragment = preprocess
+      attributes.each { |attr_name,value| send("#{attr_name}=", value) }
+    end
+
+    # Generate a file basename of the form "<name>.<section>.<type>"
+    # for the given file extension. Uses the name and section from
+    # the source file path but falls back on the name and section
+    # defined in the document.
+    def basename(type=nil)
+      type = nil if ['', 'roff'].include?(type.to_s)
+      [path_name || @name, path_section || @section, type].
+      compact.join('.')
+    end
+
+    # Construct a path for a file near the source file. Uses the
+    # Document#basename method to generate the basename part and
+    # appends it to the dirname of the source document.
+    def path_for(type=nil)
+      if @basename
+        File.join(File.dirname(path), basename(type))
+      else
+        basename(type)
+      end
+    end
+
+    # Returns the <name> part of the path, or nil when no path is
+    # available. This is used as the manual page name when the
+    # file contents do not include a name section.
+    def path_name
+      @basename[/^[^.]+/] if @basename
+    end
+
+    # Returns the <section> part of the path, or nil when
+    # no path is available.
+    def path_section
+      $1 if @basename.to_s =~ /\.(\d\w*)\./
+    end
+
+    # Returns the manual page name based first on the document's
+    # contents and then on the path name.
+    def name
+      @name || path_name
+    end
+
+    # Truthful when the name was extracted from the name section
+    # of the document.
+    def name?
+      !name.nil?
+    end
+
+    # Returns the manual page section based first on the document's
+    # contents and then on the path name.
+    def section
+      @section || path_section
+    end
+
+    # True when the section number was extracted from the name
+    # section of the document.
+    def section?
+      !section.nil?
+    end
+
+    # The date the man page was published. If not set explicitly,
+    # this is the file's modified time or, if no file is given,
+    # the current time.
+    def date
+      return @date if @date
+      return File.mtime(path) if File.exist?(path)
+      Time.now
+    end
+
+    # Convert the document to :roff, :html, or :html_fragment and
+    # return the result as a string.
+    def convert(format)
+      send "to_#{format}"
+    end
+
+    # Convert the document to roff and return the result as a string.
+    def to_roff
+      RoffFilter.new(
+        to_html_fragment,
+        name,
+        section,
+        tagline,
+        manual,
+        organization,
+        date
+      ).to_s
+    end
+
+    # Convert the document to HTML and return the result as a string.
+    def to_html
+      layout_filter(to_html_fragment)
+    end
+
+    # Convert the document to HTML and return the result
+    # as a string. The HTML does not include <html>, <head>,
+    # or <style> tags.
+    def to_html_fragment
+      buf = []
+      if name? && section?
+        buf << "<h2 id='NAME'>NAME</h2>"
+        buf << "<p><code>#{name}</code> -- #{tagline}</p>"
+      elsif tagline
+        buf << "<h1>#{[name, tagline].compact.join(' -- ')}</h1>"
+      end
+      buf << @fragment.to_s
+      buf.join("\n")
+    end
+
+  protected
+    # Parse the document and extract the name, section, and tagline
+    # from its contents. This is called while the object is being
+    # initialized.
+    def preprocess
+      [
+        :angle_quote_pre_filter,
+        :markdown_filter,
+        :angle_quote_post_filter,
+        :definition_list_filter
+      ].inject(data) { |res,filter| send(filter, res) }
+    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
+
+    # Convert special format unordered lists to definition lists.
+    def definition_list_filter(html)
+      doc = parse_html(html)
+      # process all unordered lists depth-first
+      doc.search('ul').to_a.reverse.each do |ul|
+        items = ul.search('li')
+        next if items.any? { |item| item.inner_text.split("\n", 2).first !~ /:$/ }
+
+        ul.name = 'dl'
+        items.each do |item|
+          if child = item.at('p')
+            wrap = '<p></p>'
+            container = child
+          else
+            wrap = '<dd></dd>'
+            container = item
+          end
+          term, definition = container.inner_html.split(":\n", 2)
+
+          dt = item.before("<dt>#{term}</dt>").first
+          dt.attributes['class'] = 'flush' if dt.inner_text.length <= 7
+
+          item.name = 'dd'
+          container.swap(wrap.sub(/></, ">#{definition}<"))
+        end
+      end
+      doc
+    end
+
+    # Perform angle quote (<THESE>) post filtering.
+    def angle_quote_post_filter(html)
+      doc = parse_html(html)
+      # convert all angle quote vars nested in code blocks
+      # back to the original text
+      doc.search('code').search('text()').each do |node|
+        next unless node.to_html.include?('var&gt;')
+        new =
+          node.to_html.
+            gsub('&lt;var&gt;', '&lt;').
+            gsub("&lt;/var&gt;", '>')
+        node.swap(new)
+      end
+      doc
+    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)
+      if html.nil?
+        html = @tagline
+        @tagline = nil
+      else
+        # grab name and section from title
+        @tagline.sub!('<h1>', '')
+        if @tagline =~ /([\w_.\[\]~+=@:-]+)\s*\((\d\w*)\)\s*--?\s*(.*)/
+          @name = $1
+          @section = $2
+          @tagline = $3
+        elsif @tagline =~ /([\w_.\[\]~+=@:-]+)\s+--\s+(.*)/
+          @name = $1
+          @tagline = $2
+        end
+      end
+
+      html.to_s
+    end
+
+    # Convert all <WORD> to <var>WORD</var> but only if WORD
+    # isn't an HTML tag.
+    def angle_quote_pre_filter(data)
+      data.gsub(/\<([^:.\/]+?)\>/) do |match|
+        contents = $1
+        tag, attrs = contents.split(' ', 2)
+        if attrs =~ /\/=/ ||
+           HTML.include?(tag.sub(/^\//, '')) ||
+           data.include?("</#{tag}>")
+          match.to_s
+        else
+          "<var>#{contents}</var>"
+        end
+      end
+    end
+
+    HTML = %w[
+      a abbr acronym b bdo big br cite code dfn
+      em i img input kbd label q samp select
+      small span strong sub sup textarea tt var
+      address blockquote div dl fieldset form
+      h1 h2 h3 h4 h5 h6 hr noscript ol p pre
+      table ul
+    ].to_set
+
+  private
+    def parse_html(html)
+      if html.respond_to?(:doc?) && html.doc?
+        html
+      else
+        Hpricot(html.to_s)
+      end
+    end
+  end
+end