binman 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1cc5d7a68d2e6551e60382f9b64667e099ce762f
-  data.tar.gz: 2a8ecf5be7b27cc58f680c63ef8f90fc96a7088e
+  metadata.gz: 2b919eb526cd3af62dc86a638b74af4569487723
+  data.tar.gz: 1ddf9d14c886406da79b2c4b6f5fbe6129ae629f
 SHA512:
-  metadata.gz: 8b96360d2329f069691839253409f0d261b72caceaa612762817938b056529a7e26fea03f8f830330ebf867252d7ca718b53cbb435820ab5108ad2422a93d27a
-  data.tar.gz: a332414eed9ce3a4f0e5d70ce83c8ca2169063052deff307f1778b42a9ed2923a76a0736d946be6b757f93633c485a474fe3d417acac99eb3f1658009d04de0c
+  metadata.gz: 18978c8074e6b15cb9201f54b8e7c2a2366414dd01d78e6c0f34889dfc84cc1b51eb6526296b0b26d0e459a0d7ce8d5771ade4b9ca7c536b74bc36ad93bae91b
+  data.tar.gz: ecbfcfb0be03016bf1f1ed836ffeb059e0b1d6dd232c424c0e6365f07da548446b36f1eb91de53d01579a1e8bef6c10ceb5d756cd918bd79678b91ca4f8f5835

data/VERSION.markdown

@@ -1,3 +1,46 @@
+## Version 4.1.0 (2016-02-10)
+
+### Minor:
+
+  * Print path of HTML man page to STDOUT when launching browser.
+
+### Patch:
+
+  * Revert "ensure 'binman:web' task works the first time thru".
+
+    This reverts commit dd0511e78e02546cac4903b5c6de6243607a8bba,
+    which was causing the following error under Ruby 2.3.0p0.
+
+      % rake build
+      mkdir -p man/man1
+      rake aborted!
+      LoadError: cannot load such file -- md2man/rakefile.rb
+      ./lib/binman/rakefile.rb:29:in `load'
+      ./lib/binman/rakefile.rb:29:in `block in <top (required)>'
+      Tasks: TOP => build => binman => binman:man
+      (See full trace by running task with --trace)
+      exit 1
+
+  * Show HTML manual only as fallback to TTY man page.
+
+    This prevents annoying browser launches every time you run `--help`.
+
+  * `BinMan::show()` didn't always fallback to plain text header.
+
+  * Don't override `man -P` pager; set `$LESS` and `$MORE` instead.
+
+    Also, shell escaping the pattern prevents you from using regexp syntax.
+
+  * `man FILE` isn't portable; use `man -M ...` instead.
+
+    `man FILE` used to work in Debian, but doesn't work under Void Linux.
+
+    `man -l FILE` works in Linux and OpenBSD but not on MacOSX / FreeBSD.
+
+    Therefore, avoid all this portability mess using `man -M ...` instead.
+
+  * Handle case where roff manual page is missing but HTML version exists.
+
 ## Version 4.0.0 (2014-10-26)
 
 ### Major:

data/bin/binman

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN 1 2014-10-26 4.0.0
+# BINMAN 1 2016-02-10 4.1.0
 
 ## NAME
 

data/bin/binman-rake

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN-RAKE 1 2014-10-26 4.0.0
+# BINMAN-RAKE 1 2016-02-10 4.1.0
 
 ## NAME
 

data/lib/binman.rb

@@ -1,3 +1,4 @@
+require 'fileutils'
 require 'shellwords'
 require 'binman/version'
 
@@ -45,38 +46,13 @@ module BinMan
     if file = find(source) and File.exist? file
       man_page = File.basename(file)
       man_path = File.expand_path('../../man', file)
-
-      # try showing HTML manual page in a web browser in background
-      require 'opener'
-      Dir["#{man_path}/**/#{man_page}.*.html"].each do |man_html|
-        # close streams to avoid interference with man(1) reader below
-        begin
-          Opener.spawn man_html, 0 => :close, 1 => :close, 2 => :close
-        rescue Errno::ENOENT
-          # designated opener program could not be found on this system
-        end
-      end
-
-      # try showing roff manual page in man(1) reader in foreground;
-      # close STDERR to avoid interference with the fall back below
-      return if view query, '-M', man_path, '-a', man_page, 2 => :close
+      return if show_man(man_path, man_page, query)
     end
 
-    # fall back to showing leading comment header as-is
+    # fall back to rendering leading comment header or showing it as-is
     header = snip(source)
-
-    begin
-      roff = conv(header)
-      require 'tempfile'
-      Tempfile.open 'binman' do |temp|
-        temp.write roff
-        temp.close
-        view query, temp.path, 2 => :close
-      end
-    rescue => error
-      warn "binman: #{error}"
-      puts header
-    end
+    return if show_str(header, query)
+    puts header
   end
 
   # Shows leading comment header from given source as UNIX man page and exits
@@ -95,16 +71,12 @@ module BinMan
 private
 
   # Launches man(1) with the given arguments and then tries to search for the
-  # query (if given) within.  If man(1) is not able to launch with the search
-  # capability, then it tries launching man(1) without the search capability.
+  # query (if given) within.  This is achieved by specifying the LESS and MORE
+  # environment variables used by the less(1) and more(1) pagers respectively.
   def view query, *argv
-    # man(1) defaults to `pager -s` under Debian but `less -is` under CentOS
-    # so try different pagers, but always fall back to using no pager at all.
-    # See https://www.debian-administration.org/article/246/ for pager list.
-    query and %w[ pager less most more ].any? do |pager|
-      # the `-s` and `+/pattern` options are universally supported by pagers
-      system 'man', '-P', "#{pager} -s +/#{query.shellescape}", *argv
-    end or system 'man', *argv
+    env = query ? {'LESS' => [ENV['LESS'], "+/#{query}"].compact.join(' '),
+                   'MORE' => [ENV['MORE'], "+/#{query}"].compact.join(' ')} : {}
+    system env, 'man', *argv
   end
 
   # Converts given markdown(7) source into roff(7).
