ron 0.1 → 0.2

data/README

@@ -1,4 +1,8 @@
-         ron -- the opposite of roff
+ron(7) -- the opposite of roff
+==============================
+
+DESCRIPTION
+-----------
 
 Ron is a humane text format and toolchain for
 creating UNIX man pages -- and things that
@@ -19,17 +23,17 @@ format in more detail.
 INSTALL
 -------
 
-The easiest way to install ron is with
-rubygems:
+Ron can be installed using rubygems:
 
-    $ [sudo] gem install ron -s gems.gemcutter.org
+    $ [sudo] gem install ron
 
 Or, clone the git repository and install from
 source:
 
     $ git clone git://github.com/rtomayko/ron.git
     $ cd ron
-    $ rake install
+    $ rake package
+    $ [sudo] rake install
 
 EXAMPLES
 --------
@@ -47,7 +51,7 @@ BASIC USAGE
 -----------
 
 To generate a roff man page from the included
-markdown.5.ron file and open it in man(1):
+`markdown.5.ron` file and open it in man(1):
 
     $ ron -b man/markdown.5.ron
     building: man/markdown.5

data/Rakefile

@@ -11,6 +11,13 @@ Rake::TestTask.new(:test) do |t|
   t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
+# DOCS =================================================================
+
+desc 'Build the manual'
+task 'man' do
+  sh "ron -br5 --manual='Ron Manual' --organization='Ryan Tomayko' man/*.ron"
+end
+
 # PACKAGING ============================================================
 
 require 'rubygems/specification'

data/bin/ron

@@ -1,24 +1,37 @@
 #!/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:
+##       --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
+##
+##       --help                show this help message
 ##
-## See the ron(2)
 require 'optparse'
 
 formats = []
+options = {}
 build = false
 install = false
 man = false
@@ -38,12 +51,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 +78,19 @@ elsif ARGV.empty?
   ARGV.push '-'
 end
 
+# turn the --date arg into
+if options[:date]
+  options[:date] = Date.strptime(options[:date], '%Y-%m-%d')
+end
+
 formats = ['roff'] if formats.empty?
+formats.delete('html') if formats.include?('html_fragment')
 pid = nil
 
 require 'ron'
 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
@@ -79,11 +108,11 @@ ARGV.each do |file|
   formats.each do |format|
     output = doc.convert(format)
     if build
-      path = doc.path(format)
+      path = doc.path_for(format)
       info "building: #{path}"
-      File.open(path, 'wb') { |f| f.write(output) }
+      File.open(path, 'wb') { |f| f.puts(output) }
     else
-      wr.write(output)
+      wr.puts(output)
     end
   end
 

data/lib/ron.rb

@@ -3,13 +3,14 @@
 # install standard UNIX roff(7) formatted manpages or to generate
 # beautiful HTML manpages.
 module Ron
-  VERSION = '0.1'
+  VERSION = '0.2'
 
   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)
+  # Create a new Ron::Document for the given ron file. See
+  # Ron::Document.new for usage information.
+  def self.new(filename, attributes={}, &block)
+    Document.new(filename, attributes, &block)
   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
+    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
+    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

data/lib/ron/layout.html

@@ -1,39 +1,70 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>#{name}(#{section}) -- #{tagline}</title>
+  <meta http-equiv='content-type' value='text/html;charset=utf8'>
+  <meta name='generator' value='Ron/v#{Ron::VERSION}'>
+  <title>#{name}(#{section})#{tagline ? " -- " + tagline : ''}</title>
   <style type='text/css'>
