ronn 0.5 → 0.6.0

data/man/ronn.7.ronn

@@ -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/ronn.gemspec

@@ -1,10 +1,7 @@
 Gem::Specification.new do |s|
-  s.specification_version = 2 if s.respond_to? :specification_version=
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-
   s.name = 'ronn'
-  s.version = '0.5'
-  s.date = '2010-04-02'
+  s.version = '0.6.0'
+  s.date = '2010-06-13'
 
   s.description = "The opposite of roff"
   s.summary     = "The opposite of roff"
@@ -14,16 +11,26 @@ Gem::Specification.new do |s|
 
   # = MANIFEST =
   s.files = %w[
+    AUTHORS
+    CHANGES
     COPYING
     README.md
     Rakefile
     bin/ronn
+    config.ru
     lib/ronn.rb
     lib/ronn/document.rb
-    lib/ronn/layout.html
     lib/ronn/roff.rb
-    man/markdown.5
-    man/markdown.5.ronn
+    lib/ronn/server.rb
+    lib/ronn/template.rb
+    lib/ronn/template/80c.css
+    lib/ronn/template/dark.css
+    lib/ronn/template/darktoc.css
+    lib/ronn/template/default.html
+    lib/ronn/template/man.css
+    lib/ronn/template/print.css
+    lib/ronn/template/screen.css
+    lib/ronn/template/toc.css
     man/ronn.1
     man/ronn.1.ronn
     man/ronn.5
@@ -35,18 +42,26 @@ Gem::Specification.new do |s|
     test/angle_bracket_syntax.ronn
     test/basic_document.html
     test/basic_document.ronn
+    test/contest.rb
     test/custom_title_document.html
     test/custom_title_document.ronn
     test/definition_list_syntax.html
+    test/definition_list_syntax.roff
     test/definition_list_syntax.ronn
     test/document_test.rb
     test/entity_encoding_test.html
     test/entity_encoding_test.roff
     test/entity_encoding_test.ronn
+    test/markdown_syntax.html
+    test/markdown_syntax.roff
+    test/markdown_syntax.ronn
     test/middle_paragraph.html
     test/middle_paragraph.roff
     test/middle_paragraph.ronn
     test/ronn_test.rb
+    test/section_reference_links.html
+    test/section_reference_links.roff
+    test/section_reference_links.ronn
     test/titleless_document.html
     test/titleless_document.ronn
   ]
@@ -55,13 +70,13 @@ Gem::Specification.new do |s|
   s.executables = ['ronn']
   s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ }
 
-  s.extra_rdoc_files = %w[COPYING]
+  s.extra_rdoc_files = %w[COPYING AUTHORS]
   s.add_dependency 'hpricot',     '>= 0.8.2'
   s.add_dependency 'rdiscount',   '>= 1.5.8'
-  s.add_development_dependency 'contest', '~> 0.1'
+  s.add_dependency 'mustache',    '>= 0.7.0'
 
   s.has_rdoc = true
-  s.homepage = "http://rtomayko.github.com/ronn/"
+  s.homepage = "http://github.com/rtomayko/ronn/"
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ronn"]
   s.require_paths = %w[lib]
   s.rubygems_version = '1.1.1'

data/test/angle_bracket_syntax.html

@@ -1,5 +1,6 @@
+<div class='mp'>
 <h2 id='NAME'>NAME</h2>
-<p><code>angle_bracket_syntax</code> -- angle bracket syntax test</p>
+<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>
 
@@ -11,3 +12,5 @@ code block,
 <p>or when <code>&lt;WORD></code> is enclosed in backticks.</p>
 
 <p>or when <var>WORD</var> has a &lt;dot.> or &lt;foo:colon>.</p>
+
+</div>

data/test/basic_document.html

@@ -1,4 +1,7 @@
+<div class='mp'>
 <h2 id='NAME'>NAME</h2>
-<p><code>simple</code> -- a simple ron example</p>
+<p><code>simple</code> - a simple ron example</p>
 
 <p>This document created by ron.</p>
+
+</div>

data/test/contest.rb

@@ -0,0 +1,68 @@
+require "test/unit"
+
+# Test::Unit loads a default test if the suite is empty, whose purpose is to
+# fail. Since having empty contexts is a common practice, we decided to
+# overwrite TestSuite#empty? in order to allow them. Having a failure when no
+# tests have been defined seems counter-intuitive.
+class Test::Unit::TestSuite
+  def empty?
+    false
+  end
+end
+
+# Contest adds +teardown+, +test+ and +context+ as class methods, and the
+# instance methods +setup+ and +teardown+ now iterate on the corresponding
+# blocks. Note that all setup and teardown blocks must be defined with the
+# block syntax. Adding setup or teardown instance methods defeats the purpose
+# of this library.
+class Test::Unit::TestCase
+  def self.setup(&block)
+    define_method :setup do
+      super(&block)
+      instance_eval(&block)
+    end
+  end
+
+  def self.teardown(&block)
+    define_method :teardown do
+      instance_eval(&block)
+      super(&block)
+    end
+  end
+
+  def self.context(name, &block)
+    subclass = Class.new(self)
+    remove_tests(subclass)
+    subclass.class_eval(&block) if block_given?
+    const_set(context_name(name), subclass)
+  end
+
+  def self.test(name, &block)
+    define_method(test_name(name), &block)
+  end
+
+  class << self
+    alias_method :should, :test
+    alias_method :describe, :context
+  end
+
+private
+
+  def self.context_name(name)
+    "Test#{sanitize_name(name).gsub(/(^| )(\w)/) { $2.upcase }}".to_sym
+  end
+
+  def self.test_name(name)
+    "test_#{sanitize_name(name).gsub(/\s+/,'_')}".to_sym
+  end
+
+  def self.sanitize_name(name)
+    name.gsub(/\W+/, ' ').strip
+  end
+
+  def self.remove_tests(subclass)
+    subclass.public_instance_methods.grep(/^test_/).each do |meth|
+      subclass.send(:undef_method, meth.to_sym)
+    end
+  end
+end