@@ -132,4 +104,55 @@ private
       first_caller.sub(/:\d+.*$/, '')
     end
   end
+
+  # Tries to show the given manual page file in man(1) reader
+  # and returns true if successful; else you need a fallback.
+  # If HTML manual page shown, its path is printed to stdout.
+  def show_man path, page, query=nil
+    # try showing roff manual page in man(1) reader in foreground
+    Dir["#{path}/man?/#{page}.?"].any? and
+    view query, '-M', path, '-a', page, 2 => :close or
+    begin
+      # try showing HTML manual page in a web browser in background
+      require 'opener'
+      Dir["#{path}/**/#{page}.*.html"].map do |html|
+        begin
+          # close streams to avoid interference with man(1) reader
+          Opener.spawn html, 0 => :close, 1 => :close, 2 => :close
+          puts html
+          true
+        rescue Errno::ENOENT
+          # designated opener program was not found on this system
+        end
+      end.compact.any?
+    end
+  end
+
+  # Tries to display the given header string in man(1) reader
+  # and returns true if successful; else you need a fallback.
+  def show_str header, query=nil
+    roff = conv(header)
+
+    require 'tempfile'
+    Tempfile.open 'binman' do |temp|
+      temp_man_root = temp.path + '_man'
+      begin
+        # create a temporary man/ directory structure for `man -M ...`
+        temp_man_page = 'temporary_manual_page'
+        temp_man_path = "#{temp_man_root}/man"
+        temp_man_file = "#{temp_man_path}/man1/#{temp_man_page}.1"
+        FileUtils.mkdir_p File.dirname(temp_man_file)
+
+        # write the given header string to temporary file and show it
+        File.open(temp_man_file, 'w') {|file| file << roff }
+        return true if show_man(temp_man_path, temp_man_page, query)
+      ensure
+        FileUtils.rm_rf temp_man_root
+      end
+    end
+
+    false
+  rescue => error
+    warn "binman: #{error}"
+  end
 end

data/lib/binman/rakefile.rb

@@ -26,7 +26,7 @@ end
 desc 'Build UNIX manual pages for bin/ scripts.'
 task 'binman:man' => mkds do
 #-----------------------------------------------------------------------------
-  load 'md2man/rakefile.rb'
+  require 'md2man/rakefile'
   Rake::Task['md2man:man'].invoke
 end
 
@@ -34,6 +34,6 @@ end
 desc 'Build HTML manual pages for bin/ scripts.'
 task 'binman:web' => mkds do
 #-----------------------------------------------------------------------------
-  load 'md2man/rakefile.rb'
+  require 'md2man/rakefile'
   Rake::Task['md2man:web'].invoke
 end

data/lib/binman/version.rb

@@ -1,3 +1,3 @@
 module BinMan
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/man/index.html

@@ -2,7 +2,7 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 4.0.0 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 4.0.1 https://github.com/sunaku/md2man" />
   <title>man/index</title>
   <link rel="stylesheet" href="style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->

data/man/man0/EXAMPLE.png

@@ -0,0 +1 @@
+../../EXAMPLE.png

data/man/man0/README.html

@@ -2,7 +2,7 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 4.0.0 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 4.0.1 https://github.com/sunaku/md2man" />
   <title>README</title>
   <link rel="stylesheet" href="../style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->

data/man/man0/README.markdown

@@ -0,0 +1 @@
+../../README.markdown

data/man/man0/VERSION.html

@@ -2,12 +2,34 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 4.0.0 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 4.0.1 https://github.com/sunaku/md2man" />
   <title>VERSION</title>
   <link rel="stylesheet" href="../style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
 </head>
-<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man0">man0</a>/VERSION</span></div></div><div class="container-fluid"><h2 id="version-4-0-0-2014-10-26"><a name="version-4-0-0-2014-10-26" href="#version-4-0-0-2014-10-26" class="md2man-permalink" title="permalink"></a>Version 4.0.0 (2014-10-26)</h2><h3 id="major"><a name="major" href="#major" class="md2man-permalink" title="permalink"></a>Major:</h3>
+<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man0">man0</a>/VERSION</span></div></div><div class="container-fluid"><h2 id="version-4-1-0-2016-02-10"><a name="version-4-1-0-2016-02-10" href="#version-4-1-0-2016-02-10" class="md2man-permalink" title="permalink"></a>Version 4.1.0 (2016-02-10)</h2><h3 id="minor"><a name="minor" href="#minor" class="md2man-permalink" title="permalink"></a>Minor:</h3>
+<ul>
+<li>Print path of HTML man page to STDOUT when launching browser.</li>
+</ul>
+<h3 id="patch"><a name="patch" href="#patch" class="md2man-permalink" title="permalink"></a>Patch:</h3>
+<ul>
+<li><p>Revert &quot;ensure &#39;binman:web&#39; task works the first time thru&quot;.</p><p>This reverts commit dd0511e78e02546cac4903b5c6de6243607a8bba,
+which was causing the following error under Ruby 2.3.0p0.</p><dl><dd>% rake build
+mkdir -p man/man1
+rake aborted!
+LoadError: cannot load such file -- md2man/rakefile.rb
+./lib/binman/rakefile.rb:29:in <code>load&#39;
+./lib/binman/rakefile.rb:29:in</code>block in <top (required)>&#39;
+Tasks: TOP =&gt; build =&gt; binman =&gt; binman:man
+(See full trace by running task with --trace)
+exit 1</dd></dl></li>
+<li><p>Show HTML manual only as fallback to TTY man page.</p><p>This prevents annoying browser launches every time you run <code>--help</code>.</p></li>
+<li><p><code>BinMan::show()</code> didn&#39;t always fallback to plain text header.</p></li>
+<li><p>Don&#39;t override <code>man -P</code> pager; set <code>$LESS</code> and <code>$MORE</code> instead.</p><p>Also, shell escaping the pattern prevents you from using regexp syntax.</p></li>
+<li><p><code>man FILE</code> isn&#39;t portable; use <code>man -M ...</code> instead.</p><p><code>man FILE</code> used to work in Debian, but doesn&#39;t work under Void Linux.</p><p><code>man -l FILE</code> works in Linux and OpenBSD but not on MacOSX / FreeBSD.</p><p>Therefore, avoid all this portability mess using <code>man -M ...</code> instead.</p></li>
+<li><p>Handle case where roff manual page is missing but HTML version exists.</p></li>
+</ul>
+<h2 id="version-4-0-0-2014-10-26"><a name="version-4-0-0-2014-10-26" href="#version-4-0-0-2014-10-26" class="md2man-permalink" title="permalink"></a>Version 4.0.0 (2014-10-26)</h2><h3 id="major"><a name="major" href="#major" class="md2man-permalink" title="permalink"></a>Major:</h3>
 <ul>
 <li><p><a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a>: Rename the <code>load</code> command to <code>snip</code> and remove <code>conv</code>.</p>
 <ul>
