binman 5.0.1 → 5.1.0

data/bin/binman-roff

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# BINMAN-ROFF 1                   2016-02-28                            5.1.0
+
+## NAME
+
+binman-roff - UNIX manpage from header comment
+
+## SYNOPSIS
+
+`binman-roff` [*OPTION*]... [*FILE*]
+
+
+## DESCRIPTION
+
+Extracts the "embedded manpage source", described in binman-text(1), from the
+given *FILE* or STDIN and transforms it into roff(7) for display by man(1).
+
+## SEE ALSO
+
+binman-text(1), binman-html(1), binman(1), roff(7), man(1)
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+puts BinMan.roff(ARGF)

data/bin/binman-show

@@ -0,0 +1,193 @@
+#!/usr/bin/env ruby
+#
+# # BINMAN-SHOW 1                 2016-02-28                            5.1.0
+#
+# ## NAME
+#
+# binman-show - show manpage from header comment
+#
+# ## SYNOPSIS
+#
+# `binman-show` [*OPTION*]... [*FILE*] [*PATTERN*]
+#
+# ## DESCRIPTION
+#
+# Extracts the "embedded manpage source", described in binman-text(1), from the
+# given *FILE* or STDIN, transforms it into roff(7), and displays it in man(1).
+#
+# If the optional *PATTERN* regular expression is specified, searches for it
+# inside the output displayed by man(1) and jumps to the first match if found.
+#
+# If man(1) cannot display the roff(7) conversion, falls back to the displaying
+# the HTML conversion. And if that fails too, displays the manpage source as-is.
+#
+# ### Examples
+#
+# See "Embedded manpage sources" in binman-text(1) for header comment syntax.
+#
+# #### From a shell script
+#
+# ```sh
+# #!/usr/bin/sh
+# # your program's manual page goes here
+#
+# binman-show "$0"
+# ```
+#
+# #### From a Ruby script
+#
+# ```ruby
+# #!/usr/bin/env ruby
+# # your program's manual page goes here
+#
+# require 'binman'
+# 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
+# ```
+#
+# #### From a Perl script
+#
+# ```perl
+# #!/usr/bin/env perl
+# # your program's manual page goes here
+#
+# 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
+# ```
+#
+# #### From a Python script
+#
+# ```python
+# #!/usr/bin/env python
+# # your program's manual page goes here
+#
+# import subprocess
+#
+# 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
+# """
+# ```
+#
+# #### From 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
+#
+# BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
+#        system("binman-show" c)}
+# ```
+#
+# #### From a Tcl script
+#
+# ```tcl
+# #!/usr/bin/env tclsh
+# # your program's manual page goes here
+#
+# 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
+# }
+# ```
+#
+# #### From a Node.js script
+#
+# ```javascript
+# /*
+# =begin
+# your program's manual page goes here
+# =end
+# */
+#
+# require('child_process').exec(['>/dev/tty', 'binman-show', __filename].join(' '));
+# ```
+#
+# ## OPTIONS
+#
+# `-h` [*PATTERN*], `--help` [*PATTERN*]
+#   Show this help manual and optionally search for *PATTERN* regular expression.
+#
+# ## SEE ALSO
+#
+# binman-text(1), binman-roff(1), binman-html(1), binman-help(1), binman(1)
+
+require 'binman'
+BinMan.help
+BinMan.show(ARGF)

data/bin/binman-text

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# BINMAN-TEXT 1                   2016-02-28                            5.1.0
+
+## NAME
+
+binman-text - extract embedded manpage sources
+
+## SYNOPSIS
+
+`binman-text` [*OPTION*]... [*FILE*]
+
+## DESCRIPTION
+
+Prints the "embedded manpage source" extracted from the given *FILE* or STDIN.
+
+### Embedded manpage sources
+
+An "embedded manpage source" is an md2man(5) document that is embedded in your
+script, typically inside a multi-line block comment or "here document"; or in
+a header comment composed of single-line comments near the top of your script.
+
+#### In multi-line comments
+
+In the former case, where it's possible to write a freeform block of text, the
+embedded manpage source must be delimited by `=begin` and `=end` lines, which
+start with their respective delimiters and, optionally, continue with a single
+space followed by any amount and kind of characters until the end of line.
+
+To illustrate, here is the simplest case:
+
+    =begin
+    This is an embedded manpage source!
+    =end
+
+Next, we can add decorations after the delimiters:
+
+    =begin \\\\\\\\\\\\\\\\\\\\\\\\\\\\
+    This is an embedded manpage source!
+    =end //////////////////////////////
+
+Similarly, using different characters this time:
+
+    =begin abcdefghijklmnopqrstuvwxyz'"
+    This is an embedded manpage source!
+    =end 0123456789!@#$%^&*()=+-_:;,\/?
+
+#### In single-line comments
+
+In the latter case, the embedded manpage source is expected to be found in a
+contiguous block of single-line comments that begins at the top of the script
+(optionally after a `#!` line, `coding:` line, and any number of blank lines)
+and ends at the first blank line.  Each single-line comment inside this block
+must begin with a `#` character and may, optionally, continue with a single
+space followed by any amount and kind of characters until the end of line.
+
+To illustrate, here is the simplest case:
+
+    # This is an embedded manpage source!
+
+Next, we can add a `#!` line at the top:
+
+    #!/bin/sh
+    # This is an embedded manpage source!
+
+Next, we can add a `coding:` line after `#!`:
+
+    #!/bin/sh
+    # coding: utf-8
+    # This is an embedded manpage source!
+
+Or, using the Emacs coding system syntax:
+
+    #!/bin/sh
+    # -*- encoding: utf-8 -*-
+    # This is an embedded manpage source!
+
+Next, we can add blank lines between them:
+
+    #!/bin/sh
+    # coding: utf-8
+
+    # This is an embedded manpage source!
+
+Here is another permutation of the above:
+
+    #!/bin/sh
+
+    # This is an embedded manpage source!
+
+## OPTIONS
+
+`-h` [*PATTERN*], `--help` [*PATTERN*]
+  Show this help manual and optionally search for *PATTERN* regular expression.
+
+## SEE ALSO
+
+md2man(5), binman-roff(1), binman-html(1), binman(1)
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+puts BinMan.text(ARGF)

