binman 3.2.1 → 3.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 59dacb035f95229d4261bc1ede0d49c5351d2bfd
+  data.tar.gz: 3d08a026878970843143de1234a6f9274b94c166
+SHA512:
+  metadata.gz: b4687dde4ceb788cdb51a298d0e10a4798904467d7aac99531401f327e7e4c02d7c873503f81a63ee8310b5fc80f7a2cd95b901b6f06e762fcd1e47926a23089
+  data.tar.gz: aa1b36901f76a242909f99595eaee06f4b63897cf6197c9b6b8e9d9d6b7b3b6d7780cfe671f7e81b380004a248486ef15661545368df46b3e051b868ef8fbae0

data/README.markdown

@@ -47,6 +47,8 @@ If you also want to build your own manual pages:
 
 ### At the command line
 
+See binman(1) manual:
+
     binman --help
 
 ### Inside a Ruby script
@@ -210,12 +212,21 @@ You can also write the manual as a multi-line Ruby comment inside an `if 0`:
 
 ## Packaging
 
-### Pre-building man pages
+### Building man pages
+
+#### At the command line
+
+See binman-rake(1) manual:
+
+    binman-rake --help
+
+#### Inside a Ruby script
 
-Add the following lines to your gemspec:
+Add this snippet to your gemspec file:
 
-    s.files += Dir['man/man?/*.?']
-    s.add_development_dependency 'md2man', '~> 1.4'
+    s.files += Dir['man/man?/*.?']            # UNIX man pages
+    s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
+    s.add_development_dependency 'md2man', '~> 2.0'
 
 Add the following line to your Rakefile:
 

data/{HISTORY.markdown → VERSION.markdown}

@@ -1,3 +1,19 @@
+## 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:

data/bin/binman

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN 1 2013-05-04 3.2.1
+# BINMAN 1 2013-05-08 3.3.0
 
 ## NAME
 
@@ -55,8 +55,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/bin/binman-rake

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# BINMAN-RAKE 1 2013-05-08 3.3.0
+
+## NAME
+
+binman-rake - run rake(1) tasks from binman(1)
+
+## SYNOPSIS
+
+`binman-rake` [*OPTION*]... [*TASK*]...
+
+## DESCRIPTION
+
+This program lets you run rake(1) tasks provided by binman(1) without having
+to create a special file named `Rakefile` that contains the following snippet:
+
+    require 'binman/rakefile'
+
+If no *TASK* is specified, then the `binman` task is run by default.
+
+## TASKS
+
+`binman`
+  Runs the `binman:man` and `binman:web` tasks, in that order.
+
+`binman:man`
+  Builds UNIX manual pages from scripts found in your `bin/` directory.
+  It also runs the `md2man:man` task, provided by md2man-rake(1), which
+  builds UNIX manual pages from `*.markdown`, `*.mkd`, and `*.md` files
+  found in or beneath the `man/` subdirectory in your working directory.
+
+`binman:web`
+  Builds HTML manual pages from scripts found in your `bin/` directory.
+  It also runs the `md2man:web` task, provided by md2man-rake(1), which
+  builds HTML manual pages from `*.markdown`, `*.mkd`, and `*.md` files
+  found in or beneath the `man/` subdirectory in your working directory.
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+Run `rake --help` to see more options.
+
+## SEE ALSO
+
+rake(1), binman(1), md2man-rake(1)
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+
+require 'rake'
+Rake.application.init File.basename(__FILE__)
+
+require 'binman/rakefile'
+task :default => :binman
+
+Rake.application.top_level

data/binman.gemspec

@@ -16,6 +16,10 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_development_dependency 'md2man', '~> 1.4'
+  s.files += Dir['man/man?/*.?']            # UNIX man pages
+  s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
+  s.add_development_dependency 'md2man', '~> 2.0'
+
+  s.add_dependency 'opener', '>= 0.1.0', '< 1'
   s.add_development_dependency 'rake', '>= 0.9.2.2', '< 1'
 end

data/lib/binman.rb

@@ -31,10 +31,10 @@ module BinMan
 
   # Converts given markdown(7) source into roff(7).
   def conv source=nil
-    require 'md2man'
-    Md2Man::ENGINE.render(read(source))
+    require 'md2man/roff/engine'
+    Md2Man::Roff::ENGINE.render(read(source))
   rescue LoadError
-    raise 'Run `gem install md2man -v "~>1"` to use BinMan::conv().'
+    raise 'Run `gem install md2man --version "~> 2.0"` to use BinMan::conv().'
   end
 
   # Extracts leading comment header content from given