@@ -17,7 +39,7 @@
 <li><p>Upgrade to md2man 4.0, which no longer expands cross references in code
 spans and code blocks.  Your manuals might be rendered differently now.</p></li>
 </ul>
-<h2 id="version-3-4-1-2014-07-01"><a name="version-3-4-1-2014-07-01" href="#version-3-4-1-2014-07-01" class="md2man-permalink" title="permalink"></a>Version 3.4.1 (2014-07-01)</h2><p>This release fixes the help options&#39; REGEXP argument under non-Debian systems.</p><h3 id="patch"><a name="patch" href="#patch" class="md2man-permalink" title="permalink"></a>Patch:</h3>
+<h2 id="version-3-4-1-2014-07-01"><a name="version-3-4-1-2014-07-01" href="#version-3-4-1-2014-07-01" class="md2man-permalink" title="permalink"></a>Version 3.4.1 (2014-07-01)</h2><p>This release fixes the help options&#39; REGEXP argument under non-Debian systems.</p><h3 id="patch-1"><a name="patch-1" href="#patch-1" class="md2man-permalink" title="permalink"></a>Patch:</h3>
 <ul>
 <li><p><a class="md2man-reference">pager(1)</a> isn&#39;t a universal command: CentOS uses <code>less -is</code> instead.</p></li>
 <li><p>Silence <a class="md2man-reference">man(1)</a> stderr when displaying dynamically extracted manual.</p></li>