data/binman.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.authors,
   s.email         = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
   s.homepage      = 'http://github.com/sunaku/binman'
-  s.summary       = 'man pages for bin scripts'
+  s.summary       = 'manpages from comment headers'
   s.description   = 'Produces UNIX manual pages for executable scripts.'
 
   s.files         = `git ls-files`.split("\n") + Dir['man/man?/*.?']
@@ -16,9 +16,9 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.files += Dir['man/man?/*.?']            # UNIX man pages
-  s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
-  s.add_development_dependency 'md2man', '~> 5.0'
+  s.files += Dir['man/man?/*.?']            # UNIX manual pages
+  s.files += Dir['man/**/*.{html,css,js}']  # HTML manual pages
+  s.add_development_dependency 'md2man', '~> 5.1'
 
   s.add_dependency 'opener', '>= 0.1.0', '< 1'
   s.add_development_dependency 'rake', '~> 10.1'

data/lib/binman.rb

@@ -5,7 +5,7 @@ require 'binman/version'
 module BinMan
   extend self
 
-  # Extracts content of leading comment header (which can be one of the
+  # Extracts content of embedded manpage source (which can be one of the
   # following two choices) from given source (IO, file name, or string).
   #
   # (1) A contiguous sequence of single-line comments starting at the
@@ -23,7 +23,7 @@ module BinMan
     header.sub! /\A#!.+\n?/, ''
     header.sub! /\A#.*coding:.+\n?/, ''
 
