md2man 1.3.0 → 1.3.1

data/HISTORY.markdown

@@ -1,3 +1,31 @@
+## Version 1.3.1 (2012-10-09)
+
+Patch:
+
+  * roff: do not render references inside code blocks.
+
+  * roff: do not render references inside code spans.
+
+  * roff: fix single-line indented paragraph detection.
+
+  * roff: also indent block\_code just like block\_quote.
+
+  * roff: add paragraph above block\_quote for spacing.
+
+  * roff: render code blocks as paragraphs for spacing.
+
+    Otherwise there's not enough space between the previous paragraph and
+    the code block: it appears on the next line and appears ugly in man(1).
+
+  * document: make reference regexp match more manpages.
+
+Other:
+
+  * document: stronger digest encoding using NUL bytes.
+
+  * document: super() can't reach Redcarpet's renderer classes.
+    See https://github.com/vmg/redcarpet/issues/51 for details.
+
 ## Version 1.3.0 (2012-09-27)
 
 Minor:

data/README.markdown

@@ -18,9 +18,10 @@ documents into UNIX manual pages (really [Roff] documents) using [Redcarpet].
 Try converting [this example Markdown file][example] into a UNIX manual page:
 
     md2man EXAMPLE.markdown > EXAMPLE.1
-    man EXAMPLE.1
+    man -l EXAMPLE.1
 