@@ -47,10 +47,23 @@ module BinMan
   # possible, else falls back to showing leading comment header as-is.
   def show source=nil
     # try showing existing man page files for given source
-    return if file = find(source) and File.exist? file and
-      File.exist? man_path = File.expand_path('../../man', file) and
-      system 'man', '-M', man_path, '-a', File.basename(file)
+    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
+        Opener.spawn man_html, 0 => :close, 1 => :close, 2 => :close
+      end
+
+      # try showing roff manual page in man(1) reader in foreground;
+      # close STDERR to avoid interference with the fall back below
+      return if system 'man', '-M', man_path, '-a', man_page, 2 => :close
+    end
+
+    # fall back to showing leading comment header as-is
     header = load(source)
 
     begin

data/lib/binman/rakefile.rb

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

data/lib/binman/version.rb

@@ -1,3 +1,3 @@
 module BinMan
-  VERSION = "3.2.1"
+  VERSION = "3.3.0"
 end

data/man/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="md2man 2.0.0 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]-->
+</head>
+<body><div class="container-fluid"><h2 id="man0">man0</h2><dl class="dl-horizontal"><dt><a href="man0/README.html">README</a></dt><dd></dd></dl><dl class="dl-horizontal"><dt><a href="man0/VERSION.html">VERSION</a></dt><dd></dd></dl><h2 id="man1">man1</h2><dl class="dl-horizontal"><dt><a href="man1/binman-rake.1.html">binman-rake(1)</a></dt><dd>run rake(1) tasks from binman(1)</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman.1.html">binman(1)</a></dt><dd>man pages for bin scripts</dd></dl></div></body>
+</html>

data/man/man0/README.html