-    # extract the leading comment header
+    # extract the embedded manpage source
     if header =~ /\A\s*^#/
       header.split(/^\s*$/, 2).first.gsub(/^# ?/, '')
     else
@@ -31,19 +31,19 @@ module BinMan
     end.strip
   end
 
-  # Renders leading comment header from given source as UNIX man page.
+  # Renders embedded manpage source from given source as UNIX man page.
   def roff source=nil
     to_roff text(source)
   end
 
-  # Renders leading comment header from given source as HTML man page.
+  # Renders embedded manpage source from given source as HTML man page.
   def html source=nil
     to_html text(source)
   end
 
-  # Shows leading comment header from given source as UNIX man page and
+  # Shows embedded manpage source from given source as UNIX man page and
   # optionally jumps to first match of query regular expression if given.
-  # If not possible, falls back to showing leading comment header as-is.
+  # If not possible, falls back to showing embedded manpage source as-is.
   # Tries to display a pre-rendered UNIX man page under ./man/ if possible.
   def show source=nil, query=nil
     # try showing existing man page files for given source
@@ -53,13 +53,13 @@ module BinMan
       return if show_man(man_path, man_page, query)
     end
 
-    # fall back to rendering leading comment header or showing it as-is
+    # fall back to rendering embedded manpage source or showing it as-is
     header = text(source)
     return if show_str(header, query)
     puts header
   end
 
-  # Shows leading comment header from given source as UNIX man page and exits
+  # Shows embedded manpage source from given source as UNIX man page and exits
   # if the given argument vector contains '-h' or '--help', except after '--',
   # optionally followed by a regular expression argument that specifies text
   # to search for and, if found, jump to inside the displayed UNIX man page.

data/lib/binman/rakefile.rb

@@ -29,12 +29,12 @@ task 'binman:mkd' => mkds
 desc 'Build UNIX manual pages for bin/ scripts.'
 task 'binman:man' => 'binman:mkd' do
 #-----------------------------------------------------------------------------
-  sh 'md2man-rake', 'md2man:man'
+  sh 'md2man-rake', 'man'
 end
 
 #-----------------------------------------------------------------------------
 desc 'Build HTML manual pages for bin/ scripts.'
 task 'binman:web' => 'binman:mkd' do
 #-----------------------------------------------------------------------------
-  sh 'md2man-rake', 'md2man:web'
+  sh 'md2man-rake', 'web'
 end

data/lib/binman/version.rb

@@ -1,3 +1,3 @@
 module BinMan
-  VERSION = "5.0.1"
+  VERSION = "5.1.0"
 end

data/man/index.html

@@ -2,10 +2,10 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 5.0.1 https://github.com/sunaku/md2man" />
-  <title>man/index</title>
+  <meta name="generator" content="md2man 5.1.0 https://github.com/sunaku/md2man" />
+  <title>man/index &mdash; binman</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>
+<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.1.html">binman(1)</a></dt><dd>deprecated; use binman-* instead</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-help.1.html">binman-help(1)</a></dt><dd>add help options to your program</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-html.1.html">binman-html(1)</a></dt><dd>HTML manpage from header comment</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-rake.1.html">binman-rake(1)</a></dt><dd>run rake(1) tasks from command line</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-roff.1.html">binman-roff(1)</a></dt><dd>UNIX manpage from header comment</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-show.1.html">binman-show(1)</a></dt><dd>show manpage from header comment</dd></dl><dl class="dl-horizontal"><dt><a href="man1/binman-text.1.html">binman-text(1)</a></dt><dd>extract embedded manpage sources</dd></dl><h2 id="man5">man5</h2><dl class="dl-horizontal"><dt><a href="man5/md2man.5.html">md2man(5)</a></dt><dd>UNIX manual page flavoring for Markdown</dd></dl></div></body>
 </html>

data/man/man0/README.html

@@ -2,312 +2,547 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 5.0.1 https://github.com/sunaku/md2man" />
-  <title>README</title>
+  <meta name="generator" content="md2man 5.1.0 https://github.com/sunaku/md2man" />
+  <title>README &mdash; binman</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"><span class="md2man-title">binman</span> <span class="md2man-section">-</span> <span class="md2man-date">man</span> <span class="md2man-source">pages</span> <span class="md2man-manual">for</span><a name="binman-man-pages-for" href="#binman-man-pages-for" class="md2man-permalink" title="permalink"></a></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>.
-Simply <a href="https://sunaku.github.io/md2man/man/man5/md2man.5.html">document your script in Markdown</a> as a comment at the
-top of your script and call <code>binman show</code> to display it as a UNIX manual page!
-Or, call <code>binman help</code> to display your manual <em>only</em> when your script receives
-with <code>-h</code> or <code>--help</code> command-line options.  Or, call <code>binman text</code> to extract
-the manual from your script for your own custom processing, outside of binman.
-And that&#39;s not all: <a href="https://sunaku.github.io/binman/man/man1/binman.1.html">see the manual page</a> for more possibilities!</p>
-<ul>
-<li>Manuals: <a href="https://sunaku.github.io/binman/man">https://sunaku.github.io/binman/man</a></li>
-<li>Sources: <a href="https://github.com/sunaku/binman">https://github.com/sunaku/binman</a></li>
-<li>Support: <a href="https://github.com/sunaku/binman/issues">https://github.com/sunaku/binman/issues</a></li>
-<li>Package: <a href="https://rubygems.org/gems/binman">https://rubygems.org/gems/binman</a></li>
-</ul>
-<h2 id="features">Features<a name="features" href="#features" class="md2man-permalink" title="permalink"></a></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 165 lines of pure Ruby code! :-)</p></li>
-</ul>
-<h3 id="demonstration">Demonstration<a name="demonstration" href="#demonstration" class="md2man-permalink" title="permalink"></a></h3><p><img src="EXAMPLE.png" alt="Obligatory screen-shot of binman(1) in action!"></p><h4 id="what-can-binman-1-do">What can <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a> do?<a name="what-can-binman-1-do" href="#what-can-binman-1-do" class="md2man-permalink" title="permalink"></a></h4><p>Here are some real examples of processed bin scripts to help you get started:</p>
-<ul>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork.1.markdown">tork.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork.1">tork.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork.1.html">tork.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-runner.1.markdown">tork-runner.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-runner.1">tork-runner.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-runner.1.html">tork-runner.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-herald.1.markdown">tork-herald.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-herald.1">tork-herald.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-herald.1.html">tork-herald.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-driver.1.markdown">tork-driver.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-driver.1">tork-driver.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-driver.1.html">tork-driver.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-engine.1.markdown">tork-engine.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-engine.1">tork-engine.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-engine.1.html">tork-engine.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-master.1.markdown">tork-master.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-master.1">tork-master.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-master.1.html">tork-master.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-remote.1.markdown">tork-remote.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-remote.1">tork-remote.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-remote.1.html">tork-remote.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-notify.1.markdown">tork-notify.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
-&gt; <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-notify.1">tork-notify.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
-&gt; <a href="https://sunaku.github.io/tork/man/man1/tork-notify.1.html">tork-notify.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-roff.1.markdown">md2man-roff.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-roff.1">md2man-roff.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
-&gt; <a href="https://sunaku.github.io/md2man/man/man1/md2man-roff.1.html">md2man-roff.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-html.1.markdown">md2man-html.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-html.1">md2man-html.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
-&gt; <a href="https://sunaku.github.io/md2man/man/man1/md2man-html.1.html">md2man-html.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-rake.1.markdown">md2man-rake.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
-&gt; <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-rake.1">md2man-rake.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
-&gt; <a href="https://sunaku.github.io/md2man/man/man1/md2man-rake.1.html">md2man-rake.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
-&gt; <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman.1.markdown">binman.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
-&gt; <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman.1">binman.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
-&gt; <a href="https://sunaku.github.io/binman/man/man1/binman.1.html">binman.1.html</a></li>
-<li><code>binman text</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
-&gt; <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-rake.1.markdown">binman-rake.1.markdown</a></li>
-<li><code>binman roff</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
-&gt; <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-rake.1">binman-rake.1</a></li>
-<li><code>binman html</code>
-&lt; <a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
-&gt; <a href="https://sunaku.github.io/binman/man/man1/binman-rake.1.html">binman-rake.1.html</a></li>
-</ul>
-<p>For examples in even more scripting languages, see the &quot;Usage&quot; section below!</p><h4 id="what-can-binman-rake-1-do">What can <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a> do?<a name="what-can-binman-rake-1-do" href="#what-can-binman-rake-1-do" class="md2man-permalink" title="permalink"></a></h4><p>Here are some examples of HTML manual <em>sets</em> produced by <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a>:</p>
+<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"><ul>
+<li>Code: <a href="https://github.com/sunaku/binman">https://github.com/sunaku/binman</a></li>
+<li>Docs: <a href="https://sunaku.github.io/binman/man">https://sunaku.github.io/binman/man</a></li>
+<li>Bugs: <a href="https://github.com/sunaku/binman/issues">https://github.com/sunaku/binman/issues</a></li>
+</ul>
+<h1 id="binman-manpages-from-header-comments"><span class="md2man-title">binman</span> <span class="md2man-section">-</span> <span class="md2man-date">manpages</span> <span class="md2man-source">from</span> <span class="md2man-manual">header</span> comments<a name="binman-manpages-from-header-comments" href="#binman-manpages-from-header-comments" class="md2man-permalink" title="permalink"></a></h1><p>binman generates manual pages from header comments in your scripts so that you
+can keep your documentation and implementation together, in the same file, for
+easy maintenance. But keeping them apart, in separate files, is supported too.</p><p><img src="https://github.com/sunaku/binman/raw/gh-pages/EXAMPLE.png" alt="screenshot"></p><h2 id="features">Features<a name="features" href="#features" class="md2man-permalink" title="permalink"></a></h2>
+<ul>
+<li><p>Direct support for any scripting language that has multi-line comments or
+uses <code>#</code> for single-line comments such as Ruby, Perl, PHP, Python, R, Tcl,
+Node.js, Elixir, make, AWK, sed, UNIX shells, Windows PowerShell and more!</p></li>
+<li><p>Individual commands for manual page extraction, conversion, and display.</p></li>
+<li><p>Accessible from the command line and also as a library in <a href="https://www.ruby-lang.org/">Ruby</a> scripts.</p></li>
+<li><p>Implemented in roughly 165 statement lines (SLOC) of pure <a href="https://www.ruby-lang.org/">Ruby</a> code! :-)</p></li>
+</ul>
+<h2 id="examples">Examples<a name="examples" href="#examples" class="md2man-permalink" title="permalink"></a></h2><p>Here are some examples of HTML manual page <em>sets</em> generated by <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a>:</p>
 <ul>
