md2man 1.3.0 → 1.3.1

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/EXAMPLE.png ADDED
Binary file
data/HISTORY.markdown CHANGED
@@ -1,3 +1,31 @@
1
+ ## Version 1.3.1 (2012-10-09)
2
+
3
+ Patch:
4
+
5
+ * roff: do not render references inside code blocks.
6
+
7
+ * roff: do not render references inside code spans.
8
+
9
+ * roff: fix single-line indented paragraph detection.
10
+
11
+ * roff: also indent block\_code just like block\_quote.
12
+
13
+ * roff: add paragraph above block\_quote for spacing.
14
+
15
+ * roff: render code blocks as paragraphs for spacing.
16
+
17
+ Otherwise there's not enough space between the previous paragraph and
18
+ the code block: it appears on the next line and appears ugly in man(1).
19
+
20
+ * document: make reference regexp match more manpages.
21
+
22
+ Other:
23
+
24
+ * document: stronger digest encoding using NUL bytes.
25
+
26
+ * document: super() can't reach Redcarpet's renderer classes.
27
+ See https://github.com/vmg/redcarpet/issues/51 for details.
28
+
1
29
  ## Version 1.3.0 (2012-09-27)
2
30
 
3
31
  Minor:
data/README.markdown CHANGED
@@ -18,9 +18,10 @@ documents into UNIX manual pages (really [Roff] documents) using [Redcarpet].
18
18
  Try converting [this example Markdown file][example] into a UNIX manual page:
19
19
 
20
20
  md2man EXAMPLE.markdown > EXAMPLE.1
21
- man EXAMPLE.1
21
+ man -l EXAMPLE.1
22
22
 
