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.
- data/AUTHORS +7 -0
- data/CHANGES +128 -0
- data/README.md +64 -79
- data/Rakefile +81 -28
- data/bin/ronn +124 -65
- data/config.ru +15 -0
- data/lib/ronn.rb +13 -5
- data/lib/ronn/document.rb +87 -13
- data/lib/ronn/roff.rb +43 -18
- data/lib/ronn/server.rb +70 -0
- data/lib/ronn/template.rb +157 -0
- data/lib/ronn/template/80c.css +6 -0
- data/lib/ronn/template/dark.css +21 -0
- data/lib/ronn/template/darktoc.css +17 -0
- data/lib/ronn/template/default.html +43 -0
- data/lib/ronn/template/man.css +100 -0
- data/lib/ronn/template/print.css +5 -0
- data/lib/ronn/template/screen.css +105 -0
- data/lib/ronn/template/toc.css +27 -0
- data/man/ronn.1 +160 -93
- data/man/ronn.1.ronn +206 -89
- data/man/ronn.5 +94 -96
- data/man/ronn.5.ronn +96 -91
- data/man/ronn.7 +50 -84
- data/man/ronn.7.ronn +64 -79
- data/ronn.gemspec +26 -11
- data/test/angle_bracket_syntax.html +4 -1
- data/test/basic_document.html +4 -1
- data/test/contest.rb +68 -0
- data/test/custom_title_document.html +4 -1
- data/test/definition_list_syntax.html +4 -1
- data/test/definition_list_syntax.roff +26 -0
- data/test/document_test.rb +51 -4
- data/test/entity_encoding_test.html +4 -1
- data/test/entity_encoding_test.roff +1 -1
- data/test/markdown_syntax.html +955 -0
- data/test/markdown_syntax.roff +1467 -0
- data/{man/markdown.5.ronn → test/markdown_syntax.ronn} +0 -0
- data/test/middle_paragraph.html +5 -2
- data/test/middle_paragraph.roff +2 -2
- data/test/ronn_test.rb +19 -4
- data/test/section_reference_links.html +15 -0
- data/test/section_reference_links.roff +10 -0
- data/test/section_reference_links.ronn +12 -0
- data/test/titleless_document.html +3 -0
- metadata +34 -13
- data/lib/ronn/layout.html +0 -75
- 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
|
7
|
-
|
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
|
12
|
-
|
13
|
-
|
14
|
-
|
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
|
-
|
21
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
57
|
-
|
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
|
-
$
|
60
|
-
building: man/markdown.5
|
61
|
-
$ man man/markdown.5
|
53
|
+
$ man man/ronn.5
|
62
54
|
|
63
|
-
|
55
|
+
Generate only a standalone HTML version of one or more files:
|
64
56
|
|
65
|
-
$ ronn
|
66
|
-
|
67
|
-
$ open man/markdown.5.html
|
57
|
+
$ ronn --html man/markdown.5.ronn
|
58
|
+
html: man/markdown.5.html
|
68
59
|
|
69
|
-
|
60
|
+
Build roff versions of all ronn files in a directory:
|
70
61
|
|
71
|
-
$ ronn
|
62
|
+
$ ronn --roff man/*.ronn
|
72
63
|
|
73
|
-
|
74
|
-
building intermediate files:
|
64
|
+
View a ronn file as if it were a manpage without building intermediate files:
|
75
65
|
|
76
|
-
$ ronn
|
66
|
+
$ ronn --man man/markdown.5.ronn
|
77
67
|
|
78
|
-
The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page
|
79
|
-
|
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
|
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
|
-
|
88
|
-
|
89
|
-
|
90
|
-
- Man pages get to the point. Because they're written in an inverted
|
91
|
-
|
92
|
-
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
|
112
|
-
|
113
|
-
|
114
|
-
|
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
|
123
|
-
|
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
|
-
|
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
|
-
|
22
|
-
Dir['test/*_test.rb'].each { |
|
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
|
-
|
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
|
-
|
33
|
-
|
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
|
-
|
36
|
-
|
37
|
-
|
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
|
-
|
40
|
-
|
94
|
+
desc 'Build packages'
|
95
|
+
task :package => %w[.gem .tar.gz].map { |ext| package(ext) }
|
41
96
|
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
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
|
-
|
48
|
-
|
102
|
+
directory 'pkg/'
|
103
|
+
CLOBBER.include('pkg')
|
49
104
|
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
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
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
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
|
-
|
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|
|