md2man 1.4.1 → 1.4.2

data/HISTORY.markdown

@@ -1,3 +1,21 @@
+## Version 1.4.2 (2013-02-24)
+
+Patch:
+
+  * The `md2man:web` task from `md2man/rakefile` now:
+
+    * emits valid HTML5 with helpful HTML page titles
+
+    * uses Twitter Bootstrap styling for HTML man pages
+
+    * emits only ONE index page for all HTML man pages
+
+Other:
+
+  * README: better organize the subsections of "Usage"
+
+  * include md2man rake tasks in developer's rakefile
+
 ## Version 1.4.1 (2013-02-23)
 
 Patch:

data/README.markdown

@@ -45,15 +45,36 @@ It issues a warning when it encounters these instead.  Patches are welcome!
     cd md2man
     bundle install
     bundle exec md2man --help  # run it directly
-    bundle exec rake -T        # packaging tasks
+    bundle exec rake --tasks   # packaging tasks
 
-## Usage (for [roff] output)
+## Usage
 
-### At the command line
+### Document format
+
+md2man extends [Markdown] syntax in the following ways, as provisioned in the
+`Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
+
+  * Paragraphs whose lines are all uniformly indented by two spaces are
+    considered to be "indented paragraphs".  They are unindented accordingly
+    before emission as `.IP` in the [roff] output.
+
+  * 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 `.TP` in the [roff] output.
+
+md2man extends [Markdown] semantics in the following ways:
+
+  * 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).
+
+### For [roff] output
+
+#### At the command line
 
     md2man --help
 
-### Inside a Ruby script
+#### Inside a Ruby script
 
 Use the default renderer:
 
@@ -91,13 +112,34 @@ Mix-in your own renderer:
     engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
     your_roff_output = engine.render(your_markdown_input)
 
-## Usage (for HTML output)
+#### 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 manual pages individually as [roff] or HTML.
+
+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
+
+### For HTML output
 
-### At the command line
+#### At the command line
 
     md2man-html --help
 
-### Inside a Ruby script
+#### Inside a Ruby script
 
 Use the default renderer:
 
@@ -135,46 +177,6 @@ Mix-in your own renderer:
     engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
     your_html_output = engine.render(your_markdown_input)
 
-### Document format
-
-md2man extends [Markdown] syntax in the following ways, as provisioned in the
-`Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
-
-  * Paragraphs whose lines are all uniformly indented by two spaces are
-    considered to be "indented paragraphs".  They are unindented accordingly
-    before emission as `.IP` in the [roff] output.
-
-  * 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 `.TP` in the [roff] output.
-
-md2man extends [Markdown] semantics in the following ways:
-
-  * 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 manual pages individually as [roff] or HTML.
-
-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
 
 Released under the ISC license.  See the LICENSE file for details.

data/Rakefile

@@ -1,2 +1,3 @@
 require "bundler/gem_tasks"
 require "binman/rakefile"
+require "md2man/rakefile"

data/bin/md2man

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN 1 2013-02-23 1.4.1
+# MD2MAN 1 2013-02-24 1.4.2
 
 ## NAME
 

data/bin/md2man-html

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN-HTML 1 2013-02-23 1.4.1
+# MD2MAN-HTML 1 2013-02-24 1.4.2
 
 ## NAME
 

data/lib/md2man/rakefile.rb

@@ -40,34 +40,127 @@ desc 'Build HTML manual pages from Markdown files in man/.'
 task 'md2man:web' => 'man/index.html'
 #-----------------------------------------------------------------------------
 
