ronn 0.5 → 0.6.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (48) hide show
  1. data/AUTHORS +7 -0
  2. data/CHANGES +128 -0
  3. data/README.md +64 -79
  4. data/Rakefile +81 -28
  5. data/bin/ronn +124 -65
  6. data/config.ru +15 -0
  7. data/lib/ronn.rb +13 -5
  8. data/lib/ronn/document.rb +87 -13
  9. data/lib/ronn/roff.rb +43 -18
  10. data/lib/ronn/server.rb +70 -0
  11. data/lib/ronn/template.rb +157 -0
  12. data/lib/ronn/template/80c.css +6 -0
  13. data/lib/ronn/template/dark.css +21 -0
  14. data/lib/ronn/template/darktoc.css +17 -0
  15. data/lib/ronn/template/default.html +43 -0
  16. data/lib/ronn/template/man.css +100 -0
  17. data/lib/ronn/template/print.css +5 -0
  18. data/lib/ronn/template/screen.css +105 -0
  19. data/lib/ronn/template/toc.css +27 -0
  20. data/man/ronn.1 +160 -93
  21. data/man/ronn.1.ronn +206 -89
  22. data/man/ronn.5 +94 -96
  23. data/man/ronn.5.ronn +96 -91
  24. data/man/ronn.7 +50 -84
  25. data/man/ronn.7.ronn +64 -79
  26. data/ronn.gemspec +26 -11
  27. data/test/angle_bracket_syntax.html +4 -1
  28. data/test/basic_document.html +4 -1
  29. data/test/contest.rb +68 -0
  30. data/test/custom_title_document.html +4 -1
  31. data/test/definition_list_syntax.html +4 -1
  32. data/test/definition_list_syntax.roff +26 -0
  33. data/test/document_test.rb +51 -4
  34. data/test/entity_encoding_test.html +4 -1
  35. data/test/entity_encoding_test.roff +1 -1
  36. data/test/markdown_syntax.html +955 -0
  37. data/test/markdown_syntax.roff +1467 -0
  38. data/{man/markdown.5.ronn → test/markdown_syntax.ronn} +0 -0
  39. data/test/middle_paragraph.html +5 -2
  40. data/test/middle_paragraph.roff +2 -2
  41. data/test/ronn_test.rb +19 -4
  42. data/test/section_reference_links.html +15 -0
  43. data/test/section_reference_links.roff +10 -0
  44. data/test/section_reference_links.ronn +12 -0
  45. data/test/titleless_document.html +3 -0
  46. metadata +34 -13
  47. data/lib/ronn/layout.html +0 -75
  48. data/man/markdown.5 +0 -1639
@@ -1,43 +1,32 @@
1
1
  ronn -- the opposite of roff
2
- ===========================
2
+ ============================
3
3
 
4
4
  ## DESCRIPTION
5
5
 
6
- Ronn is a humane text format and toolchain for creating UNIX man
7
- pages, and things that appear as man pages from a distance. Use it
8
- to build and install standard UNIX roff man pages or to generate
9
- nicely formatted HTML manual pages for the web.
6
+ Ronn is a text format and toolchain for creating UNIX manpages. It converts
7
+ markdown to standard UNIX roff manpages and formatted HTML manuals for the web.
10
8
 
11
- The Ronn file format is based on Markdown. In fact, Ronn files are a
12
- compatible subset of Markdown syntax but have a more rigid structure and
13
- extend Markdown in some ways to provide features commonly found in man
14
- pages (e.g., definition lists). The ronn(5) manual page defines the
15
- format in more detail.
9
+ The source format includes all of Markdown but has a more rigid structure and
10
+ includes extensions that provide features commonly found in manpages (definition
11
+ lists, link notation, etc.). The ronn(5) manual page defines the format in
12
+ detail.
16
13
 
17
14
  ## DOCUMENTATION
18
15
 
