ronn 0.5 → 0.6.0

data/AUTHORS

@@ -0,0 +1,7 @@
+# This is a list of people who have contributed code or ideas to ronn -- for
+# copyright purposes or whatever.
+
+Ryan Tomayko         <http://github.com/rtomayko>
+Chris Wanstrath      <http://github.com/defunkt>
+Suraj N. Kurapati    <http://github.com/sunaku>
+Hallison Batista     <http://github.com/hallison>

data/CHANGES

@@ -0,0 +1,128 @@
+Ronn CHANGES
+============
+
+Version 0.6 (not yet released)
+------------------------------
+
+Features:
+
+* HTML: New styling system:
+    ronn --style=toc,print program.1.ronn
+    ronn -s dark,toc,/path/to/custom.css man/*.ronn
+
+  The --style (-s) option takes a list of CSS stylesheets to embed into the
+  generated HTML. Stylesheets are inserted in the order specified and can use
+  the cascade to add or remove visual elements.
+
+  Ronn ships with a few built in styles: toc, dark, 80c, and print. You can
+  insert your own by giving the path or manipulating the RONN_STYLE environment
+  variable.
+
+  See ronn(1) for full details on all of these things (rtomayko)
+
+* HTML: It's now possible to generate a Table Of Contents of manpage sections.
+  The TOC is disabled by default. To enable it: ronn --style=toc file.ronn
+  (sunaku)
+
+* HTML: The RONN_LAYOUT environment variable can be used to apply a custom
+  mustache layout template:
+
+  RONN_LAYOUT=mine.mustache ronn man/great-program.1.ronn
+
+  See lib/ronn/template/default.html for default markup and features
+  (defunkt)
+
+* HTML: All heading elements include page anchor id attributes to make
+  it possible to link to a specific manpage section (sunaku)
+
+* HTML: Markdown reference links can be used to refer to sections. To link
+  to the SEE ALSO section of the current manpage, use: [SEE ALSO][], or [to
+  control the link text][SEE ALSO], or even [use the relative URL](#SEE-ALSO).
+  (rtomayko)
+
+* HTML: 80 character terminal style: ronn -s 80c file.ronn -- precisely
+  emulates a 80c terminal (sunaku)
+
+* HTML: Various appearance changes to the default stylesheet: smaller type
+  with consistent vertical baseline; darker type for more contrast; em, var,
+  and u are italic instead of underline (rtomayko)
+
+* HTML: Various print stylesheet tweaks, including hyperlinks and layout
+  enhancements (sunaku)
+
+* ROFF: ronn --warnings (-w) shows troff warnings on stderr when building
+  or viewing manuals. (rtomayko)
+
+* ROFF: Ordered lists. (sunaku)
+
+* ROFF: URLs for hyperlinks are shown immediately after hyperlink text.
+  (sunaku)
+
+* The RONN_MANUAL, RONN_ORGANIZATION, and RONN_DATE environment variables
+  establish the default values of the --manual, --organization, and --date
+  options (rtomayko)
+
+Bugs:
+
+* ROFF: Don't crash with empty preformatted blocks (sunaku)
+
+* ROFF: A whole bunch of weird whitespace related problems in roff output,
+  such as the first line of definition lists being indented by two
+  characters (rtomayko)
+
+* ROFF: All ['".] characters are backslash escaped in roff output. These
+  characters are used for various roff macro syntax (rtomayko)
+
+Deprecations, Obsoletions:
+
+* The ronn(1) command line interface has changed in ways that are not
+  backward-compatible with previous versions of ronn. The --build option is
+  assumed when one or more .ronn files is given on the command line. Previous
+  versions write generated content to standard output with no explicit --build
+  options.
+
+  The default behavior when no files are given remains the same as previous
+  versions: ronn source text is read from stdin and roff is written to stdout.
+
+  See `ronn --help' or the ronn(1) manual for more on command line interface
+  changes.
+
+  (rtomayko, defunkt)
+
+* HTML: Ronn no longer uses a specific monospace font-family; the system
+  default monospace font is used instead. Use 'ronn --style' to set up a font
+  stack (rtomayko)
+
+* HTML: The following HTML elements are deprecated and will be removed at some
+  point: div#man, div#man ol.man, div#man ol.head, div#man ol.man.
+
+  The .mp, .man-decor, .man-head, .man-foot, .man-title, and .man-navigation
+  classes should be used instead (rtomayko)
+
+* The markdown(5) manpage is no longer shipped with the ronn package. It is
+  shipped with the latest version of rdiscount, however.
+  (rtomayko, sunaku)
+
+0.5 (2010 April 24)
+-------------------
+
+* Fixed a bug in roff output where multiple successive newlines were being
+  collapsed into a single newline in preformatted output.
+
+* Hexadecimal and decimal entity references generated by the Markdown to HTML
+  conversion are now properly decoded into normal characters in roff output.
+
+* The compatibility shims that allowed the ronn command to be invoked as "ron",
+  and the ronn library to be required as "ron", have been removed.
+
+
+0.4 (2010 March 08)
+-------------------
+
+* Ron has been renamed "Ronn", including the "ronn" command and the "ronn"
+  library. Compatibility shims are included in this release but will be removed
+  in the next release.
+
+* The hpricot library is now used for HTML hackery instead of the nokogiri
+  library. The hpricot library is preferred because it doesn't depend on external
+  system dependencies.

data/README.md

@@ -1,43 +1,32 @@
 ronn -- the opposite of roff
-===========================
+============================
 
 ## DESCRIPTION
 
-Ronn is a humane text format and toolchain for creating UNIX man
-pages, and things that appear as man pages from a distance. Use it
-to build and install standard UNIX roff man pages or to generate
-nicely formatted HTML manual pages for the web.
+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.
 
-The Ronn file format is based on Markdown. In fact, Ronn files are a
-compatible subset of Markdown syntax but have a more rigid structure and
-extend Markdown in some ways to provide features commonly found in man
-pages (e.g., definition lists). The ronn(5) manual page defines the
-format in more detail.
+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
+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 located under the `man/` directory show off a wide range of
+ronn capabilities and are the source of Ronn's own documentation.  The source
+files and generated HTML / roff output files are available at:
 
   * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) -
-    build markdown based manual pages at the command line.  
+    convert markdown files to manpages.<br>
     [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) -
-    humane manual page authoring format syntax reference.  
+    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)
 
-  * [markdown(5)](http://rtomayko.github.com/ronn/markdown.5) -
-    humane text markup syntax (taken from
-    [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax),
-    John Gruber)  
-    [source file](http://github.com/rtomayko/ronn/blob/master/man/markdown.5.ronn),
-    [roff output](http://github.com/rtomayko/ronn/blob/master/man/markdown.5)
-
 ## INSTALL
 
 Install with Rubygems:
@@ -53,83 +42,79 @@ Or, clone the git repository:
 
 ## BASIC USAGE
 
-To generate a roff man page from the included `markdown.5.ronn` file and
-open it with man(1):
+Build roff and HTML output files for one or more input files:
+
+    $ ronn man/ronn.5.ronn
+    roff: man/ronn.5
+    html: man/ronn.5.html
+
+View a roff manpage with man(1):
 
-    $ ronn -b man/markdown.5.ronn
-    building: man/markdown.5
-    $ man man/markdown.5
+    $ man man/ronn.5
 
-To generate a standalone HTML version:
+Generate only a standalone HTML version of one or more files:
 
-    $ ronn -b --html man/markdown.5.ronn
-    building: man/markdown.5.html
-    $ open man/markdown.5.html
+    $ ronn --html man/markdown.5.ronn
+    html: man/markdown.5.html
 
-To build roff and HTML versions of all ronn files:
+Build roff versions of all ronn files in a directory:
 
-    $ ronn -b --roff --html man/*.ronn
+    $ ronn --roff man/*.ronn
 
-If you just want to view a ronn file as if it were a man page without
-building intermediate files:
+View a ronn file as if it were a manpage without building intermediate files:
 
-    $ ronn -m man/markdown.5.ronn
+    $ ronn --man man/markdown.5.ronn
 
-The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page
-includes comprehensive documentation on `ronn` command line options.
+The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes
+comprehensive documentation on `ronn` command line options.
 
 ## ABOUT
 
-Some people think UNIX manual pages are a poor and outdated style of
+Some people say 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
+- 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.
+
+- 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(7).
+  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, 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.
 
-Ronn aims to address many of the issues with man page creation while
-preserving the things that makes man pages a great form of
-documentation.
+Ronn aims to address many of the issues with manpage creation while preserving
+the things that makes manpages a great form of documentation.
 
 ## COPYING
 
-Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
+Ronn is Copyright (C) 2009 [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)](http://rtomayko.github.com/ronn/markdown.5)
+markdown(5)

data/Rakefile

@@ -18,51 +18,104 @@ end
 
 desc 'Run tests'
 task :test => :environment do
-  require_library 'contest'
-  Dir['test/*_test.rb'].each { |test| require test }
+  $LOAD_PATH.unshift "#{ROOTDIR}/test"
+  Dir['test/*_test.rb'].each { |f| require(f) }
+end
+
+desc 'Start the server'
+task :server => :environment do
+  if system('type shotgun >/dev/null 2>&1')
+    exec "shotgun config.ru"
+  else
+    require 'ronn/server'
+    Ronn::Server.run('man/*.ronn')
+  end
+end
+
+desc 'Start the server'
+task :server => :environment do
+  if system('type shotgun >/dev/null 2>&1')
+    exec "shotgun config.ru"
+  else
+    require 'ronn/server'
+    Ronn::Server.run('man/*.ronn')
+  end
 end
 
 desc 'Build the manual'
 task :man => :environment do
-  sh "ronn -br5 --manual='Ronn Manual' --organization='Ryan Tomayko' man/*.ronn"
+  require 'ronn'
+  ENV['RONN_MANUAL']  = "Ronn #{Ronn::VERSION}"
+  ENV['RONN_ORGANIZATION'] = Ronn::REV
+  sh "ronn -w -s toc man/*.ronn"
+end
+
+desc 'Publish to github pages'
+task :pages => :man do
+  puts '----------------------------------------------'
+  puts 'Rebuilding pages ...'
+  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
+      git clone -q -b gh-pages . pages
+      cd pages
+      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
+      git commit -m 'rebuild manual'
+      git push #{push_url} gh-pages
+    ", :verbose => false
+  }
 end
 
 # PACKAGING ============================================================
 
-if defined?(Gem)
-  $spec = eval(File.read('ronn.gemspec'))
+# Rev Ronn::VERSION
+task :rev do
+  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) }
+end
 
-  def package(ext='')
-    "pkg/ronn-#{$spec.version}" + ext
-  end
+require 'rubygems'
+$spec = eval(File.read('ronn.gemspec'))
+
+def package(ext='')
+  "pkg/ronn-#{$spec.version}" + ext
+end
 
-  desc 'Build packages'
-  task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
+desc 'Build packages'
+task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
 
-  desc 'Build and install as local gem'
-  task :install => package('.gem') do
-    sh "gem install #{package('.gem')}"
-  end
+desc 'Build and install as local gem'
+task :install => package('.gem') do
+  sh "gem install #{package('.gem')}"
+end
 
-  directory 'pkg/'
-  CLOBBER.include('pkg')
+directory 'pkg/'
+CLOBBER.include('pkg')
 
-  file package('.gem') => %w[pkg/ ronn.gemspec] + $spec.files do |f|
-    sh "gem build ronn.gemspec"
-    mv File.basename(f.name), f.name
-  end
+file package('.gem') => %w[pkg/ ronn.gemspec] + $spec.files do |f|
+  sh "gem build ronn.gemspec"
+  mv File.basename(f.name), f.name
+end
 
-  file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
-    sh <<-SH
-      git archive --prefix=ronn-#{source_version}/ --format=tar HEAD |
-      gzip > #{f.name}
-    SH
-  end
+file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
+  sh <<-SH
+    git archive --prefix=ronn-#{source_version}/ --format=tar HEAD |
+    gzip > #{f.name}
+  SH
 end
 
 def source_version
-  line = File.read('lib/ronn.rb')[/^\s*VERSION = .*/]
-  line.match(/.*VERSION = '(.*)'/)[1]
+  @source_version ||= `ruby -Ilib -rronn -e 'puts Ronn::VERSION'`.chomp
 end
 
 file 'ronn.gemspec' => FileList['{lib,test,bin}/**','Rakefile'] do |f|