-![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
+![Obligatory screenshot of md2man(1) in action!](
+https://raw.github.com/sunaku/md2man/master/EXAMPLE.png)
 
 ### Limitations
 
@@ -42,9 +43,9 @@ It issues a warning when it encounters these instead.  Patches are welcome!
 
     git clone git://github.com/sunaku/md2man
     cd md2man
-    bundle install --binstubs=bundle_bin
-    bundle_bin/md2man --help  # run it directly
-    bundle exec rake -T       # packaging tasks
+    bundle install
+    bundle exec md2man --help  # run it directly
+    bundle exec rake -T        # packaging tasks
 
 ## Usage
 

data/bin/md2man

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN 1 2012-09-27 1.3.0
+# MD2MAN 1 2012-10-09 1.3.1
 
 ## NAME
 
@@ -43,8 +43,8 @@ The following [Redcarpet] extensions are enabled while processing markdown(7):
   * autolink
   * superscript
   * strikethrough
-  * no_intra_emphasis
-  * fenced_code_blocks
+  * no\_intra\_emphasis
+  * fenced\_code\_blocks
 
 ## OPTIONS
 

data/lib/md2man/document.rb

@@ -1,17 +1,47 @@
 module Md2Man
 module Document
 
+  #---------------------------------------------------------------------------
+  # document-level processing
+  #---------------------------------------------------------------------------
+
+  def preprocess document
+    @references = {}
+    encode_references document
+  end
+
   def postprocess document
-    # encode references to other manual pages
-    document.gsub(/(\S+)\(([1-9nol])\)([[:punct:]]?\s*)/){ reference $1,$2,$3 }
+    decode_references document
   end
 
-  def reference page, section, addendum
-    warn "md2man/document: reference not implemented: #{page}(#{section})"
+  #---------------------------------------------------------------------------
+  # block-level processing
+  #---------------------------------------------------------------------------
+
+  # This method blocks Redcarpet's default behavior, which cannot be accessed
+  # using super() due to the limitation of how Redcarpet is implemented in C.
+  # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
+  #
+  # You MUST override this method in derived classes and call super() therein:
+  #
+  #   def block_code code, language
+  #     code = super
+  #     # now do something with code
+  #   end
+  #
+  def block_code code, language
+    decode_references code, true
   end
 
   PARAGRAPH_INDENT = /^\s*$|^  (?=\S)/
 
+  # This method blocks Redcarpet's default behavior, which cannot be accessed
+  # using super() due to the limitation of how Redcarpet is implemented in C.
+  # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
+  #
+  # We don't call super() here deliberately: to replace paragraph nodes with
+  # normal_paragraph, tagged_paragraph, or indented_paragraph as appropriate.
+  #
   def paragraph text
     head, *body = text.lines.to_a
     head_indented = head =~ PARAGRAPH_INDENT
@@ -19,7 +49,7 @@ module Document
 
     if head_indented || body_indented
       text = text.gsub(PARAGRAPH_INDENT, '')
-      if head_indented && body_indented
+      if head_indented && (body_indented || body.empty?)
         indented_paragraph text
       else
         tagged_paragraph text
@@ -41,5 +71,55 @@ module Document
     warn "md2man/document: normal_paragraph not implemented: #{text.inspect}"
   end
 
+  #---------------------------------------------------------------------------
+  # span-level processing
+  #---------------------------------------------------------------------------
+
+  # This method blocks Redcarpet's default behavior, which cannot be accessed
+  # using super() due to the limitation of how Redcarpet is implemented in C.
+  # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
+  #
+  # You MUST override this method in derived classes and call super() therein.
+  #
+  #   def codespan code
+  #     code = super
+  #     # now do something with code
+  #   end
+  #
+  def codespan code
+    decode_references code, true
+  end
+
+  def reference page, section, addendum
+    warn "md2man/document: reference not implemented: #{page}(#{section})"
+  end
+
+protected
+
+  def encode object
+    "\0#{object.object_id}\0"
+  end
+
+private
+
+  def encode_references text
+    # the [^\n\S] captures all non-newline whitespace
+    # basically, it's meant to be \s but excluding \n
+    text.gsub(/([\w\-\.]+)\((\w+)\)(\S*[^\n\S]*)/) do
+      match = $~
+      key = encode(match)
+      @references[key] = match
+      key
+    end
+  end
+
+  def decode_references text, verbatim=false
+    @references.select do |key, match|
+      replacement = verbatim ? match.to_s : reference(*match.captures)
+      text.sub! key, replacement
+    end.each_key {|key| @references.delete key }
+    text
+  end
+
 end
 end

data/lib/md2man/roff.rb

@@ -12,7 +12,7 @@ module Roff
   def preprocess document
     @ordered_list_id = 0
     @table_cells = {}
-    document
+    super
   end
 
   def postprocess document
@@ -42,11 +42,11 @@ module Roff
   end
 
   def block_code code, language
-    "\n.nf\n#{code.chomp}\n.fi\n"
+    block_quote "\n.nf\n#{super.chomp}\n.fi\n"
   end
 
   def block_quote quote
-    "\n.RS\n#{remove_leading_pp(quote).chomp}\n.RE\n"
+    "\n.PP\n.RS\n#{remove_leading_pp(quote).chomp}\n.RE\n"
   end
 
   def block_html html
@@ -156,7 +156,7 @@ module Roff
   def codespan code
     # NOTE: this double font sequence gives us the best of both worlds:
     # man(1) shows it in bold and `groff -Thtml` shows it in monospace
-    "\\fB\\fC#{code}\\fR"
+    "\\fB\\fC#{super}\\fR"
   end
 
   def link link, title, content
@@ -223,7 +223,7 @@ private
   end
 
   def encode_table_cell cell
-    key = cell.object_id.to_s
+    key = encode(cell)
     @table_cells[key] = cell
     key + TABLE_CELL_DELIM
   end

data/lib/md2man/version.rb

@@ -1,3 +1,3 @@
 module Md2Man
-  VERSION = "1.3.0"
+  VERSION = "1.3.1"
 end

data/man/man1/md2man.1

@@ -1,4 +1,4 @@
-.TH MD2MAN 1 2012\-09\-27 1.3.0
+.TH MD2MAN 1 2012\-10\-09 1.3.1
 .SH NAME
 .PP
 md2man \- convert 
@@ -71,9 +71,9 @@ superscript
 .IP \(bu 2
 strikethrough
 .IP \(bu 2
-no\fIintra\fPemphasis
+no_intra_emphasis
 .IP \(bu 2
-fenced\fIcode\fPblocks
+fenced_code_blocks
 .RE
 .SH OPTIONS
 .TP

data/md2man.gemspec

@@ -16,8 +16,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency 'binman', '~> 3'
+  s.add_runtime_dependency 'binman', '~> 3.0'
   s.add_runtime_dependency 'redcarpet', '~> 2.1'
-  s.add_development_dependency 'minitest', '~> 2.7'
-  s.add_development_dependency 'rake', '>= 0.9.2.2', '< 1'
+  s.add_development_dependency 'minitest', '~> 4.0'
+  s.add_development_dependency 'rake', '~> 0.9.2.2'
 end

data/test/md2man/roff_test.rb

@@ -69,6 +69,11 @@ describe Md2Man::Roff do
       |  multiple
       |  lines
       |  but within 4-space indent
+      |
+      |  and a single line following
+      |
+      |  and multiple
+      |  lines following
     INPUT
       |.TP
       |just some paragraph
@@ -76,6 +81,11 @@ describe Md2Man::Roff do
       |multiple
       |lines
       |but within 4\\-space indent
+      |.IP
+      |and a single line following
+      |.IP
+      |and multiple
+      |lines following
     OUTPUT
   end
 
@@ -258,6 +268,28 @@ describe Md2Man::Roff do
       |>   lines
       |>but within 4-space indent
     INPUT
+      |.PP
+      |.RS
+      |just some paragraph
+      |spanning
+      | multiple
+      |  lines
+      |but within 4\\-space indent
+      |.RE
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |some paragraph above
+      |
+      |>just some paragraph
+      |> spanning
+      |>  multiple
+      |>   lines
+      |>but within 4-space indent
+    INPUT
+      |.PP
+      |some paragraph above
+      |.PP
       |.RS
       |just some paragraph
       |spanning
@@ -272,9 +304,12 @@ describe Md2Man::Roff do
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |    single preformatted line
     INPUT
+      |.PP
+      |.RS
       |.nf
       |single preformatted line
       |.fi
+      |.RE
     OUTPUT
 
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
@@ -284,6 +319,8 @@ describe Md2Man::Roff do
       |    >  lines
       |    with 4-space indent
     INPUT
+      |.PP
+      |.RS
       |.nf
       |just some *paragraph*
       | spanning
@@ -291,6 +328,22 @@ describe Md2Man::Roff do
       |>  lines
       |with 4-space indent
       |.fi
+      |.RE
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |normal paragraph line
+      |
+      |    single preformatted line
+    INPUT
+      |.PP
+      |normal paragraph line
+      |.PP
+      |.RS
+      |.nf
+      |single preformatted line
+      |.fi
+      |.RE
     OUTPUT
   end
 
@@ -474,6 +527,7 @@ describe Md2Man::Roff do
       |>
       |>bar
     INPUT
+      |.PP
       |.RS
       |foo
       |.ti 0
@@ -581,4 +635,55 @@ describe Md2Man::Roff do
       |using
     OUTPUT
   end
+
+  it 'does not render references inside code blocks' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |    this is a code block
+      |    containing markdown(7),
+      |    roff(7), and much more!
+    INPUT
+      |.PP
+      |.RS
+      |.nf
+      |this is a code block
+      |containing markdown(7),
+      |roff(7), and much more!
+      |.fi
+      |.RE
+    OUTPUT
+  end
+
+  it 'does not render references inside code spans' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |this is a code span `containing markdown(7), roff(7), and` much more!
+    INPUT
+      |.PP
+      |this is a code span \\fB\\fCcontaining markdown(7), roff(7), and\\fR much more!
+    OUTPUT
+  end
+
+  it 'renders references to manual pages present on my linux box' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |man(1)
+      |man-pages(7)
+      |ld.so(8)
+      |ld-linux.so(8)
+      |ld-linux(8)
+      |aio.h(0p)
+      |vi(1p)
+      |vfork(3p)
+      |exit(3tcl)
+    INPUT
+      |.PP
+      |.BR man (1)
+      |.BR man-pages (7)
+      |.BR ld.so (8)
+      |.BR ld-linux.so (8)
+      |.BR ld-linux (8)
+      |.BR aio.h (0p)
+      |.BR vi (1p)
+      |.BR vfork (3p)
+      |.BR exit (3tcl)
+    OUTPUT
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-27 00:00:00.000000000 Z
+date: 2012-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -50,7 +50,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -58,29 +58,23 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.2.2
-    - - <
-      - !ruby/object:Gem::Version
-        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.2.2
-    - - <
-      - !ruby/object:Gem::Version
-        version: '1'
 description: Converts markdown documents into UNIX manual pages.
 email:
 - sunaku@gmail.com
@@ -91,6 +85,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - EXAMPLE.markdown
+- EXAMPLE.png
 - Gemfile
 - HISTORY.markdown
 - LICENSE
@@ -118,12 +113,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2252989265192127039
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2252989265192127039
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23