+<li><a href="https://sunaku.github.io/dasht/man">https://sunaku.github.io/dasht/man</a></li>
 <li><a href="https://sunaku.github.io/tork/man">https://sunaku.github.io/tork/man</a></li>
 <li><a href="https://sunaku.github.io/binman/man">https://sunaku.github.io/binman/man</a></li>
 <li><a href="https://sunaku.github.io/md2man/man">https://sunaku.github.io/md2man/man</a></li>
 </ul>
-<h2 id="installation">Installation<a name="installation" href="#installation" class="md2man-permalink" title="permalink"></a></h2><p>If you only want to view pre-built manual pages:</p><pre><code>gem install binman
+<p>For examples of input and output files, see &quot;From the command line&quot; below.</p><h2 id="installation">Installation<a name="installation" href="#installation" class="md2man-permalink" title="permalink"></a></h2><h3 id="requirements">Requirements<a name="requirements" href="#requirements" class="md2man-permalink" title="permalink"></a></h3>
+<ul>
+<li><a href="https://www.ruby-lang.org/">Ruby</a> 1.8.7 or newer</li>
+</ul>
+<h3 id="for-users">For users<a name="for-users" href="#for-users" class="md2man-permalink" title="permalink"></a></h3><p>If you only want to view pre-built manual pages:</p><pre class="highlight shell"><code>gem install binman
+</code></pre>
+<p>If you also want to build your own manual pages:</p><pre class="highlight shell"><code>gem install md2man -v <span class="s1">'~&gt; 5.1'</span>
 </code></pre>
-<p>If you also want to build your own manual pages:</p><pre><code>gem install md2man -v &#39;~&gt; 5.0&#39;
+<h3 id="for-developers">For developers<a name="for-developers" href="#for-developers" class="md2man-permalink" title="permalink"></a></h3><pre class="highlight shell"><code>git clone https://github.com/sunaku/binman
+<span class="nb">cd </span>binman
+bundle install
+bundle <span class="nb">exec </span>rake --tasks       <span class="c"># packaging tasks</span>
+bundle <span class="nb">exec </span>binman-text --help <span class="c"># run it directly</span>
+bundle <span class="nb">exec </span>binman-roff --help <span class="c"># run it directly</span>
+bundle <span class="nb">exec </span>binman-html --help <span class="c"># run it directly</span>
+bundle <span class="nb">exec </span>binman-show --help <span class="c"># run it directly</span>
+bundle <span class="nb">exec </span>binman-help --help <span class="c"># run it directly</span>
+bundle <span class="nb">exec </span>binman-rake --help <span class="c"># run it directly</span>
 </code></pre>
