ron 0.1 → 0.3

data/README.md

@@ -0,0 +1,133 @@
+ron -- the opposite of roff
+===========================
+
+## DESCRIPTION
+
+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 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 ron(5) manual page defines the
+format in more detail.
+
+## DOCUMENTATION
+
+The `.ron` files located under the `man/` directory show off a wide
+range of ron capabilities and are the source of Ron's own documentation.
+The source files and generated HTML / roff output files are available
+at:
+
+  * [ron(1)](http://rtomayko.github.com/ron/ron.1.html) -
+    build markdown based manual pages at the command line.  
+    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.1.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.1)
+
+  * [ron(5)](http://rtomayko.github.com/ron/ron.5.html) -
+    humane manual page authoring format syntax reference.  
+    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.5.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
+
+  * [markdown(5)](http://rtomayko.github.com/ron/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/ron/blob/master/man/ron.5.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
+
+## INSTALL
+
+Install with Rubygems:
+
+    $ [sudo] gem install ron
+    $ ron --help
+
+Or, clone the git repository:
+
+    $ git clone git://github.com/rtomayko/ron.git
+    $ PATH=ron/bin:$PATH
+    $ ron --help
+
+## BASIC USAGE
+
+To generate a roff man page from the included
+[`markdown.5.ron`](man/markdown.5.ron) file and open it with 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 intermediate files:
+
+    $ ron -m man/markdown.5.ron
+
+The [ron(1)](http://rtomayko.github.com/ron/ron.1.html) manual page
+includes comprehensive documentation on `ron` 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.
+
+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.
+
+## COPYING
+
+Ron is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
+See the file COPYING for information of licensing and distribution.
+
+## SEE ALSO
+
+ron(1), ron(5), markdown(5)

data/Rakefile

@@ -1,14 +1,27 @@
 require 'rake/clean'
-require 'rake/testtask'
 
 task :default => :test
-task :spec => :test
 
-# SPECS ===============================================================
+task :environment do
+  require_library 'nokogiri'
+  require_library 'rdiscount'
+  ENV['RUBYLIB'] = "#{$:.join(':')}:#{ENV['RUBYLIB']}"
+  ENV['PATH'] = "bin:#{ENV['PATH']}"
+end
+
+desc 'Run tests'
+task :test => :environment do
+  require_library 'contest'
+  if ENV['PATH'].split(':').any? { |p| File.executable?("#{p}/turn") }
+    sh 'turn -Ilib test/*_test.rb'
+  else
+    sh 'testrb Ilib test/*_test.rb'
+  end
+end
 
-Rake::TestTask.new(:test) do |t|
-  t.test_files = FileList['test/*_test.rb']
-  t.ruby_opts = ['-rubygems'] if defined? Gem
+desc 'Build the manual'
+task :man => :environment do
+  sh "ron -br5 --manual='Ron Manual' --organization='Ryan Tomayko' man/*.ron"
 end
 
 # PACKAGING ============================================================
@@ -71,3 +84,11 @@ file 'ron.gemspec' => FileList['{lib,test}/**','Rakefile'] do |f|
   File.open(f.name, 'w') { |io| io.write(spec) }
   puts "updated #{f.name}"
 end
+
+# Misc ===============================================================
+
+def require_library(name)
+  require name
+rescue LoadError => boom
+  abort "fatal: the '#{name}' library is required (gem install #{name})"
+end

data/bin/ron

@@ -1,24 +1,38 @@
 #!/usr/bin/env ruby
-## Usage: ron [ OPTIONS ] [ FILE ... ]
+## Usage: ron [ OPTIONS ] [ FILE ]
 ##        ron --build FILE ...
 ##        ron --install FILE ...
-##        ron --man FILE
-## Convert ron file to roff or html.
+##        ron --man FILE ...
+## Convert ron FILE to roff man page or HTML and write to standard
+## output. With no FILE, ron reads from standard input. The build,
+## install, and man forms accept multiple FILE arguments.
 ##
-## 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)
+## 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)
 ##
-##       --roff              generate roff/man text; this is the default behavior
-##   -5, --html              generate HTML
+## 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
 ##
-##       --help              show this help message
+## 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
 ##
-## See the ron(2)
+##       --help                show this help message
+##
+require 'date'
 require 'optparse'
 
 formats = []
+options = {}
 build = false
 install = false
 man = false
@@ -38,12 +52,22 @@ end
 
 # parse command line options
 ARGV.options do |option|
-  option.on("--roff") { formats << 'roff' }
-  option.on("-5", "--html") { formats << 'html' }
+  # 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
@@ -55,13 +79,23 @@ 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
 
-require 'ron'
+begin
+  require 'ron'
+rescue LoadError
+  $:.unshift File.dirname(__FILE__) + "../lib"
+  require 'ron'
+end
+
 wr = STDOUT
 ARGV.each do |file|
-  doc = Ron.new(file) { file == '-' ? STDIN.read : File.read(file) }
+  doc = Ron.new(file, options) { file == '-' ? STDIN.read : File.read(file) }
 
   # setup the man pipeline if the --man option was specified
   if man && !build
@@ -77,13 +111,15 @@ ARGV.each do |file|
 
   # 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) }
+      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
-      wr.write(output)
+      output = doc.convert(format)
+      wr.puts(output)
     end
   end
 

data/lib/ron/document.rb

@@ -1,60 +1,178 @@
+require 'set'
 require 'nokogiri'
 require 'rdiscount'
 require 'ron/roff'
 
 module Ron
+  # The Document class can be used to load and inspect a ron document
+  # and to convert a ron document into other formats, like roff or
+  # HTML.
+  #
+  # Ron files may optionally follow the naming convention:
+  # "<name>.<section>.ron". The <name> and <section> are used in
+  # generated documentation unless overridden by the information
+  # extracted from the document's name section.
   class Document
-    VERSION = '0.1'
-    attr_reader :filename, :data, :basename, :name, :section, :tagline
+    attr_reader :path, :data
 
-    def initialize(filename, &block)
-      @filename = filename
+    # 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 Ron::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(filename)
+      @data = @reader.call(path)
+      @name, @section, @tagline = nil
+      @manual, @organization, @date = nil
+      @fragment = preprocess
+      attributes.each { |attr_name,value| send("#{attr_name}=", value) }
+    end
 
-      @basename = File.basename(filename)
-      @name, @section =
-        if @basename =~ /(\w+)\.(\d\w*)\.ron/
-          [$1, $2]
-        else
-          [@basename[/\w+/], nil]
-        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
 
-    # 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)
+    # 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
 
-    # Convert the document to :roff or :html
+    # 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.
+    # Convert the document to roff and return the result as a string.
     def to_roff
       RoffFilter.new(
         to_html_fragment,
         name,
         section,
-        tagline
+        tagline,
+        manual,
+        organization,
+        date
       ).to_s
     end
 
-    # Convert the document to HTML and return result
-    # as a string.
+    # 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 result
+    # 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
-      definition_list_filter(markdown_filter(data))
+      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.
@@ -64,31 +182,12 @@ module Ron
       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)
-
+      doc = parse_html(html)
       # process all unordered lists depth-first
-      doc.xpath('//ul').to_a.reverse.each do |ul|
-        items = ul.xpath('li')
+      doc.search('ul').to_a.reverse.each do |ul|
+        items = ul.search('li')
         next if items.any? { |item| item.text.split("\n", 2).first !~ /:$/ }
 
         ul.name = 'dl'
@@ -103,15 +202,88 @@ module Ron
           term, definition = container.inner_html.split(":\n", 2)
 
           dt = item.before("<dt>#{term}</dt>").previous_sibling
-          dt['class'] = 'flush' if dt.content.length <= 10
+          dt['class'] = 'flush' if dt.content.length <= 7
 
           item.name = 'dd'
           container.swap(wrap.sub(/></, ">#{definition}<"))
         end
       end
+      doc
+    end
 
-      doc.css('html > body').inner_html
+    # 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 text()').each do |node|
+        next unless node.to_s.include?('var&gt;')
+        new = node.document.create_text_node(
+          node.to_s.
+            gsub('&lt;var&gt;', '<').
+            gsub("&lt;/var&gt;", '>')
+        )
+        node.replace(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.kind_of?(Nokogiri::HTML::DocumentFragment)
+        html
+      else
+        Nokogiri::HTML.fragment(html.to_s)
+      end
+    end
   end
 end