ronn 0.6.6 → 0.7.0

data/CHANGES

@@ -1,6 +1,40 @@
 Ronn CHANGES
 ============
 
+Version 0.7.0 (2010 June 21)
+----------------------------
+
+* HTML: Manual references (like 'grep(1)', 'ls(1)', etc.) are now hyperlinked
+  based on a set of name -> URL mappings defined in an index.txt file. The index
+  may also define links to things that aren't manuals for use in markdown
+  reference-style links. See the ronn(1) manual on LINK INDEXES for more
+  inforation: <http://rtomayko.github.com/ronn/ronn.1.html#LINK-INDEXES>
+  (rtomayko)
+
+* ROFF: Fixed a bug where multiple dot characters (.) at the beginning of a
+  line were not being escaped properly and were not displayed when viewed
+  in the terminal. (rtomayko)
+
+* ROFF: Non-breaking space characters (&nbsp;) can now be used to control line
+  wrap in roff output. (rtomayko)
+
+* ROFF: Named HTML entities like &bull;, &trade;, &copy;, and &mdash; are now
+  converted to their roff escaped equivalents. (rtomayko)
+
+* An undocumented --markdown format option argument has been added to ronn(1).
+  When given, ronn generates a <name>.<section>.markdown file with the
+  post-processed markdown text. This is mostly useful for debugging but may be
+  useful for converting ronn-format to 100% compatible markdown text.
+  (rtomayko)
+
+* The ronn(5) manpage is now known as ronn-format(7) (section 5 is limited
+  to configuration files and stuff like that historically). The old ronn(7)
+  manpage, which was really just the README, has been removed.
+  (rtomayko)
+
+* Performance improvements. Fixed a few cases where HTML was being reparsed
+  needlessly, tuned dom selectors, ... (rtomayko)
+
 Version 0.6.6 (2010 June 13)
 ----------------------------
 

data/INSTALLING

@@ -0,0 +1,18 @@
+Ronn is currently distributed mainly as a gem package. Install with rubygems:
+
+    $ gem install ronn
+    $ ronn --help
+
+Tarballs available at: <http://github.com/rtomayko/ronn/downloads>
+
+    $ curl -L http://github.com/rtomayko/ronn/downloads/0.6.6 | tar xvzf -
+    $ cd rtomayko-r*
+    $ ruby setup.rb
+
+The hpricot, mustache, and rdiscount packages are required.
+
+Hacking? Clone the git repository and put ronn/bin on your PATH:
+
+    $ git clone git://github.com/rtomayko/ronn.git
+    $ PATH=$(pwd)/ronn/bin:$PATH
+    $ ronn --help

data/README.md

@@ -1,46 +1,27 @@
-ronn -- the opposite of roff
-============================
+# Ronn
 
-## DESCRIPTION
-
-Ronn is a text format and toolchain for creating UNIX manpages. It converts
-markdown to standard UNIX roff manpages and formatted HTML manuals for the web.
+Ronn builds manuals. It converts simple, human readable textfiles to roff for
+terminal display, and also to HTML for the web.
 
 The source format includes all of Markdown but has a more rigid structure and
-includes extensions that provide features commonly found in manpages (definition
-lists, link notation, etc.). The ronn(5) manual page defines the format in
+syntax extensions for features commonly found in manpages (definition lists,
+link notation, etc.). The ronn-format(7) manual page defines the format in
 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:
+The `*.ronn` files found in the [`man/`][1] directory show off a wide range of
+ronn capabilities:
 
-  * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) -
-    convert markdown files to manpages.<br>
+  * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) command -
     [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) -
-    markdown-based text format for authoring manpages<br>
-    [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)
-
-## INSTALL
-
-Install with Rubygems:
-
-    $ [sudo] gem install ronn
-    $ ronn --help
+  * [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) -
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7)
 
-Or, clone the git repository:
+[1]: http://github.com/rtomayko/ronn/tree/master/man
 
-    $ git clone git://github.com/rtomayko/ronn.git
-    $ PATH=ronn/bin:$PATH
-    $ ronn --help
-
-## BASIC USAGE
+## Examples
 
 Build roff and HTML output files for one or more input files:
 
@@ -48,10 +29,6 @@ Build roff and HTML output files for one or more input files:
     roff: man/ronn.5
     html: man/ronn.5.html
 
-View a roff manpage with man(1):
-
-    $ man man/ronn.5
-
 Generate only a standalone HTML version of one or more files:
 
     $ ronn --html man/markdown.5.ronn
@@ -65,56 +42,53 @@ View a ronn file as if it were a manpage without building intermediate files:
 
     $ ronn --man man/markdown.5.ronn
 
+View roff output with man(1):
+
+    $ man man/ronn.5
+
 The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes
 comprehensive documentation on `ronn` command line options.
 