-<h3 id="prerequisites">Prerequisites<a name="prerequisites" href="#prerequisites" class="md2man-permalink" title="permalink"></a></h3>
+<h2 id="usage">Usage<a name="usage" href="#usage" class="md2man-permalink" title="permalink"></a></h2><p>First, write <a class="md2man-reference" href="../man5/md2man.5.html">md2man(5)</a> text for your script: either in a comment at the top of
+your script file, described as &quot;Embedded manpage sources&quot; in <a class="md2man-reference" href="../man1/binman-text.1.html">binman-text(1)</a>,
+or in a separate Markdown file located at <code>man/man?/*.?.{markdown,mkd,md}</code>.</p>
 <ul>
-<li>Ruby 1.8.7 or 1.9.2 or newer.</li>
+<li>For real examples of what to write, see &quot;From the command line&quot; below.</li>
+<li>For the detailed syntax and semantics of what to write, see <a class="md2man-reference" href="../man5/md2man.5.html">md2man(5)</a>.</li>
 </ul>
-<h3 id="development">Development<a name="development" href="#development" class="md2man-permalink" title="permalink"></a></h3><pre><code>git clone https://github.com/sunaku/binman
-cd binman
-bundle install
-bundle exec binman --help # run it directly
-bundle exec rake --tasks  # packaging tasks
+<p>Next, you have two ways of generating manual pages from what you&#39;ve written:</p>
+<ol>
+<li>Generate manual pages at &quot;compile time&quot; and ship them with your scripts.</li>
+<li>Generate manual pages at &quot;run time&quot; so that your scripts are standalone.</li>
+</ol>
+<h3 id="at-compile-time">At compile time<a name="at-compile-time" href="#at-compile-time" class="md2man-permalink" title="permalink"></a></h3><p>Run <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a> to generate manual pages for all of your <code>./bin/*</code> scripts.</p><p>Alternatively, to have more control over the generation of your manual pages:</p>
+<ul>
+<li>Run <a class="md2man-reference" href="../man1/binman-text.1.html">binman-text(1)</a> to extract manual page text from a specified script.</li>
+<li>Run <a class="md2man-reference" href="../man1/binman-roff.1.html">binman-roff(1)</a> to generate a UNIX manual page from a specified script.</li>
+<li>Run <a class="md2man-reference" href="../man1/binman-html.1.html">binman-html(1)</a> to generate a HTML manual page from a specified script.</li>
+</ul>
+<h4 id="from-the-command-line">From the command line<a name="from-the-command-line" href="#from-the-command-line" class="md2man-permalink" title="permalink"></a></h4><p>Below are some real examples of generating manual pages from the command line.
+Note that <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a> abstracts away all of the complexity you see below!</p><p><a class="md2man-reference">dasht(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht">dasht</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht.1.markdown">dasht.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht">dasht</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht.1">dasht.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht">dasht</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht.1.html">dasht.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-docsets(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets">dasht-docsets</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets.1.markdown">dasht-docsets.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets">dasht-docsets</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets.1">dasht-docsets.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets">dasht-docsets</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-docsets.1.html">dasht-docsets.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-docsets-install(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-install">dasht-docsets-install</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-install.1.markdown">dasht-docsets-install.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-install">dasht-docsets-install</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-install.1">dasht-docsets-install.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-install">dasht-docsets-install</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-docsets-install.1.html">dasht-docsets-install.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-docsets-remove(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-remove">dasht-docsets-remove</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-remove.1.markdown">dasht-docsets-remove.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-remove">dasht-docsets-remove</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-remove.1">dasht-docsets-remove.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-remove">dasht-docsets-remove</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-docsets-remove.1.html">dasht-docsets-remove.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-docsets-update(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-update">dasht-docsets-update</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-update.1.markdown">dasht-docsets-update.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-update">dasht-docsets-update</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-docsets-update.1">dasht-docsets-update.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-docsets-update">dasht-docsets-update</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-docsets-update.1.html">dasht-docsets-update.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-query-exec(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-exec">dasht-query-exec</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-exec.1.markdown">dasht-query-exec.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-exec">dasht-query-exec</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-exec.1">dasht-query-exec.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-exec">dasht-query-exec</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-query-exec.1.html">dasht-query-exec.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-query-html(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-html">dasht-query-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-html.1.markdown">dasht-query-html.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-html">dasht-query-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-html.1">dasht-query-html.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-html">dasht-query-html</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-query-html.1.html">dasht-query-html.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-query-line(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-line">dasht-query-line</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-line.1.markdown">dasht-query-line.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-line">dasht-query-line</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-query-line.1">dasht-query-line.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-query-line">dasht-query-line</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-query-line.1.html">dasht-query-line.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-server(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server">dasht-server</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-server.1.markdown">dasht-server.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server">dasht-server</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-server.1">dasht-server.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server">dasht-server</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-server.1.html">dasht-server.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">dasht-server-http(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server-http">dasht-server-http</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-server-http.1.markdown">dasht-server-http.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server-http">dasht-server-http</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/dasht/gh-pages/man/man1/dasht-server-http.1">dasht-server-http.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/dasht/master/bin/dasht-server-http">dasht-server-http</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/dasht/man/man1/dasht-server-http.1.html">dasht-server-http.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork.1.markdown">tork.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork.1">tork.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork">tork</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork.1.html">tork.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-runner(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-runner.1.markdown">tork-runner.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-runner.1">tork-runner.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-runner">tork-runner</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-runner.1.html">tork-runner.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-herald(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-herald.1.markdown">tork-herald.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-herald.1">tork-herald.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-herald">tork-herald</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-herald.1.html">tork-herald.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-driver(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-driver.1.markdown">tork-driver.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-driver.1">tork-driver.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-driver">tork-driver</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-driver.1.html">tork-driver.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-engine(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-engine.1.markdown">tork-engine.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-engine.1">tork-engine.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-engine">tork-engine</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-engine.1.html">tork-engine.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-master(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-master.1.markdown">tork-master.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-master.1">tork-master.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-master">tork-master</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-master.1.html">tork-master.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-remote(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-remote.1.markdown">tork-remote.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-remote.1">tork-remote.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-remote">tork-remote</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-remote.1.html">tork-remote.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">tork-notify(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-notify.1.markdown">tork-notify.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/tork/gh-pages/man/man1/tork-notify.1">tork-notify.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/tork/master/bin/tork-notify">tork-notify</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/tork/man/man1/tork-notify.1.html">tork-notify.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman.1.markdown">binman.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman.1">binman.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman">binman</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman.1.html">binman.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-text.1.html">binman-text(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-text">binman-text</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-text.1.markdown">binman-text.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-text">binman-text</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-text.1">binman-text.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-text">binman-text</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-text.1.html">binman-text.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-roff.1.html">binman-roff(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-roff">binman-roff</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-roff.1.markdown">binman-roff.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-roff">binman-roff</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-roff.1">binman-roff.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-roff">binman-roff</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-roff.1.html">binman-roff.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-html.1.html">binman-html(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-html">binman-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-html.1.markdown">binman-html.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-html">binman-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-html.1">binman-html.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-html">binman-html</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-html.1.html">binman-html.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-show.1.html">binman-show(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-show">binman-show</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-show.1.markdown">binman-show.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-show">binman-show</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-show.1">binman-show.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-show">binman-show</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-show.1.html">binman-show.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-help.1.html">binman-help(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-help">binman-help</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-help.1.markdown">binman-help.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-help">binman-help</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-help.1">binman-help.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-help">binman-help</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-help.1.html">binman-help.1.html</a></li>
+</ul>
+<p><a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-rake.1.markdown">binman-rake.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/binman/gh-pages/man/man1/binman-rake.1">binman-rake.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/binman/master/bin/binman-rake">binman-rake</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/binman/man/man1/binman-rake.1.html">binman-rake.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">md2man-roff(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-roff.1.markdown">md2man-roff.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-roff.1">md2man-roff.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-roff">md2man-roff</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/md2man/man/man1/md2man-roff.1.html">md2man-roff.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">md2man-html(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-html.1.markdown">md2man-html.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-html.1">md2man-html.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-html">md2man-html</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/md2man/man/man1/md2man-html.1.html">md2man-html.1.html</a></li>
+</ul>
+<p><a class="md2man-reference">md2man-rake(1)</a>:</p>
+<ul>
+<li><code>binman-text</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-rake.1.markdown">md2man-rake.1.markdown</a></li>
+<li><code>binman-roff</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
+<code>&gt;</code> <a href="https://raw.github.com/sunaku/md2man/gh-pages/man/man1/md2man-rake.1">md2man-rake.1</a></li>
+<li><code>binman-html</code>
+<a href="https://raw.github.com/sunaku/md2man/master/bin/md2man-rake">md2man-rake</a>
+<code>&gt;</code> <a href="https://sunaku.github.io/md2man/man/man1/md2man-rake.1.html">md2man-rake.1.html</a></li>
+</ul>
+<h4 id="for-a-ruby-package">For a Ruby package<a name="for-a-ruby-package" href="#for-a-ruby-package" class="md2man-permalink" title="permalink"></a></h4><p>Add this snippet to your gemspec file:</p><pre class="highlight ruby"><code><span class="n">s</span><span class="p">.</span><span class="nf">files</span> <span class="o">+=</span> <span class="no">Dir</span><span class="p">[</span><span class="s1">'man/man?/*.?'</span><span class="p">]</span>         <span class="c1"># UNIX manpages</span>
+<span class="n">s</span><span class="p">.</span><span class="nf">files</span> <span class="o">+=</span> <span class="no">Dir</span><span class="p">[</span><span class="s1">'man/**/*.{html,css}'</span><span class="p">]</span>  <span class="c1"># HTML webpages</span>
+<span class="n">s</span><span class="p">.</span><span class="nf">add_development_dependency</span> <span class="s1">'md2man'</span><span class="p">,</span> <span class="s1">'~&gt; 5.1'</span>
 </code></pre>