@@ -28,7 +50,7 @@ spans and code blocks.  Your manuals might be rendered differently now.</p></li>
 <li><p>Document REGEXP argument for help options in <code>bin/*</code>.</p></li>
 <li><p>Refer to REGEXP argument as PATTERN like less does.</p></li>
 </ul>
-<h2 id="version-3-4-0-2014-06-29"><a name="version-3-4-0-2014-06-29" href="#version-3-4-0-2014-06-29" class="md2man-permalink" title="permalink"></a>Version 3.4.0 (2014-06-29)</h2><h3 id="minor"><a name="minor" href="#minor" class="md2man-permalink" title="permalink"></a>Minor:</h3>
+<h2 id="version-3-4-0-2014-06-29"><a name="version-3-4-0-2014-06-29" href="#version-3-4-0-2014-06-29" class="md2man-permalink" title="permalink"></a>Version 3.4.0 (2014-06-29)</h2><h3 id="minor-1"><a name="minor-1" href="#minor-1" class="md2man-permalink" title="permalink"></a>Minor:</h3>
 <ul>
 <li><p>GH-3: add optional regexp argument to <code>-h</code>/<code>--help</code> to search in <a class="md2man-reference">man(1)</a>.</p><p>The <code>-h</code> and <code>--help</code> options in <code>BinMan.help()</code> can now be optionally
 followed by a regular expression argument that specifies text to search

data/man/man0/VERSION.markdown

@@ -0,0 +1 @@
+../../VERSION.markdown

data/man/man1/binman-rake.1

@@ -1,4 +1,4 @@
-.TH BINMAN\-RAKE 1 2014\-10\-26 4.0.0
+.TH BINMAN\-RAKE 1 2016\-02\-10 4.1.0
 .SH NAME
 .PP
 binman\-rake \- run 

data/man/man1/binman-rake.1.html

@@ -2,12 +2,12 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 4.0.0 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 4.0.1 https://github.com/sunaku/md2man" />
   <title>binman-rake(1) &mdash; run rake(1) tasks from binman(1)</title>
   <link rel="stylesheet" href="../style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
 </head>
-<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man1">man1</a>/binman-rake.1</span></div></div><div class="container-fluid"><h1 id="binman-rake-1-2014-10-26-4-0-0"><a name="binman-rake-1-2014-10-26-4-0-0" href="#binman-rake-1-2014-10-26-4-0-0" class="md2man-permalink" title="permalink"></a><span class="md2man-title">BINMAN-RAKE</span> <span class="md2man-section">1</span> <span class="md2man-date">2014-10-26</span> <span class="md2man-source">4.0.0</span></h1><h2 id="name"><a name="name" href="#name" class="md2man-permalink" title="permalink"></a>NAME</h2><p>binman-rake - run <a class="md2man-reference">rake(1)</a> tasks from <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a></p><h2 id="synopsis"><a name="synopsis" href="#synopsis" class="md2man-permalink" title="permalink"></a>SYNOPSIS</h2><p><code>binman-rake</code> [<em>OPTION</em>]... [<em>TASK</em>]...</p><h2 id="description"><a name="description" href="#description" class="md2man-permalink" title="permalink"></a>DESCRIPTION</h2><p>This program lets you run <a class="md2man-reference">rake(1)</a> tasks provided by <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a> without having
+<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man1">man1</a>/binman-rake.1</span></div></div><div class="container-fluid"><h1 id="binman-rake-1-2016-02-10-4-1-0"><a name="binman-rake-1-2016-02-10-4-1-0" href="#binman-rake-1-2016-02-10-4-1-0" class="md2man-permalink" title="permalink"></a><span class="md2man-title">BINMAN-RAKE</span> <span class="md2man-section">1</span> <span class="md2man-date">2016-02-10</span> <span class="md2man-source">4.1.0</span></h1><h2 id="name"><a name="name" href="#name" class="md2man-permalink" title="permalink"></a>NAME</h2><p>binman-rake - run <a class="md2man-reference">rake(1)</a> tasks from <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a></p><h2 id="synopsis"><a name="synopsis" href="#synopsis" class="md2man-permalink" title="permalink"></a>SYNOPSIS</h2><p><code>binman-rake</code> [<em>OPTION</em>]... [<em>TASK</em>]...</p><h2 id="description"><a name="description" href="#description" class="md2man-permalink" title="permalink"></a>DESCRIPTION</h2><p>This program lets you run <a class="md2man-reference">rake(1)</a> tasks provided by <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a> without having
 to create a special file named <code>Rakefile</code> that contains the following snippet:</p><pre><code>require &#39;binman/rakefile&#39;
 </code></pre>
 <p>If no <em>TASK</em> is specified, then the <code>binman</code> task is run by default.</p><h2 id="tasks"><a name="tasks" href="#tasks" class="md2man-permalink" title="permalink"></a>TASKS</h2><dl><dt><code>binman</code></dt><dd>Runs the <code>binman:man</code> and <code>binman:web</code> tasks, in that order.</dd></dl><dl><dt><code>binman:man</code></dt><dd>Builds UNIX manual pages from scripts found in your <code>bin/</code> directory.

data/man/man1/binman.1

@@ -1,4 +1,4 @@
-.TH BINMAN 1 2014\-10\-26 4.0.0
+.TH BINMAN 1 2016\-02\-10 4.1.0
 .SH NAME
 .PP
 binman \- man pages for bin scripts

data/man/man1/binman.1.html

@@ -2,12 +2,12 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 4.0.0 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 4.0.1 https://github.com/sunaku/md2man" />
   <title>binman(1) &mdash; man pages for bin scripts</title>
   <link rel="stylesheet" href="../style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
 </head>
-<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man1">man1</a>/binman.1</span></div></div><div class="container-fluid"><h1 id="binman-1-2014-10-26-4-0-0"><a name="binman-1-2014-10-26-4-0-0" href="#binman-1-2014-10-26-4-0-0" class="md2man-permalink" title="permalink"></a><span class="md2man-title">BINMAN</span> <span class="md2man-section">1</span> <span class="md2man-date">2014-10-26</span> <span class="md2man-source">4.0.0</span></h1><h2 id="name"><a name="name" href="#name" class="md2man-permalink" title="permalink"></a>NAME</h2><p>binman - man pages for bin scripts</p><h2 id="synopsis"><a name="synopsis" href="#synopsis" class="md2man-permalink" title="permalink"></a>SYNOPSIS</h2><p><code>binman</code> [<em>OPTION</em>]... <em>COMMAND</em></p><h2 id="description"><a name="description" href="#description" class="md2man-permalink" title="permalink"></a>DESCRIPTION</h2><p><a href="https://github.com/sunaku/binman">binman</a> produces UNIX manual pages for your executable scripts. It can
+<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man1">man1</a>/binman.1</span></div></div><div class="container-fluid"><h1 id="binman-1-2016-02-10-4-1-0"><a name="binman-1-2016-02-10-4-1-0" href="#binman-1-2016-02-10-4-1-0" class="md2man-permalink" title="permalink"></a><span class="md2man-title">BINMAN</span> <span class="md2man-section">1</span> <span class="md2man-date">2016-02-10</span> <span class="md2man-source">4.1.0</span></h1><h2 id="name"><a name="name" href="#name" class="md2man-permalink" title="permalink"></a>NAME</h2><p>binman - man pages for bin scripts</p><h2 id="synopsis"><a name="synopsis" href="#synopsis" class="md2man-permalink" title="permalink"></a>SYNOPSIS</h2><p><code>binman</code> [<em>OPTION</em>]... <em>COMMAND</em></p><h2 id="description"><a name="description" href="#description" class="md2man-permalink" title="permalink"></a>DESCRIPTION</h2><p><a href="https://github.com/sunaku/binman">binman</a> produces UNIX manual pages for your executable scripts. It can
 extract their leading comment headers (defined below), convert them from
 <a class="md2man-reference">markdown(7)</a> into <a class="md2man-reference">roff(7)</a> using <a href="https://github.com/sunaku/md2man">md2man</a>, and display them using <a class="md2man-reference">man(1)</a>.</p><h3 id="leading-comment-headers"><a name="leading-comment-headers" href="#leading-comment-headers" class="md2man-permalink" title="permalink"></a>Leading comment headers</h3><p>A leading comment header can be one of the following two things:</p>
 <ol>

data/man/style.css

@@ -40,15 +40,20 @@
     float: left;
     margin-left: -1em;
     opacity: 0.25;
+    font-size: xx-large;
   }
 
   a.md2man-permalink:before {
-    content: '\2665'; /* ♥ */
+    content: '\2605'; /* ★ */
   }
 
   a.md2man-permalink:hover,
   *:target > a.md2man-permalink {
-    opacity: initial
+    opacity: inherit;
+  }
+
+  *:target > a.md2man-permalink {
+    color: red;
   }
 }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: binman
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Suraj N. Kurapati
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-26 00:00:00.000000000 Z
+date: 2016-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: md2man
@@ -110,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: man pages for bin scripts

