ronn-ng 0.7.4 → 0.8.0.SNAPSHOT
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES +12 -3
- data/Gemfile +2 -0
- data/INSTALLING.md +100 -0
- data/README.md +19 -1
- data/Rakefile +39 -49
- data/bin/ronn +93 -75
- data/completion/bash/ronn +32 -0
- data/completion/zsh/_ronn +24 -0
- data/config.ru +3 -3
- data/lib/ronn/document.rb +127 -106
- data/lib/ronn/index.rb +8 -9
- data/lib/ronn/roff.rb +153 -76
- data/lib/ronn/server.rb +19 -22
- data/lib/ronn/template.rb +27 -26
- data/lib/ronn/utils.rb +9 -7
- data/lib/ronn.rb +5 -3
- data/man/ronn-format.7 +6 -62
- data/man/ronn.1 +21 -123
- data/man/ronn.1.ronn +8 -0
- data/ronn-ng.gemspec +38 -13
- data/test/angle_bracket_syntax.html +4 -5
- data/test/backticks.html +14 -0
- data/test/backticks.ronn +10 -0
- data/test/basic_document.html +3 -4
- data/test/basic_document.ronn +2 -2
- data/test/circumflexes.ronn +1 -0
- data/test/code_blocks.7.ronn +41 -0
- data/test/contest.rb +56 -54
- data/test/custom_title_document.html +2 -2
- data/test/definition_list_syntax.html +13 -9
- data/test/definition_list_syntax.roff +2 -9
- data/test/definition_list_syntax.ronn +2 -2
- data/test/dots_at_line_start_test.roff +12 -3
- data/test/dots_at_line_start_test.ronn +8 -0
- data/test/ellipses.roff +7 -0
- data/test/ellipses.ronn +7 -0
- data/test/entity_encoding_test.html +13 -14
- data/test/entity_encoding_test.roff +1 -22
- data/test/entity_encoding_test.ronn +1 -1
- data/test/markdown_syntax.html +4 -5
- data/test/markdown_syntax.roff +1 -561
- data/test/middle_paragraph.html +2 -3
- data/test/middle_paragraph.roff +1 -5
- data/test/middle_paragraph.ronn +1 -1
- data/test/missing_spaces.roff +0 -2
- data/test/nested_list.ronn +19 -0
- data/test/nested_list_with_code.html +15 -0
- data/test/nested_list_with_code.roff +11 -0
- data/test/nested_list_with_code.ronn +6 -0
- data/test/page.with.periods.in.name.5.ronn +4 -0
- data/test/pre_block_with_quotes.roff +0 -5
- data/test/section_reference_links.html +2 -3
- data/test/section_reference_links.roff +1 -4
- data/test/section_reference_links.ronn +1 -1
- data/test/tables.ronn +24 -0
- data/test/test_ronn.rb +49 -35
- data/test/test_ronn_document.rb +81 -81
- data/test/test_ronn_index.rb +11 -11
- data/test/titleless_document.html +0 -1
- data/test/underline_spacing_test.roff +0 -8
- metadata +140 -22
- data/INSTALLING +0 -20
data/man/ronn-format.7
CHANGED
@@ -1,21 +1,16 @@
|
|
1
|
-
.\" generated with Ronn/v0.
|
2
|
-
.\" http://github.com/
|
3
|
-
.
|
4
|
-
.TH "RONN\-FORMAT" "7" "June 2010" "Ronn 0.7.0" "Ronn Manual"
|
5
|
-
.
|
1
|
+
.\" generated with Ronn-NG/v0.8.0
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.8.0-SNAPSHOT
|
3
|
+
.TH "RONN\-FORMAT" "7" "December 2018" "Ronn-NG 0.8.0-SNAPSHOT" "Ronn Manual"
|
6
4
|
.SH "NAME"
|
7
5
|
\fBronn\-format\fR \- manual authoring format based on Markdown
|
8
|
-
.
|
9
6
|
.SH "SYNOPSIS"
|
10
|
-
.
|
11
7
|
.nf
|
12
|
-
|
13
8
|
name(1) \-\- short, single\-sentence description
|
14
9
|
=============================================
|
15
10
|
|
16
11
|
## SYNOPSIS
|
17
12
|
|
18
|
-
`name` [<optional
|
13
|
+
`name` [<optional>\|\.\|\.\|\.] <flags>
|
19
14
|
|
20
15
|
## DESCRIPTION
|
21
16
|
|
@@ -53,110 +48,70 @@ Frequently used sections:
|
|
53
48
|
## AUTHOR
|
54
49
|
## COPYRIGHT
|
55
50
|
## SEE ALSO
|
56
|
-
.
|
57
51
|
.fi
|
58
|
-
.
|
59
52
|
.SH "DESCRIPTION"
|
60
53
|
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\.
|
61
|
-
.
|
62
54
|
.P
|
63
55
|
Not all roff(7) typesetting features can be expressed using ronn syntax\.
|
64
|
-
.
|
65
56
|
.SH "MANPAGE TITLE"
|
66
57
|
Manpages have a \fIname\fR, \fIsection\fR, and a one\-line \fIdescription\fR\. Files must start with a level one heading defining these attributes:
|
67
|
-
.
|
68
58
|
.IP "" 4
|
69
|
-
.
|
70
59
|
.nf
|
71
|
-
|
72
60
|
ls(1) \-\- list directory contents
|
73
61
|
================================
|
74
|
-
.
|
75
62
|
.fi
|
76
|
-
.
|
77
63
|
.IP "" 0
|
78
|
-
.
|
79
64
|
.P
|
80
|
-
Indicates that the manpage is named \fBls\fR in manual section \fB1\fR (
|
81
|
-
.
|
65
|
+
Indicates that the manpage is named \fBls\fR in manual section \fB1\fR ("user commands")\.
|
82
66
|
.SH "SECTION HEADINGS"
|
83
67
|
Man section headings are expressed with markdown level two headings\. There are two syntaxes for level two headings\.
|
84
|
-
.
|
85
68
|
.P
|
86
69
|
Hash prefix syntax:
|
87
|
-
.
|
88
70
|
.IP "" 4
|
89
|
-
.
|
90
71
|
.nf
|
91
|
-
|
92
72
|
## HEADING TEXT
|
93
|
-
.
|
94
73
|
.fi
|
95
|
-
.
|
96
74
|
.IP "" 0
|
97
|
-
.
|
98
75
|
.P
|
99
76
|
Dash underline syntax:
|
100
|
-
.
|
101
77
|
.IP "" 4
|
102
|
-
.
|
103
78
|
.nf
|
104
|
-
|
105
79
|
HEADING TEXT
|
106
80
|
\-\-\-\-\-\-\-\-\-\-\-\-
|
107
|
-
.
|
108
81
|
.fi
|
109
|
-
.
|
110
82
|
.IP "" 0
|
111
|
-
.
|
112
83
|
.P
|
113
84
|
Section headings should be all uppercase and may not contain inline markup\.
|
114
|
-
.
|
115
85
|
.SH "INLINE MARKUP"
|
116
86
|
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:
|
117
|
-
.
|
118
87
|
.TP
|
119
88
|
\fB`backticks`\fR (markdown compatible)
|
120
89
|
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\.
|
121
|
-
.
|
122
90
|
.TP
|
123
91
|
\fB**double\-stars**\fR (markdown compatible)
|
124
92
|
Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML output: \fB<strong>\fR\.
|
125
|
-
.
|
126
93
|
.TP
|
127
94
|
\fB<anglequotes>\fR (non\-compatible markdown extension)
|
128
95
|
User\-specified arguments, variables, or user input\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<var/>\fR\.
|
129
|
-
.
|
130
96
|
.TP
|
131
97
|
\fB_\fR\fIunderbars\fR\fB_\fR (markdown compatible)
|
132
98
|
Emphasis\. May be used for literal option values\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<em>\fR\.
|
133
|
-
.
|
134
99
|
.P
|
135
100
|
Here is grep(1)\'s DESCRIPTION section represented in \fBronn\fR:
|
136
|
-
.
|
137
101
|
.IP "" 4
|
138
|
-
.
|
139
102
|
.nf
|
140
|
-
|
141
103
|
`Grep` searches the named input <FILE> (or standard input if
|
142
104
|
no files are named, or the file name `\-` is given) for lines
|
143
105
|
containing a match to the given <PATTERN>\. By default, `grep`
|
144
106
|
prints the matching lines\.
|
145
|
-
.
|
146
107
|
.fi
|
147
|
-
.
|
148
108
|
.IP "" 0
|
149
|
-
.
|
150
109
|
.SH "DEFINITION LISTS"
|
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
|
152
|
-
.
|
110
|
+
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\.
|
153
111
|
.P
|
154
112
|
An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
|
155
|
-
.
|
156
113
|
.IP "" 4
|
157
|
-
.
|
158
114
|
.nf
|
159
|
-
|
160
115
|
The following primaries are used to construct expressions:
|
161
116
|
|
162
117
|
* `\-b` <file>:
|
@@ -167,21 +122,14 @@ An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
|
|
167
122
|
|
168
123
|
* `\-d` <file>:
|
169
124
|
True if file exists and is a directory\.
|
170
|
-
.
|
171
125
|
.fi
|
172
|
-
.
|
173
126
|
.IP "" 0
|
174
|
-
.
|
175
127
|
.SH "LINKS"
|
176
128
|
All markdown(7) linking features are supported\.
|
177
|
-
.
|
178
129
|
.P
|
179
130
|
Markdown reference\-style links can be used to link to specific sections by name:
|
180
|
-
.
|
181
131
|
.IP "" 4
|
182
|
-
.
|
183
132
|
.nf
|
184
|
-
|
185
133
|
## SECTION 1
|
186
134
|
|
187
135
|
See the following section\.
|
@@ -189,13 +137,9 @@ See the following section\.
|
|
189
137
|
## SECTION 2
|
190
138
|
|
191
139
|
See [SECTION 1][] or [to put it another way][SECTION 1]\.
|
192
|
-
.
|
193
140
|
.fi
|
194
|
-
.
|
195
141
|
.IP "" 0
|
196
|
-
.
|
197
142
|
.P
|
198
143
|
The anchor name would be \fB#SECTION\-1\fR and \fB#SECTION\-2\fR\. All non\-word characters are removed and spaces are replaced by dashes\.
|
199
|
-
.
|
200
144
|
.SH "SEE ALSO"
|
201
145
|
ronn(1), markdown(7), roff(7)
|
data/man/ronn.1
CHANGED
@@ -1,133 +1,95 @@
|
|
1
|
-
.\" generated with Ronn/v0.
|
2
|
-
.\" http://github.com/
|
3
|
-
.
|
4
|
-
.TH "RONN" "1" "June 2010" "Ronn 0.7.0" "Ronn Manual"
|
5
|
-
.
|
1
|
+
.\" generated with Ronn-NG/v0.8.0
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.8.0-SNAPSHOT
|
3
|
+
.TH "RONN" "1" "December 2018" "Ronn-NG 0.8.0-SNAPSHOT" "Ronn Manual"
|
6
4
|
.SH "NAME"
|
7
5
|
\fBronn\fR \- convert markdown files to manpages
|
8
|
-
.
|
9
6
|
.SH "SYNOPSIS"
|
10
|
-
\fBronn\fR [\fIformat\fR
|
11
|
-
.
|
7
|
+
\fBronn\fR [\fIformat\fR\|\.\|\.\|\.] \fIfile\fR\|\.\|\.\|\.
|
12
8
|
.br
|
13
|
-
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR
|
14
|
-
.
|
9
|
+
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\|\.\|\.\|\.
|
15
10
|
.br
|
16
|
-
\fBronn\fR \fB\-S\fR|\fB\-\-server\fR \fIfile\fR
|
17
|
-
.
|
11
|
+
\fBronn\fR \fB\-S\fR|\fB\-\-server\fR \fIfile\fR\|\.\|\.\|\.
|
18
12
|
.br
|
19
13
|
\fBronn\fR \fB\-\-pipe\fR \fIfile\fR
|
20
|
-
.
|
21
14
|
.br
|
22
15
|
\fBronn\fR < \fIfile\fR
|
23
|
-
.
|
24
16
|
.SH "DESCRIPTION"
|
25
17
|
\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
|
-
.
|
27
18
|
.P
|
28
19
|
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
|
-
.
|
30
20
|
.P
|
31
21
|
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
|
-
.
|
33
22
|
.P
|
34
23
|
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
|
-
.
|
36
24
|
.SH "FILES"
|
37
25
|
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
|
-
.
|
39
26
|
.P
|
40
27
|
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
|
-
.
|
42
28
|
.SH "OPTIONS"
|
43
29
|
These options control whether output is written to file(s), standard output, or directly to a man pager\.
|
44
|
-
.
|
45
|
-
|
46
|
-
\
|
47
|
-
Don\'t generate files,
|
48
|
-
.
|
49
|
-
.TP
|
50
|
-
\fB\-S\fR, \fB\-\-server\fR
|
51
|
-
Don\'t generate files, start an HTTP server at \fIhttp://localhost:1207/\fR and serve dynamically generated HTML for the set of input \fIfile\fRs\. A file named \fIexample\.2\.ronn\fR is served as \fI/example\.2\.html\fR\. There\'s also an index page at the root with links to each \fIfile\fR\.
|
52
|
-
.
|
30
|
+
.IP "\[ci]" 4
|
31
|
+
\fB\-m\fR, \fB\-\-man\fR: Don\'t generate files, display \fIfile\fRs as if man(1) were invoked on the roff output file\. This simulates default man behavior by piping the roff output through groff(1) and the paging program specified by the \fBMANPAGER\fR environment variable\.
|
32
|
+
.IP "\[ci]" 4
|
33
|
+
\fB\-S\fR, \fB\-\-server\fR: Don\'t generate files, start an HTTP server at \fIhttp://localhost:1207/\fR and serve dynamically generated HTML for the set of input \fIfile\fRs\. A file named \fIexample\.2\.ronn\fR is served as \fI/example\.2\.html\fR\. There\'s also an index page at the root with links to each \fIfile\fR\.
|
53
34
|
.IP
|
54
35
|
The server respects the \fB\-\-style\fR and document attribute options (\fB\-\-manual\fR, \fB\-\-date\fR, etc\.)\. These same options can be varied at request time by giving them as query parameters: \fB?manual=FOO&style=dark,toc\fR
|
55
|
-
.
|
56
36
|
.IP
|
57
37
|
\fINOTE: The builtin server is designed to assist in the process of writing and styling manuals\. It is in no way recommended as a general purpose web server\.\fR
|
58
|
-
.
|
59
|
-
|
60
|
-
\
|
61
|
-
Don\'t generate files, write generated output to standard output\. This is the default behavior when ronn source text is piped in on standard input and no \fIfile\fR arguments are provided\.
|
62
|
-
.
|
38
|
+
.IP "\[ci]" 4
|
39
|
+
\fB\-\-port\fR=\fIport\fR When used with \fB\-S\fR/\fB\-\-server\fR, runs the server at the specified port instead of the default port 1207\.
|
40
|
+
.IP "\[ci]" 4
|
41
|
+
\fB\-\-pipe\fR: Don\'t generate files, write generated output to standard output\. This is the default behavior when ronn source text is piped in on standard input and no \fIfile\fR arguments are provided\.
|
42
|
+
.IP "\[ci]" 4
|
43
|
+
\fB\-o\fR=\fIdirectory\fR, \fB\-\-output\-dir\fR=\fIdirectory\fR: Write generated files to the specified directory instead of the default location\.
|
44
|
+
.IP "" 0
|
63
45
|
.P
|
64
46
|
Format options control the files \fBronn\fR generates, or the output format when the \fB\-\-pipe\fR argument is specified\. When no format options are given, both \fB\-\-roff\fR and \fB\-\-html\fR are assumed\.
|
65
|
-
.
|
66
47
|
.TP
|
67
48
|
\fB\-r\fR, \fB\-\-roff\fR
|
68
49
|
Generate roff output\. This is the default behavior when no \fIfile\fRs are given and ronn source text is read from standard input\.
|
69
|
-
.
|
70
50
|
.TP
|
71
51
|
\fB\-5\fR, \fB\-\-html\fR
|
72
52
|
Generate output in HTML format\.
|
73
|
-
.
|
74
53
|
.TP
|
75
54
|
\fB\-f\fR, \fB\-\-fragment\fR
|
76
55
|
Generate output in HTML format but only the document fragment, not the header, title, or footer\.
|
77
|
-
.
|
78
56
|
.P
|
79
57
|
Document attributes displayed in the header and footer areas of generated content are specified with these options\. (These values may also be set via the \fIENVIRONMENT\fR\.)
|
80
|
-
.
|
81
58
|
.TP
|
82
59
|
\fB\-\-manual\fR=\fImanual\fR
|
83
60
|
The name of the manual this man page belongs to; \fImanual\fR is prominently displayed top\-center in the header area\.
|
84
|
-
.
|
85
61
|
.TP
|
86
62
|
\fB\-\-organization\fR=\fIname\fR
|
87
63
|
The name of the group, organization, or individual responsible for publishing the document; \fIname\fR is displayed in the bottom\-left footer area\.
|
88
|
-
.
|
89
64
|
.TP
|
90
65
|
\fB\-\-date\fR=\fIdate\fR
|
91
66
|
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
|
-
.
|
93
67
|
.P
|
94
68
|
HTML output can be customized through the use of CSS stylesheets:
|
95
|
-
.
|
96
69
|
.TP
|
97
|
-
\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]
|
70
|
+
\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\|\.\|\.\|\.
|
98
71
|
The list of CSS stylesheets to apply to the document\. Multiple \fImodule\fR arguments may be specified, but must be separated by commas or spaces\.
|
99
|
-
.
|
100
72
|
.IP
|
101
73
|
When \fImodule\fR is a simple word, search for files named \fImodule\fR\fB\.css\fR in all directories listed in the \fI\fBRONN_STYLE\fR\fR environment variable, and then search internal styles\.
|
102
|
-
.
|
103
74
|
.IP
|
104
75
|
When \fImodule\fR includes a \fI/\fR character, use it as the full path to a stylesheet file\.
|
105
|
-
.
|
106
76
|
.IP
|
107
77
|
Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\. See \fISTYLES\fR for descriptions of features added by each module\.
|
108
|
-
.
|
109
78
|
.P
|
110
79
|
Miscellaneous options:
|
111
|
-
.
|
112
80
|
.TP
|
113
81
|
\fB\-w\fR, \fB\-\-warnings\fR
|
114
82
|
Show troff warnings on standard error when performing roff conversion\. Warnings are most often the result of a bug in ronn\'s HTML to roff conversion logic\.
|
115
|
-
.
|
116
83
|
.TP
|
117
84
|
\fB\-W\fR
|
118
85
|
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
|
-
.
|
120
86
|
.TP
|
121
87
|
\fB\-v\fR, \fB\-\-version\fR
|
122
88
|
Show ronn version and exit\.
|
123
|
-
.
|
124
89
|
.SH "LINK INDEXES"
|
125
90
|
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
91
|
.IP "" 4
|
128
|
-
.
|
129
92
|
.nf
|
130
|
-
|
131
93
|
# manuals included in this project:
|
132
94
|
whisky(1) whisky\.1\.ronn
|
133
95
|
tango(5) tango\.5\.ronn
|
@@ -138,188 +100,124 @@ ls(1) http://man\.cx/ls(1)
|
|
138
100
|
|
139
101
|
# other URLs for use with markdown reference links
|
140
102
|
src http://github\.com/
|
141
|
-
.
|
142
103
|
.fi
|
143
|
-
.
|
144
104
|
.IP "" 0
|
145
|
-
.
|
146
105
|
.P
|
147
106
|
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
107
|
.P
|
150
108
|
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
|
-
.
|
152
109
|
.SH "STYLES"
|
153
110
|
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\.
|
154
|
-
.
|
155
111
|
.SS "Builtin Stylesheets"
|
156
112
|
These styles are included with the distribution:
|
157
|
-
.
|
158
113
|
.TP
|
159
114
|
\fBman\fR
|
160
115
|
Basic manpage styles: typography, definition lists, indentation\. This is always included regardless of \fB\-\-style\fR argument\. It is however possible to replace the default \fBman\fR module with a custom one by placing a \fBman\.css\fR file on the \fBRONN_STYLE\fR path\.
|
161
|
-
.
|
162
116
|
.TP
|
163
117
|
\fBprint\fR
|
164
118
|
Basic print stylesheet\. The generated \fB<style>\fR tag includes a \fBmedia=print\fR attribute\.
|
165
|
-
.
|
166
119
|
.TP
|
167
120
|
\fBtoc\fR
|
168
121
|
Enables the Table of Contents navigation\. The TOC markup is included in generated HTML by default but hidden with an inline \fBdisplay:none\fR style rule; the \fBtoc\fR module turns it on and applies basic TOC styles\.
|
169
|
-
.
|
170
122
|
.TP
|
171
123
|
\fBdark\fR
|
172
124
|
Light text on a dark background\.
|
173
|
-
.
|
174
125
|
.TP
|
175
126
|
\fB80c\fR
|
176
127
|
Changes the display width to mimic the display of a classic 80 character terminal\. The default display width causes lines to wrap at a gratuitous 100 characters\.
|
177
|
-
.
|
178
128
|
.SS "Custom Stylesheets"
|
179
129
|
Writing custom stylesheets is straight\-forward\. The following core selectors allow targeting all generated elements:
|
180
|
-
.
|
181
130
|
.TP
|
182
131
|
\fB\.mp\fR
|
183
132
|
The manual page container element\. Present on full documents and document fragments\.
|
184
|
-
.
|
185
133
|
.TP
|
186
134
|
\fBbody#manpage\fR
|
187
135
|
Signifies that the page was fully\-generated by Ronn and contains a single manual page (\fB\.mp\fR element)\.
|
188
|
-
.
|
189
136
|
.TP
|
190
137
|
\fB\.man\-decor\fR
|
191
138
|
The three\-item heading and footing elements both have this class\.
|
192
|
-
.
|
193
139
|
.TP
|
194
140
|
\fB\.man\-head\fR, \fB\.man\-foot\fR
|
195
141
|
The heading and footing, respectively\.
|
196
|
-
.
|
197
142
|
.TP
|
198
143
|
\fB\.man\-title\fR
|
199
144
|
The main \fB<h1>\fR element\. Hidden by default unless the manual has no \fIname\fR or \fIsection\fR attributes\.
|
200
|
-
.
|
201
145
|
.P
|
202
|
-
See the builtin style sources \fIhttp://github\.com/
|
203
|
-
.
|
146
|
+
See the builtin style sources \fIhttp://github\.com/apjanke/ronn\-ng/tree/master/lib/ronn/template\fR for examples\.
|
204
147
|
.SH "EXAMPLES"
|
205
148
|
Build roff and HTML output files and view the roff manpage using man(1):
|
206
|
-
.
|
207
149
|
.IP "" 4
|
208
|
-
.
|
209
150
|
.nf
|
210
|
-
|
211
151
|
$ ronn some\-great\-program\.1\.ronn
|
212
152
|
roff: some\-great\-program\.1
|
213
153
|
html: some\-great\-program\.1\.html
|
214
154
|
$ man \./some\-great\-program\.1
|
215
|
-
.
|
216
155
|
.fi
|
217
|
-
.
|
218
156
|
.IP "" 0
|
219
|
-
.
|
220
157
|
.P
|
221
158
|
Build only the roff manpage for all \fB\.ronn\fR files in the current directory:
|
222
|
-
.
|
223
159
|
.IP "" 4
|
224
|
-
.
|
225
160
|
.nf
|
226
|
-
|
227
161
|
$ ronn \-\-roff *\.ronn
|
228
162
|
roff: mv\.1
|
229
163
|
roff: ls\.1
|
230
164
|
roff: cd\.1
|
231
165
|
roff: sh\.1
|
232
|
-
.
|
233
166
|
.fi
|
234
|
-
.
|
235
167
|
.IP "" 0
|
236
|
-
.
|
237
168
|
.P
|
238
169
|
Build only the HTML manpage for a few files and apply the \fBdark\fR and \fBtoc\fR stylesheets:
|
239
|
-
.
|
240
170
|
.IP "" 4
|
241
|
-
.
|
242
171
|
.nf
|
243
|
-
|
244
172
|
$ ronn \-\-html \-\-style=dark,toc mv\.1\.ronn ls\.1\.ronn
|
245
173
|
html: mv\.1\.html
|
246
174
|
html: ls\.1\.html
|
247
|
-
.
|
248
175
|
.fi
|
249
|
-
.
|
250
176
|
.IP "" 0
|
251
|
-
.
|
252
177
|
.P
|
253
178
|
Generate roff output on standard output and write to file:
|
254
|
-
.
|
255
179
|
.IP "" 4
|
256
|
-
.
|
257
180
|
.nf
|
258
|
-
|
259
181
|
$ ronn <hello\.1\.ronn >hello\.1
|
260
|
-
.
|
261
182
|
.fi
|
262
|
-
.
|
263
183
|
.IP "" 0
|
264
|
-
.
|
265
184
|
.P
|
266
185
|
View a ronn file in the same way as man(1) without building a roff file:
|
267
|
-
.
|
268
186
|
.IP "" 4
|
269
|
-
.
|
270
187
|
.nf
|
271
|
-
|
272
188
|
$ ronn \-\-man hello\.1\.ronn
|
273
|
-
.
|
274
189
|
.fi
|
275
|
-
.
|
276
190
|
.IP "" 0
|
277
|
-
.
|
278
191
|
.P
|
279
192
|
Serve HTML manpages at \fIhttp://localhost:1207/\fR for all \fB*\.ronn\fR files under a \fBman/\fR directory:
|
280
|
-
.
|
281
193
|
.IP "" 4
|
282
|
-
.
|
283
194
|
.nf
|
284
|
-
|
285
195
|
$ ronn \-\-server man/*\.ronn
|
286
196
|
$ open http://localhost:1207/
|
287
|
-
.
|
288
197
|
.fi
|
289
|
-
.
|
290
198
|
.IP "" 0
|
291
|
-
.
|
292
199
|
.SH "ENVIRONMENT"
|
293
|
-
.
|
294
200
|
.TP
|
295
201
|
\fBRONN_MANUAL\fR
|
296
202
|
A default manual name to be displayed in the top\-center header area\. The \fB\-\-manual\fR option takes precedence over this value\.
|
297
|
-
.
|
298
203
|
.TP
|
299
204
|
\fBRONN_ORGANIZATION\fR
|
300
205
|
The default manual publishing group, organization, or individual to be displayed in the bottom\-left footer area\. The \fB\-\-organization\fR option takes precedence over this value\.
|
301
|
-
.
|
302
206
|
.TP
|
303
207
|
\fBRONN_DATE\fR
|
304
208
|
The default manual date in \fBYYYY\-MM\-DD\fR format\. Displayed in the bottom\-center footer area\. The \fB\-\-date\fR option takes precedence over this value\.
|
305
|
-
.
|
306
209
|
.TP
|
307
210
|
\fBRONN_STYLE\fR
|
308
211
|
A \fBPATH\fR\-style list of directories to check for stylesheets given to the \fB\-\-style\fR option\. Directories are separated by a \fI:\fR; blank entries are ignored\. Use \fI\.\fR to include the current working directory\.
|
309
|
-
.
|
310
212
|
.TP
|
311
213
|
\fBMANPAGER\fR
|
312
214
|
The paging program used for man pages\. This is typically set to something like \'less \-is\'\.
|
313
|
-
.
|
314
215
|
.TP
|
315
216
|
\fBPAGER\fR
|
316
217
|
Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
|
317
|
-
.
|
318
218
|
.SH "BUGS"
|
319
219
|
\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\.
|
320
|
-
.
|
321
220
|
.SH "COPYRIGHT"
|
322
|
-
Ronn is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR
|
323
|
-
.
|
221
|
+
Ronn\-NG is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR and (C) 2018 Andrew Janke \fIhttps://apjanke\.net\fR
|
324
222
|
.SH "SEE ALSO"
|
325
|
-
|
223
|
+
groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn\-format(7)
|
data/man/ronn.1.ronn
CHANGED
@@ -66,11 +66,19 @@ directly to a man pager.
|
|
66
66
|
and styling manuals. It is in no way recommended as a general purpose web
|
67
67
|
server.*
|
68
68
|
|
69
|
+
* `--port`=<port>
|
70
|
+
When used with `-S`/`--server`, runs the server at the specified port instead
|
71
|
+
of the default port 1207.
|
72
|
+
|
69
73
|
* `--pipe`:
|
70
74
|
Don't generate files, write generated output to standard output. This is the
|
71
75
|
default behavior when ronn source text is piped in on standard input and no
|
72
76
|
<file> arguments are provided.
|
73
77
|
|
78
|
+
* `-o`=<directory>, `--output-dir`=<directory>:
|
79
|
+
Write generated files to the specified directory instead of the default
|
80
|
+
location.
|
81
|
+
|
74
82
|
Format options control the files `ronn` generates, or the output format when the
|
75
83
|
`--pipe` argument is specified. When no format options are given, both `--roff`
|
76
84
|
and `--html` are assumed.
|
data/ronn-ng.gemspec
CHANGED
@@ -1,25 +1,34 @@
|
|
1
1
|
Gem::Specification.new do |s|
|
2
2
|
s.name = 'ronn-ng'
|
3
|
-
s.version = '0.
|
4
|
-
s.date = '2018-12-
|
3
|
+
s.version = '0.8.0.SNAPSHOT'
|
4
|
+
s.date = '2018-12-25'
|
5
5
|
|
6
|
-
s.summary =
|
7
|
-
s.description =
|
8
|
-
s.homepage =
|
9
|
-
s.license =
|
6
|
+
s.summary = 'Builds man pages from Markdown'
|
7
|
+
s.description = 'Ronn-NG builds manuals in HTML and Unix man page format from Markdown.'
|
8
|
+
s.homepage = 'https://github.com/apjanke/ronn-ng'
|
9
|
+
s.license = 'MIT'
|
10
10
|
|
11
|
-
s.authors = [
|
12
|
-
s.email =
|
11
|
+
s.authors = ['Andrew Janke']
|
12
|
+
s.email = 'floss@apjanke.net'
|
13
|
+
|
14
|
+
s.metadata = {
|
15
|
+
'bug_tracker_uri' => 'https://github.com/apjanke/ronn-ng/issues',
|
16
|
+
'source_code_uri' => 'https://github.com/apjanke/ronn-ng',
|
17
|
+
'changelog_uri' => 'https://github.com/apjanke/ronn-ng/blob/master/CHANGES'
|
18
|
+
}
|
13
19
|
|
14
20
|
# = MANIFEST =
|
15
21
|
s.files = %w[
|
16
22
|
AUTHORS
|
17
23
|
CHANGES
|
24
|
+
Gemfile
|
25
|
+
INSTALLING.md
|
18
26
|
LICENSE.txt
|
19
|
-
INSTALLING
|
20
27
|
README.md
|
21
28
|
Rakefile
|
22
29
|
bin/ronn
|
30
|
+
completion/bash/ronn
|
31
|
+
completion/zsh/_ronn
|
23
32
|
config.ru
|
24
33
|
lib/ronn.rb
|
25
34
|
lib/ronn/document.rb
|
@@ -45,8 +54,12 @@ Gem::Specification.new do |s|
|
|
45
54
|
ronn-ng.gemspec
|
46
55
|
test/angle_bracket_syntax.html
|
47
56
|
test/angle_bracket_syntax.ronn
|
57
|
+
test/backticks.html
|
58
|
+
test/backticks.ronn
|
48
59
|
test/basic_document.html
|
49
60
|
test/basic_document.ronn
|
61
|
+
test/circumflexes.ronn
|
62
|
+
test/code_blocks.7.ronn
|
50
63
|
test/contest.rb
|
51
64
|
test/custom_title_document.html
|
52
65
|
test/custom_title_document.ronn
|
@@ -55,6 +68,8 @@ Gem::Specification.new do |s|
|
|
55
68
|
test/definition_list_syntax.ronn
|
56
69
|
test/dots_at_line_start_test.roff
|
57
70
|
test/dots_at_line_start_test.ronn
|
71
|
+
test/ellipses.roff
|
72
|
+
test/ellipses.ronn
|
58
73
|
test/entity_encoding_test.html
|
59
74
|
test/entity_encoding_test.roff
|
60
75
|
test/entity_encoding_test.ronn
|
@@ -67,11 +82,17 @@ Gem::Specification.new do |s|
|
|
67
82
|
test/middle_paragraph.ronn
|
68
83
|
test/missing_spaces.roff
|
69
84
|
test/missing_spaces.ronn
|
85
|
+
test/nested_list.ronn
|
86
|
+
test/nested_list_with_code.html
|
87
|
+
test/nested_list_with_code.roff
|
88
|
+
test/nested_list_with_code.ronn
|
89
|
+
test/page.with.periods.in.name.5.ronn
|
70
90
|
test/pre_block_with_quotes.roff
|
71
91
|
test/pre_block_with_quotes.ronn
|
72
92
|
test/section_reference_links.html
|
73
93
|
test/section_reference_links.roff
|
74
94
|
test/section_reference_links.ronn
|
95
|
+
test/tables.ronn
|
75
96
|
test/test_ronn.rb
|
76
97
|
test/test_ronn_document.rb
|
77
98
|
test/test_ronn_index.rb
|
@@ -86,12 +107,16 @@ Gem::Specification.new do |s|
|
|
86
107
|
s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ }
|
87
108
|
|
88
109
|
s.extra_rdoc_files = %w[LICENSE.txt AUTHORS]
|
89
|
-
s.add_dependency 'hpricot', '~> 0.8', '>= 0.8.2'
|
90
|
-
s.add_dependency 'rdiscount', '~> 1.5', '>= 1.5.8'
|
91
110
|
s.add_dependency 'mustache', '~> 0.7', '>= 0.7.0'
|
111
|
+
s.add_dependency 'nokogiri', '~> 1.9', '>= 1.9.0'
|
112
|
+
s.add_dependency 'rdiscount', '~> 2.0', '>= 2.0.7'
|
113
|
+
s.add_development_dependency 'rack', '~> 2.0', '>= 2.0.6'
|
114
|
+
s.add_development_dependency 'rake', '~> 12.3', '>= 12.3.0'
|
115
|
+
s.add_development_dependency 'rubocop', '~> 0.60', '>= 0.57.1'
|
116
|
+
s.add_development_dependency 'sinatra', '~> 2.0', '>= 2.0.0'
|
117
|
+
s.add_development_dependency 'test-unit', '~> 3.2', '>= 3.2.7'
|
92
118
|
|
93
|
-
s.
|
94
|
-
s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ronn"]
|
119
|
+
s.rdoc_options = ['--line-numbers', '--inline-source', '--title', 'Ronn']
|
95
120
|
s.require_paths = %w[lib]
|
96
121
|
s.rubygems_version = '1.1.1'
|
97
122
|
end
|
@@ -1,18 +1,17 @@
|
|
1
1
|
<div class='mp'>
|
2
|
+
|
2
3
|
<h2 id="NAME">NAME</h2>
|
3
4
|
<p class="man-name">
|
4
5
|
<code>angle_bracket_syntax</code> - <span class="man-whatis">angle bracket syntax test</span>
|
5
6
|
</p>
|
6
|
-
|
7
7
|
<p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
|
8
8
|
|
9
|
-
<pre><code>except when <WORD
|
9
|
+
<pre><code>except when <WORD> is
|
10
10
|
part of a preformatted
|
11
11
|
code block,
|
12
12
|
</code></pre>
|
13
13
|
|
14
|
-
<p>or when <code><WORD
|
15
|
-
|
16
|
-
<p>or when <var>WORD</var> has a <dot.> or <foo:colon>.</p>
|
14
|
+
<p>or when <code><WORD></code> is enclosed in backticks.</p>
|
17
15
|
|
16
|
+
<p>or when <var>WORD</var> has a <dot.> or <foo:colon>.</p>
|
18
17
|
</div>
|
data/test/backticks.html
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
<div class='mp'>
|
2
|
+
|
3
|
+
<h2 id="NAME">NAME</h2>
|
4
|
+
<p class="man-name">
|
5
|
+
<code>backticks</code> - <span class="man-whatis">testing the link index with backticks</span>
|
6
|
+
</p>
|
7
|
+
<p><a class="man-ref" href="http://man.cx/grep(1)">grep<span class="s">(1)</span></a></p>
|
8
|
+
|
9
|
+
<p><a class="man-ref" href="http://man.cx/grep(1)"><code>grep</code><span class="s">(1)</span></a></p>
|
10
|
+
|
11
|
+
<p><span class="man-ref">man<span class="s">(1)</span></span></p>
|
12
|
+
|
13
|
+
<p><span class="man-ref"><code>man</code><span class="s">(1)</span></span></p>
|
14
|
+
</div>
|