-<h2 id="usage">Usage<a name="usage" href="#usage" class="md2man-permalink" title="permalink"></a></h2><h3 id="at-the-command-line">At the command line<a name="at-the-command-line" href="#at-the-command-line" class="md2man-permalink" title="permalink"></a></h3><p>See <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a> manual:</p><pre><code>binman --help
+<p>Add the following line to your Rakefile:</p><pre class="highlight ruby"><code><span class="nb">require</span> <span class="s1">'binman/rakefile'</span>
 </code></pre>
-<h3 id="inside-a-ruby-script">Inside a Ruby script<a name="inside-a-ruby-script" href="#inside-a-ruby-script" class="md2man-permalink" title="permalink"></a></h3><pre><code>#!/usr/bin/env ruby
-# your program&#39;s manual page goes here
-
-require &#39;binman&#39;
+<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 class="highlight shell"><code>bundle <span class="nb">exec </span>rake build
+gem spec pkg/<span class="k">*</span>.gem | fgrep man/man
+</code></pre>
+<h3 id="at-run-time">At run time<a name="at-run-time" href="#at-run-time" class="md2man-permalink" title="permalink"></a></h3><p>Run <a class="md2man-reference" href="../man1/binman-show.1.html">binman-show(1)</a> to display the manual page (which may have been
+pre-generated at &quot;compile time&quot;) for a specified script.</p><p>Alternatively, an easy way to add support for <code>-h</code> and <code>--help</code> options in a
+specified script is to run <a class="md2man-reference" href="../man1/binman-help.1.html">binman-help(1)</a> with its file path and command line
+arguments.  This displays its manual page (which may have been pre-generated
+at &quot;compile time&quot;) <em>only when</em> those help options are found in its arguments.</p><h4 id="from-a-shell-script">From a shell script<a name="from-a-shell-script" href="#from-a-shell-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight shell"><code><span class="c">#!/usr/bin/sh</span>
+<span class="c"># your program's manual page goes here</span>
 
-# OPTION 1: show manual and exit if ARGV has -h or --help except after --
-BinMan.help
+<span class="c"># OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+binman-help <span class="s2">"</span><span class="nv">$0</span><span class="s2">"</span> <span class="s2">"</span><span class="nv">$@</span><span class="s2">"</span> <span class="o">&amp;&amp;</span> <span class="nb">exit</span>
 