data/man/man0/README.markdown

@@ -1,376 +0,0 @@
-# binman - man pages for bin scripts
-
-[binman] produces UNIX manual pages for executable scripts using [md2man].
-Simply [document your script in Markdown][md2man-markdown] as a comment at the
-top of your script and call `binman show` to display it as a UNIX manual page!
-Or, call `binman help` to display your manual _only_ when your script receives
-with `-h` or `--help` command-line options.  Or, call `binman snip` to extract
-the manual from your script for your own custom processing, outside of binman.
-And that's not all: [see the manual page][binman-man] for more possibilities!
-
-* Manuals: <https://sunaku.github.io/binman/man>
-* Sources: <https://github.com/sunaku/binman>
-* Support: <https://github.com/sunaku/binman/issues>
-* Package: <https://rubygems.org/gems/binman>
-
-## Features
-
-  * Supports any scripting language that has multi-line
-    comments or uses `#` for single-line comments: Ruby,
-    Perl, Python, Node.js, Tcl, AWK, UNIX shell, and more!
-
-  * Provides a Ruby library and a command-line client too.
-
-  * Individual extraction, conversion, and display commands.
-
-  * Implemented in roughly 150 lines of pure Ruby code! :-)
-
-### Demonstration
-
-![Obligatory screen-shot of binman(1) in action!](EXAMPLE.png)
-
-#### What can binman(1) do?
-
-Here are some real examples of processed bin scripts to help you get started:
-
-* [bin/tork](https://raw.github.com/sunaku/tork/master/bin/tork) &rArr;
-  [tork.1.markdown](https://sunaku.github.io/tork/man/man1/tork.1.markdown) &rArr;
-  [tork.1](https://sunaku.github.io/tork/man/man1/tork.1) +
-  [tork.1.html](https://sunaku.github.io/tork/man/man1/tork.1.html)
-* [bin/tork-runner](https://raw.github.com/sunaku/tork/master/bin/tork-runner) &rArr;
-  [tork-runner.1.markdown](https://sunaku.github.io/tork/man/man1/tork-runner.1.markdown) &rArr;
-  [tork-runner.1](https://sunaku.github.io/tork/man/man1/tork-runner.1) +
-  [tork-runner.1.html](https://sunaku.github.io/tork/man/man1/tork-runner.1.html)
-* [bin/tork-herald](https://raw.github.com/sunaku/tork/master/bin/tork-herald) &rArr;
-  [tork-herald.1.markdown](https://sunaku.github.io/tork/man/man1/tork-herald.1.markdown) &rArr;
-  [tork-herald.1](https://sunaku.github.io/tork/man/man1/tork-herald.1) +
-  [tork-herald.1.html](https://sunaku.github.io/tork/man/man1/tork-herald.1.html)
-* [bin/tork-driver](https://raw.github.com/sunaku/tork/master/bin/tork-driver) &rArr;
-  [tork-driver.1.markdown](https://sunaku.github.io/tork/man/man1/tork-driver.1.markdown) &rArr;
-  [tork-driver.1](https://sunaku.github.io/tork/man/man1/tork-driver.1) +
-  [tork-driver.1.html](https://sunaku.github.io/tork/man/man1/tork-driver.1.html)
-* [bin/tork-engine](https://raw.github.com/sunaku/tork/master/bin/tork-engine) &rArr;
-  [tork-engine.1.markdown](https://sunaku.github.io/tork/man/man1/tork-engine.1.markdown) &rArr;
-  [tork-engine.1](https://sunaku.github.io/tork/man/man1/tork-engine.1) +
-  [tork-engine.1.html](https://sunaku.github.io/tork/man/man1/tork-engine.1.html)
-* [bin/tork-master](https://raw.github.com/sunaku/tork/master/bin/tork-master) &rArr;
-  [tork-master.1.markdown](https://sunaku.github.io/tork/man/man1/tork-master.1.markdown) &rArr;
-  [tork-master.1](https://sunaku.github.io/tork/man/man1/tork-master.1) +
-  [tork-master.1.html](https://sunaku.github.io/tork/man/man1/tork-master.1.html)
-* [bin/tork-remote](https://raw.github.com/sunaku/tork/master/bin/tork-remote) &rArr;
-  [tork-remote.1.markdown](https://sunaku.github.io/tork/man/man1/tork-remote.1.markdown) &rArr;
-  [tork-remote.1](https://sunaku.github.io/tork/man/man1/tork-remote.1) +
-  [tork-remote.1.html](https://sunaku.github.io/tork/man/man1/tork-remote.1.html)
-* [bin/tork-notify](https://raw.github.com/sunaku/tork/master/bin/tork-notify) &rArr;
-  [tork-notify.1.markdown](https://sunaku.github.io/tork/man/man1/tork-notify.1.markdown) &rArr;
-  [tork-notify.1](https://sunaku.github.io/tork/man/man1/tork-notify.1) +
-  [tork-notify.1.html](https://sunaku.github.io/tork/man/man1/tork-notify.1.html)
-* [bin/md2man-roff](https://raw.github.com/sunaku/md2man/master/bin/md2man-roff) &rArr;
-  [md2man-roff.1.markdown](https://sunaku.github.io/md2man/man/man1/md2man-roff.1.markdown) &rArr;
-  [md2man-roff.1](https://sunaku.github.io/md2man/man/man1/md2man-roff.1) +
-  [md2man-roff.1.html](https://sunaku.github.io/md2man/man/man1/md2man-roff.1.html)
-* [bin/md2man-html](https://raw.github.com/sunaku/md2man/master/bin/md2man-html) &rArr;
-  [md2man-html.1.markdown](https://sunaku.github.io/md2man/man/man1/md2man-html.1.markdown) &rArr;
-  [md2man-html.1](https://sunaku.github.io/md2man/man/man1/md2man-html.1) +
-  [md2man-html.1.html](https://sunaku.github.io/md2man/man/man1/md2man-html.1.html)
-* [bin/md2man-rake](https://raw.github.com/sunaku/md2man/master/bin/md2man-rake) &rArr;
-  [md2man-rake.1.markdown](https://sunaku.github.io/md2man/man/man1/md2man-rake.1.markdown) &rArr;
-  [md2man-rake.1](https://sunaku.github.io/md2man/man/man1/md2man-rake.1) +
-  [md2man-rake.1.html](https://sunaku.github.io/md2man/man/man1/md2man-rake.1.html)
-* [bin/binman](https://raw.github.com/sunaku/binman/master/bin/binman) &rArr;
-  [binman.1.markdown](https://sunaku.github.io/binman/man/man1/binman.1.markdown) &rArr;
-  [binman.1](https://sunaku.github.io/binman/man/man1/binman.1) +
-  [binman.1.html](https://sunaku.github.io/binman/man/man1/binman.1.html)
-* [bin/binman-rake](https://raw.github.com/sunaku/binman/master/bin/binman-rake) &rArr;
-  [binman-rake.1.markdown](https://sunaku.github.io/binman/man/man1/binman-rake.1.markdown) &rArr;
-  [binman-rake.1](https://sunaku.github.io/binman/man/man1/binman-rake.1) +
-  [binman-rake.1.html](https://sunaku.github.io/binman/man/man1/binman-rake.1.html)
-
-For examples in even more scripting languages, see the "Usage" section below!
-
-#### What can binman-rake(1) do?
-
-Here are some examples of HTML manual _sets_ produced by binman-rake(1):
-
-* https://sunaku.github.io/tork/man
-* https://sunaku.github.io/binman/man
-* https://sunaku.github.io/md2man/man
-
-## Installation
-
-If you only want to view pre-built manual pages:
-
-```sh
-gem install binman
-```
-
-If you also want to build your own manual pages:
-
-```sh
-gem install md2man -v '~> 4.0'
-```
-
-### Prerequisites
-
-  * Ruby 1.8.7 or 1.9.2 or newer.
-
-### Development
-
-```sh
-git clone git://github.com/sunaku/binman
-cd binman
-bundle install
-bundle exec binman --help # run it directly
-bundle exec rake --tasks  # packaging tasks
-```
-
-## Usage
-
-### At the command line
-
-See binman(1) manual:
-
-```sh
-binman --help
-```
-
-### Inside a Ruby script
-
-```ruby
-#!/usr/bin/env ruby
-# your program's manual page goes here
-
-require 'binman'
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-BinMan.help
-
-# OPTION 2: show manual unconditionally
-BinMan.show
-```
-
-You can also specify your program's source file encoding above the manual:
-
-```ruby
-#!/usr/bin/env ruby
-# -*- coding: utf-8 -*-
-# your program's manual page goes here
-```
-
-You can also write the manual as a multi-line Ruby comment:
-
-```ruby
-#!/usr/bin/env ruby
-=begin
-your program's manual page goes here
-=end
-```
-
-You can also specify your program's source file encoding above the manual:
-
-```ruby
-#!/usr/bin/env ruby
-# -*- coding: utf-8 -*-
-=begin
-your program's manual page goes here
-=end
-```
-
-See the [API documentation][binman-api] for even more possibilities!
-
-### Inside a shell script
-
-```ruby
-#!/usr/bin/sh
-# your program's manual page goes here
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-binman help "$0" "$@" && exit
-
-# OPTION 2: show manual unconditionally
-binman show "$0"
-```
-
-### Inside a Perl script
-
-```perl
-#!/usr/bin/env perl
-# your program's manual page goes here
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
-
-# OPTION 2: show manual unconditionally
-system('binman', 'show', __FILE__);
-```
-
-You can also write the manual as a multi-line Ruby comment after `__END__`:
-
-```perl
-#!/usr/bin/env perl
-print "your program's code goes here";
-__END__
-=begin
-your program's manual page goes here
-=end
-```
-
-### Inside a Python script
-
-```python
-#!/usr/bin/env python
-# your program's manual page goes here
-
-import sys, subprocess
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
-
-# OPTION 2: show manual unconditionally
-subprocess.call(['binman', 'show', __file__])
-```
-
-You can also specify your program's source file encoding above the manual:
-
-```python
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-# your program's manual page goes here
-```
-
-You can also write the manual as a multi-line Ruby comment inside a docstring:
-
-```python
-#!/usr/bin/env python
-"""
-=begin
-your program's manual page goes here
-=end
-"""
-```
-
-You can also specify your program's source file encoding above the manual:
-
-```python
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-"""
-=begin
-your program's manual page goes here
-=end
-"""
-```
-
-### Inside an AWK script
-
-The technique for determining current AWK script file name [comes from here](
-http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html
-).
-
-```awk
-#!/usr/bin/awk -f
-# your program's manual page goes here
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
-       if(system("binman help" c) == 0){ exit }}
-
-# OPTION 2: show manual unconditionally
-BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
-       system("binman show" c)}
-```
-
-### Inside a Tcl script
-
-```tcl
-#!/usr/bin/env tclsh
-# your program's manual page goes here
-
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
-
-# OPTION 2: show manual unconditionally
-exec >/dev/tty binman show $argv0
-```
-
-You can also write the manual as a multi-line Ruby comment inside an `if 0`:
-
-```tcl
-#!/usr/bin/env tclsh
-if 0 {
-=begin
-your program's manual page goes here
-=end
-}
-```
-
-### Inside a Node.js script
-
-```javascript
-/*
-=begin
-your program's manual page goes here
-=end
-*/
-
-var exec = require('child_process').exec;
-
-// OPTION 1: show manual and exit if ARGV has -h or --help except after --
-exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
-join(' '), function(error){ if (error === null){ process.exit(); } });
-
-// OPTION 2: show manual unconditionally
-exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
-```
-
-## Packaging
-
-### Building man pages
-
-#### At the command line
-
-See binman-rake(1) manual:
-
-```sh
-binman-rake --help
-```
-
-#### Inside a Ruby script
-
-Add this snippet to your gemspec file:
-
-```ruby
-s.files += Dir['man/man?/*.?']            # UNIX man pages
-s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
-s.add_development_dependency 'md2man', '~> 4.0'
-```
-
-Add the following line to your Rakefile:
-
-```ruby
-require 'binman/rakefile'
-```
-
-You now have a `rake binman` task that pre-builds UNIX manual page files for
-your `bin/` scripts into a `man/` directory so that your end-users do not need
-[md2man] installed in order to view the manual pages you've embedded therein!
-There are also sub-tasks to build manual pages individually as [roff] or HTML.
-
-If you're using Bundler, this task also hooks into its gem packaging tasks and
-ensures that your UNIX manual pages are pre-built and packaged into your gem:
-
-```shell
-bundle exec rake build
-gem spec pkg/*.gem | fgrep man/man
-```
-
-## License
-
-Released under the ISC license.  See the LICENSE file for details.
-
-[roff]: http://troff.org
-[binman]: https://github.com/sunaku/binman
-[binman-man]: https://sunaku.github.io/binman/man/man1/binman.1.html
-[binman-api]: http://rubydoc.info/gems/binman/frames
-[md2man]: https://github.com/sunaku/md2man
-[md2man-markdown]: https://sunaku.github.io/md2man/man/man5/md2man.5.html

data/man/man0/VERSION.markdown

@@ -1,290 +0,0 @@
-## Version 4.0.0 (2014-10-26)
-
-### Major:
-
-  * binman(1): Rename the `load` command to `snip` and remove `conv`.
-
-    * The `binman conv` command has been removed; use `md2man-roff` instead.
-
-    * We no longer require a specific md2man version at runtime; any will do.
-
-  * Upgrade to md2man 4.0, which no longer expands cross references in code
-    spans and code blocks.  Your manuals might be rendered differently now.
-
-## Version 3.4.1 (2014-07-01)
-
-This release fixes the help options' REGEXP argument under non-Debian systems.
-
-### Patch:
-
-  * pager(1) isn't a universal command: CentOS uses `less -is` instead.
-
-  * Silence man(1) stderr when displaying dynamically extracted manual.
-
-### Other:
-
-  * README: add intro hook and source+result examples.
-
-  * Document REGEXP argument for help options in `bin/*`.
-
-  * Refer to REGEXP argument as PATTERN like less does.
-
-## Version 3.4.0 (2014-06-29)
-
-### Minor:
-
-  * GH-3: add optional regexp argument to `-h`/`--help` to search in man(1).
-
-    The `-h` and `--help` options in `BinMan.help()` can now be optionally
-    followed by a regular expression argument that specifies text to search
-    for and, if found, jump to inside the displayed UNIX man page.  Such a
-    regular expression argument can now also be passed into `BinMan.show()`.
-
-### Other:
-
-  * README: add syntax highlighting to code snippets.
-
-## Version 3.3.3 (2014-06-22)
-
-This release upgrades to md2man 3.0 for improved HTML manuals.
-
-### Other:
-
-  * README: add links to package, manuals, and GitHub.
-
-  * GitHub now supports relative links from the README:
-
-    https://help.github.com/articles/relative-links-in-readmes
-
-  * Upgrade to md2man 3.0 for improved HTML manuals.
-
-## Version 3.3.2 (2013-08-30)
-
-Patch:
-
-  * Rescue error when designated opener is not found:
-
-        $ binman -h
-        /gems/opener-0.1.0/lib/opener.rb:97:in `spawn': No such file or directory - xdg-open (Errno::ENOENT)
-                from /gems/opener-0.1.0/lib/opener.rb:97:in `spawn'
-                from /gems/binman-3.3.1/lib/binman.rb:57:in `block in show'
-                from /gems/binman-3.3.1/lib/binman.rb:55:in `each'
-                from /gems/binman-3.3.1/lib/binman.rb:55:in `show'
-                from /gems/binman-3.3.1/lib/binman.rb:88:in `help'
-                from /gems/binman-3.3.1/bin/binman:106:in `<top (required)>'
-                from /bin/binman:23:in `load'
-                from /bin/binman:23:in `<main>'
-
-  * Fix an undefined local variable or method error:
-
-        binman: undefined local variable or method `library' for BinMan:Module
-
-Other:
-
-  * Add screenshot to git repo since OmpLoader is dead.
-
-## Version 3.3.1 (2013-06-01)
-
-Patch:
-
-  * Ensure that md2man 2.0 is loaded before running any BinMan rake tasks.
-
-## Version 3.3.0 (2013-05-08)
-
-Minor:
-
-  * Add binman-rake(1) script to provide access to `binman/rakefile` tasks.
-
-  * Always try showing HTML manual page in web browser from `BinMan.show()`.
-
-Other:
-
-  * Upgrade to md2man 2.0.0.
-
-  * Rename HISTORY to VERSION so it sorts after README.
-
-  * Add man/man0/ subdir containing README and VERSION.
-
-## Version 3.2.1 (2013-05-04)
-
-Patch:
-
-  * Ensure that the `binman:web` Rake task works the first time through.
-
-  * Fix "uninitialized constant Md2Man::VERSION" errors in `binman/rakefile`.
-
-  * Hook into the `build` Rake task only if Bundler's Rake tasks are loaded:
-
-    https://github.com/sunaku/md2man/pull/7#issuecomment-9467621
-
-    Thanks to Postmodern for raising this issue.
-
-## Version 3.2.0 (2012-10-14)
-
-Minor:
-
-  * add binman:web task to produce man pages in HTML
-
-Other:
-
-  * gemspec: package only roff files from inside man/
-
-## Version 3.1.1 (2012-10-13)
-
-Patch:
-
-  * load() failed when leading comment header missing
-
-  * lstrip() is too powerful; consume lines carefully
-
-Other:
-
-  * fix broken link to redcarpet library home page
-
-## Version 3.1.0 (2012-02-06)
-
-Minor:
-
-  * Added `binman help` command for use by non-Ruby bin scripts.  See README
-    for usage examples from Perl, Python, Node.js, Tcl, AWK, and UNIX shell!
-
-Patch:
-
-  * Replace `gem install binman --development` tip in `BinMan::conv()` with
-    `gem install md2man` tip because the former just hangs in RubyGems 1.8.
-
-Other:
-
-  * Shorten markdown headings; improve documentation; clean up.
-
-## Version 3.0.1 (2012-02-02)
-
-Patch:
-
-  * BinMan.help(): ignore `-h` and `--help` options after standard `--` flag.
-
-  * BinMan.show(): write temp file because not all systems support `man -l`.
-
-Other:
-
-  * HISTORY: group changes by version number components.
-
-  * README: add instructions on pre-building man pages.
-
-  * README: fix installation commands for development.
-
-  * bundler suggests moving all dev deps into gemspec.
-
-## Version 3.0.0 (2012-01-09)
-
-Major:
-
-  * Removed the `binman/gemspec` helper library because it did not play well
-    with Bundler.  Use the standard `add_runtime_dependency` method instead.
-    [This example][1] shows what work is involved in upgrading.
-
-Minor:
-
-  * The `binman/Rakefile` helper library now hooks into Bundler's Rake tasks.
-    Be sure to add the `man/**/*` files to your gemspec [accordingly][1].
-
-[1]: https://github.com/sunaku/md2man/commit/75d7a0064fa86f1c98dd01391ad82245fd387c20
-
-## Version 2.0.0 (2011-12-06)
-
-Major:
-
-  * Removed the deprecated `binman/rake_tasks` helper library.  Use
-    `binman/rakefile` instead.
-
-Patch:
-
-  * Fixed infinite looping in the `binman/gemspec` helper library.
-
-Other:
-
-  * Upgraded to md2man v1 for Markdown to UNIX man page conversion.
-
-  * Do not hard-code the version number in `binman/gemspec` helper.
-
-## Version 1.1.0 (2011-11-05)
-
-Alert:
-
-  * The `binman/rake_tasks` library has been renamed (with deprecation) to
-    `binman/rakefile`.  The deprecation warning will be removed in the next
-    major release.
-
-Minor:
-
-  * Add `binman/gemspec` packaging convenience library which automatically
-    builds and includes your UNIX man page files in your gem packages and also
-    adds binman as a runtime and development gem dependency.
-
-## Version 1.0.0 (2011-10-13)
-
-Major:
-
-  * The `BinMan::dump()` method and corresponding `binman dump` command now
-    extract the leading comment header from their input before returning the
-    markdown to roff conversion thereof.
-
-  * The `BinMan::read()` method and corresponding `binman read` command have
-    been renamed to `BinMan::load()` and `binman load` respectively.
-
-Minor:
-
-  * Added `BinMan::conv()` method and corresponding `binman conv` command to
-    encapsulate the markdown to roff conversion process.
-
-Patch:
-
-  * Pre-built man pages included alongside a `bin/` script were not displayed.
-    Instead, binman was (incorrectly) always trying to convert the leading
-    comment header from the `bin/` script into a UNIX man page for display.
-
-Other:
-
-  * README: explain dev deps and `man/` dir packaging.
-
-## Version 0.1.2 (2011-10-13)
-
-Minor:
-
-  * The [Redcarpet2] library is not a runtime gem dependency anymore.
-
-Other:
-
-  * Extracted `BinMan::Renderer` into [redcarpet-manpage] library.
-
-  * Forgot to introduce leading comment headers in binman(1) man page.
-
-[Redcarpet2]: https://github.com/tanoku/redcarpet
-[redcarpet-manpage]: http://rdoc.info/github/sunaku/redcarpet-manpage
-
-## Version 0.1.1 (2011-10-13)
-
-Minor:
-
-  * `BinMan.read()` now supports embedded document (=begin/=end) comments
-    also.  See binman(1) for the new description of leading comment headers.
-
-Patch:
-
-  * Ignore encoding comment line after shebang line.
-
-  * roff: fix first paragraphs inside list items.
-
-Other:
-
-  * gemspec: build man page files before building gem.
-
-  * binman: raise error and suggest --help option.
-
-  * README: add link to example of binman markdown.
-
-  * README: add obligatory screenshot! >:-)
-
-## Version 0.0.1 (2011-10-12)
-
-First release!  Happy birthday!  Woohoo!  :-)