data/test/custom_title_document.html

@@ -1,4 +1,7 @@
-<h1>custom_title_document -- This is a custom title</h1>
+<div class='mp'>
+<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>
+
+</div>

data/test/definition_list_syntax.html

@@ -1,5 +1,6 @@
+<div class='mp'>
 <h2 id='NAME'>NAME</h2>
-<p><code>defition_list_syntax</code> -- hiya</p>
+<p><code>defition_list_syntax</code> - hiya</p>
 
 <p>Definition lists look like unordered lists:</p>
 
@@ -14,3 +15,5 @@ multiple lines and even</p>
 <dt><code>--somearg</code>=<var>VALUE</var></dt><dd><p>We can do that too.</p></dd>
 </dl>
 
+
+</div>

data/test/definition_list_syntax.roff

@@ -0,0 +1,26 @@
+.TH "DEFITION_LIST_SYNTAX" "5" "January 1979" "" ""
+.
+.SH "NAME"
+\fBdefition_list_syntax\fR \- hiya
+.
+.P
+Definition lists look like unordered lists:
+.
+.TP
+term
+definition
+.
+.TP
+another one
+The definition may span multiple lines and even
+.
+.IP
+start
+.
+.IP
+new paragraphs
+.
+.TP
+\fB\-\-somearg\fR=\fIVALUE\fR
+We can do that too\.
+

data/test/document_test.rb

@@ -50,6 +50,24 @@ class DocumentTest < Test::Unit::TestCase
     assert_equal 'brandy.5.foo', doc.path_for(:foo)
   end
 
+  1.upto(5) do |i|
+    dashes = '-' * i
+
+    test "new with no path and #{i} dashes in name" do
+      doc = Ronn::Document.new { "# brandy #{dashes} wootderitis" }
+      assert_equal 'brandy', doc.name
+      assert_equal nil, doc.section
+      assert_equal 'wootderitis', doc.tagline
+    end
+
+    test "new with no path and a name section and #{i} dashes in name" do
+      doc = Ronn::Document.new { "# brandy(5) #{dashes} wootderitis" }
+      assert_equal 'brandy', doc.name
+      assert_equal '5', doc.section
+      assert_equal 'wootderitis', doc.tagline
+    end
+  end
+
   context "simple conventionally named document" do
     setup do
       @doc = Ronn::Document.new('hello.1.ronn') { "# hello(1) -- hello world" }
@@ -67,14 +85,19 @@ class DocumentTest < Test::Unit::TestCase
       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
+    should "convert to an HTML fragment with no wrap div" do
+      assert_equal %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>\n],
+        @doc.to_html_fragment(wrap=nil)
+    end
+
+    should "convert to an HTML fragment with a wrap class" do
+      assert_equal %[<div class='pm'>\n<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>\n\n</div>],
+        @doc.to_html_fragment(wrap_class='pm')
     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>],
+      assert_match %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>],
         @doc.to_html
     end
 
@@ -84,5 +107,29 @@ class DocumentTest < Test::Unit::TestCase
       assert_equal "./hello.1", @doc.path_for('')
       assert_equal "./hello.1", @doc.path_for(nil)
     end
+
+    test "uses default styles" do
+      assert_equal %w[man], @doc.styles
+    end
+  end
+
+  test 'extracting section heads' do
+    @doc = Ronn::Document.new(File.expand_path('../markdown_syntax.ronn', __FILE__))
+    expected = [
+      ["NAME", "NAME"],
+      ["SYNOPSIS", "SYNOPSIS"],
+      ["DESCRIPTION", "DESCRIPTION"],
+      ["BLOCK-ELEMENTS", "BLOCK ELEMENTS"],
+      ["SPAN-ELEMENTS", "SPAN ELEMENTS"],
+      ["MISCELLANEOUS", "MISCELLANEOUS"],
+      ["AUTHOR", "AUTHOR"],
+      ["SEE-ALSO", "SEE ALSO"]
+    ]
+    assert_equal expected, @doc.section_heads
+  end
+
+  test "passing a list of styles" do
+    @doc = Ronn::Document.new('hello.1.ronn', :styles => %w[test boom test]) { '' }
+    assert_equal %w[man test boom], @doc.styles
   end
 end