-# OPTION 2: show manual unconditionally
-BinMan.show
+<span class="c"># OPTION 2: show manual unconditionally</span>
+binman-show <span class="s2">"</span><span class="nv">$0</span><span class="s2">"</span>
 </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
+<h4 id="from-a-ruby-script">From a Ruby script<a name="from-a-ruby-script" href="#from-a-ruby-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight ruby"><code><span class="c1">#!/usr/bin/env ruby</span>
+<span class="c1"># your program's manual page goes here</span>
+
+<span class="nb">require</span> <span class="s1">'binman'</span>
+
+<span class="c1"># OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+<span class="no">BinMan</span><span class="p">.</span><span class="nf">help</span>
+
+<span class="c1"># OPTION 2: show manual unconditionally</span>
+<span class="no">BinMan</span><span class="p">.</span><span class="nf">show</span>
 </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
+<p>You can also specify your program&#39;s source file encoding above the manual:</p><pre class="highlight ruby"><code><span class="c1">#!/usr/bin/env ruby</span>
+<span class="c1"># -*- coding: utf-8 -*-</span>
+<span class="c1"># your program's manual page goes here</span>
 </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
+<p>You can also write the manual as a multi-line Ruby comment:</p><pre class="highlight ruby"><code><span class="c1">#!/usr/bin/env ruby</span>
+<span class="cm">=begin
+your program's manual page goes here
+=end</span>
 </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<a name="inside-a-shell-script" href="#inside-a-shell-script" class="md2man-permalink" title="permalink"></a></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;
+<p>You can also specify your program&#39;s source file encoding above the manual:</p><pre class="highlight ruby"><code><span class="c1">#!/usr/bin/env ruby</span>
+<span class="c1"># -*- coding: utf-8 -*-</span>
+<span class="cm">=begin
+your program's manual page goes here
+=end</span>
 </code></pre>
-<h3 id="inside-a-perl-script">Inside a Perl script<a name="inside-a-perl-script" href="#inside-a-perl-script" class="md2man-permalink" title="permalink"></a></h3><pre><code>#!/usr/bin/env perl
-# your program&#39;s manual page goes here
+<p>See the <a href="http://rubydoc.info/gems/binman/frames">API documentation</a> for even more possibilities!</p><h4 id="from-a-perl-script">From a Perl script<a name="from-a-perl-script" href="#from-a-perl-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight perl"><code><span class="c1">#!/usr/bin/env perl</span>
+<span class="c1"># your program's manual page goes here</span>
 
-# 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;
+<span class="c1"># OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+<span class="nb">system</span><span class="p">(</span><span class="s">'binman-help'</span><span class="p">,</span> <span class="nv">__FILE__</span><span class="p">,</span> <span class="nv">@ARGV</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> <span class="ow">and</span> <span class="nb">exit</span><span class="p">;</span>
 
