ronn 0.5 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
data/AUTHORS ADDED
@@ -0,0 +1,7 @@
1
+ # This is a list of people who have contributed code or ideas to ronn -- for
2
+ # copyright purposes or whatever.
3
+
4
+ Ryan Tomayko <http://github.com/rtomayko>
5
+ Chris Wanstrath <http://github.com/defunkt>
6
+ Suraj N. Kurapati <http://github.com/sunaku>
7
+ Hallison Batista <http://github.com/hallison>
data/CHANGES ADDED
@@ -0,0 +1,128 @@
1
+ Ronn CHANGES
2
+ ============
3
+
4
+ Version 0.6 (not yet released)
5
+ ------------------------------
6
+
7
+ Features:
8
+
9
+ * HTML: New styling system:
10
+ ronn --style=toc,print program.1.ronn
11
+ ronn -s dark,toc,/path/to/custom.css man/*.ronn
12
+
13
+ The --style (-s) option takes a list of CSS stylesheets to embed into the
14
+ generated HTML. Stylesheets are inserted in the order specified and can use
15
+ the cascade to add or remove visual elements.
16
+
17
+ Ronn ships with a few built in styles: toc, dark, 80c, and print. You can
18
+ insert your own by giving the path or manipulating the RONN_STYLE environment
19
+ variable.
20
+
21
+ See ronn(1) for full details on all of these things (rtomayko)
22
+
23
+ * HTML: It's now possible to generate a Table Of Contents of manpage sections.
24
+ The TOC is disabled by default. To enable it: ronn --style=toc file.ronn
25
+ (sunaku)
26
+
27
+ * HTML: The RONN_LAYOUT environment variable can be used to apply a custom
28
+ mustache layout template:
29
+
30
+ RONN_LAYOUT=mine.mustache ronn man/great-program.1.ronn
31
+
32
+ See lib/ronn/template/default.html for default markup and features
33
+ (defunkt)
34
+
35
+ * HTML: All heading elements include page anchor id attributes to make
36
+ it possible to link to a specific manpage section (sunaku)
37
+
38
+ * HTML: Markdown reference links can be used to refer to sections. To link
39
+ to the SEE ALSO section of the current manpage, use: [SEE ALSO][], or [to
40
+ control the link text][SEE ALSO], or even [use the relative URL](#SEE-ALSO).
41
+ (rtomayko)
42
+
43
+ * HTML: 80 character terminal style: ronn -s 80c file.ronn -- precisely
44
+ emulates a 80c terminal (sunaku)
45
+
46
+ * HTML: Various appearance changes to the default stylesheet: smaller type
47
+ with consistent vertical baseline; darker type for more contrast; em, var,
48
+ and u are italic instead of underline (rtomayko)
49
+
50
+ * HTML: Various print stylesheet tweaks, including hyperlinks and layout
51
+ enhancements (sunaku)
52
+
53
+ * ROFF: ronn --warnings (-w) shows troff warnings on stderr when building
54
+ or viewing manuals. (rtomayko)
55
+
56
+ * ROFF: Ordered lists. (sunaku)
57
+
58
+ * ROFF: URLs for hyperlinks are shown immediately after hyperlink text.
59
+ (sunaku)
60
+
61
+ * The RONN_MANUAL, RONN_ORGANIZATION, and RONN_DATE environment variables
62
+ establish the default values of the --manual, --organization, and --date
63
+ options (rtomayko)
64
+
65
+ Bugs:
66
+
67
+ * ROFF: Don't crash with empty preformatted blocks (sunaku)
68
+
69
+ * ROFF: A whole bunch of weird whitespace related problems in roff output,
70
+ such as the first line of definition lists being indented by two
71
+ characters (rtomayko)
72
+
73
+ * ROFF: All ['".] characters are backslash escaped in roff output. These
74
+ characters are used for various roff macro syntax (rtomayko)
75
+
76
+ Deprecations, Obsoletions:
77
+
78
+ * The ronn(1) command line interface has changed in ways that are not
79
+ backward-compatible with previous versions of ronn. The --build option is
80
+ assumed when one or more .ronn files is given on the command line. Previous
81
+ versions write generated content to standard output with no explicit --build
82
+ options.
83
+
84
+ The default behavior when no files are given remains the same as previous
85
+ versions: ronn source text is read from stdin and roff is written to stdout.
86
+
87
+ See `ronn --help' or the ronn(1) manual for more on command line interface
88
+ changes.
89
+
90
+ (rtomayko, defunkt)
91
+
92
+ * HTML: Ronn no longer uses a specific monospace font-family; the system
93
+ default monospace font is used instead. Use 'ronn --style' to set up a font
94
+ stack (rtomayko)
95
+
96
+ * HTML: The following HTML elements are deprecated and will be removed at some
97
+ point: div#man, div#man ol.man, div#man ol.head, div#man ol.man.
98
+
99
+ The .mp, .man-decor, .man-head, .man-foot, .man-title, and .man-navigation
100
+ classes should be used instead (rtomayko)
101
+
102
+ * The markdown(5) manpage is no longer shipped with the ronn package. It is
103
+ shipped with the latest version of rdiscount, however.
104
+ (rtomayko, sunaku)
105
+
106
+ 0.5 (2010 April 24)
107
+ -------------------
108
+
109
+ * Fixed a bug in roff output where multiple successive newlines were being
110
+ collapsed into a single newline in preformatted output.
111
+
112
+ * Hexadecimal and decimal entity references generated by the Markdown to HTML
113
+ conversion are now properly decoded into normal characters in roff output.
114
+
115
+ * The compatibility shims that allowed the ronn command to be invoked as "ron",
116
+ and the ronn library to be required as "ron", have been removed.
117
+
118
+
119
+ 0.4 (2010 March 08)
120
+ -------------------
121
+
122
+ * Ron has been renamed "Ronn", including the "ronn" command and the "ronn"
123
+ library. Compatibility shims are included in this release but will be removed
124
+ in the next release.
125
+
126
+ * The hpricot library is now used for HTML hackery instead of the nokogiri
127
+ library. The hpricot library is preferred because it doesn't depend on external
128
+ system dependencies.
data/README.md CHANGED
@@ -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)
data/Rakefile CHANGED
@@ -18,51 +18,104 @@ end
18
18
 
19
19
  desc 'Run tests'
20
20
  task :test => :environment do
21
- require_library 'contest'
22
- Dir['test/*_test.rb'].each { |test| require test }
21
+ $LOAD_PATH.unshift "#{ROOTDIR}/test"
22
+ Dir['test/*_test.rb'].each { |f| require(f) }
23
+ end
24
+
25
+ desc 'Start the server'
26
+ task :server => :environment do
27
+ if system('type shotgun >/dev/null 2>&1')
28
+ exec "shotgun config.ru"
29
+ else
30
+ require 'ronn/server'
31
+ Ronn::Server.run('man/*.ronn')
32
+ end
33
+ end
34
+
35
+ desc 'Start the server'
36
+ task :server => :environment do
37
+ if system('type shotgun >/dev/null 2>&1')
38
+ exec "shotgun config.ru"
39
+ else
40
+ require 'ronn/server'
41
+ Ronn::Server.run('man/*.ronn')
42
+ end
23
43
  end
24
44
 
25
45
  desc 'Build the manual'
26
46
  task :man => :environment do
27
- sh "ronn -br5 --manual='Ronn Manual' --organization='Ryan Tomayko' man/*.ronn"
47
+ require 'ronn'
48
+ ENV['RONN_MANUAL'] = "Ronn #{Ronn::VERSION}"
49
+ ENV['RONN_ORGANIZATION'] = Ronn::REV
50
+ sh "ronn -w -s toc man/*.ronn"
51
+ end
52
+
53
+ desc 'Publish to github pages'
54
+ task :pages => :man do
55
+ puts '----------------------------------------------'
56
+ puts 'Rebuilding pages ...'
57
+ verbose(false) {
58
+ rm_rf 'pages'
59
+ push_url = `git remote show origin`.grep(/Push.*URL/).first[/git@.*/]
60
+ rev = `git rev-parse origin/gh-pages`
61
+ sh "
62
+ set -e
63
+ git fetch -q origin
64
+ git clone -q -b gh-pages . pages
65
+ cd pages
66
+ git reset --hard #{rev}
67
+ rm -f ronn*.html index.html
68
+ cp -rp ../man/ronn*.html ./
69
+ cp -p ronn.7.html index.html
70
+ git add -u ronn*.html index.html
71
+ git commit -m 'rebuild manual'
72
+ git push #{push_url} gh-pages
73
+ ", :verbose => false
74
+ }
28
75
  end