@@ -0,0 +1,198 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="md2man 2.0.0 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]-->
+</head>
+<body><div class="navbar"><div class="navbar-inner"><span class="brand"><a href="../index.html#man0">man0</a>/README</span></div></div><div class="container-fluid"><h1 id="binman-man-pages-for-bin-scripts">binman - man pages for bin scripts</h1><p><a href="https://github.com/sunaku/binman">binman</a> produces UNIX manual pages for executable scripts using <a href="https://github.com/sunaku/md2man">md2man</a>.</p><h2 id="Features">Features</h2>
+<ul>
+<li><p>Supports any scripting language that has multi-line
+comments or uses <code>#</code> for single-line comments: Ruby,
+Perl, Python, Node.js, Tcl, AWK, UNIX shell, and more!</p></li>
+<li><p>Provides a Ruby library and a command-line client too.</p></li>
+<li><p>Individual extraction, conversion, and display commands.</p></li>
+<li><p>Implemented in roughly 100 lines of pure Ruby code! :-)</p></li>
+</ul>
+<h3 id="Demonstration">Demonstration</h3><p><img src="http://ompldr.org/vYm5mcg" alt="Obligatory screen-shot of binman(1) in action!"></p><p>Here is <a href="https://raw.github.com/sunaku/binman/master/bin/binman">a complete example in Ruby</a> to help you get started.
+For examples in other scripting languages, see the &quot;Usage&quot; section below!</p><h2 id="Installation">Installation</h2><p>If you only want to view pre-built manual pages:</p>
+<pre><code>gem install binman
+</code></pre>
+<p>If you also want to build your own manual pages:</p>
+<pre><code>gem install md2man -v &#39;~&gt; 1.4&#39;
+</code></pre>
+<h3 id="Prerequisites">Prerequisites</h3>
+<ul>
+<li>Ruby 1.8.7 or 1.9.2 or newer.</li>
+</ul>
+<h3 id="Development">Development</h3>
+<pre><code>git clone git://github.com/sunaku/binman
+cd binman
+bundle install
+bundle exec binman --help # run it directly
+bundle exec rake --tasks  # packaging tasks
+</code></pre>
+<h2 id="Usage">Usage</h2><h3 id="At-the-command-line">At the command line</h3><p>See <a class="md2man-xref" href="../man1/binman.1.html">binman(1)</a> manual:</p>
+<pre><code>binman --help
+</code></pre>
+<h3 id="Inside-a-Ruby-script">Inside a Ruby script</h3>
+<pre><code>#!/usr/bin/env ruby
+# your program&#39;s manual page goes here
+
+require &#39;binman&#39;
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+BinMan.help
+
+# OPTION 2: show manual unconditionally
+BinMan.show
+</code></pre>
+<p>You can also specify your program&#39;s source file encoding above the manual:</p>
+<pre><code>#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+# your program&#39;s manual page goes here
+</code></pre>
+<p>You can also write the manual as a multi-line Ruby comment:</p>
+<pre><code>#!/usr/bin/env ruby
+=begin
+your program&#39;s manual page goes here
+=end
+</code></pre>
+<p>You can also specify your program&#39;s source file encoding above the manual:</p>
+<pre><code>#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+=begin
+your program&#39;s manual page goes here
+=end
+</code></pre>
+<p>See the <a href="http://rubydoc.info/gems/binman/frames">API documentation</a> for even more possibilities!</p><h3 id="Inside-a-shell-script">Inside a shell script</h3>
+<pre><code>#!/usr/bin/sh
+# your program&#39;s manual page goes here
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+binman help &quot;$0&quot; &quot;$@&quot; &amp;&amp; exit
+
+# OPTION 2: show manual unconditionally
+binman show &quot;$0&quot;
+</code></pre>
+<h3 id="Inside-a-Perl-script">Inside a Perl script</h3>
+<pre><code>#!/usr/bin/env perl
+# your program&#39;s manual page goes here
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+system(&#39;binman&#39;, &#39;help&#39;, __FILE__, @ARGV) == 0 and exit;
+
+# OPTION 2: show manual unconditionally
+system(&#39;binman&#39;, &#39;show&#39;, __FILE__);
+</code></pre>
+<p>You can also write the manual as a multi-line Ruby comment after <code>__END__</code>:</p>
+<pre><code>#!/usr/bin/env perl
+print &quot;your program&#39;s code goes here&quot;;
+__END__
+=begin
+your program&#39;s manual page goes here
+=end
+</code></pre>
+<h3 id="Inside-a-Python-script">Inside a Python script</h3>
+<pre><code>#!/usr/bin/env python
+# your program&#39;s manual page goes here
+
+import sys, subprocess
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+subprocess.call([&#39;binman&#39;, &#39;help&#39;, __file__] + sys.argv) == 0 and sys.exit()
+
+# OPTION 2: show manual unconditionally
+subprocess.call([&#39;binman&#39;, &#39;show&#39;, __file__])
+</code></pre>
+<p>You can also specify your program&#39;s source file encoding above the manual:</p>
+<pre><code>#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# your program&#39;s manual page goes here
+</code></pre>
+<p>You can also write the manual as a multi-line Ruby comment inside a docstring:</p>
+<pre><code>#!/usr/bin/env python
+&quot;&quot;&quot;
+=begin
+your program&#39;s manual page goes here
+=end
+&quot;&quot;&quot;
+</code></pre>
+<p>You can also specify your program&#39;s source file encoding above the manual:</p>
+<pre><code>#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+&quot;&quot;&quot;
+=begin
+your program&#39;s manual page goes here
+=end
+&quot;&quot;&quot;
+</code></pre>
+<h3 id="Inside-an-AWK-script">Inside an AWK script</h3><p>The technique for determining current AWK script file name <a href="http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html">comes from here</a>.</p>
+<pre><code>#!/usr/bin/awk -f
+# your program&#39;s manual page goes here
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+BEGIN {getline c &lt;&quot;/proc/self/cmdline&quot;; sub(&quot;.*-f\0&quot;,&quot; &quot;,c); gsub(&quot;\0&quot;,&quot; &quot;,c);
+       if(system(&quot;binman help&quot; c) == 0){ exit }}
+
+# OPTION 2: show manual unconditionally
+BEGIN {getline c &lt;&quot;/proc/self/cmdline&quot;; sub(&quot;.*-f\0&quot;,&quot; &quot;,c); sub(&quot;\0.*&quot;,&quot;&quot;,c);
+       system(&quot;binman show&quot; c)}
+</code></pre>
+<h3 id="Inside-a-Tcl-script">Inside a Tcl script</h3>
+<pre><code>#!/usr/bin/env tclsh
+# your program&#39;s manual page goes here
+
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+if {![catch {exec -- &gt;/dev/tty binman help $argv0 {*}$argv}]} {exit}
+
+# OPTION 2: show manual unconditionally
+exec &gt;/dev/tty binman show $argv0
+</code></pre>
+<p>You can also write the manual as a multi-line Ruby comment inside an <code>if 0</code>:</p>
+<pre><code>#!/usr/bin/env tclsh
+if 0 {
+=begin
+your program&#39;s manual page goes here
+=end
+}
+</code></pre>
+<h3 id="Inside-a-Node-js-script">Inside a Node.js script</h3>
+<pre><code>/*
+=begin
+your program&#39;s manual page goes here
+=end
+*/
+
+var exec = require(&#39;child_process&#39;).exec;
+
+// OPTION 1: show manual and exit if ARGV has -h or --help except after --
+exec([&#39;&gt;/dev/tty&#39;, &#39;binman&#39;, &#39;help&#39;, __filename].concat(process.argv).
+join(&#39; &#39;), <a class="md2man-xref">function(error)</a>{ if (error === null){ process.exit(); } });
+
+// OPTION 2: show manual unconditionally
+exec([&#39;&gt;/dev/tty&#39;, &#39;binman&#39;, &#39;show&#39;, __filename].join(&#39; &#39;));
+</code></pre>
+<h2 id="Packaging">Packaging</h2><h3 id="Building-man-pages">Building man pages</h3><h4 id="At-the-command-line">At the command line</h4><p>See <a class="md2man-xref" href="../man1/binman-rake.1.html">binman-rake(1)</a> manual:</p>
+<pre><code>binman-rake --help
+</code></pre>
+<h4 id="Inside-a-Ruby-script">Inside a Ruby script</h4><p>Add this snippet to your gemspec file:</p>
+<pre><code>s.files += Dir[&#39;man/man?/*.?&#39;]            # UNIX man pages
+s.files += Dir[&#39;man/**/*.{html,css,js}&#39;]  # HTML man pages
+s.add_development_dependency &#39;md2man&#39;, &#39;~&gt; 2.0&#39;
+</code></pre>
+<p>Add the following line to your Rakefile:</p>
+<pre><code>require &#39;binman/rakefile&#39;
+</code></pre>
+<p>You now have a <code>rake binman</code> task that pre-builds UNIX manual page files for
+your <code>bin/</code> scripts into a <code>man/</code> directory so that your end-users do not need
+<a href="https://github.com/sunaku/md2man">md2man</a> installed in order to view the manual pages you&#39;ve embedded therein!
+There are also sub-tasks to build manual pages individually as <a href="http://troff.org">roff</a> or HTML.</p><p>If you&#39;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:</p>
+<pre><code>bundle exec rake build
+gem spec pkg/*.gem | fgrep man/man
+</code></pre>
+<h2 id="License">License</h2><p>Released under the ISC license.  See the LICENSE file for details.</p></div></body>
+</html>

data/man/man0/README.markdown

@@ -0,0 +1,254 @@
+# binman - man pages for bin scripts
+
+[binman] produces UNIX manual pages for executable scripts using [md2man].
+
+## 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 100 lines of pure Ruby code! :-)
+
+### Demonstration
+
+![Obligatory screen-shot of binman(1) in action!](http://ompldr.org/vYm5mcg)
+
+Here is [a complete example in Ruby][binman-bin] to help you get started.
+For examples in other scripting languages, see the "Usage" section below!
+
+## Installation
+
+If you only want to view pre-built manual pages:
+
+    gem install binman
+
+If you also want to build your own manual pages:
+
+    gem install md2man -v '~> 1.4'
+
+### Prerequisites
+
+  * Ruby 1.8.7 or 1.9.2 or newer.
+
+### Development
+
+    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:
+
+    binman --help
+
+### Inside a Ruby script
+
+    #!/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:
+
+    #!/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:
+
+    #!/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:
+
+    #!/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
+
+    #!/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
+
+    #!/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__`:
+
+    #!/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
+
+    #!/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:
+
+    #!/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:
+
+    #!/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:
+
+    #!/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
+).
+
+    #!/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
+
+    #!/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`:
+
+    #!/usr/bin/env tclsh
+    if 0 {
+    =begin
+    your program's manual page goes here
+    =end
+    }
+
+### Inside a Node.js script
+
+    /*
+    =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:
+
+    binman-rake --help
+
+#### Inside a Ruby script
+
+Add this snippet to your gemspec file:
+
+    s.files += Dir['man/man?/*.?']            # UNIX man pages
+    s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
+    s.add_development_dependency 'md2man', '~> 2.0'
+
+Add the following line to your Rakefile:
+
+    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:
+
+    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-api]: http://rubydoc.info/gems/binman/frames
+[binman-bin]: https://raw.github.com/sunaku/binman/master/bin/binman
+[md2man]: https://github.com/sunaku/md2man