md2man 1.0.1

data/lib/md2man/version.rb

@@ -0,0 +1,3 @@
+module Md2Man
+  VERSION = "1.0.1"
+end

data/lib/md2man.rb

@@ -0,0 +1,2 @@
+require 'md2man/version'
+require 'md2man/engine'

data/man/man1/md2man.1

@@ -0,0 +1,79 @@
+.TH MD2MAN 1 "2011\-12\-06" "1.0.1"
+.SH NAME
+.PP
+md2man \- convert 
+.BR markdown (7) 
+into 
+.BR roff (7)
+.SH SYNOPSIS
+.PP
+\fB\fCmd2man\fR [\fIOPTION\fP]... [\fIFILE\fP]
+.SH DESCRIPTION
+.PP
+md2man
+.UR https://github.com/sunaku/md2man
+.UE
+converts 
+.BR markdown (7) 
+input from the given \fIFILE\fP into 
+.BR roff (7) 
+using
+Redcarpet2
+.UR https://github.com/tanoku/redcarpet
+.UE
+and then prints the result to the standard output stream.  If
+\fIFILE\fP is not given, then the standard input stream is read in its place.
+.SS Document Format
+.PP
+The following additional semantics are attached to 
+.BR markdown (7):
+.RS
+.IP \(bu 2
+There can be at most one top\-level heading (H1).  It is emitted as \fB\fC.TH\fR
+in the 
+.BR roff (7) 
+output, specifying the UNIX man page's header and footer.
+.IP \(bu 2
+Paragraphs whose lines are all uniformly indented by two spaces are
+considered to be "indented paragraphs".  They are unindented accordingly
+before emission as \fB\fC.IP\fR in the 
+.BR roff (7) 
+output.
+.IP \(bu 2
+Paragraphs whose subsequent lines (all except the first) are uniformly
+indented by two spaces are considered to be a "tagged paragraphs".  They
+are unindented accordingly before emission as \fB\fC.TP\fR in the 
+.BR roff (7) 
+output.
+.RE
+.SS Markdown Extensions
+.PP
+The following Redcarpet2
+.UR https://github.com/tanoku/redcarpet
+.UE
+extensions for 
+.BR markdown (7) 
+are enabled:
+.RS
+.IP \(bu 2
+tables
+.IP \(bu 2
+autolink
+.IP \(bu 2
+superscript
+.IP \(bu 2
+strikethrough
+.IP \(bu 2
+no_intra_emphasis
+.IP \(bu 2
+fenced_code_blocks
+.RE
+.SH OPTIONS
+.TP
+\fB\fC-h\fR, \fB\fC--help\fR
+Display this help manual using 
+.BR man (1).
+.SH SEE ALSO
+.PP
+.BR markdown (7), 
+.BR roff (7)

data/md2man.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "md2man/version"
+require "binman/gemspec"
+
+Gem::Specification.new do |s|
+  s.name        = "md2man"
+  s.version     = Md2Man::VERSION
+  s.authors,
+  s.email       = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
+  s.homepage    = "http://github.com/sunaku/md2man"
+  s.summary     = "UNIX man pages using Redcarpet2"
+  s.description = nil
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "redcarpet", ">= 2.0.0b5", "< 3"
+  s.add_development_dependency "minitest", ">= 2.7.0", "< 3"
+end

data/test/md2man/roff_test.rb

@@ -0,0 +1,584 @@
+# http://www.linuxjournal.com/article/1158
+# http://www.premvet.co.uk/premvet/faq/roff.html
+# http://www.linuxhowtos.org/System/creatingman.htm
+# http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
+# http://serverfault.com/questions/109490/how-do-i-write-man-pages
+# man groff_man
+# man 7 groff
+
+require 'test_helper'
+require 'md2man/engine'
+
+describe Md2Man::Roff do
+  before do
+    @markdown = Redcarpet::Markdown.new(
+      Md2Man::Engine,
+      :tables => true,
+      :autolink => true,
+    )
+  end
+
+  SPACE = 0x20.chr
+
+  def heredoc document
+    document.gsub(/^\s*\|/, '').chomp
+  end
+
+  it 'renders nothing as nothing' do
+    @markdown.render('').must_be_empty
+  end
+
+  it 'renders paragraphs' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some paragraph
+      |spanning
+      |multiple
+      |lines
+      |but within 4-space indent
+    INPUT
+      |.PP
+      |just some paragraph
+      |spanning
+      |multiple
+      |lines
+      |but within 4\\-space indent
+    OUTPUT
+  end
+
+  it 'renders paragraphs with unevenly indented bodies' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some paragraph
+      | spanning
+      |  multiple
+      |   lines
+      |but within 4-space indent
+    INPUT
+      |.PP
+      |just some paragraph
+      | spanning
+      |  multiple
+      |   lines
+      |but within 4\\-space indent
+    OUTPUT
+  end
+
+  it 'renders tagged paragraphs with uniformly two-space indented bodies' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some paragraph
+      |  spanning
+      |  multiple
+      |  lines
+      |  but within 4-space indent
+    INPUT
+      |.TP
+      |just some paragraph
+      |spanning
+      |multiple
+      |lines
+      |but within 4\\-space indent
+    OUTPUT
+  end
+
+  it 'renders indented paragraphs that are uniformly two-space indented' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |  just some paragraph
+      |  spanning
+      |  multiple
+      |  lines
+      |  but within 4-space indent
+    INPUT
+      |.IP
+      |just some paragraph
+      |spanning
+      |multiple
+      |lines
+      |but within 4\\-space indent
+    OUTPUT
+  end
+
+  it 'renders tagged, indented, and normal paragraphs' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |This is a
+      |normal paragraph.
+      |
+      |This is a
+      |  tagged paragraph.
+      |
+      |  This is another
+      |tagged paragraph.
+      |
+      |  This is an
+      |  indented
+      |  paragraph.
+      |
+      |This
+      | is another
+      |  normal
+      |   paragraph.
+    INPUT
+      |.PP
+      |This is a
+      |normal paragraph.
+      |.TP
+      |This is a
+      |tagged paragraph.
+      |.TP
+      |This is another
+      |tagged paragraph.
+      |.IP
+      |This is an
+      |indented
+      |paragraph.
+      |.PP
+      |This
+      | is another
+      |  normal
+      |   paragraph.
+    OUTPUT
+  end
+  it 'escapes hyphens in normal text' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |pre-process
+    INPUT
+      |.PP
+      |pre\\-process
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |1-5
+    INPUT
+      |.PP
+      |1\\-5
+    OUTPUT
+  end
+
+  it 'renders emphasis' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just *some paragraph*
+      | spanning
+      |  multiple
+      |   *lines*
+      |but within 4-*space* indent
+    INPUT
+      |.PP
+      |just \\fIsome paragraph\\fP
+      | spanning
+      |  multiple
+      |   \\fIlines\\fP
+      |but within 4\\-\\fIspace\\fP indent
+    OUTPUT
+  end
+
+  it 'renders double emphasis' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just **some paragraph**
+      | spanning
+      |  multiple
+      |   **lines**
+      |but within 4-**space** indent
+    INPUT
+      |.PP
+      |just \\fBsome paragraph\\fP
+      | spanning
+      |  multiple
+      |   \\fBlines\\fP
+      |but within 4\\-\\fBspace\\fP indent
+    OUTPUT
+  end
+
+  it 'renders triple emphasis' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just ***some paragraph***
+      | spanning
+      |  multiple
+      |   ***lines***
+      |but within 4-***space*** indent
+    INPUT
+      |.PP
+      |just \\s+2\\fBsome paragraph\\fP\\s-2
+      | spanning
+      |  multiple
+      |   \\s+2\\fBlines\\fP\\s-2
+      |but within 4\\-\\s+2\\fBspace\\fP\\s-2 indent
+    OUTPUT
+  end
+
+  it 'renders top-level headings' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some h1 heading
+      |====================
+    INPUT
+      |.TH just some h1 heading
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |BINMAN 1 "2011-11-05" "1.1.0" "Ruby User Manuals"
+      |=================================================
+    INPUT
+      |.TH BINMAN 1 "2011\\-11\\-05" "1.1.0" "Ruby User Manuals"
+    OUTPUT
+  end
+
+  it 'renders 2nd-level headings' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some h2 heading
+      |--------------------
+    INPUT
+      |.SH just some h2 heading
+    OUTPUT
+  end
+
+  it 'renders level 3..6 headings' do
+    (3..6).each do |level|
+      @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+        |#{'#' * level} just some subheading
+      INPUT
+        |.SS just some subheading
+      OUTPUT
+    end
+  end
+
+  it 'renders linebreaks (2 spaces at EOL)' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |line#{SPACE}#{SPACE}
+      |break
+    INPUT
+      |.PP
+      |line
+      |.br
+      |break
+    OUTPUT
+  end
+
+  it 'renders blockquotes' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |>just some paragraph
+      |> spanning
+      |>  multiple
+      |>   lines
+      |>but within 4-space indent
+    INPUT
+      |.RS
+      |just some paragraph
+      |spanning
+      | multiple
+      |  lines
+      |but within 4\\-space indent
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders code blocks' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |    single preformatted line
+    INPUT
+      |.nf
+      |single preformatted line
+      |.fi
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |    just some *paragraph*
+      |     spanning
+      |      **multiple**
+      |    >  lines
+      |    with 4-space indent
+    INPUT
+      |.nf
+      |just some *paragraph*
+      | spanning
+      |  **multiple**
+      |>  lines
+      |with 4-space indent
+      |.fi
+    OUTPUT
+  end
+
+  it 'renders code spans' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |here is `some code` for you
+    INPUT
+      |.PP
+      |here is \\fB\\fCsome code\\fR for you
+    OUTPUT
+  end
+
+  it 'renders hyperlinks' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Send [me](mailto:foo@bar.baz), e-mail.
+    INPUT
+      |.PP
+      |Send me
+      |.MT foo@bar.baz
+      |.ME , e\\-mail.
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Take [me](http://myself), somewhere.
+    INPUT
+      |.PP
+      |Take me
+      |.UR http://myself
+      |.UE , somewhere.
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Mail me foo@bar.baz now.
+    INPUT
+      |.PP
+      |Mail me#{SPACE}
+      |.MT foo@bar.baz
+      |.ME
+      |now.
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Take me http://www.somewhere now.
+    INPUT
+      |.PP
+      |Take me#{SPACE}
+      |.UR http://www.somewhere
+      |.UE
+      |now.
+    OUTPUT
+  end
+
+  it 'renders unordered lists' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Here is an unordered list:
+      |
+      |* foo
+      |    * bar
+      |        * baz
+      |* qux
+    INPUT
+      |.PP
+      |Here is an unordered list:
+      |.RS
+      |.IP \\(bu 2
+      |foo
+      |.RS
+      |.IP \\(bu 2
+      |bar
+      |.RS
+      |.IP \\(bu 2
+      |baz
+      |.RE
+      |.RE
+      |.IP \\(bu 2
+      |qux
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders unordered lists while squashing first paragraphs' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Here is an unordered list:
+      |
+      |  * here is a
+      |    paragraph
+      |
+      |    here is a
+      |    subparagraph
+    INPUT
+      |.PP
+      |Here is an unordered list:
+      |.RS
+      |.IP \\(bu 2
+      |here is a
+      |paragraph
+      |.PP
+      |here is a
+      |subparagraph
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders ordered lists' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Here is an ordered list:
+      |
+      |1.  foo
+      |    1.  bar
+      |        1.  baz
+      |2.  qux
+    INPUT
+      |.PP
+      |Here is an ordered list:
+      |.nr step2 0 1
+      |.RS
+      |.IP \\n+[step2]
+      |foo
+      |.nr step1 0 1
+      |.RS
+      |.IP \\n+[step1]
+      |bar
+      |.nr step0 0 1
+      |.RS
+      |.IP \\n+[step0]
+      |baz
+      |.RE
+      |.RE
+      |.IP \\n+[step2]
+      |qux
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders ordered lists while squashing first paragraphs' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Here is an ordered list:
+      |
+      |1.  here is a
+      |    paragraph
+      |
+      |    here is a
+      |    subparagraph
+    INPUT
+      |.PP
+      |Here is an ordered list:
+      |.nr step0 0 1
+      |.RS
+      |.IP \\n+[step0]
+      |here is a
+      |paragraph
+      |.PP
+      |here is a
+      |subparagraph
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders horizontal rules' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |foo
+      |
+      |* * *
+      |
+      |bar
+    INPUT
+      |.PP
+      |foo
+      |.ti 0
+      |\\l'\\n(.lu'
+      |.PP
+      |bar
+    OUTPUT
+  end
+
+  it 'renders horizontal rules inside blockquotes' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |>foo
+      |>
+      |>* * *
+      |>
+      |>bar
+    INPUT
+      |.RS
+      |foo
+      |.ti 0
+      |\\l'\\n(.lu'
+      |.PP
+      |bar
+      |.RE
+    OUTPUT
+  end
+
+  it 'renders some named entities' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |&middot; &#183;
+      |&copy; &#169;
+      |&cent; &#162;
+      |&Dagger; &#8225;
+      |&deg; &#176;
+      |&dagger; &#8224;
+      |&quot; &#34;
+      |&mdash; &#8212;
+      |&ndash; &#8211;
+      |&reg; &#174;
+      |&sect; &#167;
+      |&oline; &#8254;
+      |&equiv; &#8801;
+      |&ge; &#8805;
+      |&le; &#8804;
+      |&ne; &#8800;
+      |&rarr; &#8594;
+      |&larr; &#8592;
+      |&plusmn; &#177;
+    INPUT
+      |.PP
+      |\\[pc] \\[pc]
+      |\\[co] \\[co]
+      |\\[ct] \\[ct]
+      |\\[dd] \\[dd]
+      |\\[de] \\[de]
+      |\\[dg] \\[dg]
+      |\\[dq] \\[dq]
+      |\\[em] \\[em]
+      |\\[en] \\[en]
+      |\\[rg] \\[rg]
+      |\\[sc] \\[sc]
+      |\\[rn] \\[rn]
+      |\\[==] \\[==]
+      |\\[>=] \\[>=]
+      |\\[<=] \\[<=]
+      |\\[!=] \\[!=]
+      |\\[->] \\[->]
+      |\\[<-] \\[<-]
+      |\\[+-] \\[+-]
+    OUTPUT
+  end
+
+  it 'renders tables' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |First Header  | Second Header
+      |------------- | -------------
+      |First Content | Second Content
+    INPUT
+      |.TS
+      |allbox;
+      |cb cb
+      |l l
+      |.
+      |First Header\tSecond Header
+      |First Content\tSecond Content
+      |.TE
+    OUTPUT
+  end
+
+  it 'renders tables with alignment' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      || Item      | Value |
+      || --------- | -----:|
+      || Computer  | $1600 |
+      || Phone     |   $12 |
+      || Pipe      |    $1 |
+    INPUT
+      |.TS
+      |allbox;
+      |cb cb
+      |l r
+      |l r
+      |l r
+      |.
+      |Item\tValue
+      |Computer\t$1600
+      |Phone\t$12
+      |Pipe\t$1
+      |.TE
+    OUTPUT
+  end
+
+  it 'renders references to other man pages as hyperlinks' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |convert them from markdown(7) into roff(7), using
+    INPUT
+      |.PP
+      |convert them from#{SPACE}
+      |.BR markdown (7)#{SPACE}
+      |into#{SPACE}
+      |.BR roff (7),#{SPACE}
+      |using
+    OUTPUT
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'minitest/spec'
+require 'minitest/autorun'