md2man 1.3.2 → 1.4.0

data/HISTORY.markdown

@@ -1,3 +1,25 @@
+## Version 1.4.0 (2012-10-14)
+
+Minor:
+
+  * roff: emit non-first H1 headings as H2 headings
+
+  * html: add `Md2Man::HTML::Engine` class for HTML manual page generation
+
+  * html: add md2man-html(1) bin script for command line access to the above
+
+  * html: add ID attributes on all headings for easy permalinking
+
+  * rake: add `md2man/rakefile` to process markdown files in man/
+
+    This library provides a `rake md2man` task that builds UNIX and HTML
+    manual pages from Markdown files (with ".markdown", ".mkd", or ".md"
+    extension) inside your `man/man*/` directories.  It also provides
+    sub-tasks to build *only* UNIX or HTML manual pages separately.
+
+    It also hooks into Bundler's gem packaging tasks to automatically build
+    your manual pages for packaging into a gem.  See the README for details.
+
 ## Version 1.3.2 (2012-10-13)
 
 Patch:

data/README.markdown

@@ -104,8 +104,30 @@ md2man extends [Markdown] syntax in the following ways, as provisioned in the
 
 md2man extends [Markdown] semantics in the following ways:
 
-  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
-    in the [Roff] output, defining the UNIX manual page's header and footer.
+  * The first top-level heading (H1) found in the document is emitted as `.TH`
+    in the roff(7) output to define the UNIX manual page's header and footer.
+    Any subsequent top-level headings (H1) are treated as second-level (H2).
+
+### Pre-building man pages
+
+Add the following lines to your gemspec:
+
+    s.files += Dir['man/man?/*.?']
+    s.add_development_dependency 'md2man', '~> 1.4'
+
+Add the following line to your Rakefile:
+
+    require 'md2man/rakefile'
+
+You now have a `rake md2man` task that builds manual pages from Markdown files
+(with ".markdown", ".mkd", or ".md" extension) inside `man/man*/` directories.
+There are also sub-tasks to build *only* UNIX or HTML manual pages separately.
+
+If you're using Bundler, this task also hooks into Bundler's gem packaging
+tasks and ensures that your manual pages are built for packaging into a gem:
+
+    bundle exec rake build
+    gem spec pkg/*.gem | fgrep man/man
 
 ## License
 

data/bin/md2man

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN 1 2012-10-13 1.3.2
+# MD2MAN 1 2012-10-14 1.4.0
 
 ## NAME
 
@@ -32,8 +32,9 @@ md2man extends markdown(7) syntax in the following ways, as provisioned in the
 
 md2man extends markdown(7) semantics in the following ways:
 
-  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
+  * The first top-level heading (H1) found in the document is emitted as `.TH`
     in the roff(7) output to define the UNIX manual page's header and footer.
+    Any subsequent top-level headings (H1) are treated as second-level (H2).
 
 ### Markdown extensions
 
@@ -53,7 +54,7 @@ The following [Redcarpet] extensions are enabled while processing markdown(7):
 
 ## SEE ALSO
 
-markdown(7), roff(7)
+md2man-html(1)
 
 [md2man]: https://github.com/sunaku/md2man
 [Redcarpet]: https://github.com/vmg/redcarpet

data/bin/md2man-html

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# MD2MAN-HTML 1 2012-10-14 1.4.0
+
+## NAME
+
+md2man-html - convert md2man(1) flavored markdown(7) into HTML
+
+## SYNOPSIS
+
+`md2man-html` [*OPTION*]... [*FILE*]
+
+## DESCRIPTION
+
+This program converts the markdown(7) input from the given *FILE* into HTML
+and then prints the result to stdout.  stdin is read if *FILE* is not given.
+
+### Document format
+
+See md2man(1) for details about the document format and Markdown extensions.
+
+### Cross linking
+
+References to other manual pages are converted into hyperlinks that have
+class="manpage-reference" and href="../man${section}/${page}.${section}.html"
+attributes.
+
+For example, the markdown(7) reference would be converted into HTML as:
+
+    <a class="manpage-reference" href="../man7/markdown.7.html">markdown(7)</a>
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+## SEE ALSO
+
+md2man(1)
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+
+require 'md2man/html/engine'
+puts Md2Man::HTML::ENGINE.render(ARGF.read)

data/lib/md2man/html/engine.rb

@@ -0,0 +1,21 @@
+require 'redcarpet'
+require 'md2man/html'
+
+module Md2Man
+module HTML
+
+  class Engine < Redcarpet::Render::HTML
+    include HTML
+  end
+
+  ENGINE = Redcarpet::Markdown.new(Engine,
+    :tables => true,
+    :autolink => true,
+    :superscript => true,
+    :strikethrough => true,
+    :no_intra_emphasis => false,
+    :fenced_code_blocks => true
+  )
+
+end
+end

data/lib/md2man/html.rb

@@ -0,0 +1,55 @@
+require 'cgi'
+require 'md2man/document'
+
+module Md2Man
+module HTML
+
+  include Document
+
+  #---------------------------------------------------------------------------
+  # block-level processing
+  #---------------------------------------------------------------------------
+
+  def normal_paragraph text
+    "<p>#{text}</p>"
+  end
+
+  def tagged_paragraph text
+    head, *body = text.lines.to_a
+    "<dl><dt>#{head.chomp}</dt><dd>#{body.join}</dd></dl>"
+  end
+
+  def indented_paragraph text
+    "<dl><dd>#{text}</dd></dl>"
+  end
+
+  def block_code code, language
+    "<pre>#{codespan(super)}</pre>"
+  end
+
+  def header text, level
+    id = text.gsub(/<.+?>/, '-').        # strip all HTML tags
+      gsub(/\W+/, '-').gsub(/^-|-$/, '') # fold non-word chars
+    %{<h#{level} id="#{id}">#{text}</h#{level}>}
+  end
+
+  #---------------------------------------------------------------------------
+  # span-level processing
+  #---------------------------------------------------------------------------
+
+  def codespan code
+    "<code>#{CGI.escapeHTML(super)}</code>"
+  end
+
+  def reference page, section, addendum
+    url = reference_url(page, section)
+    %{<a class="manpage-reference" href="#{url}">#{page}(#{section})</a>#{addendum}}
+  end
+
+  # You can override this in a derived class to compute URLs as you like!
+  def reference_url page, section
+    "../man#{section}/#{page}.#{section}.html"
+  end
+
+end
+end

data/lib/md2man/rakefile.rb

@@ -0,0 +1,71 @@
+require 'rake'
+
+# build man pages before building ruby gem using bundler
+%w[build install release].each {|t| task t => :md2man }
+
+#-----------------------------------------------------------------------------
+desc 'Build manual pages from Markdown files in man/.'
+task :md2man => ['md2man:man', 'md2man:web']
+#-----------------------------------------------------------------------------
+
+mkds = FileList['man/man*/*.{markdown,mkd,md}']
+mans = mkds.pathmap('%X')
+webs = mans.pathmap('%p.html')
+
+render_file_task = lambda do |src, dst, renderer|
+  directory dir = dst.pathmap('%d')
+  file dst => [dir, src] do
+    input = File.read(src)
+    output = renderer.call(input)
+    File.open(dst, 'w') {|f| f << output }
+  end
+end
+
+#-----------------------------------------------------------------------------
+desc 'Build UNIX manual pages from Markdown files in man/.'
+task 'md2man:man' => mans
+#-----------------------------------------------------------------------------
+
+mkds.zip(mans).each do |src, dst|
+  render_file_task.call src, dst, lambda {|input|
+    require 'md2man/engine'
+    Md2Man::ENGINE.render(input)
+  }
+end
+
+#-----------------------------------------------------------------------------
+desc 'Build HTML manual pages from Markdown files in man/.'
+task 'md2man:web' => 'man/index.html'
+#-----------------------------------------------------------------------------
+
+file 'man/index.html' => webs do |t|
+  output = []
+  dirs = webs.group_by {|web| web.pathmap('%d') }.each do |dir, dir_webs|
+    subdir = dir.pathmap('%f')
+    output << %{<h2 id="#{subdir}">#{subdir}</h2>}
+    dir_webs.each do |web|
+      title = web.pathmap('%n').sub(/\.(.+)$/, '(\1)')
+      link = %{<a href="#{subdir}/#{web.pathmap('%f')}">#{title}</a>}
+      info = File.read(web).scan(%r{<h2.*?>NAME</h2>(.+?)<h2}m).flatten.first.
+             to_s.split(/\s+-\s+/, 2).last.to_s.gsub(/<.+?>/, '') # strip HTML
+      output << "<dl><dt>#{link}</dt><dd>#{info}</dd></dl>"
+    end
+    File.open("#{dir}/index.html", 'w') do |f|
+      f << %{<meta http-equiv="refresh" content="0;url=../index.html##{subdir}"/>}
+    end
+  end
+  File.open(t.name, 'w') {|f| f.puts output }
+end
+
+mkds.zip(webs).each do |src, dst|
+  render_file_task.call src, dst, lambda {|input|
+    require 'md2man/html/engine'
+    output = Md2Man::HTML::ENGINE.render(input)
+    navbar = '<div class="manpath-navigation">' + [
+      %{<a href="../index.html">#{dst.pathmap('%1d')}</a>},
+      %{<a href="index.html">#{dst.pathmap('%-1d')}</a>},
+      %{<a href="">#{dst.pathmap('%n')}</a>},
+    ].join(' &rarr; ') + '</div>'
+    [navbar, output, navbar].join('<hr/>')
+  }
+end

data/lib/md2man/roff.rb

@@ -12,6 +12,7 @@ module Roff
   def preprocess document
     @ordered_list_id = 0
     @table_cells = {}
+    @h1_seen = false
     super
   end
 
@@ -57,7 +58,13 @@ module Roff
   def header text, level
     macro =
       case level
-      when 1 then :TH
+      when 1
+        if @h1_seen
+          :SH
+        else
+          @h1_seen = true
+          :TH
+        end
       when 2 then :SH
       else :SS
       end

data/lib/md2man/version.rb

@@ -1,3 +1,3 @@
 module Md2Man
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

data/man/man1/md2man-html.1

@@ -0,0 +1,44 @@
+.TH MD2MAN\-HTML 1 2012\-10\-14 1.4.0
+.SH NAME
+.PP
+md2man\-html \- convert 
+.BR md2man (1) 
+flavored 
+.BR markdown (7) 
+into HTML
+.SH SYNOPSIS
+.PP
+\fB\fCmd2man-html\fR [\fIOPTION\fP]... [\fIFILE\fP]
+.SH DESCRIPTION
+.PP
+This program converts the 
+.BR markdown (7) 
+input from the given \fIFILE\fP into HTML
+and then prints the result to stdout.  stdin is read if \fIFILE\fP is not given.
+.SS Document format
+.PP
+See 
+.BR md2man (1) 
+for details about the document format and Markdown extensions.
+.SS Cross linking
+.PP
+References to other manual pages are converted into hyperlinks that have
+class="manpage\-reference" and href="../man${section}/${page}.${section}.html"
+attributes.
+.PP
+For example, the 
+.BR markdown (7) 
+reference would be converted into HTML as:
+.PP
+.RS
+.nf
+<a class="manpage-reference" href="../man7/markdown.7.html">markdown(7)</a>
+.fi
+.RE
+.SH OPTIONS
+.TP
+\fB\fC-h\fR, \fB\fC--help\fR
+Show this help manual.
+.SH SEE ALSO
+.PP
+.BR md2man (1)

data/man/man1/md2man.1

@@ -1,4 +1,4 @@
-.TH MD2MAN 1 2012\-10\-13 1.3.2
+.TH MD2MAN 1 2012\-10\-14 1.4.0
 .SH NAME
 .PP
 md2man \- convert 
@@ -49,10 +49,11 @@ md2man extends
 semantics in the following ways:
 .RS
 .IP \(bu 2
-There can be at most one top\-level heading (H1).  It is emitted as \fB\fC.TH\fR
+The first top\-level heading (H1) found in the document is emitted as \fB\fC.TH\fR
 in the 
 .BR roff (7) 
 output to define the UNIX manual page's header and footer.
+Any subsequent top\-level headings (H1) are treated as second\-level (H2).
 .RE
 .SS Markdown extensions
 .PP
@@ -81,5 +82,4 @@ fenced_code_blocks
 Show this help manual.
 .SH SEE ALSO
 .PP
-.BR markdown (7), 
-.BR roff (7)
+.BR md2man-html (1)

data/md2man.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.summary       = 'markdown to manpage'
   s.description   = 'Converts markdown documents into UNIX manual pages.'
 
-  s.files         = `git ls-files`.split("\n") + Dir['man/**/*']
+  s.files         = `git ls-files`.split("\n") + Dir['man/man?/*.?']
   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']

data/test/md2man/html_test.rb

@@ -0,0 +1,127 @@
+require 'test_helper'
+require 'md2man/html/engine'
+
+describe 'html engine' do
+  before do
+    @markdown = Redcarpet::Markdown.new(Md2Man::HTML::Engine)
+  end
+
+  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
+      |<p>just some paragraph
+      |spanning
+      |multiple
+      |lines
+      |but within 4-space indent</p>
+    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
+      |
+      |  and a single line following
+      |
+      |  and multiple
+      |  lines following
+    INPUT
+      |<dl><dt>just some paragraph</dt><dd>spanning
+      |multiple
+      |lines
+      |but within 4-space indent</dd></dl><dl><dd>and a single line following</dd></dl><dl><dd>and multiple
+      |lines following</dd></dl>
+    OUTPUT
+  end
+
+  it 'renders references to other man pages as hyperlinks in middle of line' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |convert them from markdown(7) into roff(7), using
+    INPUT
+      |<p>convert them from <a class="manpage-reference" href="../man7/markdown.7.html">markdown(7)</a> into <a class="manpage-reference" href="../man7/roff.7.html">roff(7)</a>, using</p>
+    OUTPUT
+  end
+
+  it 'renders references to other man pages as hyperlinks at beginning of line' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |markdown(1) into roff(2)
+    INPUT
+      |<p><a class="manpage-reference" href="../man1/markdown.1.html">markdown(1)</a> into <a class="manpage-reference" href="../man2/roff.2.html">roff(2)</a></p>
+    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
+      |<pre><code>this is a code block
+      |containing markdown(7),
+      |roff(7), and much more!
+      |</code></pre>
+    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
+      |<p>this is a code span <code>containing markdown(7), roff(7), and</code> much more!</p>
+    OUTPUT
+  end
+
+  it 'escapes backslashes inside code blocks' do
+    # NOTE: we have to escape backslashes in the INPUT to
+    #       prevent Ruby from interpreting them as escapes
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |    _______      _______
+      |     ___  /___________ /__
+      |      _  __/ __ \\  __/ /_/
+      |      / /_/ /_/ / / / ,\\
+      |      \\__/\\____/_/ /_/|_\\
+      |                 >>>------>
+    INPUT
+      |<pre><code>_______      _______
+      | ___  /___________ /__
+      |  _  __/ __ \\  __/ /_/
+      |  / /_/ /_/ / / / ,\\
+      |  \\__/\\____/_/ /_/|_\\
+      |             &gt;&gt;&gt;------&gt;
+      |</code></pre>
+    OUTPUT
+  end
+
+  it 'adds ID attributes on headings for permalinking' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# foo *BAR*
+      |## bar BAZ
+      |### --BAZ-QUX--
+      |#### qux (MOZ)
+      |##### {m}oz END
+    INPUT
+<h1 id="foo-BAR">foo <em>BAR</em></h1>\
+<h2 id="bar-BAZ">bar BAZ</h2>\
+<h3 id="BAZ-QUX">--BAZ-QUX--</h3>\
+<h4 id="qux-MOZ">qux (MOZ)</h4>\
+<h5 id="m-oz-END">{m}oz END</h5>
+    OUTPUT
+  end
+end

data/test/md2man/roff_test.rb

@@ -9,7 +9,7 @@
 require 'test_helper'
 require 'md2man/engine'
 
-describe Md2Man::Roff do
+describe 'roff engine' do
   before do
     @markdown = Redcarpet::Markdown.new(
       Md2Man::Engine,
@@ -229,6 +229,30 @@ describe Md2Man::Roff do
     OUTPUT
   end
 
+  it 'renders non-first top-level headings as 2nd-level headings' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |just some h1 heading
+      |====================
+      |
+      |yet another h1 heading
+      |======================
+    INPUT
+      |.TH just some h1 heading
+      |.SH yet another h1 heading
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |BINMAN 1 "2011-11-05" "1.1.0" "Ruby User Manuals"
+      |=================================================
+      |
+      |DUPMAN 1 "2011-11-05" "1.1.0" "Ruby User Manuals"
+      |=================================================
+    INPUT
+      |.TH BINMAN 1 "2011\\-11\\-05" "1.1.0" "Ruby User Manuals"
+      |.SH DUPMAN 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-13 00:00:00.000000000 Z
+date: 2012-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
@@ -80,6 +80,7 @@ email:
 - sunaku@gmail.com
 executables:
 - md2man
+- md2man-html
 extensions: []
 extra_rdoc_files: []
 files:
@@ -92,14 +93,20 @@ files:
 - README.markdown
 - Rakefile
 - bin/md2man
+- bin/md2man-html
 - lib/md2man.rb
 - lib/md2man/document.rb
 - lib/md2man/engine.rb
+- lib/md2man/html.rb
+- lib/md2man/html/engine.rb
+- lib/md2man/rakefile.rb
 - lib/md2man/roff.rb
 - lib/md2man/version.rb
 - md2man.gemspec
+- test/md2man/html_test.rb
 - test/md2man/roff_test.rb
 - test/test_helper.rb
+- man/man1/md2man-html.1
 - man/man1/md2man.1
 homepage: http://github.com/sunaku/md2man
 licenses: []
@@ -115,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3059084899837276996
+      hash: -1838080913948275679
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -124,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3059084899837276996
+      hash: -1838080913948275679
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -132,5 +139,6 @@ signing_key:
 specification_version: 3
 summary: markdown to manpage
 test_files:
+- test/md2man/html_test.rb
 - test/md2man/roff_test.rb
 - test/test_helper.rb