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
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|