ronn-ng 0.10.0.pre.SNAPSHOT → 0.10.1.pre1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES +6 -1
- data/Gemfile.lock +70 -0
- data/README.md +40 -30
- data/lib/ronn.rb +1 -1
- data/lib/ronn/roff.rb +4 -0
- data/man/ronn-format.7 +7 -7
- data/man/ronn.1 +20 -20
- data/ronn-ng.gemspec +12 -2
- data/test/angle_bracket_syntax.roff +24 -0
- data/test/code_blocks.html +38 -0
- data/test/code_blocks.roff +38 -0
- data/test/code_blocks_regression +19 -0
- data/test/code_blocks_regression.html +38 -0
- data/test/code_blocks_regression.ronn +40 -0
- data/test/single_quotes.html +11 -0
- data/test/single_quotes.roff +5 -0
- data/test/single_quotes.ronn +9 -0
- data/test/test_ronn.rb +8 -8
- metadata +12 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 717e3056a1751d795f7584cdc1024e2b3f391ab1fad7a415f92384e2c09466fb
|
|
4
|
+
data.tar.gz: 6bfc3273ec1218c858248fe7783db4280f7bee0330b2deaf1673210ad1c0b1a0
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: afaf5a115cf75430f54f4699d2cc693172c358c5e2d8d4e86517bed361e5950066a0a923579b1e2aa660fdcedc317f565382e32adf109b51e3531e5e2af7d414
|
|
7
|
+
data.tar.gz: 20a63fce583758ce3ec9330a7550e451a735402997fe71f9d59fb90ce51bd2b7c8d7a94310d872173232d3012187a2423606f0daf689215e65fa61d1c99d6398
|
data/CHANGES
CHANGED
|
@@ -1,14 +1,19 @@
|
|
|
1
1
|
Ronn-NG CHANGES
|
|
2
2
|
===============
|
|
3
3
|
|
|
4
|
-
Version 0.10.
|
|
4
|
+
Version 0.10.1 (in progress)
|
|
5
5
|
----------------------------
|
|
6
6
|
|
|
7
7
|
* Switch to GitHub Flavored Markdown, fixing code block rendering (<https://github.com/apjanke/ronn-ng/pull/53>)
|
|
8
8
|
* Revert `\[ci]` back to `\(bu)` (<https://github.com/apjanke/ronn-ng/pull/51>)
|
|
9
9
|
* Minor fix to single-quote escaping (<https://github.com/apjanke/ronn-ng/issues/55>)
|
|
10
|
+
* Elide HTML comments when producing roff output (<https://github.com/apjanke/ronn-ng/issues/65>)
|
|
10
11
|
* Bump to mustache 1.x
|
|
11
12
|
|
|
13
|
+
Version 0.10.0 (never)
|
|
14
|
+
---------------------------
|
|
15
|
+
* Doesn't exist due to a RubyGems publishing mistake
|
|
16
|
+
|
|
12
17
|
Version 0.9.1 (2020 Apr 09)
|
|
13
18
|
---------------------------
|
|
14
19
|
|
data/Gemfile.lock
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
PATH
|
|
2
|
+
remote: .
|
|
3
|
+
specs:
|
|
4
|
+
ronn-ng (0.10.1.pre1)
|
|
5
|
+
kramdown (~> 2.1)
|
|
6
|
+
kramdown-parser-gfm (~> 1.0.1)
|
|
7
|
+
mustache (~> 1.0)
|
|
8
|
+
nokogiri (~> 1.9, >= 1.9.0)
|
|
9
|
+
|
|
10
|
+
GEM
|
|
11
|
+
remote: https://rubygems.org/
|
|
12
|
+
specs:
|
|
13
|
+
ast (2.4.1)
|
|
14
|
+
kramdown (2.3.0)
|
|
15
|
+
rexml
|
|
16
|
+
kramdown-parser-gfm (1.0.1)
|
|
17
|
+
kramdown (~> 2.0)
|
|
18
|
+
mini_portile2 (2.4.0)
|
|
19
|
+
mustache (1.1.1)
|
|
20
|
+
mustermann (1.1.1)
|
|
21
|
+
ruby2_keywords (~> 0.0.1)
|
|
22
|
+
nokogiri (1.10.10)
|
|
23
|
+
mini_portile2 (~> 2.4.0)
|
|
24
|
+
parallel (1.20.1)
|
|
25
|
+
parser (2.7.2.0)
|
|
26
|
+
ast (~> 2.4.1)
|
|
27
|
+
power_assert (1.2.0)
|
|
28
|
+
rack (2.2.3)
|
|
29
|
+
rack-protection (2.1.0)
|
|
30
|
+
rack
|
|
31
|
+
rainbow (3.0.0)
|
|
32
|
+
rake (12.3.3)
|
|
33
|
+
regexp_parser (2.0.1)
|
|
34
|
+
rexml (3.2.4)
|
|
35
|
+
rubocop (0.93.1)
|
|
36
|
+
parallel (~> 1.10)
|
|
37
|
+
parser (>= 2.7.1.5)
|
|
38
|
+
rainbow (>= 2.2.2, < 4.0)
|
|
39
|
+
regexp_parser (>= 1.8)
|
|
40
|
+
rexml
|
|
41
|
+
rubocop-ast (>= 0.6.0)
|
|
42
|
+
ruby-progressbar (~> 1.7)
|
|
43
|
+
unicode-display_width (>= 1.4.0, < 2.0)
|
|
44
|
+
rubocop-ast (1.3.0)
|
|
45
|
+
parser (>= 2.7.1.5)
|
|
46
|
+
ruby-progressbar (1.10.1)
|
|
47
|
+
ruby2_keywords (0.0.2)
|
|
48
|
+
sinatra (2.1.0)
|
|
49
|
+
mustermann (~> 1.0)
|
|
50
|
+
rack (~> 2.2)
|
|
51
|
+
rack-protection (= 2.1.0)
|
|
52
|
+
tilt (~> 2.0)
|
|
53
|
+
test-unit (3.3.7)
|
|
54
|
+
power_assert
|
|
55
|
+
tilt (2.0.10)
|
|
56
|
+
unicode-display_width (1.7.0)
|
|
57
|
+
|
|
58
|
+
PLATFORMS
|
|
59
|
+
ruby
|
|
60
|
+
|
|
61
|
+
DEPENDENCIES
|
|
62
|
+
rack (~> 2.2, >= 2.2.3)
|
|
63
|
+
rake (~> 12.3, >= 12.3.3)
|
|
64
|
+
ronn-ng!
|
|
65
|
+
rubocop (~> 0.88, >= 0.88.0)
|
|
66
|
+
sinatra (~> 2.0, >= 2.0.8)
|
|
67
|
+
test-unit (~> 3.3, >= 3.3.6)
|
|
68
|
+
|
|
69
|
+
BUNDLED WITH
|
|
70
|
+
2.1.4
|
data/README.md
CHANGED
|
@@ -14,13 +14,13 @@ detail.
|
|
|
14
14
|
The `*.ronn` files found in the [`man/`][1] directory show off a wide range of
|
|
15
15
|
ronn capabilities:
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
* [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) command -
|
|
18
|
+
[source file](http://github.com/apjanke/ronn-ng/blob/master/man/ronn.1.ronn),
|
|
19
|
+
[roff output](http://github.com/apjanke/ronn-ng/blob/master/man/ronn.1)
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
* [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) -
|
|
22
|
+
[source file](http://github.com/apjanke/ronn-ng/blob/master/man/ronn-format.7.ronn),
|
|
23
|
+
[roff output](http://github.com/apjanke/ronn-ng/blob/master/man/ronn-format.7)
|
|
24
24
|
|
|
25
25
|
[1]: http://github.com/apjanke/ronn-ng/tree/master/man
|
|
26
26
|
|
|
@@ -30,14 +30,14 @@ As an alternative, you might want to check out [pandoc](http://johnmacfarlane.ne
|
|
|
30
30
|
|
|
31
31
|
Install with Homebrew on macOS:
|
|
32
32
|
|
|
33
|
-
```
|
|
33
|
+
```bash
|
|
34
34
|
brew tap apjanke/ronn-ng
|
|
35
35
|
brew install ronn-ng
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
Install with `gem` anywhere that supports it:
|
|
39
39
|
|
|
40
|
-
```
|
|
40
|
+
```bash
|
|
41
41
|
gem install ronn-ng
|
|
42
42
|
```
|
|
43
43
|
|
|
@@ -47,74 +47,84 @@ See [INSTALLING.md](INSTALLING.md) for details on other systems and installation
|
|
|
47
47
|
|
|
48
48
|
Build roff and HTML output files for one or more input files:
|
|
49
49
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
50
|
+
```bash
|
|
51
|
+
$ ronn man/ronn.5.ronn
|
|
52
|
+
roff: man/ronn.5
|
|
53
|
+
html: man/ronn.5.html
|
|
54
|
+
```
|
|
53
55
|
|
|
54
56
|
Generate only a standalone HTML version of one or more files:
|
|
55
57
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
+
```bash
|
|
59
|
+
$ ronn --html man/markdown.5.ronn
|
|
60
|
+
html: man/markdown.5.html
|
|
61
|
+
```
|
|
58
62
|
|
|
59
63
|
Build roff versions of all ronn files in a directory:
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
```bash
|
|
66
|
+
$ ronn --roff man/*.ronn
|
|
67
|
+
```
|
|
62
68
|
|
|
63
69
|
View a ronn file as if it were a manpage without building intermediate files:
|
|
64
70
|
|
|
65
|
-
|
|
71
|
+
```bash
|
|
72
|
+
$ ronn --man man/markdown.5.ronn
|
|
73
|
+
```
|
|
66
74
|
|
|
67
75
|
View roff output with man(1):
|
|
68
76
|
|
|
69
|
-
|
|
77
|
+
```bash
|
|
78
|
+
$ man man/ronn.5
|
|
79
|
+
```
|
|
70
80
|
|
|
71
81
|
The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes
|
|
72
82
|
comprehensive documentation on `ronn` command line options.
|
|
73
83
|
|
|
74
84
|
## Background
|
|
75
85
|
|
|
76
|
-
Some think Unix manual pages are a poor and outdated form of documentation.
|
|
77
|
-
|
|
86
|
+
Some think Unix manual pages are a poor and outdated form of documentation. Ronn-NG
|
|
87
|
+
disagrees:
|
|
78
88
|
|
|
79
|
-
|
|
89
|
+
* Manpages follow a well defined structure that's immediately familiar. This
|
|
80
90
|
gives developers a starting point when documenting new tools, libraries, and
|
|
81
91
|
formats.
|
|
82
92
|
|
|
83
|
-
|
|
93
|
+
* Manpages get to the point. Because they're written in an inverted style, with
|
|
84
94
|
a SYNOPSIS section followed by additional detail, prose and references to
|
|
85
95
|
other sources of information, manpages provide the best of both cheat sheet
|
|
86
96
|
and reference style documentation.
|
|
87
97
|
|
|
88
|
-
|
|
98
|
+
* Historically, manpages use an extremely — unbelievably — limited set of
|
|
89
99
|
text formatting capabilities. You get a couple of headings, lists, bold,
|
|
90
100
|
underline and no more. This is a feature.
|
|
91
101
|
|
|
92
|
-
|
|
102
|
+
* Although two levels of section hierarchy are technically supported, most
|
|
93
103
|
manpages use only a single level. Unwieldy document hierarchies complicate
|
|
94
104
|
otherwise good documentation. Remember that Feynman covered all of physics
|
|
95
|
-
|
|
105
|
+
— heavenly bodies through QED — with only two levels of document hierarchy
|
|
96
106
|
(_The Feynman Lectures on Physics_, 1970).
|
|
97
107
|
|
|
98
|
-
|
|
108
|
+
* The classical terminal manpage display is typographically well thought out.
|
|
99
109
|
Big bold section headings, justified monospace text, nicely indented
|
|
100
110
|
paragraphs, intelligently aligned definition lists, and an informational
|
|
101
111
|
header and footer.
|
|
102
112
|
|
|
103
|
-
|
|
113
|
+
* Manpages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7).
|
|
104
114
|
HTML versions can use this to generate links between pages.
|
|
105
115
|
|
|
106
116
|
Unfortunately, figuring out how to create a manpage is a fairly tedious process.
|
|
107
117
|
The roff/mandoc/mdoc macro languages are highly extensible, fractured between
|
|
108
|
-
multiple dialects, and include a bunch of device
|
|
109
|
-
modern publishing tools.
|
|
118
|
+
multiple dialects, and include a bunch of device-specific stuff irrelevant to
|
|
119
|
+
modern publishing tools. Ronn aims to solve that problem.
|
|
110
120
|
|
|
111
121
|
## Requirements
|
|
112
122
|
|
|
113
|
-
Ruby 2.3 or newer.
|
|
123
|
+
Ruby 2.3 or newer, and gems as listed in `ronn-ng.gemspec`.
|
|
114
124
|
|
|
115
125
|
## Project Management
|
|
116
126
|
|
|
117
|
-
The project home page is at https://github.com/apjanke/ronn-ng
|
|
127
|
+
The project home page is at <https://github.com/apjanke/ronn-ng>. Bug reports,
|
|
118
128
|
feature requests, and patch submissions are welcome.
|
|
119
129
|
|
|
120
130
|
Ronn-NG was forked from the original Ronn project in 2018 after Ronn
|
|
@@ -127,7 +137,7 @@ MIT License.
|
|
|
127
137
|
|
|
128
138
|
Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about).
|
|
129
139
|
|
|
130
|
-
New Ronn-NG material is Copyright (C) 2018
|
|
140
|
+
New Ronn-NG material is Copyright (C) 2018-2020 [Andrew Janke](https://apjanke.net).
|
|
131
141
|
|
|
132
142
|
See the file LICENSE.txt for information of licensing and distribution.
|
|
133
143
|
|
data/lib/ronn.rb
CHANGED
data/lib/ronn/roff.rb
CHANGED
|
@@ -250,10 +250,14 @@ module Ronn
|
|
|
250
250
|
text = node.to_html.dup
|
|
251
251
|
write escape(text)
|
|
252
252
|
|
|
253
|
+
elsif node.comment?
|
|
254
|
+
# ignore HTML comments
|
|
255
|
+
|
|
253
256
|
elsif node.elem?
|
|
254
257
|
case node.name
|
|
255
258
|
when 'span'
|
|
256
259
|
inline_filter(node.children)
|
|
260
|
+
|
|
257
261
|
when 'code'
|
|
258
262
|
if child_of?(node, 'pre')
|
|
259
263
|
inline_filter(node.children)
|
data/man/ronn-format.7
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
.\" generated with Ronn-NG/v0.
|
|
2
|
-
.\" http://github.com/apjanke/ronn-ng/tree/0.
|
|
3
|
-
.TH "RONN\-FORMAT" "7" "December 2018" "Ronn-NG 0.
|
|
1
|
+
.\" generated with Ronn-NG/v0.10.1
|
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1.pre1
|
|
3
|
+
.TH "RONN\-FORMAT" "7" "December 2018" "Ronn-NG 0.10.1.pre1" "Ronn Manual"
|
|
4
4
|
.SH "NAME"
|
|
5
5
|
\fBronn\-format\fR \- manual authoring format based on Markdown
|
|
6
6
|
.SH "SYNOPSIS"
|
|
@@ -83,7 +83,7 @@ HEADING TEXT
|
|
|
83
83
|
.P
|
|
84
84
|
Section headings should be all uppercase and may not contain inline markup\.
|
|
85
85
|
.SH "INLINE MARKUP"
|
|
86
|
-
Manpages have a limited set of text formatting capabilities\. There
|
|
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:
|
|
87
87
|
.TP
|
|
88
88
|
\fB\e`backticks\e`\fR (markdown compatible)
|
|
89
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\.
|
|
@@ -97,7 +97,7 @@ User\-specified arguments, variables, or user input\. Typically displayed with \
|
|
|
97
97
|
\fB_\fR\fIunderbars\fR\fB_\fR (markdown compatible)
|
|
98
98
|
Emphasis\. May be used for literal option values\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<em>\fR\.
|
|
99
99
|
.P
|
|
100
|
-
Here is grep(1)
|
|
100
|
+
Here is grep(1)'s DESCRIPTION section represented in \fBronn\fR:
|
|
101
101
|
.IP "" 4
|
|
102
102
|
.nf
|
|
103
103
|
`Grep` searches the named input <FILE> (or standard input if
|
|
@@ -107,9 +107,9 @@ prints the matching lines\.
|
|
|
107
107
|
.fi
|
|
108
108
|
.IP "" 0
|
|
109
109
|
.SH "DEFINITION LISTS"
|
|
110
|
-
The definition list syntax is compatible with markdown
|
|
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\.
|
|
111
111
|
.P
|
|
112
|
-
An example definition list, taken from BSD test(1)
|
|
112
|
+
An example definition list, taken from BSD test(1)'s \fIDESCRIPTION\fR section:
|
|
113
113
|
.IP "" 4
|
|
114
114
|
.nf
|
|
115
115
|
The following primaries are used to construct expressions:
|
data/man/ronn.1
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
.\" generated with Ronn-NG/v0.
|
|
2
|
-
.\" http://github.com/apjanke/ronn-ng/tree/0.
|
|
3
|
-
.TH "RONN" "1" "January 2020" "Ronn-NG 0.
|
|
1
|
+
.\" generated with Ronn-NG/v0.10.1
|
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1.pre1
|
|
3
|
+
.TH "RONN" "1" "January 2020" "Ronn-NG 0.10.1.pre1" "Ronn Manual"
|
|
4
4
|
.SH "NAME"
|
|
5
5
|
\fBronn\fR \- convert markdown files to manpages
|
|
6
6
|
.SH "SYNOPSIS"
|
|
@@ -24,29 +24,29 @@ The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from f
|
|
|
24
24
|
.P
|
|
25
25
|
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\.
|
|
26
26
|
.SH "FILES"
|
|
27
|
-
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
|
|
27
|
+
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\.
|
|
28
28
|
.P
|
|
29
29
|
Source files must be in UTF\-8 encoding, or the encoding specified by the \fB\-E\fR/\fB\-\-encoding\fR option, regardless of the locale that \fBronn\fR is running under\.
|
|
30
30
|
.P
|
|
31
31
|
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\.
|
|
32
32
|
.SH "OPTIONS"
|
|
33
33
|
These options control whether output is written to file(s), standard output, or directly to a man pager\.
|
|
34
|
-
.IP "\
|
|
35
|
-
\fB\-m\fR, \fB\-\-man\fR: Don
|
|
36
|
-
.IP "\
|
|
37
|
-
\fB\-S\fR, \fB\-\-server\fR: Don
|
|
34
|
+
.IP "\(bu" 4
|
|
35
|
+
\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\.
|
|
36
|
+
.IP "\(bu" 4
|
|
37
|
+
\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\.
|
|
38
38
|
.IP
|
|
39
39
|
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
|
|
40
40
|
.IP
|
|
41
41
|
\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
|
|
42
|
-
.IP "\
|
|
42
|
+
.IP "\(bu" 4
|
|
43
43
|
\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\.
|
|
44
|
-
.IP "\
|
|
45
|
-
\fB\-\-pipe\fR: Don
|
|
46
|
-
.IP "\
|
|
44
|
+
.IP "\(bu" 4
|
|
45
|
+
\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\.
|
|
46
|
+
.IP "\(bu" 4
|
|
47
47
|
\fB\-o\fR=\fIdirectory\fR, \fB\-\-output\-dir\fR=\fIdirectory\fR: Write generated files to the specified directory instead of the default location\.
|
|
48
|
-
.IP "\
|
|
49
|
-
\fB\-E\fR=\fIencoding\fR, \fB\-\-encoding\fR=<encoding: Specify the encoding that input files are in\. Default is UTF\-8, regardless of user
|
|
48
|
+
.IP "\(bu" 4
|
|
49
|
+
\fB\-E\fR=\fIencoding\fR, \fB\-\-encoding\fR=<encoding: Specify the encoding that input files are in\. Default is UTF\-8, regardless of user's locale settings\. Input sent to STDIN is always treated as UTF\-8, regardless of whether \fB\-E\fR is passed\.
|
|
50
50
|
.IP "" 0
|
|
51
51
|
.P
|
|
52
52
|
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\.
|
|
@@ -69,7 +69,7 @@ The name of the manual this man page belongs to; \fImanual\fR is prominently dis
|
|
|
69
69
|
The name of the group, organization, or individual responsible for publishing the document; \fIname\fR is displayed in the bottom\-left footer area\.
|
|
70
70
|
.TP
|
|
71
71
|
\fB\-\-date\fR=\fIdate\fR
|
|
72
|
-
The document
|
|
72
|
+
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\.
|
|
73
73
|
.P
|
|
74
74
|
HTML output can be customized through the use of CSS stylesheets:
|
|
75
75
|
.TP
|
|
@@ -85,7 +85,7 @@ Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\.
|
|
|
85
85
|
Miscellaneous options:
|
|
86
86
|
.TP
|
|
87
87
|
\fB\-w\fR, \fB\-\-warnings\fR
|
|
88
|
-
Show troff warnings on standard error when performing roff conversion\. Warnings are most often the result of a bug in ronn
|
|
88
|
+
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\.
|
|
89
89
|
.TP
|
|
90
90
|
\fB\-W\fR
|
|
91
91
|
Disable troff warnings\. Warnings are disabled by default\. This option can be used to revert the effect of a previous \fB\-w\fR argument\.
|
|
@@ -93,7 +93,7 @@ Disable troff warnings\. Warnings are disabled by default\. This option can be u
|
|
|
93
93
|
\fB\-v\fR, \fB\-\-version\fR
|
|
94
94
|
Show ronn version and exit\.
|
|
95
95
|
.SH "LINK INDEXES"
|
|
96
|
-
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
|
|
96
|
+
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:
|
|
97
97
|
.IP "" 4
|
|
98
98
|
.nf
|
|
99
99
|
# manuals included in this project:
|
|
@@ -109,9 +109,9 @@ src http://github\.com/
|
|
|
109
109
|
.fi
|
|
110
110
|
.IP "" 0
|
|
111
111
|
.P
|
|
112
|
-
The \fIlocation\fR is an absolute or relative URL that usually points at an HTML version of manpage\. It
|
|
112
|
+
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\.
|
|
113
113
|
.P
|
|
114
|
-
All manuals in an individual directory share the references defined in that directory
|
|
114
|
+
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\.
|
|
115
115
|
.SH "STYLES"
|
|
116
116
|
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\.
|
|
117
117
|
.SS "Builtin Stylesheets"
|
|
@@ -217,7 +217,7 @@ The default manual date in \fBYYYY\-MM\-DD\fR format\. Displayed in the bottom\-
|
|
|
217
217
|
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\.
|
|
218
218
|
.TP
|
|
219
219
|
\fBMANPAGER\fR
|
|
220
|
-
The paging program used for man pages\. This is typically set to something like
|
|
220
|
+
The paging program used for man pages\. This is typically set to something like 'less \-is'\.
|
|
221
221
|
.TP
|
|
222
222
|
\fBPAGER\fR
|
|
223
223
|
Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
|
data/ronn-ng.gemspec
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Gem::Specification.new do |s|
|
|
2
2
|
s.name = 'ronn-ng'
|
|
3
|
-
s.version = '0.10.
|
|
4
|
-
s.date = '2020-
|
|
3
|
+
s.version = '0.10.1.pre1'
|
|
4
|
+
s.date = '2020-12-22'
|
|
5
5
|
s.required_ruby_version = '>= 2.4'
|
|
6
6
|
|
|
7
7
|
s.summary = 'Builds man pages from Markdown'
|
|
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
|
|
|
23
23
|
AUTHORS
|
|
24
24
|
CHANGES
|
|
25
25
|
Gemfile
|
|
26
|
+
Gemfile.lock
|
|
26
27
|
INSTALLING.md
|
|
27
28
|
LICENSE.txt
|
|
28
29
|
README.md
|
|
@@ -54,13 +55,19 @@ Gem::Specification.new do |s|
|
|
|
54
55
|
man/ronn.1.ronn
|
|
55
56
|
ronn-ng.gemspec
|
|
56
57
|
test/angle_bracket_syntax.html
|
|
58
|
+
test/angle_bracket_syntax.roff
|
|
57
59
|
test/angle_bracket_syntax.ronn
|
|
58
60
|
test/backticks.html
|
|
59
61
|
test/backticks.ronn
|
|
60
62
|
test/basic_document.html
|
|
61
63
|
test/basic_document.ronn
|
|
62
64
|
test/circumflexes.ronn
|
|
65
|
+
test/code_blocks.html
|
|
66
|
+
test/code_blocks.roff
|
|
63
67
|
test/code_blocks.ronn
|
|
68
|
+
test/code_blocks_regression
|
|
69
|
+
test/code_blocks_regression.html
|
|
70
|
+
test/code_blocks_regression.ronn
|
|
64
71
|
test/contest.rb
|
|
65
72
|
test/custom_title_document.html
|
|
66
73
|
test/custom_title_document.ronn
|
|
@@ -96,6 +103,9 @@ Gem::Specification.new do |s|
|
|
|
96
103
|
test/section_reference_links.html
|
|
97
104
|
test/section_reference_links.roff
|
|
98
105
|
test/section_reference_links.ronn
|
|
106
|
+
test/single_quotes.html
|
|
107
|
+
test/single_quotes.roff
|
|
108
|
+
test/single_quotes.ronn
|
|
99
109
|
test/tables.ronn
|
|
100
110
|
test/test_ronn.rb
|
|
101
111
|
test/test_ronn_document.rb
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
.TH "ANGLE_BRACKET_SYNTAX" "5" "January 1979" ""
|
|
2
|
+
.SH "NAME"
|
|
3
|
+
\fBangle_bracket_syntax\fR \- angle bracket syntax test
|
|
4
|
+
.P
|
|
5
|
+
A \fIWORD\fR in angle brackets is converted to \fIWORD\fR,
|
|
6
|
+
.IP "" 4
|
|
7
|
+
.nf
|
|
8
|
+
except when <WORD> is
|
|
9
|
+
part of a preformatted
|
|
10
|
+
code block,
|
|
11
|
+
.fi
|
|
12
|
+
.IP "" 0
|
|
13
|
+
.P
|
|
14
|
+
or when \fB<WORD>\fR is enclosed in backticks\.
|
|
15
|
+
.P
|
|
16
|
+
or when \fIWORD\fR has a
|
|
17
|
+
.SH "Escaping angle brackets"
|
|
18
|
+
You can escape <angle> <brackets> with backslashes, since we're using GitHub Flavored Markdown\.
|
|
19
|
+
.P
|
|
20
|
+
Example:
|
|
21
|
+
.P
|
|
22
|
+
\fBpxzgrep\fR [\fB\-p\fR<n>] [\fB\-V\fR] [<xzgrep options>] <pattern> <file1> <file2> [<more files>]
|
|
23
|
+
.P
|
|
24
|
+
(Though really you should just put that in a fenced code block\.)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
<div class='mp'>
|
|
2
|
+
|
|
3
|
+
<h1 id="Example-Code-Blocks">Example Code Blocks</h1>
|
|
4
|
+
<h2 id="Basic-code-block">Basic code block</h2>
|
|
5
|
+
|
|
6
|
+
<pre><code>Hello, world!
|
|
7
|
+
</code></pre>
|
|
8
|
+
|
|
9
|
+
<h2 id="Language-identified-code-blocks">Language-identified code blocks</h2>
|
|
10
|
+
|
|
11
|
+
<pre><code class="language-html"><html>
|
|
12
|
+
<head>
|
|
13
|
+
<title>Hello, world!</title>
|
|
14
|
+
</head>
|
|
15
|
+
<body>
|
|
16
|
+
Hello, world!
|
|
17
|
+
</body>
|
|
18
|
+
</html>
|
|
19
|
+
</code></pre>
|
|
20
|
+
|
|
21
|
+
<h2 id="Interspersed-code-blocks-and-text">Interspersed code blocks and text</h2>
|
|
22
|
+
|
|
23
|
+
<p>Some text.</p>
|
|
24
|
+
|
|
25
|
+
<pre><code>Some code.
|
|
26
|
+
</code></pre>
|
|
27
|
+
|
|
28
|
+
<p>Here's some <pre> text.</p>
|
|
29
|
+
|
|
30
|
+
<pre>
|
|
31
|
+
This is pre text.
|
|
32
|
+
</pre>
|
|
33
|
+
|
|
34
|
+
<p>Some more text.</p>
|
|
35
|
+
|
|
36
|
+
<pre><code>Some more code.
|
|
37
|
+
</code></pre>
|
|
38
|
+
</div>
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
.TH "CODE_BLOCKS" "" "January 1979" ""
|
|
2
|
+
.SH "Basic code block"
|
|
3
|
+
.nf
|
|
4
|
+
Hello, world!
|
|
5
|
+
.fi
|
|
6
|
+
.SH "Language\-identified code blocks"
|
|
7
|
+
.nf
|
|
8
|
+
<html>
|
|
9
|
+
<head>
|
|
10
|
+
<title>Hello, world!</title>
|
|
11
|
+
</head>
|
|
12
|
+
<body>
|
|
13
|
+
Hello, world!
|
|
14
|
+
</body>
|
|
15
|
+
</html>
|
|
16
|
+
.fi
|
|
17
|
+
.SH "Interspersed code blocks and text"
|
|
18
|
+
Some text\.
|
|
19
|
+
.IP "" 4
|
|
20
|
+
.nf
|
|
21
|
+
Some code\.
|
|
22
|
+
.fi
|
|
23
|
+
.IP "" 0
|
|
24
|
+
.P
|
|
25
|
+
Here's some <pre> text\.
|
|
26
|
+
.IP "" 4
|
|
27
|
+
.nf
|
|
28
|
+
This is pre text\.
|
|
29
|
+
.fi
|
|
30
|
+
.IP "" 0
|
|
31
|
+
.P
|
|
32
|
+
Some more text\.
|
|
33
|
+
.IP "" 4
|
|
34
|
+
.nf
|
|
35
|
+
Some more code\.
|
|
36
|
+
.fi
|
|
37
|
+
.IP "" 0
|
|
38
|
+
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
.\" generated with Ronn-NG/v0.9.1
|
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
|
|
3
|
+
.TH "CODE_BLOCKS_REGRESSION" "" "July 2020" ""
|
|
4
|
+
.SH "In the text:"
|
|
5
|
+
This is Renzo\'s code\.
|
|
6
|
+
.P
|
|
7
|
+
Debian\'s lintian returns the following warning: acute\-accent\-in\-manual\-page
|
|
8
|
+
.P
|
|
9
|
+
This manual page uses the \' groff sequence\. Usually, the intent to generate an apostrophe, but that sequence actually renders as a an acute accent\.
|
|
10
|
+
.P
|
|
11
|
+
For an apostrophe or a single closing quote, use plain \'\. For single opening quote, i\.e\. a straight downward line \' like the one used in shell commands, use \e(aq\.
|
|
12
|
+
.SH "Basic code block"
|
|
13
|
+
The situation is even worse when there are code blocks, mainly code chunks or commands\. E\.g\., copy\-paste fails\.
|
|
14
|
+
.P
|
|
15
|
+
Type the following command \fBecho \'Hello World\'\fR\.
|
|
16
|
+
.P
|
|
17
|
+
\fBbash $ echo \'hello world\'\fR
|
|
18
|
+
.P
|
|
19
|
+
The following code cannot be compiled: \fBC int main() { int example = 42; switch (example) { case \'a\': return 10; default: return 42; } }\fR
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
<div class='mp'>
|
|
2
|
+
|
|
3
|
+
<h1 id="Example-Quote-Error">Example Quote Error</h1>
|
|
4
|
+
<h2 id="In-the-text-">In the text:</h2>
|
|
5
|
+
|
|
6
|
+
<p>This is Renzo's code.</p>
|
|
7
|
+
|
|
8
|
+
<p>Debian's lintian returns the following warning:
|
|
9
|
+
acute-accent-in-manual-page</p>
|
|
10
|
+
|
|
11
|
+
<p>This manual page uses the ' groff sequence. Usually, the intent to
|
|
12
|
+
generate an apostrophe, but that sequence actually renders as a an acute
|
|
13
|
+
accent.</p>
|
|
14
|
+
|
|
15
|
+
<p>For an apostrophe or a single closing quote, use plain '. For single
|
|
16
|
+
opening quote, i.e. a straight downward line ' like the one used in
|
|
17
|
+
shell commands, use \(aq.</p>
|
|
18
|
+
|
|
19
|
+
<h2 id="Basic-code-block">Basic code block</h2>
|
|
20
|
+
|
|
21
|
+
<p>The situation is even worse when there are code blocks, mainly code
|
|
22
|
+
chunks or commands. E.g., copy-paste fails.</p>
|
|
23
|
+
|
|
24
|
+
<p>Type the following command <code>echo 'Hello World'</code>.</p>
|
|
25
|
+
|
|
26
|
+
<pre><code class="language-bash">$ echo 'hello world'
|
|
27
|
+
</code></pre>
|
|
28
|
+
|
|
29
|
+
<p>The following code cannot be compiled:</p>
|
|
30
|
+
<pre><code class="language-C">int main() {
|
|
31
|
+
int example = 42;
|
|
32
|
+
switch (example) {
|
|
33
|
+
case 'a': return 10;
|
|
34
|
+
default: return 42;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
</code></pre>
|
|
38
|
+
</div>
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
Example Quote Error
|
|
2
|
+
===================
|
|
3
|
+
|
|
4
|
+
## In the text:
|
|
5
|
+
|
|
6
|
+
This is Renzo's code.
|
|
7
|
+
|
|
8
|
+
Debian's lintian returns the following warning:
|
|
9
|
+
acute-accent-in-manual-page
|
|
10
|
+
|
|
11
|
+
This manual page uses the \' groff sequence. Usually, the intent to
|
|
12
|
+
generate an apostrophe, but that sequence actually renders as a an acute
|
|
13
|
+
accent.
|
|
14
|
+
|
|
15
|
+
For an apostrophe or a single closing quote, use plain '. For single
|
|
16
|
+
opening quote, i.e. a straight downward line ' like the one used in
|
|
17
|
+
shell commands, use \(aq.
|
|
18
|
+
|
|
19
|
+
## Basic code block
|
|
20
|
+
|
|
21
|
+
The situation is even worse when there are code blocks, mainly code
|
|
22
|
+
chunks or commands. E.g., copy-paste fails.
|
|
23
|
+
|
|
24
|
+
Type the following command `echo 'Hello World'`.
|
|
25
|
+
|
|
26
|
+
``` bash
|
|
27
|
+
$ echo 'hello world'
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The following code cannot be compiled:
|
|
31
|
+
``` C
|
|
32
|
+
int main() {
|
|
33
|
+
int example = 42;
|
|
34
|
+
switch (example) {
|
|
35
|
+
case 'a': return 10;
|
|
36
|
+
default: return 42;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<div class='mp'>
|
|
2
|
+
|
|
3
|
+
<h1 id="Single-quotes">Single quotes</h1>
|
|
4
|
+
<h2 id="Single-quote-at-beginning-of-line">Single quote at beginning of line</h2>
|
|
5
|
+
|
|
6
|
+
<p>'This phrase should appear as normal, starting with a single quote.'</p>
|
|
7
|
+
|
|
8
|
+
<h2 id="Quotes-in-middle-of-line">Quotes in middle of line</h2>
|
|
9
|
+
|
|
10
|
+
<p>When you've got single quotes (') in a line, they're regular quotes.</p>
|
|
11
|
+
</div>
|
data/test/test_ronn.rb
CHANGED
|
@@ -88,10 +88,10 @@ class RonnTest < Test::Unit::TestCase
|
|
|
88
88
|
test File.basename(source, '.ronn') + ' HTML' do
|
|
89
89
|
output = `ronn --pipe --html --fragment #{source}`
|
|
90
90
|
expected = begin
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
91
|
+
File.read(dest)
|
|
92
|
+
rescue IOError
|
|
93
|
+
''
|
|
94
|
+
end
|
|
95
95
|
if expected != output
|
|
96
96
|
flunk_with_diff(dest, wrong, output)
|
|
97
97
|
elsif File.exist?(wrong)
|
|
@@ -110,10 +110,10 @@ class RonnTest < Test::Unit::TestCase
|
|
|
110
110
|
output = `ronn --pipe --roff --date=1979-01-01 #{source}`
|
|
111
111
|
.split("\n", 3).last # remove ronn version comments
|
|
112
112
|
expected = begin
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
113
|
+
File.read(dest)
|
|
114
|
+
rescue IOError
|
|
115
|
+
''
|
|
116
|
+
end
|
|
117
117
|
if expected != output
|
|
118
118
|
flunk_with_diff(dest, wrong, output)
|
|
119
119
|
elsif File.exist?(wrong)
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: ronn-ng
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.10.
|
|
4
|
+
version: 0.10.1.pre1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Andrew Janke
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2020-
|
|
11
|
+
date: 2020-12-22 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: kramdown
|
|
@@ -184,6 +184,7 @@ files:
|
|
|
184
184
|
- AUTHORS
|
|
185
185
|
- CHANGES
|
|
186
186
|
- Gemfile
|
|
187
|
+
- Gemfile.lock
|
|
187
188
|
- INSTALLING.md
|
|
188
189
|
- LICENSE.txt
|
|
189
190
|
- README.md
|
|
@@ -215,13 +216,19 @@ files:
|
|
|
215
216
|
- man/ronn.1.ronn
|
|
216
217
|
- ronn-ng.gemspec
|
|
217
218
|
- test/angle_bracket_syntax.html
|
|
219
|
+
- test/angle_bracket_syntax.roff
|
|
218
220
|
- test/angle_bracket_syntax.ronn
|
|
219
221
|
- test/backticks.html
|
|
220
222
|
- test/backticks.ronn
|
|
221
223
|
- test/basic_document.html
|
|
222
224
|
- test/basic_document.ronn
|
|
223
225
|
- test/circumflexes.ronn
|
|
226
|
+
- test/code_blocks.html
|
|
227
|
+
- test/code_blocks.roff
|
|
224
228
|
- test/code_blocks.ronn
|
|
229
|
+
- test/code_blocks_regression
|
|
230
|
+
- test/code_blocks_regression.html
|
|
231
|
+
- test/code_blocks_regression.ronn
|
|
225
232
|
- test/contest.rb
|
|
226
233
|
- test/custom_title_document.html
|
|
227
234
|
- test/custom_title_document.ronn
|
|
@@ -257,6 +264,9 @@ files:
|
|
|
257
264
|
- test/section_reference_links.html
|
|
258
265
|
- test/section_reference_links.roff
|
|
259
266
|
- test/section_reference_links.ronn
|
|
267
|
+
- test/single_quotes.html
|
|
268
|
+
- test/single_quotes.roff
|
|
269
|
+
- test/single_quotes.ronn
|
|
260
270
|
- test/tables.ronn
|
|
261
271
|
- test/test_ronn.rb
|
|
262
272
|
- test/test_ronn_document.rb
|