-    body {
+    body {margin:0}
+    #man, #man code, #man pre, #man tt, #man kbd, #man samp {
       font-family:consolas,monospace;
-      font-size:18px;
+      font-size:16px;
       line-height:1.25;
-      color:#111
-    }
-    #man { max-width:42em;text-align:justify;margin:25px }
-    #man h1, #man h2, #man h3, #man strong, #man code { color:#111 }
-    #man h1 { text-align:center }
-    #man h2 { font-size:20px;margin-bottom:0 }
-    #man h3 { font-size:18px;margin:0 0 0 50px }
-    #man p, #man ul, #man ol, #man dl, #man pre
-    { margin:0 0 24px 0; }
-    #man pre { color:#555;font-size:16px }
-    #man > p, #man > ul, #man > ol, #man > dl, #man > pre
-    { margin:0 0 24px 80px; }
-    #man dt { margin:0;clear:left }
-    #man dt.flush { float:left;width:105px }
-    #man dd { margin:0 0 0 105px }
-    #man code { font-weight:bold; }
-    #man pre code { font-weight:normal;color:#555 }
-    #man em { font-style:normal;text-decoration:underline }
+      color:#434241;
+      background:#fff; }
+    #man { max-width:85ex; text-align:justify; margin:0 25px 25px 25px }
+    #man h1, #man h2, #man h3 { color:#232221;clear:left }
+    #man h1 { font-size:28px; margin:10px 0 30px 0; text-align:center }
+    #man h2 { font-size:18px; margin-bottom:2px; margin-top:10px; line-height:1.2; }
+    #man h3 { font-size:16px; margin:0 0 0 4ex; }
+    #man p, #man ul, #man ol, #man dl, #man pre { margin:0 0 18px 0; }
+    #man pre {
+      color:#333231;
+      background:#edeceb;
+      padding:5px 10px;
+      border-left:2ex solid #ddd;
+      margin-top:-10px;
+      margin-bottom:12px; }
+    #man > p, #man > ul, #man > ol, #man > dl, #man > pre { margin-left:8ex; }
+    #man dt { margin:0; clear:left }
+    #man dt.flush { float:left; width:8ex }
+    #man dd { margin:0 0 0 9ex }
+    #man code, #man strong, #man b { font-weight:bold; color:#131211; }
+    #man pre code { font-weight:normal; color:#232221; background:inherit }
+    #man em, var, u {
+      font-style:normal; color:#333231; border-bottom:1px solid #999; }
+    #man h1.man-title { display:none; }
+    #man ol.man, #man ol.man li { margin:2px 0 10px 0; padding:0;
+      float:left; width:33%; list-style-type:none;
+      text-transform:uppercase; font-size:18px; color:#999;
+      letter-spacing:1px;}
+    #man ol.man { width:100%; }
+    #man ol.man li.tl { text-align:left }
+    #man ol.man li.tc { text-align:center;letter-spacing:4px }
+    #man ol.man li.tr { text-align:right }
+    #man ol.man a { color:#999 }
+    #man ol.man a:hover { color:#333231 }
   </style>
 </head>
 <body>
 <div id='man'>
 
-<h1>#{@name}(#{@section})</h1>
+<h1 class='man-title'>#{name}(#{section})</h1>
+
+<ol class='head man'>
+  <li class='tl'>#{name if section}#{"("+section+")" if name and section}</li>
+  <li class='tc'>#{manual}</li>
+  <li class='tr'>#{name if section}#{"("+section+")" if name and section}</li>
+</ol>
 
 #{html}
 
+<ol class='foot man'>
+  <li class='tl'>#{organization}</li>
+  <li class='tc'>#{date.strftime('%B %Y')}</li>
+  <li class='tr'>#{name if section}#{"("+section+")" if name and section}</li>
+</ol>
+
 </div>
 </body>
 </html>

data/lib/ron/roff.rb

@@ -16,9 +16,9 @@ module Ron
 
   protected
     def title_heading(name, section, tagline, manual, version, date)
-      comment "generated with Ron"
+      comment "generated with Ron/v#{Ron::VERSION}"
       comment "http://github.com/rtomayko/ron/"