19
- The `.ronn` files located under the `man/` directory show off a wide
20
- range of ronn capabilities and are the source of Ronn's own documentation.
21
- The source files and generated HTML / roff output files are available
22
- at:
16
+ The `.ronn` files located under the `man/` directory show off a wide range of
17
+ ronn capabilities and are the source of Ronn's own documentation. The source
18
+ files and generated HTML / roff output files are available at:
23
19
 
24
20
  * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) -
25
- build markdown based manual pages at the command line.
21
+ convert markdown files to manpages.<br>
26
22
  [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn),
27
23
  [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1)
28
24
 
29
25
  * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5) -
30
- humane manual page authoring format syntax reference.
26
+ markdown-based text format for authoring manpages<br>
31
27
  [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn),
32
28
  [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5)
33
29
 
34
- * [markdown(5)](http://rtomayko.github.com/ronn/markdown.5) -
35
- humane text markup syntax (taken from
36
- [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax),
37
- John Gruber)
38
- [source file](http://github.com/rtomayko/ronn/blob/master/man/markdown.5.ronn),
39
- [roff output](http://github.com/rtomayko/ronn/blob/master/man/markdown.5)
40
-
41
30
  ## INSTALL
42
31
 
43
32
  Install with Rubygems:
@@ -53,83 +42,79 @@ Or, clone the git repository:
53
42
 
54
43
  ## BASIC USAGE
55
44
 
56
- To generate a roff man page from the included `markdown.5.ronn` file and
57
- open it with man(1):
45
+ Build roff and HTML output files for one or more input files:
46
+
47
+ $ ronn man/ronn.5.ronn
48
+ roff: man/ronn.5
49
+ html: man/ronn.5.html
50
+
51
+ View a roff manpage with man(1):
58
52
 
59
- $ ronn -b man/markdown.5.ronn
60
- building: man/markdown.5
61
- $ man man/markdown.5
53
+ $ man man/ronn.5
62
54
 
63
- To generate a standalone HTML version:
55
+ Generate only a standalone HTML version of one or more files:
64
56
 
65
- $ ronn -b --html man/markdown.5.ronn
66
- building: man/markdown.5.html
67
- $ open man/markdown.5.html
57
+ $ ronn --html man/markdown.5.ronn
58
+ html: man/markdown.5.html
68
59
 
69
- To build roff and HTML versions of all ronn files:
60
+ Build roff versions of all ronn files in a directory:
70
61
 
71
- $ ronn -b --roff --html man/*.ronn
62
+ $ ronn --roff man/*.ronn
72
63
 
73
- If you just want to view a ronn file as if it were a man page without
74
- building intermediate files:
64
+ View a ronn file as if it were a manpage without building intermediate files:
75
65
 
76
- $ ronn -m man/markdown.5.ronn
66
+ $ ronn --man man/markdown.5.ronn
77
67
 
78
- The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page
79
- includes comprehensive documentation on `ronn` command line options.
68
+ The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes
69
+ comprehensive documentation on `ronn` command line options.
80
70
 
81
71
  ## ABOUT
82
72
 
83
- Some people think UNIX manual pages are a poor and outdated style of
73
+ Some people say UNIX manual pages are a poor and outdated style of
84
74
  documentation. I disagree:
85
75
 
86
- - Man pages follow a well defined structure that's immediately
87
- familiar and provides a useful starting point for developers
88
- documenting new tools, libraries, and formats.
89
-
90
- - Man pages get to the point. Because they're written in an inverted
91
- style, with a SYNOPSIS section followed by additional detail,
92
- prose and references to other sources of information, man pages
93
- provide the best of both cheat sheet and reference style
94
- documentation.
95
-
96
- - Man pages have extremely -- unbelievably -- limited text
97
- formatting capabilities. You get a couple of headings, lists, bold,
98
- underline and no more. This is a feature.
99
-
100
- - Although two levels of section hierarchy are technically
101
- supported, most man pages use only a single level. Unwieldy
102
- document hierarchies complicate otherwise good documentation.
103
- Feynman covered all of physics -- heavenly bodies through QED --
104
- with only two levels of document hierarchy (_The Feynman Lectures
105
- on Physics_, 1970).
106
-
107
- - Man pages have a simple referencing syntax; e.g., sh(1), fork(2),
108
- markdown(5). HTML versions can use this to generate links between
109
- pages.
110
-
111
- - The classical terminal man page display is typographically well
112
- thought out. Big bold section headings, justified monospace text,
113
- nicely indented paragraphs, intelligently aligned definition
114
- lists, and an informational header and footer.
115
-
116
- Unfortunately, trying to figure out how to create a man page is a
117
- fairly tedious process. The roff/man macro languages are highly
118
- extensible, fractured between multiple dialects, and include a bunch
119
- of device specific stuff that's entirely irrelevant to modern
76
+ - Man pages follow a well defined structure that's immediately familiar. This
77
+ provides developers with a useful starting point when documenting new tools,
78
+ libraries, and formats.
79
+
80
+ - Man pages get to the point. Because they're written in an inverted style, with
81
+ a SYNOPSIS section followed by additional detail, prose and references to
82
+ other sources of information, man pages provide the best of both cheat sheet
83
+ and reference style documentation.
84
+
85
+ - Man pages have extremely -- unbelievably -- limited text formatting
86
+ capabilities. You get a couple of headings, lists, bold, underline and no
87
+ more. This is a feature.
88
+
89
+ - Although two levels of section hierarchy are technically supported, most man
90
+ pages use only a single level. Unwieldy document hierarchies complicate
91
+ otherwise good documentation. Feynman covered all of physics -- heavenly
92
+ bodies through QED -- with only two levels of document hierarchy (_The Feynman
93
+ Lectures on Physics_, 1970).
94
+
95
+ - Man pages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7).
96
+ HTML versions can use this to generate links between pages.
97
+
98
+ - The classical terminal man page display is typographically well thought out.
99
+ Big bold section headings, justified monospace text, nicely indented
100
+ paragraphs, intelligently aligned definition lists, and an informational
101
+ header and footer.
102
+
103
+ Unfortunately, figuring out how to create a manpage is a fairly tedious process.
104
+ The roff/man macro languages are highly extensible, fractured between multiple
105
+ dialects, and include a bunch of device specific stuff irrelevant to modern
120
106
  publishing tools.
121
107
 
122
- Ronn aims to address many of the issues with man page creation while
123
- preserving the things that makes man pages a great form of
124
- documentation.
108
+ Ronn aims to address many of the issues with manpage creation while preserving
109
+ the things that makes manpages a great form of documentation.
125
110
 
126
111
  ## COPYING
127
112
 
128
- Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
113
+ Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)<br>
129
114
  See the file COPYING for information of licensing and distribution.
130
115
 
131
116
  ## SEE ALSO
132
117
 
133
118
  [ronn(1)](http://rtomayko.github.com/ronn/ronn.1),
134
119
  [ronn(5)](http://rtomayko.github.com/ronn/ronn.5),
135
- [markdown(5)](http://rtomayko.github.com/ronn/markdown.5)
120
+ markdown(5)
@@ -1,10 +1,7 @@
1
1
  Gem::Specification.new do |s|
2
- s.specification_version = 2 if s.respond_to? :specification_version=
3
- s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
4
-
5
2
  s.name = 'ronn'
6
- s.version = '0.5'
7
- s.date = '2010-04-02'
3
+ s.version = '0.6.0'
4
+ s.date = '2010-06-13'
8
5
 
9
6
  s.description = "The opposite of roff"
10
7
  s.summary = "The opposite of roff"
@@ -14,16 +11,26 @@ Gem::Specification.new do |s|
14
11
 
15
12
  # = MANIFEST =
16
13
  s.files = %w[
14
+ AUTHORS
15
+ CHANGES
17
16
  COPYING
18
17
  README.md
19
18
  Rakefile
20
19
  bin/ronn
20
+ config.ru
21
21
  lib/ronn.rb
22
22
  lib/ronn/document.rb
23
- lib/ronn/layout.html
24
23
  lib/ronn/roff.rb
25
- man/markdown.5
26
- man/markdown.5.ronn
24
+ lib/ronn/server.rb
25
+ lib/ronn/template.rb
26
+ lib/ronn/template/80c.css
27
+ lib/ronn/template/dark.css
28
+ lib/ronn/template/darktoc.css
29
+ lib/ronn/template/default.html
30
+ lib/ronn/template/man.css
31
+ lib/ronn/template/print.css
32
+ lib/ronn/template/screen.css
33
+ lib/ronn/template/toc.css
27
34
  man/ronn.1
28
35
  man/ronn.1.ronn
29
36
  man/ronn.5
@@ -35,18 +42,26 @@ Gem::Specification.new do |s|
35
42
  test/angle_bracket_syntax.ronn
36
43
  test/basic_document.html
37
44
  test/basic_document.ronn
45
+ test/contest.rb
38
46
  test/custom_title_document.html
39
47
  test/custom_title_document.ronn
40
48
  test/definition_list_syntax.html
49
+ test/definition_list_syntax.roff
41
50
  test/definition_list_syntax.ronn
42
51
  test/document_test.rb
43
52
  test/entity_encoding_test.html
44
53
  test/entity_encoding_test.roff
45
54
  test/entity_encoding_test.ronn
55
+ test/markdown_syntax.html
56
+ test/markdown_syntax.roff
57
+ test/markdown_syntax.ronn
46
58
  test/middle_paragraph.html
47
59
  test/middle_paragraph.roff
48
60
  test/middle_paragraph.ronn
49
61
  test/ronn_test.rb
62
+ test/section_reference_links.html
63
+ test/section_reference_links.roff
64
+ test/section_reference_links.ronn
50
65
  test/titleless_document.html
51
66
  test/titleless_document.ronn
52
67
  ]
@@ -55,13 +70,13 @@ Gem::Specification.new do |s|
55
70
  s.executables = ['ronn']
56
71
  s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ }
57
72
 
58
- s.extra_rdoc_files = %w[COPYING]
73
+ s.extra_rdoc_files = %w[COPYING AUTHORS]
59
74
  s.add_dependency 'hpricot', '>= 0.8.2'
60
75
  s.add_dependency 'rdiscount', '>= 1.5.8'
61
- s.add_development_dependency 'contest', '~> 0.1'
76
+ s.add_dependency 'mustache', '>= 0.7.0'
62
77
 
63
78
  s.has_rdoc = true
64
- s.homepage = "http://rtomayko.github.com/ronn/"
79
+ s.homepage = "http://github.com/rtomayko/ronn/"
65
80
  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ronn"]
66
81
  s.require_paths = %w[lib]
67
82
  s.rubygems_version = '1.1.1'
@@ -1,5 +1,6 @@
1
+ <div class='mp'>
1
2
  <h2 id='NAME'>NAME</h2>
2
- <p><code>angle_bracket_syntax</code> -- angle bracket syntax test</p>
3
+ <p><code>angle_bracket_syntax</code> - angle bracket syntax test</p>
3
4
 
4
5
  <p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
5
6
 
@@ -11,3 +12,5 @@ code block,
11
12
  <p>or when <code>&lt;WORD></code> is enclosed in backticks.</p>
12
13
 
13
14
  <p>or when <var>WORD</var> has a &lt;dot.> or &lt;foo:colon>.</p>
15
+
16
+ </div>
@@ -1,4 +1,7 @@
1
+ <div class='mp'>
1
2
  <h2 id='NAME'>NAME</h2>
2
- <p><code>simple</code> -- a simple ron example</p>
3
+ <p><code>simple</code> - a simple ron example</p>
3
4
 
4
5
  <p>This document created by ron.</p>
6
+
7
+ </div>
@@ -0,0 +1,68 @@
1
+ require "test/unit"
2
+
3
+ # Test::Unit loads a default test if the suite is empty, whose purpose is to
4
+ # fail. Since having empty contexts is a common practice, we decided to
5
+ # overwrite TestSuite#empty? in order to allow them. Having a failure when no
6
+ # tests have been defined seems counter-intuitive.
7
+ class Test::Unit::TestSuite
8
+ def empty?
9
+ false
10
+ end
11
+ end
12
+
13
+ # Contest adds +teardown+, +test+ and +context+ as class methods, and the
14
+ # instance methods +setup+ and +teardown+ now iterate on the corresponding
15
+ # blocks. Note that all setup and teardown blocks must be defined with the
16
+ # block syntax. Adding setup or teardown instance methods defeats the purpose
17
+ # of this library.
18
+ class Test::Unit::TestCase
19
+ def self.setup(&block)
20
+ define_method :setup do
21
+ super(&block)
22
+ instance_eval(&block)
23
+ end
24
+ end
25
+
26
+ def self.teardown(&block)
27
+ define_method :teardown do
28
+ instance_eval(&block)
29
+ super(&block)
30
+ end
31
+ end
32
+
33
+ def self.context(name, &block)
34
+ subclass = Class.new(self)
35
+ remove_tests(subclass)
36
+ subclass.class_eval(&block) if block_given?
37
+ const_set(context_name(name), subclass)
38
+ end
39
+
40
+ def self.test(name, &block)
41
+ define_method(test_name(name), &block)
42
+ end
43
+
44
+ class << self
45
+ alias_method :should, :test
46
+ alias_method :describe, :context
47
+ end
48
+
49
+ private
50
+
51
+ def self.context_name(name)
52
+ "Test#{sanitize_name(name).gsub(/(^| )(\w)/) { $2.upcase }}".to_sym
53
+ end
54
+
55
+ def self.test_name(name)
56
+ "test_#{sanitize_name(name).gsub(/\s+/,'_')}".to_sym
57
+ end
58
+
59
+ def self.sanitize_name(name)
60
+ name.gsub(/\W+/, ' ').strip
61
+ end
62
+
63
+ def self.remove_tests(subclass)
64
+ subclass.public_instance_methods.grep(/^test_/).each do |meth|
65
+ subclass.send(:undef_method, meth.to_sym)
66
+ end
67
+ end
68
+ end
@@ -1,4 +1,7 @@
1
- <h1>custom_title_document -- This is a custom title</h1>
1
+ <div class='mp'>
2
+ <h1>custom_title_document - This is a custom title</h1>
2
3
 
3
4
  <p>It doesn't define the name or section of this manual page and is
4
5
  output as a simple <code>&lt;h1&gt;</code> instead of a <code>NAME</code> section.</p>
6
+
7
+ </div>
@@ -1,5 +1,6 @@
1
+ <div class='mp'>
1
2
  <h2 id='NAME'>NAME</h2>
2
- <p><code>defition_list_syntax</code> -- hiya</p>
3
+ <p><code>defition_list_syntax</code> - hiya</p>
3
4
 
4
5
  <p>Definition lists look like unordered lists:</p>
5
6
 
@@ -14,3 +15,5 @@ multiple lines and even</p>
14
15
  <dt><code>--somearg</code>=<var>VALUE</var></dt><dd><p>We can do that too.</p></dd>
15
16
  </dl>
16
17
 
18
+
19
+ </div>
@@ -0,0 +1,26 @@
1
+ .TH "DEFITION_LIST_SYNTAX" "5" "January 1979" "" ""
2
+ .
3
+ .SH "NAME"
4
+ \fBdefition_list_syntax\fR \- hiya
5
+ .
6
+ .P
7
+ Definition lists look like unordered lists:
8
+ .
9
+ .TP
10
+ term
11
+ definition
12
+ .
13
+ .TP
14
+ another one
15
+ The definition may span multiple lines and even
16
+ .
17
+ .IP
18
+ start
19
+ .
20
+ .IP
21
+ new paragraphs
22
+ .
23
+ .TP
24
+ \fB\-\-somearg\fR=\fIVALUE\fR
25
+ We can do that too\.
26
+
@@ -50,6 +50,24 @@ class DocumentTest < Test::Unit::TestCase
50
50
  assert_equal 'brandy.5.foo', doc.path_for(:foo)
51
51
  end
52
52
 
53
+ 1.upto(5) do |i|
54
+ dashes = '-' * i
55
+
56
+ test "new with no path and #{i} dashes in name" do
57
+ doc = Ronn::Document.new { "# brandy #{dashes} wootderitis" }
58
+ assert_equal 'brandy', doc.name
59
+ assert_equal nil, doc.section
60
+ assert_equal 'wootderitis', doc.tagline
61
+ end
62
+
63
+ test "new with no path and a name section and #{i} dashes in name" do
64
+ doc = Ronn::Document.new { "# brandy(5) #{dashes} wootderitis" }
65
+ assert_equal 'brandy', doc.name
66
+ assert_equal '5', doc.section
67
+ assert_equal 'wootderitis', doc.tagline
68
+ end
69
+ end
70
+
53
71
  context "simple conventionally named document" do
54
72
  setup do
55
73
  @doc = Ronn::Document.new('hello.1.ronn') { "# hello(1) -- hello world" }
@@ -67,14 +85,19 @@ class DocumentTest < Test::Unit::TestCase
67
85
  assert_equal '1', @doc.section
68
86
  end
69
87
 
70
- should "convert to an HTML fragment" do
71
- assert_equal %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> -- hello world</p>\n],
72
- @doc.to_html_fragment
88
+ should "convert to an HTML fragment with no wrap div" do
89
+ assert_equal %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>\n],
90
+ @doc.to_html_fragment(wrap=nil)
91
+ end
92
+
93
+ should "convert to an HTML fragment with a wrap class" do
94
+ assert_equal %[<div class='pm'>\n<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>\n\n</div>],
95
+ @doc.to_html_fragment(wrap_class='pm')
73
96
  end
74
97
 
75
98
  should "convert to HTML with a layout" do
76
99
  assert_match %r{^<!DOCTYPE html.*}m, @doc.to_html
77
- assert_match %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> -- hello world</p>],
100
+ assert_match %[<h2 id='NAME'>NAME</h2>\n<p><code>hello</code> - hello world</p>],
78
101
  @doc.to_html
79
102
  end
80
103
 
@@ -84,5 +107,29 @@ class DocumentTest < Test::Unit::TestCase
84
107
  assert_equal "./hello.1", @doc.path_for('')
85
108
  assert_equal "./hello.1", @doc.path_for(nil)
86
109
  end
110
+
111
+ test "uses default styles" do
112
+ assert_equal %w[man], @doc.styles
113
+ end
114
+ end
115
+
116
+ test 'extracting section heads' do
117
+ @doc = Ronn::Document.new(File.expand_path('../markdown_syntax.ronn', __FILE__))
118
+ expected = [
119
+ ["NAME", "NAME"],
120
+ ["SYNOPSIS", "SYNOPSIS"],
121
+ ["DESCRIPTION", "DESCRIPTION"],
122
+ ["BLOCK-ELEMENTS", "BLOCK ELEMENTS"],
123
+ ["SPAN-ELEMENTS", "SPAN ELEMENTS"],
124
+ ["MISCELLANEOUS", "MISCELLANEOUS"],
125
+ ["AUTHOR", "AUTHOR"],
126
+ ["SEE-ALSO", "SEE ALSO"]
127
+ ]
128
+ assert_equal expected, @doc.section_heads
129
+ end
130
+
131
+ test "passing a list of styles" do
132
+ @doc = Ronn::Document.new('hello.1.ronn', :styles => %w[test boom test]) { '' }
133
+ assert_equal %w[man test boom], @doc.styles
87
134
  end
88
135
  end