ronn 0.5 → 0.6.0

data/bin/ronn

@@ -1,90 +1,120 @@
 #!/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
-##
+#/ Usage: ronn <options> <file>...
+#/        ronn -m|--man <file> ...
+#/        ronn -S|--server <file> ...
+#/        ronn --pipe [<file>...]
+#/ Convert ronn source <file>s to roff or HTML manpage. In the first synopsis form,
+#/ build HTML and roff output files based on the input file names.
+#/
+#/ Mode options alter the default file generating behavior:
+#/       --pipe                write to standard output instead of generating files
+#/   -m, --man                 show manual like with man(1)
+#/   -S, --server              serve <file>s at http://localhost:1207/
+#/
+#/ Format options control which files are generated:
+#/   -r, --roff                generate roff output
+#/   -5, --html                generate entire HTML page with layout
+#/   -f, --fragment            generate HTML fragment
+#/
+#/ Document attributes:
+#/       --date=DATE           published date in YYYY-MM-DD format (bottom-center)
+#/       --manual=NAME         name of the manual (top-center)
+#/       --organization=NAME   publishing group or individual (bottom-left)
+#/
+#/ Misc options:
+#/   -w, --warnings            show troff warnings on stderr
+#/   -W                        disable previously enabled troff warnings
+#/       --help                show this help message
+#/
+#/ A <file> named example.1.ronn generates example.1.html (HTML manpage)
+#/ and example.1 (roff manpage) by default.
 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(/^##.*/).
+    grep(/^#\/.*/).
     map { |line| line.chomp[3..-1] }.
     join("\n")
 end
 
-# parse command line options
-ARGV.options do |option|
+##
+# Argument defaults
+
+build  = true
+view   = false
+server = false
+formats = nil
+options = {}
+styles  = %w[man]
+groff   = "groff -Wall -mtty-char -mandoc -Tascii"
+pager   = ENV['MANPAGER'] || ENV['PAGER'] || 'more'
+
+##
+# Environment variables
+
+%w[manual organization date].each do |attribute|
+  value = ENV["RONN_#{attribute.upcase}"]
+  next if value.nil? or value.empty?
+  options[attribute] = value
+end
+
+##
+# Argument parsing
+
+ARGV.options do |argv|
   # modes
-  option.on("--pipe") { }
-  option.on("-b", "--build") { build = true }
-  option.on("-i", "--install") { install = true }
-  option.on("-m", "--man") { man = true }
+  argv.on("--pipe")           { build = server = false }
+  argv.on("-b", "--build")    { build = true; server = false }
+  argv.on("-m", "--man")      { build = server = false; view = true }
+  argv.on("-S", "--server")   { build = view = false; server = true }
+  argv.on("-w", "--warnings") { groff += ' -ww' }
+  argv.on("-W")               { groff += ' -Ww' }
 
   # format options
-  option.on("-r", "--roff") { formats << 'roff' }
-  option.on("-5", "--html") { formats << 'html' }
-  option.on("-f", "--fragment") { formats << 'html_fragment' }
+  argv.on("-r", "--roff")     { (formats ||= []) << 'roff' }
+  argv.on("-5", "--html")     { (formats ||= []) << 'html' }
+  argv.on("-f", "--fragment") { (formats ||= []) << 'html_fragment' }
+
+  # html output options
+  argv.on("-s", "--style=V")  { |val| styles += val.split(/[, \n]+/) }
 
   # manual attribute options
-  [:name, :section, :manual, :organization, :date].each do |option_attr|
-    option.on("--#{option_attr}=VALUE") { |val| options[option_attr] = val }
+  %w[name section manual organization date].each do |attribute|
+    argv.on("--#{attribute}=VALUE") { |val| options[attribute] = val }
   end
 
-  option.on_tail("--help") { usage ; exit }
-  option.parse!
+  argv.on_tail("--help") { usage ; exit 0 }
+  argv.parse!
 end
 
-if ARGV.empty? && STDIN.tty?
+##
+# Modes, Formats, Options
+
+case
+when ARGV.empty? && $stdin.tty?
   usage
-  exit
-elsif ARGV.empty?
+  exit 2
+when ARGV.empty? && !server
   ARGV.push '-'
+  build = false
+  formats ||= %w[roff]
+when view
+  formats ||= %w[roff]
+when build
+  formats ||= %w[roff html]
 end
+formats ||= []
+formats.delete('html') if formats.include?('html_fragment')
 
 # turn the --date arg into a real date object
-options[:date] &&= Date.strptime(options[:date], '%Y-%m-%d')
+options['date'] &&= Date.strptime(options['date'], '%Y-%m-%d')
 
-formats = ['roff'] if formats.empty?
-formats.delete('html') if formats.include?('html_fragment')
-pid = nil
+# pass the styles option
+options['styles'] = styles
+
+##
+# Libraries and LOAD_PATH shenanigans
 
 begin
   require 'hpricot'
@@ -97,6 +127,8 @@ rescue LoadError
   end
 end
 
+# load ronn libs, setting up the load path if something fails and
+# we're in a development environment.
 begin
   require 'ronn'
 rescue LoadError
@@ -110,12 +142,25 @@ rescue LoadError
   raise
 end
 
+##
+# Server
+
+if server
+  require 'ronn/server'
+  Ronn::Server.run(ARGV, options)
+  exit 0
+end
+
+##
+# Build Pipeline
+
+pid = nil
 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
+  if view && !build
     rd, wr = IO.pipe
     if pid = fork
       rd.close
@@ -130,16 +175,30 @@ ARGV.each do |file|
   formats.each do |format|
     if build
       path = doc.path_for(format)
-      info "building: #{path}" if build
+      case format
+      when 'html'
+        warn "%5s: %-48s%15s" % [format, path, '+' + doc.styles.join(',')]
+      when 'roff', 'html_fragment'
+        warn "%5s: %-48s" % [format, path]
+      end
+
       output = doc.convert(format)
       File.open(path, 'wb') { |f| f.puts(output) }
-      system "man #{path}" if man && format == 'roff'
+
+      if format == 'roff'
+        if view
+          system "man #{path}"
+        else
+          system "#{groff} <#{path} >/dev/null"
+        end
+      end
     else
       output = doc.convert(format)
       wr.puts(output)
     end
   end
 
+  # wait for children to exit
   if pid
     wr.close
     Process.wait

data/config.ru

@@ -0,0 +1,15 @@
+#\ -p 1207
+$: << File.expand_path(__FILE__, '../lib')
+
+require 'ronn'
+require 'ronn/server'
+
+# use Rack::Lint
+
+options = {
+  :styles  => %w[man toc],
+  :organization => "Ronn v#{Ronn::VERSION}"
+}
+files = Dir['man/*.ronn'] + Dir['test/*.ronn']
+
+run Ronn::Server.new(files, options)

data/lib/ronn.rb

@@ -3,14 +3,22 @@
 # install standard UNIX roff(7) formatted manpages or to generate
 # beautiful HTML manpages.
 module Ronn
-  VERSION = '0.5'
-
-  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
+
+  # bring REV up to date with: rake rev
+  REV = '0.6.0'
+  VERSION = REV[/(?:[\d.]+)(?:-\d+)?/].tr('-', '.')
+
+  def self.release?
+    REV != '' && !REV.include?('-')
+  end
+
+  autoload :Document, 'ronn/document'
+  autoload :Roff,     'ronn/roff'
+  autoload :Server,   'ronn/server'
+  autoload :Template, 'ronn/template'
 end

data/lib/ronn/document.rb

@@ -1,7 +1,9 @@
 require 'set'
+require 'cgi'
 require 'hpricot'
 require 'rdiscount'
 require 'ronn/roff'
+require 'ronn/template'
 
 module Ronn
   # The Document class can be used to load and inspect a ronn document
@@ -41,6 +43,9 @@ module Ronn
     # the document footer.
     attr_accessor :date
 
+    # Array of style modules to apply to the document.
+    attr_accessor :styles
+
     # 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
@@ -53,6 +58,8 @@ module Ronn
       @name, @section, @tagline = nil
       @manual, @organization, @date = nil
       @fragment = preprocess
+      @styles = %w[man]
+
       attributes.each { |attr_name,value| send("#{attr_name}=", value) }
     end
 
@@ -123,6 +130,21 @@ module Ronn
       Time.now
     end
 
+    # Retrieve a list of top-level section headings in the document and return
+    # as an array of +[id, text]+ tuples, where +id+ is the element's generated
+    # id and +text+ is the inner text of the heading element.
+    def section_heads
+      parse_html(to_html_fragment).search('h2[@id]').map do |heading|
+        [heading.attributes['id'], heading.inner_text]
+      end
+    end
+
+    # Styles to insert in the generated HTML output. This is a simple Array of
+    # string module names or file paths.
+    def styles=(styles)
+      @styles = (%w[man] + styles).uniq
+    end
+
     # Convert the document to :roff, :html, or :html_fragment and
     # return the result as a string.
     def convert(format)
@@ -132,7 +154,7 @@ module Ronn
     # Convert the document to roff and return the result as a string.
     def to_roff
       RoffFilter.new(
-        to_html_fragment,
+        to_html_fragment(wrap_class=nil),
         name,
         section,
         tagline,
@@ -144,42 +166,79 @@ module Ronn
 
     # Convert the document to HTML and return the result as a string.
     def to_html
-      layout_filter(to_html_fragment)
+      if layout = ENV['RONN_LAYOUT']
+        if !File.exist?(layout_path = File.expand_path(layout))
+          warn "warn: can't find #{layout}, using default layout."
+          layout_path = nil
+        end
+      end
+
+      template = Ronn::Template.new(self)
+      template.render(layout_path || 'default')
     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
+    def to_html_fragment(wrap_class='mp')
+      wrap_class = nil if wrap_class.to_s.empty?
       buf = []
+      buf << "<div class='#{wrap_class}'>" if wrap_class
       if name? && section?
         buf << "<h2 id='NAME'>NAME</h2>"
-        buf << "<p><code>#{name}</code> -- #{tagline}</p>"
+        buf << "<p><code>#{name}</code> - #{tagline}</p>"
       elsif tagline
-        buf << "<h1>#{[name, tagline].compact.join(' -- ')}</h1>"
+        buf << "<h1>#{[name, tagline].compact.join(' - ')}</h1>"
       end
       buf << @fragment.to_s
+      buf << "</div>" if wrap_class
       buf.join("\n")
     end
 
   protected
+    # The preprocessed markdown source text.
+    attr_reader :markdown
+
     # Parse the document and extract the name, section, and tagline
     # from its contents. This is called while the object is being
     # initialized.
     def preprocess
       [
+        :heading_anchor_pre_filter,
         :angle_quote_pre_filter,
         :markdown_filter,
         :angle_quote_post_filter,
-        :definition_list_filter
+        :definition_list_filter,
+        :heading_anchor_filter,
+        :annotate_bare_links_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)
+    # Add a 'data-bare-link' attribute to hyperlinks
+    # whose text labels are the same as their href URLs.
+    def annotate_bare_links_filter(html)
+      doc = parse_html(html)
+      doc.search('a[@href]').each do |node|
+        href = node.attributes['href']
+        text = node.inner_text
+
+        if href == text  ||
+           href[0] == ?# ||
+           CGI.unescapeHTML(href) == "mailto:#{CGI.unescapeHTML(text)}"
+        then
+          node.set_attribute('data-bare-link', 'true')
+        end
+      end
+      doc
+    end
+
+    # Add URL anchors to all HTML heading elements.
+    def heading_anchor_filter(html)
+      doc = parse_html(html)
+      doc.search('h1|h2|h3|h4|h5|h6').not('[@id]').each do |heading|
+        heading.set_attribute('id', heading.inner_text.gsub(/\W+/, '-'))
+      end
+      doc
     end
 
     # Convert special format unordered lists to definition lists.
@@ -230,6 +289,7 @@ module Ronn
     # Run markdown on the data and extract name, section, and
     # tagline.
     def markdown_filter(data)
+      @markdown = data
       html = Markdown.new(data).to_html
       @tagline, html = html.split("</h1>\n", 2)
       if html.nil?
@@ -238,11 +298,11 @@ module Ronn
       else
         # grab name and section from title
         @tagline.sub!('<h1>', '')
-        if @tagline =~ /([\w_.\[\]~+=@:-]+)\s*\((\d\w*)\)\s*--?\s*(.*)/
+        if @tagline =~ /([\w_.\[\]~+=@:-]+)\s*\((\d\w*)\)\s*-+\s*(.*)/
           @name = $1
           @section = $2
           @tagline = $3
-        elsif @tagline =~ /([\w_.\[\]~+=@:-]+)\s+--\s+(.*)/
+        elsif @tagline =~ /([\w_.\[\]~+=@:-]+)\s+-+\s+(.*)/
           @name = $1
           @tagline = $2
         end
@@ -267,6 +327,20 @@ module Ronn
       end
     end
 
+    # Add [id]: #ANCHOR elements to the markdown source text for all sections.
+    # This lets us use the [SECTION-REF][] syntax
+    def heading_anchor_pre_filter(data)
+      first = true
+      data.split("\n").grep(/^[#]{2,5} +[\w '-]+[# ]*$/).each do |line|
+        data << "\n\n" if first
+        first = false
+        title = line.gsub(/[^\w -]/, '').strip
+        anchor = title.gsub(/\W+/, '-').gsub(/(^-+|-+$)/, '')
+        data << "[#{title}]: ##{anchor} \"#{title}\"\n"
+      end
+      data
+    end
+
     HTML = %w[
       a abbr acronym b bdo big br cite code dfn
       em i img input kbd label q samp select