-      macro "TH", %["#{escape(name.upcase)}" #{section} "#{date}" "#{version}" "#{manual}"]
+      macro "TH", %["#{escape(name.upcase)}" #{section} "#{date.strftime('%B %Y')}" "#{version}" "#{manual}"]
     end
 
     def block_filter(node)
@@ -74,6 +74,22 @@ module Ron
         end
         write "\n"
 
+      # ordered/unordered lists
+      # when 'ul'
+      #   # macro "IP", '\(bu'
+      #   block_filter(node.children)
+      # when 'ol'
+      #   macro "IP", '1.'
+      #   block_filter(node.children)
+      # when 'li'
+      #   macro "IP" unless prev.nil?
+      #   if node.search('p').any?
+      #     block_filter(node.children)
+      #   else
+      #     inline_filter(node.children)
+      #   end
+      #   write "\n"
+
       else
         warn "unrecognized block tag: %p", node.name
       end
@@ -85,14 +101,19 @@ module Ron
         return
       end
 
+      prev = node.previous_sibling
+      prev = prev.previous_sibling until prev.nil? || prev.element?
+
       case node.name
       when 'text'
-        write escape(node.to_s.sub(/\n+$/, ' '))
-      when 'code', 'b', 'strong'
+        text = node.content
+        text = text.sub(/^\n+/m, '') if prev && prev.name == 'br'
+        write escape(text.sub(/\n+$/, ' '))
+      when 'code', 'b', 'strong', 'kbd', 'samp'
         write '\fB'
         inline_filter(node.children)
         write '\fR'
-      when 'em', 'i', 'u'
+      when 'var', 'em', 'i', 'u'
         write '\fI'
         inline_filter(node.children)
         write '\fR'

data/man/ron.1.ron

@@ -1,12 +1,12 @@
-ron(1) -- the opposite of roff
-==============================
+ron(1) -- build markdown-based man pages
+========================================
 
 ## SYNOPSIS
 
-`ron` [ _OPTIONS_ ]  
-`ron` --build _FILE_ ...  
-`ron` --install _FILE_ ...  
-`ron` --man _FILE_
+`ron` [ <OPTIONS> ]  
+`ron` --build <FILE> ...  
+`ron` --install <FILE> ...  
+`ron` --man <FILE>
 
 ## DESCRIPTION
 
@@ -15,7 +15,7 @@ ron(1) -- the opposite of roff
 and install standard UNIX / roff(7) formatted man pages and to
 generate nicely formatted HTML manual pages.
 
-The `ron` command converts one or more named input <em>FILE</em>s
+The `ron` command converts one or more named input <FILE>s
 (or standard input when no files are named or the file name `-`
 is given) from humane man page markup to one or more destination
 output formats. If no output format is selected explicitly, `ron`
@@ -24,13 +24,13 @@ writes output in roff format.
 ## FILES
 
 The `ron` command expects input to be formatted as ron(5) text.
-Source files are typically named '_name_._section_.ron' (e.g.,
-`hello.1.ron`). The _name_ and _section_ should match the name
-and section defined in _FILE_'s heading.
+Source files are typically named '<NAME>.<SECTION>.ron' (e.g.,
+`hello.1.ron`). The <NAME> and <SECTION> should match the name
+and section defined in <FILE>'s heading.
 
 When building roff and/or HTML output files with the `--build`
 argument, destination filenames are determined by taking the basename
-of the input _FILE_ and adding the appropriate file extension (or
+of the input <FILE> and adding the appropriate file extension (or
 removing the file extension in the case of roff output).
 
 For example, the command `ron -b --html --roff hello.1.ron` would
@@ -46,8 +46,8 @@ The following arguments change this behavior:
   * `-b`, `--build`:
     Write output directly to files instead of standard output. When
     the `--roff` option is provided, writes roff output to
-    _file_._section_. When the `--html` option is provided, writes
-    output to '_file_._section_.html'.
+    <file>.<section>. When the `--html` option is provided, writes
+    output to '<file>.<section>.html'.
 
   * `-i`, `--install`:
     Install the roff formatted man page to the local system such
@@ -59,20 +59,42 @@ The following arguments change this behavior:
     _/usr/local/man_.
 
   * `-m`, `--man`:
-    Display _FILE_ as if man(1) were invoked on the roff output
+    Display <FILE>s as if man(1) were invoked on the roff output
     file. This simulates default man behavior by piping the roff
     output through groff(1) and the paging program specified by the
     `MANPAGER` environment variable.
 
-The following options control the output formats generated:
+These options control the format used in generated output:
 
-  * `--html`:
-    Generate HTML output.
-
-  * `--roff`:
+  * `-r`, `--roff`:
     Generate roff output. This is the default behavior when no
     other format argument is provided.
 
+  * `-5`, `--html`:
+    Generate output in HTML format.
+
+  * `-f`, `--fragment`:
+    Generate output in HTML format but only the document
+    fragment, not the header, title, or footer.
+
+All document attributes displayed in the header and footer areas
+of generated content can be specified with these options:
+
+  * `--manual`=<MANUAL>:
+    The name of the manual this man page belongs to; <MANUAL> is
+    prominently displayed top-center in the header area.
+
+  * `--organization`=<NAME>:
+    The name of the group, organization, or individual
+    responsible for publishing the document; <NAME> is displayed
+    in the bottom-left footer area.
+
+  * `--date`=<DATE>:
+    The document's published date; <DATE> must be formatted
+    `YYYY-MM-DD` and is displayed in the bottom-center footer
+    area. The <FILE> mtime is used when no <DATE> is given,
+    or the current time when no <FILE> is available.
+
 ## EXAMPLES
 
 Generate `roff(7)` output on stdout:
@@ -113,7 +135,7 @@ Install the roff man page for a ron file:
   * `MANHOME`:
     Location where roff formatted man pages should be installed.
     Relevant only when the `--installed` argument is provided.
-    _PATH_ is to the base of a man file hierarchy. e.g.,
+    <PATH> is to the base of a man file hierarchy. e.g.,
     `/usr/local/share/man`, `/home/rtomayko/man`.
 
   * `MANPAGER`:
@@ -125,7 +147,8 @@ Install the roff man page for a ron file:
 
 ## BUGS
 
-Ron is written in Ruby.
+Ron is written in Ruby. C and/or standalone Perl implementations
+would be preferable for ease of packaging and distribution.
 
 ## COPYRIGHT
 

data/man/ron.5.ron

@@ -99,11 +99,13 @@ uses the following bits of markdown(5) to accomplish this:
     displayed in in <b>boldface</b>. Note that all text included
     within `backticks` is displayed literally; other inline markup
     is not processed.
+  * `**double-stars**`:
+    Like `backticks` but may contain other inline markup.
   * `_`_underbars_`_`:
     User-specified arguments, variables, or user input; typically
-    displayed in <u>underline</u>.
-  * `**double stars**`:
-    Like `backticks` but may contain other inline markup.
+    displayed with <u>underline</u>.
+  * `<angle-quotes>`:
+    Same as _underbars_. This is not compatible with Markdown.
 
 Here is grep(1)'s DESCRIPTION section represented in `ron`:
 

data/man/ron.7.ron

@@ -0,0 +1,149 @@
+ron(7) -- 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 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
+-------
+
+Ron can be installed using rubygems:
+
+    $ [sudo] gem install ron
+
+Or, clone the git repository and install from
+source:
+
+    $ git clone git://github.com/rtomayko/ron.git
+    $ cd ron
+    $ rake package
+    $ [sudo] 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/ron.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'ron'
-  s.version = '0.1'
-  s.date = '2009-11-05'
+  s.version = '0.2'
+  s.date = '2009-11-23'
 
   s.description = "The opposite of roff"
   s.summary     = "The opposite of roff"
@@ -25,10 +25,20 @@ Gem::Specification.new do |s|
     man/markdown.5.ron
     man/ron.1.ron
     man/ron.5.ron
+    man/ron.7.ron
     ron.gemspec
+    test/angle_bracket_syntax.html
+    test/angle_bracket_syntax.ron
+    test/basic_document.html
+    test/basic_document.ron
+    test/custom_title_document.html
+    test/custom_title_document.ron
+    test/definition_list_syntax.html
+    test/definition_list_syntax.ron
     test/document_test.rb
     test/ron_test.rb
-    test/simple.ron
+    test/titleless_document.html
+    test/titleless_document.ron
   ]
   # = MANIFEST =
 

data/test/angle_bracket_syntax.html

@@ -0,0 +1,12 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>angle_bracket_syntax</code> -- angle bracket syntax test</p>
+<p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
+
+<pre><code>except when &lt;WORD&gt; is
+part of a preformatted
+code block,
+</code></pre>
+
+<p>or when <code>&lt;WORD&gt;</code> is enclosed in backticks.</p>
+
+<p>or when <var>WORD</var> has a &lt;dot.&gt; or &lt;foo:colon&gt;.</p>

data/test/angle_bracket_syntax.ron

@@ -0,0 +1,12 @@
+angle_bracket_syntax(5) -- angle bracket syntax test
+====================================================
+
+A <WORD> in angle brackets is converted to <var>WORD</var>,
+
+    except when <WORD> is
+    part of a preformatted
+    code block,
+
+or when `<WORD>` is enclosed in backticks.
+
+or when <WORD> has a <dot.> or <foo:colon>.

data/test/basic_document.html

@@ -0,0 +1,3 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>simple</code> -- a simple ron example</p>
+<p>This document created by ron.</p>

data/test/{simple.ron → basic_document.ron}

@@ -1,2 +1,4 @@
 simple(7) -- a simple ron example
 =================================
+
+This document created by ron.

data/test/custom_title_document.html

@@ -0,0 +1,3 @@
+<h1>custom_title_document -- This is a custom title</h1>
+<p>It doesn't define the name or section of this manual page and is
+output as a simple <code>&lt;h1&gt;</code> instead of a <code>NAME</code> section.</p>

data/test/custom_title_document.ron

@@ -0,0 +1,5 @@
+This is a custom title
+======================
+
+It doesn't define the name or section of this manual page and is
+output as a simple `<h1>` instead of a `NAME` section.

data/test/definition_list_syntax.html

@@ -0,0 +1,21 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>defition_list_syntax</code> -- hiya</p>
+<p>Definition lists look like unordered lists:</p>
+
+<dl>
+<dt class="flush">term</dt>
+<dd><p>definition</p></dd>
+<dt>another one</dt>
+<dd>
+<p>The definition may span
+multiple lines and even</p>
+
+<p>start</p>
+
+<p>new paragraphs</p>
+</dd>
+<dt>
+<code>--somearg</code>=<var>VALUE</var>
+</dt>
+<dd><p>We can do that too.</p></dd>
+</dl>

data/test/definition_list_syntax.ron

@@ -0,0 +1,18 @@
+defition_list_syntax(5) -- hiya
+===============================
+
+Definition lists look like unordered lists:
+
+  * term:
+    definition
+
+  * another one:
+    The definition may span
+    multiple lines and even
+
+    start
+
+    new paragraphs
+
+  * `--somearg`=<VALUE>:
+    We can do that too.

data/test/document_test.rb

@@ -2,34 +2,87 @@ require 'contest'
 require 'ron/document'
 
 class DocumentTest < Test::Unit::TestCase
-  SIMPLE_FILE = "#{File.dirname(__FILE__)}/simple.ron"
-  HELLO_DATA = "# hello(1) -- hello world"
+  SIMPLE_FILE = "#{File.dirname(__FILE__)}/basic_document.ron"
 
-  test "creating with a file" do
+  test "new with path" do
     doc = Ron::Document.new(SIMPLE_FILE)
     assert_equal File.read(SIMPLE_FILE), doc.data
   end
 
-  test "creating with a string and a file" do
-    doc = Ron::Document.new('hello.1.ron') { HELLO_DATA }
-    assert_equal HELLO_DATA, doc.data
+  test "new with path and block" do
+    doc = Ron::Document.new('hello.1.ron') { "# hello(1) -- hello world" }
+    assert_equal "# hello(1) -- hello world", doc.data
   end
 
-  context "Document" do
+  test "new with path and block but missing name section" do
+    doc = Ron::Document.new('foo.7.ron') { '' }
+    assert_equal 'foo', doc.name
+    assert_equal '7', doc.section
+  end
+
+  test "new with non conventional path and missing name section" do
+    doc = Ron::Document.new('bar.ron') { '' }
+    assert_equal 'bar', doc.name
+    assert_equal nil, doc.section
+    assert_equal "./bar.html", doc.path_for('html')
+    assert_equal "./bar", doc.path_for('roff')
+    assert_equal "./bar", doc.path_for('')
+    assert_equal "./bar", doc.path_for(nil)
+  end
+
+  test "new with path and name section mismatch" do
+    doc = Ron::Document.new('foo/rick.7.ron') { "# randy(3) -- I'm confused." }
+    assert_equal 'randy', doc.name
+    assert_equal 'rick', doc.path_name
+    assert_equal '3', doc.section
+    assert_equal '7', doc.path_section
+    assert_equal 'rick.7', doc.basename
+    assert_equal 'foo/rick.7.bar', doc.path_for(:bar)
+  end
+
+  test "new with no path and a name section" do
+    doc = Ron::Document.new { "# brandy(5) -- wootderitis" }
+    assert_equal nil, doc.path_name
+    assert_equal nil, doc.path_section
+    assert_equal 'brandy', doc.name
+    assert_equal '5', doc.section
+    assert_equal 'brandy.5', doc.basename
+    assert_equal 'brandy.5.foo', doc.path_for(:foo)
+  end
+
+  context "simple conventionally named document" do
     setup do
-      @doc = Ron::Document.new('hello.1.ron') { HELLO_DATA }
+      @doc = Ron::Document.new('hello.1.ron') { "# hello(1) -- hello world" }
     end
 
     should "load data" do
-      assert_equal HELLO_DATA, @doc.data
+      assert_equal "# hello(1) -- hello world", @doc.data
     end
 
-    should "extract the name" do
+    should "extract the manual page name from the filename or document" do
       assert_equal 'hello', @doc.name
     end
 
-    should "extract the section" do
+    should "extract the manual page section from the filename or document" do
       assert_equal '1', @doc.section
     end
+
+    should "convert to an HTML fragment" do
+      assert_equal %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> -- hello world</p>\n],
+        @doc.to_html_fragment
+    end
+
+    should "convert to HTML with a layout" do
+      assert_match %r{^<!DOCTYPE html.*}m, @doc.to_html
+      assert_match %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> -- hello world</p>],
+        @doc.to_html
+    end
+
+    should "construct a path to related documents" do
+      assert_equal "./hello.1.html", @doc.path_for(:html)
+      assert_equal "./hello.1", @doc.path_for(:roff)
+      assert_equal "./hello.1", @doc.path_for('')
+      assert_equal "./hello.1", @doc.path_for(nil)
+    end
   end
 end

