ronn 0.6.6 → 0.7.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +34 -0
- data/INSTALLING +18 -0
- data/README.md +43 -69
- data/Rakefile +9 -10
- data/bin/ronn +66 -49
- data/config.ru +1 -1
- data/lib/ronn.rb +35 -9
- data/lib/ronn/document.rb +239 -135
- data/lib/ronn/index.rb +183 -0
- data/lib/ronn/roff.rb +48 -28
- data/lib/ronn/template.rb +22 -8
- data/lib/ronn/template/dark.css +1 -4
- data/lib/ronn/template/default.html +0 -2
- data/lib/ronn/template/man.css +12 -12
- data/lib/ronn/utils.rb +8 -0
- data/man/index.html +78 -0
- data/man/index.txt +15 -0
- data/man/{ronn.5 → ronn-format.7} +26 -30
- data/man/{ronn.5.ronn → ronn-format.7.ronn} +39 -39
- data/man/ronn.1 +47 -15
- data/man/ronn.1.ronn +53 -23
- data/ronn.gemspec +14 -8
- data/test/angle_bracket_syntax.html +4 -2
- data/test/basic_document.html +4 -2
- data/test/custom_title_document.html +1 -2
- data/test/definition_list_syntax.html +4 -2
- data/test/dots_at_line_start_test.roff +10 -0
- data/test/dots_at_line_start_test.ronn +4 -0
- data/test/entity_encoding_test.html +24 -2
- data/test/entity_encoding_test.roff +41 -1
- data/test/entity_encoding_test.ronn +17 -0
- data/test/index.txt +8 -0
- data/test/markdown_syntax.html +5 -3
- data/test/markdown_syntax.roff +4 -4
- data/test/middle_paragraph.html +4 -2
- data/test/missing_spaces.roff +3 -0
- data/test/section_reference_links.html +4 -2
- data/test/{ronn_test.rb → test_ronn.rb} +18 -5
- data/test/{document_test.rb → test_ronn_document.rb} +59 -8
- data/test/test_ronn_index.rb +73 -0
- data/test/titleless_document.html +7 -2
- data/test/titleless_document.ronn +3 -2
- data/test/underline_spacing_test.roff +5 -0
- metadata +30 -14
- data/man/ronn.7 +0 -168
- data/man/ronn.7.ronn +0 -120
data/lib/ronn/utils.rb
CHANGED
data/man/index.html
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<title>Ronn</title>
|
|
5
|
+
<style>
|
|
6
|
+
body {
|
|
7
|
+
font-size:24px;
|
|
8
|
+
line-height:1.5;
|
|
9
|
+
font-family:georgia,serif;
|
|
10
|
+
color:#555;
|
|
11
|
+
}
|
|
12
|
+
div#index {
|
|
13
|
+
width:28em;
|
|
14
|
+
margin:0 auto;
|
|
15
|
+
}
|
|
16
|
+
h1 {
|
|
17
|
+
text-align:center;
|
|
18
|
+
font-weight:normal;
|
|
19
|
+
color:#000;
|
|
20
|
+
margin-bottom:0;
|
|
21
|
+
letter-spacing:-3px;
|
|
22
|
+
}
|
|
23
|
+
h3 {
|
|
24
|
+
text-align:center;
|
|
25
|
+
font-weight:normal;
|
|
26
|
+
color:#444;
|
|
27
|
+
margin-top:-20px;
|
|
28
|
+
margin-bottom:40px;
|
|
29
|
+
}
|
|
30
|
+
h4 {
|
|
31
|
+
font-weight:normal;
|
|
32
|
+
font-size:26px;
|
|
33
|
+
color:#111;
|
|
34
|
+
}
|
|
35
|
+
p, dl { margin-left:40px }
|
|
36
|
+
.aux { font-family:monospace;font-size:20px;letter-spacing:1px; }
|
|
37
|
+
.also { font-size:18px }
|
|
38
|
+
.copy { font-size:16px;text-align:center;color:#111 }
|
|
39
|
+
.man-ref { font-family:monospace;letter-spacing:-2px; }
|
|
40
|
+
</style>
|
|
41
|
+
</head>
|
|
42
|
+
<body>
|
|
43
|
+
<div id='index'>
|
|
44
|
+
<h1>Ronn</h1>
|
|
45
|
+
<h3>Builds manuals</h3>
|
|
46
|
+
|
|
47
|
+
<h4>Auxiliary</h4>
|
|
48
|
+
<p class='aux'>
|
|
49
|
+
<a href='http://github.com/rtomayko/ronn#readme'>README</a>,
|
|
50
|
+
<a href='http://github.com/rtomayko/ronn/blob/master/INSTALLING#files'>INSTALLING</a>,
|
|
51
|
+
<a href='http://github.com/rtomayko/ronn/blob/master/CHANGES#files'>CHANGES</a>,
|
|
52
|
+
<a href='http://github.com/rtomayko/ronn/blob/master/COPYING#files'>COPYING</a>,
|
|
53
|
+
<a href='http://github.com/rtomayko/ronn/blob/master/AUTHORS#files'>AUTHORS</a>
|
|
54
|
+
</p>
|
|
55
|
+
|
|
56
|
+
<h4>Manuals</h4>
|
|
57
|
+
<dl>
|
|
58
|
+
<dt><a class='man-ref' href='ronn.1.html'>ronn(1)</a></dt>
|
|
59
|
+
<dd>manual authoring tool</dd>
|
|
60
|
+
|
|
61
|
+
<dt><a class='man-ref' href='ronn-format.7.html'>ronn-format(7)</a></dt>
|
|
62
|
+
<dd>markdown-based text format for authoring manpages</dd>
|
|
63
|
+
</dl>
|
|
64
|
+
|
|
65
|
+
<h4>See Also</h4>
|
|
66
|
+
<p class='also'>
|
|
67
|
+
<a class='man-ref' href="http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man5/manpages.5.html">manpages(5)</a>,
|
|
68
|
+
<a class='man-ref' href="http://daringfireball.net/projects/markdown/syntax">markdown(7)</a>,
|
|
69
|
+
<a class='man-ref' href="http://man.cx/man(1)">man(1)</a>,
|
|
70
|
+
<a class='man-ref' href="http://man.cx/roff(7)">roff(7)</a>,
|
|
71
|
+
<a class='man-ref' href="http://man.cx/groff(1)">groff(1)</a>,
|
|
72
|
+
<a class='man-ref' href="http://mustache.github.com/mustache.5.html">mustache(5)</a>
|
|
73
|
+
</p>
|
|
74
|
+
|
|
75
|
+
<p class='copy'>Copyright © 2010 Ryan Tomayko</p>
|
|
76
|
+
</div>
|
|
77
|
+
</body>
|
|
78
|
+
</html>
|
data/man/index.txt
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# manuals
|
|
2
|
+
ronn(1) ronn.1.ronn
|
|
3
|
+
ronn(5) ronn.5.ronn
|
|
4
|
+
ronn(7) ronn.7.ronn
|
|
5
|
+
|
|
6
|
+
# external manuals
|
|
7
|
+
roff(7) http://man.cx/roff(7)
|
|
8
|
+
grep(1) http://man.cx/grep(1)
|
|
9
|
+
groff(1) http://man.cx/groff(1)
|
|
10
|
+
sh(1) http://man.cx/sh(1posix)
|
|
11
|
+
test(1) http://man.cx/test(1)
|
|
12
|
+
fork(2) http://man.cx/fork(2)
|
|
13
|
+
man(1) http://man.cx/man(1)
|
|
14
|
+
markdown(7) http://daringfireball.net/projects/markdown/syntax
|
|
15
|
+
manpages(5) http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man5/manpages.5.html
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
.\" generated with Ronn/v0.
|
|
2
|
-
.\" http://github.com/rtomayko/ronn/
|
|
1
|
+
.\" generated with Ronn/v0.7.0
|
|
2
|
+
.\" http://github.com/rtomayko/ronn/tree/0.7.0
|
|
3
3
|
.
|
|
4
|
-
.TH "RONN" "
|
|
4
|
+
.TH "RONN\-FORMAT" "7" "June 2010" "Ronn 0.7.0" "Ronn Manual"
|
|
5
5
|
.
|
|
6
6
|
.SH "NAME"
|
|
7
|
-
\fBronn\fR \-
|
|
7
|
+
\fBronn\-format\fR \- manual authoring format based on Markdown
|
|
8
8
|
.
|
|
9
9
|
.SH "SYNOPSIS"
|
|
10
10
|
.
|
|
@@ -23,24 +23,23 @@ A normal paragraph\. This can span multiple lines and is terminated with two
|
|
|
23
23
|
or more line endings \-\- just like Markdown\.
|
|
24
24
|
|
|
25
25
|
Inline markup for `code`, `user input`, and **strong** are displayed
|
|
26
|
-
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
|
|
27
|
-
underline\.
|
|
26
|
+
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
|
|
27
|
+
(HTML) or underline (roff)\.
|
|
28
28
|
|
|
29
|
-
Manual references like sh(1), markdown(7), roff(7), etc\. are
|
|
30
|
-
|
|
29
|
+
Manual references like sh(1), markdown(7), roff(7), etc\. are hyperlinked in
|
|
30
|
+
HTML output\.
|
|
31
31
|
|
|
32
|
-
Link to
|
|
33
|
-
|
|
32
|
+
Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
|
|
33
|
+
TEXT][#SEE\-ALSO]\.
|
|
34
34
|
|
|
35
35
|
Definition lists:
|
|
36
36
|
|
|
37
37
|
* `\-a`, `\-\-argument`=[<value>]:
|
|
38
38
|
One or more paragraphs describing the argument\.
|
|
39
|
+
|
|
39
40
|
* You can put whatever you *want* here, really:
|
|
40
41
|
Nesting and paragraph spacing are respected\.
|
|
41
42
|
|
|
42
|
-
Markdown ordered and unordered lists too\.
|
|
43
|
-
|
|
44
43
|
Frequently used sections:
|
|
45
44
|
|
|
46
45
|
## OPTIONS
|
|
@@ -58,16 +57,13 @@ Frequently used sections:
|
|
|
58
57
|
.fi
|
|
59
58
|
.
|
|
60
59
|
.SH "DESCRIPTION"
|
|
61
|
-
|
|
62
|
-
.
|
|
63
|
-
.P
|
|
64
|
-
Ronn files can be converted to traditional roff\-formatted manpages or to HTML using the ronn(1) command\.
|
|
60
|
+
The ronn(1) command converts text in a simple markup to UNIX manual pages\. The syntax includes all Markdown formatting features, plus conventions for expressing the structure and various notations present in standard UNIX manpages\.
|
|
65
61
|
.
|
|
66
62
|
.P
|
|
67
63
|
Not all roff(7) typesetting features can be expressed using ronn syntax\.
|
|
68
64
|
.
|
|
69
65
|
.SH "MANPAGE TITLE"
|
|
70
|
-
Manpages have a \fIname\fR, \fIsection\fR
|
|
66
|
+
Manpages have a \fIname\fR, \fIsection\fR, and a one\-line \fIdescription\fR\. Files must start with a level one heading defining these attributes:
|
|
71
67
|
.
|
|
72
68
|
.IP "" 4
|
|
73
69
|
.
|
|
@@ -120,20 +116,20 @@ Section headings should be all uppercase and may not contain inline markup\.
|
|
|
120
116
|
Manpages have a limited set of text formatting capabilities\. There\'s basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR)\. Ronn uses the following bits of markdown(7) to accomplish this:
|
|
121
117
|
.
|
|
122
118
|
.TP
|
|
123
|
-
\fB`backticks`\fR
|
|
124
|
-
Code, flags, commands, and noun\-like things; typically displayed in in \fBboldface\fR\.
|
|
119
|
+
\fB`backticks`\fR (markdown compatible)
|
|
120
|
+
Code, flags, commands, and noun\-like things; typically displayed in in \fBboldface\fR\. All text included within \fBbackticks\fR is displayed literally; other inline markup is not processed\. HTML output: \fB<code>\fR\.
|
|
125
121
|
.
|
|
126
122
|
.TP
|
|
127
|
-
\fB**double\-stars**\fR
|
|
128
|
-
|
|
123
|
+
\fB**double\-stars**\fR (markdown compatible)
|
|
124
|
+
Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML output: \fB<strong>\fR\.
|
|
129
125
|
.
|
|
130
126
|
.TP
|
|
131
|
-
\
|
|
132
|
-
User\-specified arguments, variables, or user input
|
|
127
|
+
\fB<anglequotes>\fR (non\-compatible markdown extension)
|
|
128
|
+
User\-specified arguments, variables, or user input\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<var/>\fR\.
|
|
133
129
|
.
|
|
134
130
|
.TP
|
|
135
|
-
\
|
|
136
|
-
|
|
131
|
+
\fB_\fR\fIunderbars\fR\fB_\fR (markdown compatible)
|
|
132
|
+
Emphasis\. May be used for literal option values\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<em>\fR\.
|
|
137
133
|
.
|
|
138
134
|
.P
|
|
139
135
|
Here is grep(1)\'s DESCRIPTION section represented in \fBronn\fR:
|
|
@@ -152,7 +148,7 @@ prints the matching lines\.
|
|
|
152
148
|
.IP "" 0
|
|
153
149
|
.
|
|
154
150
|
.SH "DEFINITION LISTS"
|
|
155
|
-
The definition list syntax is
|
|
151
|
+
The definition list syntax is compatible with markdown\'s unordered list syntax but requires that the first line of each list item be terminated with a colon \"\fB:\fR\" character\. The contents of the first line is the \fIterm\fR; subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists\.
|
|
156
152
|
.
|
|
157
153
|
.P
|
|
158
154
|
An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
|
|
@@ -176,11 +172,11 @@ An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
|
|
|
176
172
|
.
|
|
177
173
|
.IP "" 0
|
|
178
174
|
.
|
|
179
|
-
.P
|
|
180
|
-
The definition list syntax is intentionally backward compatible with markdown(7)\'s list syntax\. This allows \fBronn\fR documents to be piped through normal markdown processors with minor degradation in output formatting\.
|
|
181
|
-
.
|
|
182
175
|
.SH "LINKS"
|
|
183
|
-
|
|
176
|
+
All markdown(7) linking features are supported\.
|
|
177
|
+
.
|
|
178
|
+
.P
|
|
179
|
+
Markdown reference\-style links can be used to link to specific sections by name:
|
|
184
180
|
.
|
|
185
181
|
.IP "" 4
|
|
186
182
|
.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
ronn(
|
|
2
|
-
|
|
1
|
+
ronn-format(7) -- manual authoring format based on Markdown
|
|
2
|
+
===========================================================
|
|
3
3
|
|
|
4
4
|
## SYNOPSIS
|
|
5
5
|
|
|
@@ -16,24 +16,23 @@ ronn(5) -- markdown-based text format for authoring manpages
|
|
|
16
16
|
or more line endings -- just like Markdown.
|
|
17
17
|
|
|
18
18
|
Inline markup for `code`, `user input`, and **strong** are displayed
|
|
19
|
-
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
|
|
20
|
-
underline.
|
|
19
|
+
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
|
|
20
|
+
(HTML) or underline (roff).
|
|
21
21
|
|
|
22
|
-
Manual references like sh(1), markdown(7), roff(7), etc. are
|
|
23
|
-
|
|
22
|
+
Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
|
|
23
|
+
HTML output.
|
|
24
24
|
|
|
25
|
-
Link to
|
|
26
|
-
|
|
25
|
+
Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
|
|
26
|
+
TEXT][#SEE-ALSO].
|
|
27
27
|
|
|
28
28
|
Definition lists:
|
|
29
29
|
|
|
30
30
|
* `-a`, `--argument`=[<value>]:
|
|
31
31
|
One or more paragraphs describing the argument.
|
|
32
|
+
|
|
32
33
|
* You can put whatever you *want* here, really:
|
|
33
34
|
Nesting and paragraph spacing are respected.
|
|
34
35
|
|
|
35
|
-
Markdown ordered and unordered lists too.
|
|
36
|
-
|
|
37
36
|
Frequently used sections:
|
|
38
37
|
|
|
39
38
|
## OPTIONS
|
|
@@ -50,19 +49,17 @@ ronn(5) -- markdown-based text format for authoring manpages
|
|
|
50
49
|
|
|
51
50
|
## DESCRIPTION
|
|
52
51
|
|
|
53
|
-
|
|
54
|
-
Markdown formatting features, plus conventions for
|
|
55
|
-
various notations present in standard UNIX
|
|
56
|
-
|
|
57
|
-
Ronn files can be converted to traditional roff-formatted manpages or to HTML
|
|
58
|
-
using the ronn(1) command.
|
|
52
|
+
The ronn(1) command converts text in a simple markup to UNIX manual pages. The
|
|
53
|
+
syntax includes all Markdown formatting features, plus conventions for
|
|
54
|
+
expressing the structure and various notations present in standard UNIX
|
|
55
|
+
manpages.
|
|
59
56
|
|
|
60
57
|
Not all roff(7) typesetting features can be expressed using ronn syntax.
|
|
61
58
|
|
|
62
59
|
## MANPAGE TITLE
|
|
63
60
|
|
|
64
|
-
Manpages have a <name>, <section
|
|
65
|
-
|
|
61
|
+
Manpages have a <name>, <section>, and a one-line <description>. Files must
|
|
62
|
+
start with a level one heading defining these attributes:
|
|
66
63
|
|
|
67
64
|
ls(1) -- list directory contents
|
|
68
65
|
================================
|
|
@@ -92,17 +89,23 @@ Manpages have a limited set of text formatting capabilities. There's basically
|
|
|
92
89
|
<b>boldface</b> and <i>italics</i> (often displayed using <u>underline</u>).
|
|
93
90
|
Ronn uses the following bits of markdown(7) to accomplish this:
|
|
94
91
|
|
|
95
|
-
* <code>\`backticks\`</code
|
|
92
|
+
* <code>\`backticks\`</code> (markdown compatible):
|
|
96
93
|
Code, flags, commands, and noun-like things; typically displayed in in
|
|
97
|
-
<b>boldface</b>.
|
|
98
|
-
literally; other inline markup is not processed.
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
*
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
94
|
+
<b>boldface</b>. All text included within `backticks` is displayed
|
|
95
|
+
literally; other inline markup is not processed. HTML output:
|
|
96
|
+
`<code>`.
|
|
97
|
+
|
|
98
|
+
* `**double-stars**` (markdown compatible):
|
|
99
|
+
Also displayed in boldface. Unlike backticks, inline markup is processed.
|
|
100
|
+
HTML output: `<strong>`.
|
|
101
|
+
|
|
102
|
+
* `<anglequotes>` (non-compatible markdown extension):
|
|
103
|
+
User-specified arguments, variables, or user input. Typically displayed with
|
|
104
|
+
<u>underline</u> in roff output. HTML output: `<var/>`.
|
|
105
|
+
|
|
106
|
+
* `_`_underbars_`_` (markdown compatible):
|
|
107
|
+
Emphasis. May be used for literal option values. Typically displayed with
|
|
108
|
+
<u>underline</u> in roff output. HTML output: `<em>`.
|
|
106
109
|
|
|
107
110
|
Here is grep(1)'s DESCRIPTION section represented in `ronn`:
|
|
108
111
|
|
|
@@ -113,11 +116,11 @@ Here is grep(1)'s DESCRIPTION section represented in `ronn`:
|
|
|
113
116
|
|
|
114
117
|
## DEFINITION LISTS
|
|
115
118
|
|
|
116
|
-
The definition list syntax is
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
119
|
+
The definition list syntax is compatible with markdown's unordered list syntax
|
|
120
|
+
but requires that the first line of each list item be terminated with a colon
|
|
121
|
+
"`:`" character. The contents of the first line is the <term>; subsequent lines
|
|
122
|
+
may be comprised of multiple paragraphs, code blocks, standard lists, and nested
|
|
123
|
+
definition lists.
|
|
121
124
|
|
|
122
125
|
An example definition list, taken from BSD test(1)'s *DESCRIPTION* section:
|
|
123
126
|
|
|
@@ -132,14 +135,11 @@ An example definition list, taken from BSD test(1)'s *DESCRIPTION* section:
|
|
|
132
135
|
* `-d` <file>:
|
|
133
136
|
True if file exists and is a directory.
|
|
134
137
|
|
|
135
|
-
The definition list syntax is intentionally backward compatible with
|
|
136
|
-
markdown(7)'s list syntax. This allows `ronn` documents to be piped through
|
|
137
|
-
normal markdown processors with minor degradation in output formatting.
|
|
138
|
-
|
|
139
138
|
## LINKS
|
|
140
139
|
|
|
141
|
-
|
|
142
|
-
|
|
140
|
+
All markdown(7) linking features are supported.
|
|
141
|
+
|
|
142
|
+
Markdown reference-style links can be used to link to specific sections by name:
|
|
143
143
|
|
|
144
144
|
## SECTION 1
|
|
145
145
|
|
data/man/ronn.1
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
.\" generated with Ronn/v0.
|
|
2
|
-
.\" http://github.com/rtomayko/ronn/
|
|
1
|
+
.\" generated with Ronn/v0.7.0
|
|
2
|
+
.\" http://github.com/rtomayko/ronn/tree/0.7.0
|
|
3
3
|
.
|
|
4
|
-
.TH "RONN" "1" "June 2010" "0.
|
|
4
|
+
.TH "RONN" "1" "June 2010" "Ronn 0.7.0" "Ronn Manual"
|
|
5
5
|
.
|
|
6
6
|
.SH "NAME"
|
|
7
7
|
\fBronn\fR \- convert markdown files to manpages
|
|
8
8
|
.
|
|
9
9
|
.SH "SYNOPSIS"
|
|
10
|
-
\fBronn\fR [\
|
|
10
|
+
\fBronn\fR [\fIformat\fR\.\.\.] \fIfile\fR\.\.\.
|
|
11
11
|
.
|
|
12
12
|
.br
|
|
13
13
|
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\.\.\.
|
|
@@ -22,25 +22,25 @@
|
|
|
22
22
|
\fBronn\fR < \fIfile\fR
|
|
23
23
|
.
|
|
24
24
|
.SH "DESCRIPTION"
|
|
25
|
-
\fBRonn\fR converts
|
|
25
|
+
\fBRonn\fR converts textfiles to standard roff\-formatted UNIX manpages or HTML\. ronn\-format(7) is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals\.
|
|
26
26
|
.
|
|
27
27
|
.P
|
|
28
|
-
In its default mode, \fBronn\fR converts one or more input \fIfile\fRs to HTML or
|
|
28
|
+
In its default mode, \fBronn\fR converts one or more input \fIfile\fRs to HTML or roff output files\. The \fB\-\-roff\fR, \fB\-\-html\fR, and \fB\-\-fragment\fR options dictate which output files are generated\. Multiple format arguments may be specified to generate multiple output files\. Output files are named after and written to the same directory as input \fIfile\fRs\.
|
|
29
29
|
.
|
|
30
30
|
.P
|
|
31
|
-
The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from
|
|
31
|
+
The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from file generation to serving dynamically generated HTML manpages or viewing \fIfile\fR as with man(1)\.
|
|
32
32
|
.
|
|
33
33
|
.P
|
|
34
|
-
With no \fIfile\fR arguments, \fBronn\fR acts as simple filter\. Ronn source text is read from standard input and roff output is written to standard output\.
|
|
34
|
+
With no \fIfile\fR arguments, \fBronn\fR acts as simple filter\. Ronn source text is read from standard input and roff output is written to standard output\. Use the \fB\-\-html\fR, \fB\-\-roff\fR, and/or \fB\-\-fragment\fR options to select the output format\.
|
|
35
35
|
.
|
|
36
36
|
.SH "FILES"
|
|
37
|
-
The \fBronn\fR command expects input to be
|
|
37
|
+
The \fBronn\fR command expects input to be valid ronn\-format(7) text\. Source files are typically named \fIname\fR\.\fIsection\fR\.ronn (e\.g\., \fBexample\.1\.ronn\fR)\. The \fIname\fR and \fIsection\fR should match the name and section defined in the \fIfile\fR\'s heading\.
|
|
38
38
|
.
|
|
39
39
|
.P
|
|
40
40
|
When building roff or HTML output files, destination filenames are determined by taking the basename of the input \fIfile\fR and adding the appropriate file extension (or removing the file extension in the case of roff output)\. For example, executing \fBronn example\.1\.ronn\fR generates \fBexample\.1\fR with roff output and \fBexample\.1\.html\fR with HTML output\.
|
|
41
41
|
.
|
|
42
42
|
.SH "OPTIONS"
|
|
43
|
-
These options control whether output is written to
|
|
43
|
+
These options control whether output is written to file(s), standard output, or directly to a man pager\.
|
|
44
44
|
.
|
|
45
45
|
.TP
|
|
46
46
|
\fB\-m\fR, \fB\-\-man\fR
|
|
@@ -91,7 +91,7 @@ The name of the group, organization, or individual responsible for publishing th
|
|
|
91
91
|
The document\'s published date; \fIdate\fR must be formatted \fBYYYY\-MM\-DD\fR and is displayed in the bottom\-center footer area\. The \fIfile\fR mtime is used when no \fIdate\fR is given, or the current time when no \fIfile\fR is available\.
|
|
92
92
|
.
|
|
93
93
|
.P
|
|
94
|
-
HTML output can be customized
|
|
94
|
+
HTML output can be customized through the use of CSS stylesheets:
|
|
95
95
|
.
|
|
96
96
|
.TP
|
|
97
97
|
\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\.\.\.
|
|
@@ -117,10 +117,42 @@ Show troff warnings on standard error when performing roff conversion\. Warnings
|
|
|
117
117
|
\fB\-W\fR
|
|
118
118
|
Disable troff warnings\. Warnings are disabled by default\. This option can be used to revert the effect of a previous \fB\-w\fR argument\.
|
|
119
119
|
.
|
|
120
|
+
.TP
|
|
121
|
+
\fB\-v\fR, \fB\-\-version\fR
|
|
122
|
+
Show ronn version and exit\.
|
|
123
|
+
.
|
|
124
|
+
.SH "LINK INDEXES"
|
|
125
|
+
When generating HTML output, \fBronn\fR hyperlinks manual references (like \fBgrep(1)\fR, \fBls(1)\fR, \fBmarkdown(7)\fR) in source text based on reference name to URL mappings defined in an \fBindex\.txt\fR file\. Each line of the index file describes a single reference link, with whitespace separating the reference\'s \fIid\fR from its \fIlocation\fR\. Blank lines are allowed; lines beginning with a \fB#\fR character are ignored:
|
|
126
|
+
.
|
|
127
|
+
.IP "" 4
|
|
128
|
+
.
|
|
129
|
+
.nf
|
|
130
|
+
|
|
131
|
+
# manuals included in this project:
|
|
132
|
+
whisky(1) whisky\.1\.ronn
|
|
133
|
+
tango(5) tango\.5\.ronn
|
|
134
|
+
|
|
135
|
+
# external manuals
|
|
136
|
+
grep(1) http://man\.cx/grep(1)
|
|
137
|
+
ls(1) http://man\.cx/ls(1)
|
|
138
|
+
|
|
139
|
+
# other URLs for use with markdown reference links
|
|
140
|
+
src http://github\.com/
|
|
141
|
+
.
|
|
142
|
+
.fi
|
|
143
|
+
.
|
|
144
|
+
.IP "" 0
|
|
145
|
+
.
|
|
146
|
+
.P
|
|
147
|
+
The \fIlocation\fR is an absolute or relative URL that usually points at an HTML version of manpage\. It\'s possible to define references for things that aren\'t manpages\.
|
|
148
|
+
.
|
|
149
|
+
.P
|
|
150
|
+
All manuals in an individual directory share the references defined in that directory\'s \fBindex\.txt\fR file\. Index references may be used explicitly in Markdown reference style links using the syntax: \fB[\fR\fItext\fR\fB][\fR\fIid\fR\fB]\fR, where \fItext\fR is the link text and \fIid\fR is a reference name defined in the index\.
|
|
151
|
+
.
|
|
120
152
|
.SH "STYLES"
|
|
121
153
|
The \fB\-\-style\fR option selects a list of CSS stylesheets to include in the generated HTML\. Styles are applied in the order defined, so each can use the cascade to override previously defined styles\.
|
|
122
154
|
.
|
|
123
|
-
.SS "
|
|
155
|
+
.SS "Builtin Stylesheets"
|
|
124
156
|
These styles are included with the distribution:
|
|
125
157
|
.
|
|
126
158
|
.TP
|
|
@@ -167,7 +199,7 @@ The heading and footing, respectively\.
|
|
|
167
199
|
The main \fB<h1>\fR element\. Hidden by default unless the manual has no \fIname\fR or \fIsection\fR attributes\.
|
|
168
200
|
.
|
|
169
201
|
.P
|
|
170
|
-
See the
|
|
202
|
+
See the builtin style sources \fIhttp://github\.com/rtomayko/ronn/tree/master/lib/ronn/template\fR for examples\.
|
|
171
203
|
.
|
|
172
204
|
.SH "EXAMPLES"
|
|
173
205
|
Build roff and HTML output files and view the roff manpage using man(1):
|
|
@@ -287,7 +319,7 @@ Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
|
|
|
287
319
|
\fBRonn\fR is written in Ruby and depends on hpricot and rdiscount, extension libraries that are non\-trivial to install on some systems\. A more portable version of this program would be welcome\.
|
|
288
320
|
.
|
|
289
321
|
.SH "COPYRIGHT"
|
|
290
|
-
Ronn is Copyright (C) 2009 Ryan Tomayko
|
|
322
|
+
Ronn is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR
|
|
291
323
|
.
|
|
292
324
|
.SH "SEE ALSO"
|
|
293
|
-
ronn(
|
|
325
|
+
ronn\-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
|