+wrap_html_template = lambda do |title, content|
+<<WRAP_HTML_TEMPLATE
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>#{title}</title>
+  <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
+  <link rel="stylesheet" href="http://twitter.github.com/bootstrap/assets/css/bootstrap.css" />
+  <style type="text/css">
+    @media all {
+      .manpage h1 {
+        font-weight: normal;
+        font-size: smaller;
+        text-align: right;
+      }
+      .manpage h2,
+      .manpage h3,
+      .manpage h4,
+      .manpage h5,
+      .manpage h6 {
+        margin-top: 1em;
+      }
+    }
+    @media screen {
+      .manpage {
+        font-family: monospace;
+        max-width: 78ex;
+      }
+      .manpage h1 {
+        margin-top: -5em;
+      }
+    }
+
+    @media print {
+      .navbar {
+        display: none;
+      }
+
+      /* improve readability of revealed hyperlink URLs */
+      a:after {
+        font-family: monospace;
+      }
+
+      /* internal links and manual page cross-references */
+      a[href^='#'], a[href^='../man'] {
+        color: inherit;
+        font-weight: bolder;
+        text-decoration: none;
+      }
+
+      /* undo bootstrap's revealing of those hyperlinks */
+      a[href^='#']:after, a[href^='../man']:after {
+        content: none;
+      }
+    }
+  </style>
+</head>
+<body>#{content}</body>
+</html>
+WRAP_HTML_TEMPLATE
+end
+
+parse_manpage_name = lambda do |html_file_name|
+  html_file_name.pathmap('%n').sub(/\.(.+)$/, '(\1)')
+end
+
+parse_manpage_info = lambda do |html_file_body|
+  html_file_body.scan(%r{<h2.*?>NAME</h2>(.+?)<h2}m).flatten.first.
+  to_s.split(/\s+-\s+/, 2).last.to_s.gsub(/<.+?>/, '') # strip HTML
+end
+
 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>}
+  buffer = ['<div class="container-fluid">']
+  webs.group_by {|web| web.pathmap('%d') }.each do |dir, dir_webs|
+    subdir = dir.sub('man/', '')
+    buffer << %{<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}"/>}
+      name = parse_manpage_name.call(web)
+      info = parse_manpage_info.call(File.read(web))
+      link = %{<a href="#{subdir}/#{web.pathmap('%f')}">#{name}</a>}
+      buffer << %{<dl class="dl-horizontal"><dt>#{link}</dt><dd>#{info}</dd></dl>}
     end
   end
-  File.open(t.name, 'w') {|f| f.puts output }
+  buffer << '</div>'
+  content = buffer.join
+
+  title = t.name.pathmap('%X')
+  output = wrap_html_template.call(title, content)
+  File.open(t.name, 'w') {|f| f << 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/>')
+
+    name = parse_manpage_name.call(dst)
+    info = parse_manpage_info.call(output)
+    title = [name, info].join(' &mdash; ')
+
+    subdir = dst.pathmap('%d').sub('man/', '')
+    ascend = '../' * subdir.count('/').next
+    content = [
+      '<div class="navbar">',
+        '<div class="navbar-inner">',
+          '<span class="brand">',
+            %{<a href="#{ascend}index.html##{subdir}">#{subdir}</a>},
+            '/',
+            dst.pathmap('%n'),
+          '</span>',
+        '</div>',
+      '</div>',
+      '<div class="container-fluid">',
+        '<div class="manpage">',
+          output,
+        '</div>',
+      '</div>',
+    ].join
+
+    wrap_html_template.call title, content
   }
 end

data/lib/md2man/version.rb

@@ -1,3 +1,3 @@
 module Md2Man
-  VERSION = "1.4.1"
+  VERSION = "1.4.2"
 end

data/man/man1/md2man-html.1

@@ -1,4 +1,4 @@
-.TH MD2MAN\-HTML 1 2013\-02\-23 1.4.1
+.TH MD2MAN\-HTML 1 2013\-02\-24 1.4.2
 .SH NAME
 .PP
 md2man\-html \- convert 

data/man/man1/md2man.1

@@ -1,4 +1,4 @@
-.TH MD2MAN 1 2013\-02\-23 1.4.1
+.TH MD2MAN 1 2013\-02\-24 1.4.2
 .SH NAME
 .PP
 md2man \- convert 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.4.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-23 00:00:00.000000000 Z
+date: 2013-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
@@ -128,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2835073792924155153
+      hash: -4385989232300827218
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23