29
76
 
30
77
  # PACKAGING ============================================================
31
78
 
32
- if defined?(Gem)
33
- $spec = eval(File.read('ronn.gemspec'))
79
+ # Rev Ronn::VERSION
80
+ task :rev do
81
+ rev = `git describe --tags`.chomp
82
+ data = File.read('lib/ronn.rb')
83
+ data.gsub!(/^( *)REV *=.*/, "\\1REV = '#{rev}'")
84
+ File.open('lib/ronn.rb', 'wb') { |fd| fd.write(data) }
85
+ end
34
86
 
35
- def package(ext='')
36
- "pkg/ronn-#{$spec.version}" + ext
37
- end
87
+ require 'rubygems'
88
+ $spec = eval(File.read('ronn.gemspec'))
89
+
90
+ def package(ext='')
91
+ "pkg/ronn-#{$spec.version}" + ext
92
+ end
38
93
 
39
- desc 'Build packages'
40
- task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
94
+ desc 'Build packages'
95
+ task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
41
96
 
42
- desc 'Build and install as local gem'
43
- task :install => package('.gem') do
44
- sh "gem install #{package('.gem')}"
45
- end
97
+ desc 'Build and install as local gem'
98
+ task :install => package('.gem') do
99
+ sh "gem install #{package('.gem')}"
100
+ end
46
101
 
47
- directory 'pkg/'
48
- CLOBBER.include('pkg')
102
+ directory 'pkg/'
103
+ CLOBBER.include('pkg')
49
104
 
50
- file package('.gem') => %w[pkg/ ronn.gemspec] + $spec.files do |f|
51
- sh "gem build ronn.gemspec"
52
- mv File.basename(f.name), f.name
53
- end
105
+ file package('.gem') => %w[pkg/ ronn.gemspec] + $spec.files do |f|
106
+ sh "gem build ronn.gemspec"
107
+ mv File.basename(f.name), f.name
108
+ end
54
109
 
55
- file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
56
- sh <<-SH
57
- git archive --prefix=ronn-#{source_version}/ --format=tar HEAD |
58
- gzip > #{f.name}
59
- SH
60
- end
110
+ file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
111
+ sh <<-SH
112
+ git archive --prefix=ronn-#{source_version}/ --format=tar HEAD |
113
+ gzip > #{f.name}
114
+ SH
61
115
  end
62
116
 
63
117
  def source_version
64
- line = File.read('lib/ronn.rb')[/^\s*VERSION = .*/]
65
- line.match(/.*VERSION = '(.*)'/)[1]
118
+ @source_version ||= `ruby -Ilib -rronn -e 'puts Ronn::VERSION'`.chomp
66
119
  end
67
120
 
68
121
  file 'ronn.gemspec' => FileList['{lib,test,bin}/**','Rakefile'] do |f|