23
- ![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
23
+ ![Obligatory screenshot of md2man(1) in action!](
24
+ https://raw.github.com/sunaku/md2man/master/EXAMPLE.png)
24
25
 
25
26
  ### Limitations
26
27
 
@@ -42,9 +43,9 @@ It issues a warning when it encounters these instead. Patches are welcome!
42
43
 
43
44
  git clone git://github.com/sunaku/md2man
44
45
  cd md2man
45
- bundle install --binstubs=bundle_bin
46
- bundle_bin/md2man --help # run it directly
47
- bundle exec rake -T # packaging tasks
46
+ bundle install
47
+ bundle exec md2man --help # run it directly
48
+ bundle exec rake -T # packaging tasks
48
49
 
49
50
  ## Usage
50
51
 
data/bin/md2man CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env ruby
2
2
  =begin =======================================================================
3
3
 
4
- # MD2MAN 1 2012-09-27 1.3.0
4
+ # MD2MAN 1 2012-10-09 1.3.1
5
5
 
6
6
  ## NAME
7
7
 
@@ -43,8 +43,8 @@ The following [Redcarpet] extensions are enabled while processing markdown(7):
43
43
  * autolink
44
44
  * superscript
45
45
  * strikethrough
46
- * no_intra_emphasis
47
- * fenced_code_blocks
46
+ * no\_intra\_emphasis
47
+ * fenced\_code\_blocks
48
48
 
49
49
  ## OPTIONS
50
50
 
@@ -1,17 +1,47 @@
1
1
  module Md2Man
2
2
  module Document
3
3
 
4
+ #---------------------------------------------------------------------------
5
+ # document-level processing
6
+ #---------------------------------------------------------------------------
7
+
8
+ def preprocess document
9
+ @references = {}
10
+ encode_references document
11
+ end
12
+
4
13
  def postprocess document
5
- # encode references to other manual pages
6
- document.gsub(/(\S+)\(([1-9nol])\)([[:punct:]]?\s*)/){ reference $1,$2,$3 }
14
+ decode_references document
7
15
  end
8
16
 
9
- def reference page, section, addendum
10
- warn "md2man/document: reference not implemented: #{page}(#{section})"
17
+ #---------------------------------------------------------------------------
18
+ # block-level processing
19
+ #---------------------------------------------------------------------------
20
+
21
+ # This method blocks Redcarpet's default behavior, which cannot be accessed
22
+ # using super() due to the limitation of how Redcarpet is implemented in C.
23
+ # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
24
+ #
25
+ # You MUST override this method in derived classes and call super() therein:
26
+ #
27
+ # def block_code code, language
28
+ # code = super
29
+ # # now do something with code
30
+ # end
31
+ #
32
+ def block_code code, language
33
+ decode_references code, true
11
34
  end
12
35
 
13
36
  PARAGRAPH_INDENT = /^\s*$|^ (?=\S)/
14
37
 
38
+ # This method blocks Redcarpet's default behavior, which cannot be accessed
39
+ # using super() due to the limitation of how Redcarpet is implemented in C.
40
+ # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
41
+ #
42
+ # We don't call super() here deliberately: to replace paragraph nodes with
43
+ # normal_paragraph, tagged_paragraph, or indented_paragraph as appropriate.
44
+ #
15
45
  def paragraph text
16
46
  head, *body = text.lines.to_a
17
47
  head_indented = head =~ PARAGRAPH_INDENT
@@ -19,7 +49,7 @@ module Document
19
49
 
20
50
  if head_indented || body_indented
21
51
  text = text.gsub(PARAGRAPH_INDENT, '')
22
- if head_indented && body_indented
52
+ if head_indented && (body_indented || body.empty?)
23
53
  indented_paragraph text
24
54
  else
25
55
  tagged_paragraph text
@@ -41,5 +71,55 @@ module Document
41
71
  warn "md2man/document: normal_paragraph not implemented: #{text.inspect}"
42
72
  end
43
73
 
74
+ #---------------------------------------------------------------------------
75
+ # span-level processing
76
+ #---------------------------------------------------------------------------
77
+
78
+ # This method blocks Redcarpet's default behavior, which cannot be accessed
79
+ # using super() due to the limitation of how Redcarpet is implemented in C.
80
+ # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
81
+ #
82
+ # You MUST override this method in derived classes and call super() therein.
83
+ #
84
+ # def codespan code
85
+ # code = super
86
+ # # now do something with code
87
+ # end
88
+ #
89
+ def codespan code
90
+ decode_references code, true
91
+ end
92
+
93
+ def reference page, section, addendum
94
+ warn "md2man/document: reference not implemented: #{page}(#{section})"
95
+ end
96
+
97
+ protected
98
+
99
+ def encode object
100
+ "\0#{object.object_id}\0"
101
+ end
102
+
103
+ private
104
+
105
+ def encode_references text
106
+ # the [^\n\S] captures all non-newline whitespace
107
+ # basically, it's meant to be \s but excluding \n
108
+ text.gsub(/([\w\-\.]+)\((\w+)\)(\S*[^\n\S]*)/) do
109
+ match = $~
110
+ key = encode(match)
111
+ @references[key] = match
112
+ key
113
+ end
114
+ end
115
+
116
+ def decode_references text, verbatim=false
117
+ @references.select do |key, match|
118
+ replacement = verbatim ? match.to_s : reference(*match.captures)
119
+ text.sub! key, replacement
120
+ end.each_key {|key| @references.delete key }
121
+ text
122
+ end
123
+
44
124
  end
45
125
  end
data/lib/md2man/roff.rb CHANGED
@@ -12,7 +12,7 @@ module Roff
12
12
  def preprocess document
13
13
  @ordered_list_id = 0
14
14
  @table_cells = {}
15
- document
15
+ super
16
16
  end
17
17
 
18
18
  def postprocess document
@@ -42,11 +42,11 @@ module Roff
42
42
  end
43
43
 
44
44
  def block_code code, language
45
- "\n.nf\n#{code.chomp}\n.fi\n"
45
+ block_quote "\n.nf\n#{super.chomp}\n.fi\n"
46
46
  end
47
47
 
48
48
  def block_quote quote
49
- "\n.RS\n#{remove_leading_pp(quote).chomp}\n.RE\n"
49
+ "\n.PP\n.RS\n#{remove_leading_pp(quote).chomp}\n.RE\n"
50
50
  end
51
51
 
52
52
  def block_html html
@@ -156,7 +156,7 @@ module Roff
156
156
  def codespan code
157
157
  # NOTE: this double font sequence gives us the best of both worlds:
158
158
  # man(1) shows it in bold and `groff -Thtml` shows it in monospace
159
- "\\fB\\fC#{code}\\fR"
159
+ "\\fB\\fC#{super}\\fR"
160
160
  end
161
161
 
162
162
  def link link, title, content
@@ -223,7 +223,7 @@ private
223
223
  end
224
224
 
225
225
  def encode_table_cell cell
226
- key = cell.object_id.to_s
226
+ key = encode(cell)
227
227
  @table_cells[key] = cell
228
228
  key + TABLE_CELL_DELIM
229
229
  end
@@ -1,3 +1,3 @@
1
1
  module Md2Man
2
- VERSION = "1.3.0"
2
+ VERSION = "1.3.1"
3
3
  end
data/man/man1/md2man.1 CHANGED
@@ -1,4 +1,4 @@
1
- .TH MD2MAN 1 2012\-09\-27 1.3.0
1
+ .TH MD2MAN 1 2012\-10\-09 1.3.1
2
2
  .SH NAME
3
3
  .PP
4
4
  md2man \- convert
@@ -71,9 +71,9 @@ superscript
71
71
  .IP \(bu 2
72
72
  strikethrough
73
73
  .IP \(bu 2
74
- no\fIintra\fPemphasis
74
+ no_intra_emphasis
75
75
  .IP \(bu 2
76
- fenced\fIcode\fPblocks
76
+ fenced_code_blocks
77
77
  .RE
78
78
  .SH OPTIONS
79
79
  .TP
data/md2man.gemspec CHANGED
@@ -16,8 +16,8 @@ Gem::Specification.new do |s|
16
16
  s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
17
17
  s.require_paths = ['lib']
18
18
 
19
- s.add_runtime_dependency 'binman', '~> 3'
19
+ s.add_runtime_dependency 'binman', '~> 3.0'
20
20
  s.add_runtime_dependency 'redcarpet', '~> 2.1'
21
- s.add_development_dependency 'minitest', '~> 2.7'
22
- s.add_development_dependency 'rake', '>= 0.9.2.2', '< 1'
21
+ s.add_development_dependency 'minitest', '~> 4.0'
22
+ s.add_development_dependency 'rake', '~> 0.9.2.2'
23
23
  end
@@ -69,6 +69,11 @@ describe Md2Man::Roff do
69
69
  | multiple
70
70
  | lines
71
71
  | but within 4-space indent
72
+ |
73
+ | and a single line following
74
+ |
75
+ | and multiple
76
+ | lines following
72
77
  INPUT
73
78
  |.TP
74
79
  |just some paragraph
@@ -76,6 +81,11 @@ describe Md2Man::Roff do
76
81
  |multiple
77
82
  |lines
78
83
  |but within 4\\-space indent
84
+ |.IP
85
+ |and a single line following
86
+ |.IP
87
+ |and multiple
88
+ |lines following
79
89
  OUTPUT
80
90
  end
81
91
 
@@ -258,6 +268,28 @@ describe Md2Man::Roff do
258
268
  |> lines
259
269
  |>but within 4-space indent
260
270
  INPUT
271
+ |.PP
272
+ |.RS
273
+ |just some paragraph
274
+ |spanning
275
+ | multiple
276
+ | lines
277
+ |but within 4\\-space indent
278
+ |.RE
279
+ OUTPUT
280
+
281
+ @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
282
+ |some paragraph above
283
+ |
284
+ |>just some paragraph
285
+ |> spanning
286
+ |> multiple
287
+ |> lines
288
+ |>but within 4-space indent
289
+ INPUT
290
+ |.PP
291
+ |some paragraph above
292
+ |.PP
261
293
  |.RS
262
294
  |just some paragraph
263
295
  |spanning
@@ -272,9 +304,12 @@ describe Md2Man::Roff do
272
304
  @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
273
305
  | single preformatted line
274
306
  INPUT
307
+ |.PP
308
+ |.RS
275
309
  |.nf
276
310
  |single preformatted line
277
311
  |.fi
312
+ |.RE
278
313
  OUTPUT
279
314
 
280
315
  @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
@@ -284,6 +319,8 @@ describe Md2Man::Roff do
284
319
  | > lines
285
320
  | with 4-space indent
286
321
  INPUT
322
+ |.PP
323
+ |.RS
287
324
  |.nf
288
325
  |just some *paragraph*
289
326
  | spanning
@@ -291,6 +328,22 @@ describe Md2Man::Roff do
291
328
  |> lines
292
329
  |with 4-space indent
293
330
  |.fi
331
+ |.RE
332
+ OUTPUT
333
+
334
+ @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
335
+ |normal paragraph line
336
+ |
337
+ | single preformatted line
338
+ INPUT
339
+ |.PP
340
+ |normal paragraph line
341
+ |.PP
342
+ |.RS
343
+ |.nf
344
+ |single preformatted line
345
+ |.fi
346
+ |.RE
294
347
  OUTPUT
295
348
  end
296
349
 
@@ -474,6 +527,7 @@ describe Md2Man::Roff do
474
527
  |>
475
528
  |>bar
476
529
  INPUT
530
+ |.PP
477
531
  |.RS
478
532
  |foo
479
533
  |.ti 0
@@ -581,4 +635,55 @@ describe Md2Man::Roff do
581
635
  |using
582
636
  OUTPUT
583
637
  end
638
+
639
+ it 'does not render references inside code blocks' do
640
+ @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
641
+ | this is a code block
642
+ | containing markdown(7),
643
+ | roff(7), and much more!
644
+ INPUT
645
+ |.PP
646
+ |.RS
647
+ |.nf
648
+ |this is a code block
649
+ |containing markdown(7),
650
+ |roff(7), and much more!
651
+ |.fi
652
+ |.RE
653
+ OUTPUT
654
+ end
655
+
656
+ it 'does not render references inside code spans' do
657
+ @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
658
+ |this is a code span `containing markdown(7), roff(7), and` much more!
659
+ INPUT
660
+ |.PP
661
+ |this is a code span \\fB\\fCcontaining markdown(7), roff(7), and\\fR much more!
662
+ OUTPUT
663
+ end
664
+
665
+ it 'renders references to manual pages present on my linux box' do
666
+ @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
667
+ |man(1)
668
+ |man-pages(7)
669
+ |ld.so(8)
670
+ |ld-linux.so(8)
671
+ |ld-linux(8)
672
+ |aio.h(0p)
673
+ |vi(1p)
674
+ |vfork(3p)
675
+ |exit(3tcl)
676
+ INPUT
677
+ |.PP
678
+ |.BR man (1)
679
+ |.BR man-pages (7)
680
+ |.BR ld.so (8)
681
+ |.BR ld-linux.so (8)
682
+ |.BR ld-linux (8)
683
+ |.BR aio.h (0p)
684
+ |.BR vi (1p)
685
+ |.BR vfork (3p)
686
+ |.BR exit (3tcl)
687
+ OUTPUT
688
+ end
584
689
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: md2man
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.3.0
4
+ version: 1.3.1
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2012-09-27 00:00:00.000000000 Z
12
+ date: 2012-10-11 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: binman
@@ -18,7 +18,7 @@ dependencies:
18
18
  requirements:
19
19
  - - ~>
20
20
  - !ruby/object:Gem::Version
21
- version: '3'
21
+ version: '3.0'
22
22
  type: :runtime
23
23
  prerelease: false
24
24
  version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
26
26
  requirements:
27
27
  - - ~>
28
28
  - !ruby/object:Gem::Version
29
- version: '3'
29
+ version: '3.0'
30
30
  - !ruby/object:Gem::Dependency
31
31
  name: redcarpet
32
32
  requirement: !ruby/object:Gem::Requirement
@@ -50,7 +50,7 @@ dependencies:
50
50
  requirements:
51
51
  - - ~>
52
52
  - !ruby/object:Gem::Version
53
- version: '2.7'
53
+ version: '4.0'
54
54
  type: :development
55
55
  prerelease: false
56
56
  version_requirements: !ruby/object:Gem::Requirement
@@ -58,29 +58,23 @@ dependencies:
58
58
  requirements:
59
59
  - - ~>
60
60
  - !ruby/object:Gem::Version
61
- version: '2.7'
61
+ version: '4.0'
62
62
  - !ruby/object:Gem::Dependency
63
63
  name: rake
64
64
  requirement: !ruby/object:Gem::Requirement
65
65
  none: false
66
66
  requirements:
67
- - - ! '>='
67
+ - - ~>
68
68
  - !ruby/object:Gem::Version
69
69
  version: 0.9.2.2
70
- - - <
71
- - !ruby/object:Gem::Version
72
- version: '1'
73
70
  type: :development
74
71
  prerelease: false
75
72
  version_requirements: !ruby/object:Gem::Requirement
76
73
  none: false
77
74
  requirements:
78
- - - ! '>='
75
+ - - ~>
79
76
  - !ruby/object:Gem::Version
80
77
  version: 0.9.2.2
81
- - - <
82
- - !ruby/object:Gem::Version
83
- version: '1'
84
78
  description: Converts markdown documents into UNIX manual pages.
85
79
  email:
86
80
  - sunaku@gmail.com
@@ -91,6 +85,7 @@ extra_rdoc_files: []
91
85
  files:
92
86
  - .gitignore
93
87
  - EXAMPLE.markdown
88
+ - EXAMPLE.png
94
89
  - Gemfile
95
90
  - HISTORY.markdown
96
91
  - LICENSE
@@ -118,12 +113,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
118
113
  - - ! '>='
119
114
  - !ruby/object:Gem::Version
120
115
  version: '0'
116
+ segments:
117
+ - 0
118
+ hash: -2252989265192127039
121
119
  required_rubygems_version: !ruby/object:Gem::Requirement
122
120
  none: false
123
121
  requirements:
124
122
  - - ! '>='
125
123
  - !ruby/object:Gem::Version
126
124
  version: '0'
125
+ segments:
126
+ - 0
127
+ hash: -2252989265192127039
127
128
  requirements: []
128
129
  rubyforge_project:
129
130
  rubygems_version: 1.8.23