-## ABOUT
+## Background
 
-Some people say UNIX manual pages are a poor and outdated style of
-documentation. I disagree:
+Some think UNIX manual pages are a poor and outdated form of documentation. I
+disagree:
 
-- Man pages follow a well defined structure that's immediately familiar. This
-  provides developers with a useful starting point when documenting new tools,
-  libraries, and formats.
+- Manpages follow a well defined structure that's immediately familiar. This
+  gives developers a starting point when documenting new tools, libraries, and
+  formats.
 
-- Man pages get to the point. Because they're written in an inverted style, with
+- Manpages 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
+  other sources of information, manpages 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.
+- Historically, manpages use an extremely -- unbelievably -- limited set of
+  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(7).
-  HTML versions can use this to generate links between pages.
+- Although two levels of section hierarchy are technically supported, most
+  manpages use only a single level. Unwieldy document hierarchies complicate
+  otherwise good documentation. Remember that Feynman covered all of physics
+  -- heavenly bodies through QED -- with only two levels of document hierarchy
+  (_The Feynman Lectures on Physics_, 1970).
 
-- The classical terminal man page display is typographically well thought out.
+- The classical terminal manpage 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.
 
+- Manpages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7).
+  HTML versions can use this to generate links between pages.
+
 Unfortunately, figuring out how to create a manpage 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 irrelevant to modern
-publishing tools.
+The roff/mandoc/mdoc macro languages are highly extensible, fractured between
+multiple dialects, and include a bunch of device specific stuff irrelevant to
+modern publishing tools.
 
-Ronn aims to address many of the issues with manpage creation while preserving
-the things that makes manpages a great form of documentation.
+Ronn aims
 
-## COPYING
+## Copying
 
-Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)<br>
+Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about)<br>
 See the file COPYING for information of licensing and distribution.