data/test/ron_test.rb

@@ -1,21 +1,22 @@
 require 'contest'
+require 'ron'
 
-# ron command tests
 class RonTest < Test::Unit::TestCase
   testdir = File.dirname(__FILE__)
   bindir = File.dirname(testdir)
   ENV['PATH'] = "#{bindir}:#{ENV['PATH']}"
+  ENV['RUBYLIB'] = $LOAD_PATH.join(':')
 
   SIMPLE_FILE = "#{File.dirname(__FILE__)}/simple.ron"
 
   test "takes ron text on stdin and produces roff on stdout" do
-    output = `echo '# hello(1) -- hello world' | ron`
+    output = `echo '# hello(1) -- hello world' | ron --date=2009-11-23`
     lines = output.split("\n")
     assert_equal 7, lines.size
-    assert_equal %[.\\" generated with Ron], lines.shift 
+    assert_equal %[.\\" generated with Ron/v#{Ron::VERSION}], lines.shift 
     assert_equal %[.\\" http://github.com/rtomayko/ron/], lines.shift
     assert_equal %[.], lines.shift
-    assert_equal %[.TH "HELLO" 1 "" "" ""], lines.shift
+    assert_equal %[.TH "HELLO" 1 "November 2009" "" ""], lines.shift
     assert_equal %[.], lines.shift
     assert_equal %[.SH "NAME"], lines.shift
     assert_equal %[\\fBhello\\fR \\-\\- hello world], lines.shift
@@ -24,6 +25,30 @@ class RonTest < Test::Unit::TestCase
 
   test "produces html instead of roff with the --html argument" do
     output = `echo '# hello(1) -- hello world' | ron --html`
-    assert_match(/<h2 id="NAME">NAME<\/h2>/, output)
+    assert_match(/<h2 id='NAME'>NAME<\/h2>/, output)
+  end
+
+  test "produces html fragment with the --fragment argument" do
+    output = `echo '# hello(1) -- hello world' | ron --fragment`
+    assert_equal "<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> -- hello world</p>\n",
+      output
+  end
+
+  # file based tests
+  Dir[testdir + '/*.ron'].each do |source|
+    dest = source.sub(/ron$/, 'html')
+    wrong = source.sub(/ron$/, "wrong")
+    test File.basename(source, '.ron') do
+      html = `ron --html --fragment #{source}`
+      expected = File.read(dest) rescue ''
+      if expected != html
+        File.open(wrong, 'wb') { |f| f.write(html) }
+        diff = `diff -u #{dest} #{wrong} 2>/dev/null`
+        fail "the #{dest} file does not exist" if diff.empty?
+        flunk diff
+      elsif File.exist?(wrong)
+        File.unlink(wrong)
+      end
+    end
   end
 end

data/test/titleless_document.html

@@ -0,0 +1,2 @@
+<p>This is a document without a level 1 heading. It doesn't output
+a <code>NAME</code> section or custom <code>&lt;h1&gt;</code>.</p>

data/test/titleless_document.ron

@@ -0,0 +1,2 @@
+This is a document without a level 1 heading. It doesn't output
+a `NAME` section or custom `<h1>`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ron
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-05 00:00:00 -08:00
+date: 2009-11-23 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -63,10 +63,20 @@ files:
 - man/markdown.5.ron
 - man/ron.1.ron
 - man/ron.5.ron
+- man/ron.7.ron
 - ron.gemspec
+- test/angle_bracket_syntax.html
+- test/angle_bracket_syntax.ron
+- test/basic_document.html
+- test/basic_document.ron
+- test/custom_title_document.html
+- test/custom_title_document.ron
+- test/definition_list_syntax.html
+- test/definition_list_syntax.ron
 - test/document_test.rb
 - test/ron_test.rb
-- test/simple.ron
+- test/titleless_document.html
+- test/titleless_document.ron
 has_rdoc: true
 homepage: http://github.com/rtomayko/ron/
 licenses: []