-# OPTION 2: show manual unconditionally
-system(&#39;binman&#39;, &#39;show&#39;, __FILE__);
+<span class="c1"># OPTION 2: show manual unconditionally</span>
+<span class="nb">system</span><span class="p">(</span><span class="s">'binman-show'</span><span class="p">,</span> <span class="nv">__FILE__</span><span class="p">);</span>
 </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__
+<p>You can also write the manual as a multi-line Ruby comment after <code>__END__</code>:</p><pre class="highlight perl"><code><span class="c1">#!/usr/bin/env perl</span>
+<span class="k">print</span> <span class="s">"your program's code goes here"</span><span class="p">;</span>
+<span class="cp">__END__
 =begin
-your program&#39;s manual page goes here
+your program's manual page goes here
 =end
-</code></pre>
-<h3 id="inside-a-python-script">Inside a Python script<a name="inside-a-python-script" href="#inside-a-python-script" class="md2man-permalink" title="permalink"></a></h3><pre><code>#!/usr/bin/env python
-# your program&#39;s manual page goes here
+</span></code></pre>
+<h4 id="from-a-python-script">From a Python script<a name="from-a-python-script" href="#from-a-python-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight python"><code><span class="c">#!/usr/bin/env python</span>
+<span class="c"># your program's manual page goes here</span>
 
-import sys, subprocess
+<span class="kn">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">subprocess</span>
 
-# 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()
+<span class="c"># OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+<span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="s">'binman-help'</span><span class="p">,</span> <span class="n">__file__</span><span class="p">]</span> <span class="o">+</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">sys</span><span class="o">.</span><span class="nb">exit</span><span class="p">()</span>
 
-# OPTION 2: show manual unconditionally
-subprocess.call([&#39;binman&#39;, &#39;show&#39;, __file__])
+<span class="c"># OPTION 2: show manual unconditionally</span>
+<span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="s">'binman-show'</span><span class="p">,</span> <span class="n">__file__</span><span class="p">])</span>
 </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
+<p>You can also specify your program&#39;s source file encoding above the manual:</p><pre class="highlight python"><code><span class="c">#!/usr/bin/env python</span>
+<span class="c"># -*- coding: utf-8 -*-</span>
+<span class="c"># your program's manual page goes here</span>
 </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;
+<p>You can also write the manual as a multi-line Ruby comment inside a docstring:</p><pre class="highlight python"><code><span class="c">#!/usr/bin/env python</span>
+<span class="s">"""
 =begin
-your program&#39;s manual page goes here
+your program's manual page goes here
 =end
-&quot;&quot;&quot;
+"""</span>
 </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;
+<p>You can also specify your program&#39;s source file encoding above the manual:</p><pre class="highlight python"><code><span class="c">#!/usr/bin/env python</span>
+<span class="c"># -*- coding: utf-8 -*-</span>
+<span class="s">"""
 =begin
-your program&#39;s manual page goes here
+your program's manual page goes here
 =end
-&quot;&quot;&quot;
+"""</span>
 </code></pre>
-<h3 id="inside-an-awk-script">Inside an AWK script<a name="inside-an-awk-script" href="#inside-an-awk-script" class="md2man-permalink" title="permalink"></a></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
+<h4 id="from-an-awk-script">From an AWK script<a name="from-an-awk-script" href="#from-an-awk-script" class="md2man-permalink" title="permalink"></a></h4><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 class="highlight plaintext"><code>#!/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 &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 }}
+BEGIN {getline c &lt;"/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 &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)}
+BEGIN {getline c &lt;"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
+       system("binman-show" c)}
 </code></pre>
-<h3 id="inside-a-tcl-script">Inside a Tcl script<a name="inside-a-tcl-script" href="#inside-a-tcl-script" class="md2man-permalink" title="permalink"></a></h3><pre><code>#!/usr/bin/env tclsh
-# your program&#39;s manual page goes here
+<h4 id="from-a-tcl-script">From a Tcl script<a name="from-a-tcl-script" href="#from-a-tcl-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight tcl"><code><span class="c1">#!/usr/bin/env tclsh</span>
+<span class="c1"># your program's manual page goes here</span>
 
-# 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}
+<span class="c1"># OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+<span class="k">if</span> <span class="p">{</span>!<span class="p">[</span><span class="k">catch</span> <span class="p">{</span><span class="nb">exec</span> -- &gt;/dev/tty binman-help <span class="nv">$argv0</span> <span class="k">{*}</span><span class="nv">$argv</span><span class="p">}]}</span> <span class="p">{</span><span class="nb">exit</span><span class="p">}</span>
 
-# OPTION 2: show manual unconditionally
-exec &gt;/dev/tty binman show $argv0
+<span class="c1"># OPTION 2: show manual unconditionally</span>
+<span class="nb">exec</span> &gt;/dev/tty binman-show <span class="nv">$argv0</span>
 </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 {
+<p>You can also write the manual as a multi-line Ruby comment inside an <code>if 0</code>:</p><pre class="highlight tcl"><code><span class="c1">#!/usr/bin/env tclsh</span>
+<span class="k">if</span> 0 <span class="p">{</span>
 =begin
-your program&#39;s manual page goes here
+your program's manual page goes here
 =end
-}
+<span class="p">}</span>
 </code></pre>
-<h3 id="inside-a-node-js-script">Inside a Node.js script<a name="inside-a-node-js-script" href="#inside-a-node-js-script" class="md2man-permalink" title="permalink"></a></h3><pre><code>/*
+<h4 id="from-a-node-js-script">From a Node.js script<a name="from-a-node-js-script" href="#from-a-node-js-script" class="md2man-permalink" title="permalink"></a></h4><pre class="highlight javascript"><code><span class="cm">/*
 =begin
-your program&#39;s manual page goes here
+your program's manual page goes here
 =end
-*/
+*/</span>
 
-var exec = require(&#39;child_process&#39;).exec;
+<span class="kd">var</span> <span class="nx">exec</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'child_process'</span><span class="p">).</span><span class="nx">exec</span><span class="p">;</span>
 
-// 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;), function(error){ if (error === null){ process.exit(); } });
+<span class="c1">// OPTION 1: show manual and exit if ARGV has -h or --help except after --</span>
+<span class="nx">exec</span><span class="p">([</span><span class="s1">'&gt;/dev/tty'</span><span class="p">,</span> <span class="s1">'binman-help'</span><span class="p">,</span> <span class="nx">__filename</span><span class="p">].</span><span class="nx">concat</span><span class="p">(</span><span class="nx">process</span><span class="p">.</span><span class="nx">argv</span><span class="p">).</span>
+<span class="nx">join</span><span class="p">(</span><span class="s1">' '</span><span class="p">),</span> <span class="kd">function</span><span class="p">(</span><span class="nx">error</span><span class="p">){</span> <span class="k">if</span> <span class="p">(</span><span class="nx">error</span> <span class="o">===</span> <span class="kc">null</span><span class="p">){</span> <span class="nx">process</span><span class="p">.</span><span class="nx">exit</span><span class="p">();</span> <span class="p">}</span> <span class="p">});</span>
 
-// 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<a name="packaging" href="#packaging" class="md2man-permalink" title="permalink"></a></h2><h3 id="building-man-pages">Building man pages<a name="building-man-pages" href="#building-man-pages" class="md2man-permalink" title="permalink"></a></h3><h4 id="at-the-command-line-1">At the command line<a name="at-the-command-line-1" href="#at-the-command-line-1" class="md2man-permalink" title="permalink"></a></h4><p>See <a class="md2man-reference" 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-1">Inside a Ruby script<a name="inside-a-ruby-script-1" href="#inside-a-ruby-script-1" class="md2man-permalink" title="permalink"></a></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; 5.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
+<span class="c1">// OPTION 2: show manual unconditionally</span>
+<span class="nx">exec</span><span class="p">([</span><span class="s1">'&gt;/dev/tty'</span><span class="p">,</span> <span class="s1">'binman-show'</span><span class="p">,</span> <span class="nx">__filename</span><span class="p">].</span><span class="nx">join</span><span class="p">(</span><span class="s1">' '</span><span class="p">));</span>
 </code></pre>
 <h2 id="license">License<a name="license" href="#license" class="md2man-permalink" title="permalink"></a></h2><p>Released under the ISC license.  See the LICENSE file for details.</p></div></body>
 </html>