-
-## SEE ALSO
-
-[ronn(1)](http://rtomayko.github.com/ronn/ronn.1),
-[ronn(5)](http://rtomayko.github.com/ronn/ronn.5),
-markdown(5)

data/Rakefile

@@ -19,7 +19,7 @@ end
 desc 'Run tests'
 task :test => :environment do
   $LOAD_PATH.unshift "#{ROOTDIR}/test"
-  Dir['test/*_test.rb'].each { |f| require(f) }
+  Dir['test/test_*.rb'].each { |f| require(f) }
 end
 
 desc 'Start the server'
@@ -45,9 +45,9 @@ end
 desc 'Build the manual'
 task :man => :environment do
   require 'ronn'
-  ENV['RONN_MANUAL']  = "Ronn #{Ronn::VERSION}"
-  ENV['RONN_ORGANIZATION'] = Ronn::REV
-  sh "ronn -w -s toc man/*.ronn"
+  ENV['RONN_MANUAL']  = "Ronn Manual"
+  ENV['RONN_ORGANIZATION'] = "Ronn #{Ronn::revision}"
+  sh "ronn -w -s toc -r5 --markdown man/*.ronn"
 end
 
 desc 'Publish to github pages'
@@ -57,17 +57,16 @@ task :pages => :man do
   verbose(false) {
     rm_rf 'pages'
     push_url = `git remote show origin`.grep(/Push.*URL/).first[/git@.*/]
-    rev = `git rev-parse origin/gh-pages`
     sh "
       set -e
       git fetch -q origin
+      rev=$(git rev-parse origin/gh-pages)
       git clone -q -b gh-pages . pages
       cd pages
-      git reset --hard #{rev}
+      git reset --hard $rev
       rm -f ronn*.html index.html
-      cp -rp ../man/ronn*.html ./
-      cp -p ronn.7.html index.html
-      git add -u ronn*.html index.html
+      cp -rp ../man/ronn*.html ../man/index.txt ../man/index.html ./
+      git add -u ronn*.html index.html index.txt
       git commit -m 'rebuild manual'
       git push #{push_url} gh-pages
     ", :verbose => false
@@ -78,7 +77,7 @@ end
 
 # Rev Ronn::VERSION
 task :rev do
-  rev = `git describe --tags`.chomp
+  rev = ENV['REV'] || `git describe --tags`.chomp
   data = File.read('lib/ronn.rb')
   data.gsub!(/^( *)REV *=.*/, "\\1REV = '#{rev}'")
   File.open('lib/ronn.rb', 'wb') { |fd| fd.write(data) }

data/bin/ronn

@@ -1,29 +1,31 @@
 #!/usr/bin/env ruby
 #/ Usage: ronn <options> <file>...
-#/        ronn -m|--man <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:
+#/ Mode options alter the default behavior of generating files:
 #/       --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:
+#/ Format options control which files / formats are generated:
 #/   -r, --roff                generate roff output
 #/   -5, --html                generate entire HTML page with layout
 #/   -f, --fragment            generate HTML fragment
+#/       --markdown            generate post-processed markdown output
 #/
 #/ 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)
+#/       --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
+#/       --version             show ronn version and exit
 #/       --help                show this help message
 #/
 #/ A <file> named example.1.ronn generates example.1.html (HTML manpage)
@@ -38,14 +40,38 @@ def usage
     join("\n")
 end
 
+##
+# Libraries and LOAD_PATH shenanigans
+
+begin
+  require 'rdiscount'
+  require 'hpricot'
+  require 'ronn'
+rescue LoadError => boom
+  if boom.to_s =~ /ronn/
+    libdir = File.expand_path("../../lib", __FILE__).sub(%r|^#{Dir.pwd}/|, './')
+    if File.directory?(libdir) && !$:.include?(libdir)
+      warn "warn: #{boom}. adding #{libdir} to RUBYLIB ..."
+      $:.unshift libdir
+      retry
+    end
+  elsif !defined?(Gem)
+    warn "warn: #{boom}. loading rubygems ..."
+    require 'rubygems'
+    retry
+  end
+  abort boom.to_s
+end
+
 ##
 # Argument defaults
 
-build  = true
-view   = false
-server = false
+build   = true
+view    = false
+server  = false
 formats = nil
 options = {}
+write_index = false
 styles  = %w[man]
 groff   = "groff -Wall -mtty-char -mandoc -Tascii"
 pager   = ENV['MANPAGER'] || ENV['PAGER'] || 'more'
@@ -68,13 +94,13 @@ ARGV.options do |argv|
   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' }
+  argv.on("-i", "--index")    { write_index = true }
 
   # format options
   argv.on("-r", "--roff")     { (formats ||= []) << 'roff' }
   argv.on("-5", "--html")     { (formats ||= []) << 'html' }
   argv.on("-f", "--fragment") { (formats ||= []) << 'html_fragment' }
+  argv.on("--markdown")       { (formats ||= []) << 'markdown' }
 
   # html output options
   argv.on("-s", "--style=V")  { |val| styles += val.split(/[, \n]+/) }
@@ -84,6 +110,19 @@ ARGV.options do |argv|
     argv.on("--#{attribute}=VALUE") { |val| options[attribute] = val }
   end
 
+  # misc
+  argv.on("-w", "--warnings") { groff += ' -ww' }
+  argv.on("-W")               { groff += ' -Ww' }
+  argv.on("-v", "--version")  do
+    require 'ronn'
+    if Ronn.release?
+      printf "Ronn v%s\n", Ronn::VERSION
+    else
+      printf "Ronn v%s (%s)\n", Ronn::VERSION, Ronn::REV
+    end
+    printf "http://github.com/rtomayko/ronn/tree/%s\n", Ronn.revision
+    exit 0
+  end
   argv.on_tail("--help") { usage ; exit 0 }
   argv.parse!
 end
@@ -107,41 +146,9 @@ 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')
-
-# pass the styles option
 options['styles'] = styles
 
-##
-# Libraries and LOAD_PATH shenanigans
-
-begin
-  require 'hpricot'
-  require 'rdiscount'
-rescue LoadError
-  if !defined?(Gem)
-    warn "warn: #{$!.to_s}. trying again with rubygems."
-    require 'rubygems'
-    retry
-  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
-  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
-
 ##
 # Server
 
@@ -156,9 +163,8 @@ end
 
 pid = nil
 wr = STDOUT
-ARGV.each do |file|
-  doc = Ronn.new(file, options) { file == '-' ? STDIN.read : File.read(file) }
-
+documents = ARGV.map { |file| Ronn::Document.new(file, options) }
+documents.each do |doc|
   # setup the man pipeline if the --man option was specified
   if view && !build
     rd, wr = IO.pipe
@@ -177,9 +183,9 @@ ARGV.each do |file|
       path = doc.path_for(format)
       case format
       when 'html'
-        warn "%5s: %-48s%15s" % [format, path, '+' + doc.styles.join(',')]
-      when 'roff', 'html_fragment'
-        warn "%5s: %-48s" % [format, path]
+        warn "%9s: %-43s%15s" % [format, path, '+' + doc.styles.join(',')]
+      when 'roff', 'html_fragment', 'markdown'
+        warn "%9s: %-43s" % [format, path]
       end
 
       output = doc.convert(format)
@@ -204,3 +210,14 @@ ARGV.each do |file|
     Process.wait
   end
 end
+
+# Write index.txt files
+
+if write_index
+  indexes = documents.map { |doc| doc.index }.uniq
+  indexes.each do |index|
+    File.open(index.path, 'wb') do |fd|
+      fd.puts(index.to_text)
+    end
+  end
+end