binman 3.3.3 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. checksums.yaml +4 -4
  2. data/README.markdown +155 -109
  3. data/VERSION.markdown +15 -0
  4. data/bin/binman +10 -7
  5. data/bin/binman-rake +1 -1
  6. data/lib/binman.rb +32 -8
  7. data/lib/binman/version.rb +1 -1
  8. data/man/man0/README.html +26 -26
  9. data/man/man0/README.markdown +155 -109
  10. data/man/man0/VERSION.html +12 -1
  11. data/man/man0/VERSION.markdown +15 -0
  12. data/man/man1/binman-rake.1 +1 -1
  13. data/man/man1/binman-rake.1.html +1 -1
  14. data/man/man1/binman.1 +14 -9
  15. data/man/man1/binman.1.html +9 -6
  16. metadata +2 -2
data/bin/binman-rake CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env ruby
2
2
  =begin =======================================================================
3
3
 
4
- # BINMAN-RAKE 1 2014-06-22 3.3.3
4
+ # BINMAN-RAKE 1 2014-06-29 3.4.0
5
5
 
6
6
  ## NAME
7
7
 
data/lib/binman.rb CHANGED
@@ -1,4 +1,5 @@
1
- require "binman/version"
1
+ require 'shellwords'
2
+ require 'binman/version'
2
3
 
3
4
  module BinMan
4
5
  extend self
@@ -42,9 +43,10 @@ module BinMan
42
43
  conv load(source)
43
44
  end
44
45
 
45
- # Shows leading comment header from given source as UNIX man page if
46
- # possible, else falls back to showing leading comment header as-is.
47
- def show source=nil
46
+ # Shows leading comment header from given source as UNIX man page and
47
+ # optionally jumps to first match of query regular expression if given.
48
+ # If not possible, falls back to showing leading comment header as-is.
49
+ def show source=nil, query=nil
48
50
  # try showing existing man page files for given source
49
51
  if file = find(source) and File.exist? file
50
52
  man_page = File.basename(file)
@@ -63,7 +65,7 @@ module BinMan
63
65
 
64
66
  # try showing roff manual page in man(1) reader in foreground;
65
67
  # close STDERR to avoid interference with the fall back below
66
- return if system 'man', '-M', man_path, '-a', man_page, 2 => :close
68
+ return if view query, '-M', man_path, '-a', man_page, 2 => :close
67
69
  end
68
70
 
69
71
  # fall back to showing leading comment header as-is
@@ -75,7 +77,7 @@ module BinMan
75
77
  Tempfile.open 'binman' do |temp|
76
78
  temp.write roff
77
79
  temp.close
78
- system 'man', temp.path
80
+ view query, temp.path
79
81
  end
80
82
  rescue => error
81
83
  warn "binman: #{error}"
@@ -84,12 +86,14 @@ module BinMan
84
86
  end
85
87
 
86
88
  # Shows leading comment header from given source as UNIX man page and exits
87
- # if the given argument vector contains '-h' or '--help', except after '--'.
89
+ # if the given argument vector contains '-h' or '--help', except after '--',
90
+ # optionally followed by a regular expression argument that specifies text
91
+ # to search for and, if found, jump to inside the displayed UNIX man page.
88
92
  def help source=nil, argv=ARGV
89
93
  limit = argv.index('--') || argv.length
90
94
  index = [argv.index('-h'), argv.index('--help')].compact.min
91
95
  if index and index < limit
92
- show source
96
+ show source, argv[index + 1]
93
97
  exit
94
98
  end
95
99
  end
@@ -105,6 +109,26 @@ module BinMan
105
109
 
106
110
  private
107
111
 
112
+ # Launches man(1) with the given arguments and then tries to search for the
113
+ # query (if given) within. If man(1) is not able to launch with the search
114
+ # capability, then it tries launching man(1) without the search capability.
115
+ def view query, *argv
116
+ if query
117
+ # man(1) uses `pager -s` as the pager command by default and both of the
118
+ # more(1) and less(1) pagers support the "+/pattern" command-line option
119
+ status = system('man', '-P', "pager -s +/#{query.shellescape}", *argv)
120
+
121
+ # exit status 3 means man(1) couldn't launch with the search capability:
122
+ #
123
+ # man: can't execute pager: No such file or directory
124
+ #
125
+ # so don't return and try launching man(1) without the search capability
126
+ return status unless $?.exitstatus == 3
127
+ end
128
+
129
+ system 'man', *argv
130
+ end
131
+
108
132
  # Returns contents of given source I/O, file name, or string.
109
133
  def read source=nil
110
134
  if source.respond_to? :read
data/lib/binman/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module BinMan
2
- VERSION = "3.3.3"
2
+ VERSION = "3.4.0"
3
3
  end
data/man/man0/README.html CHANGED
@@ -9,10 +9,10 @@
9
9
  </head>
10
10
  <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"><a name="binman-man-pages-for" href="#binman-man-pages-for" class="md2man-permalink" title="permalink"></a><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></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>
11
11
  <ul>
12
- <li>Package: <a href="https://rubygems.org/gems/binman">https://rubygems.org/gems/binman</a></li>
13
- <li>Manuals: <a href="https://sunaku.github.io/binman">https://sunaku.github.io/binman</a></li>
12
+ <li>Manuals: <a href="https://sunaku.github.io/binman/man">https://sunaku.github.io/binman/man</a></li>
14
13
  <li>Sources: <a href="https://github.com/sunaku/binman">https://github.com/sunaku/binman</a></li>
15
14
  <li>Support: <a href="https://github.com/sunaku/binman/issues">https://github.com/sunaku/binman/issues</a></li>
15
+ <li>Package: <a href="https://rubygems.org/gems/binman">https://rubygems.org/gems/binman</a></li>
16
16
  </ul>
17
17
  <h2 id="features"><a name="features" href="#features" class="md2man-permalink" title="permalink"></a>Features</h2>
18
18
  <ul>
@@ -21,31 +21,31 @@ comments or uses <code>#</code> for single-line comments: Ruby,
21
21
  Perl, Python, Node.js, Tcl, AWK, UNIX shell, and more!</p></li>
22
22
  <li><p>Provides a Ruby library and a command-line client too.</p></li>
23
23
  <li><p>Individual extraction, conversion, and display commands.</p></li>
24
- <li><p>Implemented in roughly 130 lines of pure Ruby code! :-)</p></li>
24
+ <li><p>Implemented in roughly 150 lines of pure Ruby code! :-)</p></li>
25
25
  </ul>
26
26
  <h3 id="demonstration"><a name="demonstration" href="#demonstration" class="md2man-permalink" title="permalink"></a>Demonstration</h3><p><img src="EXAMPLE.png" 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.
27
27
  For examples in other scripting languages, see the &quot;Usage&quot; section below!</p><h2 id="installation"><a name="installation" href="#installation" class="md2man-permalink" title="permalink"></a>Installation</h2><p>If you only want to view pre-built manual pages:</p>
28
- <pre><code>gem install binman
28
+ <pre><code class="sh">gem install binman
29
29
  </code></pre>
30
30
  <p>If you also want to build your own manual pages:</p>
31
- <pre><code>gem install md2man -v &#39;~&gt; 3.0&#39;
31
+ <pre><code class="sh">gem install md2man -v &#39;~&gt; 3.0&#39;
32
32
  </code></pre>
33
33
  <h3 id="prerequisites"><a name="prerequisites" href="#prerequisites" class="md2man-permalink" title="permalink"></a>Prerequisites</h3>
34
34
  <ul>
35
35
  <li>Ruby 1.8.7 or 1.9.2 or newer.</li>
36
36
  </ul>
37
37
  <h3 id="development"><a name="development" href="#development" class="md2man-permalink" title="permalink"></a>Development</h3>
38
- <pre><code>git clone git://github.com/sunaku/binman
38
+ <pre><code class="sh">git clone git://github.com/sunaku/binman
39
39
  cd binman
40
40
  bundle install
41
41
  bundle exec binman --help # run it directly
42
42
  bundle exec rake --tasks # packaging tasks
43
43
  </code></pre>
44
44
  <h2 id="usage"><a name="usage" href="#usage" class="md2man-permalink" title="permalink"></a>Usage</h2><h3 id="at-the-command-line"><a name="at-the-command-line" href="#at-the-command-line" class="md2man-permalink" title="permalink"></a>At the command line</h3><p>See <a class="md2man-reference" href="../man1/binman.1.html">binman(1)</a> manual:</p>
45
- <pre><code>binman --help
45
+ <pre><code class="sh">binman --help
46
46
  </code></pre>
47
47
  <h3 id="inside-a-ruby-script"><a name="inside-a-ruby-script" href="#inside-a-ruby-script" class="md2man-permalink" title="permalink"></a>Inside a Ruby script</h3>
48
- <pre><code>#!/usr/bin/env ruby
48
+ <pre><code class="ruby">#!/usr/bin/env ruby
49
49
  # your program&#39;s manual page goes here
50
50
 
51
51
  require &#39;binman&#39;
@@ -57,25 +57,25 @@ BinMan.help
57
57
  BinMan.show
58
58
  </code></pre>
59
59
  <p>You can also specify your program&#39;s source file encoding above the manual:</p>
60
- <pre><code>#!/usr/bin/env ruby
60
+ <pre><code class="ruby">#!/usr/bin/env ruby
61
61
  # -*- coding: utf-8 -*-
62
62
  # your program&#39;s manual page goes here
63
63
  </code></pre>
64
64
  <p>You can also write the manual as a multi-line Ruby comment:</p>
65
- <pre><code>#!/usr/bin/env ruby
65
+ <pre><code class="ruby">#!/usr/bin/env ruby
66
66
  =begin
67
67
  your program&#39;s manual page goes here
68
68
  =end
69
69
  </code></pre>
70
70
  <p>You can also specify your program&#39;s source file encoding above the manual:</p>
71
- <pre><code>#!/usr/bin/env ruby
71
+ <pre><code class="ruby">#!/usr/bin/env ruby
72
72
  # -*- coding: utf-8 -*-
73
73
  =begin
74
74
  your program&#39;s manual page goes here
75
75
  =end
76
76
  </code></pre>
77
77
  <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"><a name="inside-a-shell-script" href="#inside-a-shell-script" class="md2man-permalink" title="permalink"></a>Inside a shell script</h3>
78
- <pre><code>#!/usr/bin/sh
78
+ <pre><code class="ruby">#!/usr/bin/sh
79
79
  # your program&#39;s manual page goes here
80
80
 
81
81
  # OPTION 1: show manual and exit if ARGV has -h or --help except after --
@@ -85,7 +85,7 @@ binman help &quot;$0&quot; &quot;$@&quot; &amp;&amp; exit
85
85
  binman show &quot;$0&quot;
86
86
  </code></pre>
87
87
  <h3 id="inside-a-perl-script"><a name="inside-a-perl-script" href="#inside-a-perl-script" class="md2man-permalink" title="permalink"></a>Inside a Perl script</h3>
88
- <pre><code>#!/usr/bin/env perl
88
+ <pre><code class="perl">#!/usr/bin/env perl
89
89
  # your program&#39;s manual page goes here
90
90
 
91
91
  # OPTION 1: show manual and exit if ARGV has -h or --help except after --
@@ -95,7 +95,7 @@ system(&#39;binman&#39;, &#39;help&#39;, __FILE__, @ARGV) == 0 and exit;
95
95
  system(&#39;binman&#39;, &#39;show&#39;, __FILE__);
96
96
  </code></pre>
97
97
  <p>You can also write the manual as a multi-line Ruby comment after <code>__END__</code>:</p>
98
- <pre><code>#!/usr/bin/env perl
98
+ <pre><code class="perl">#!/usr/bin/env perl
99
99
  print &quot;your program&#39;s code goes here&quot;;
100
100
  __END__
101
101
  =begin
@@ -103,7 +103,7 @@ your program&#39;s manual page goes here
103
103
  =end
104
104
  </code></pre>
105
105
  <h3 id="inside-a-python-script"><a name="inside-a-python-script" href="#inside-a-python-script" class="md2man-permalink" title="permalink"></a>Inside a Python script</h3>
106
- <pre><code>#!/usr/bin/env python
106
+ <pre><code class="python">#!/usr/bin/env python
107
107
  # your program&#39;s manual page goes here
108
108
 
109
109
  import sys, subprocess
@@ -115,12 +115,12 @@ subprocess.call([&#39;binman&#39;, &#39;help&#39;, __file__] + sys.argv) == 0 an
115
115
  subprocess.call([&#39;binman&#39;, &#39;show&#39;, __file__])
116
116
  </code></pre>
117
117
  <p>You can also specify your program&#39;s source file encoding above the manual:</p>
118
- <pre><code>#!/usr/bin/env python
118
+ <pre><code class="python">#!/usr/bin/env python
119
119
  # -*- coding: utf-8 -*-
120
120
  # your program&#39;s manual page goes here
121
121
  </code></pre>
122
122
  <p>You can also write the manual as a multi-line Ruby comment inside a docstring:</p>
123
- <pre><code>#!/usr/bin/env python
123
+ <pre><code class="python">#!/usr/bin/env python
124
124
  &quot;&quot;&quot;
125
125
  =begin
126
126
  your program&#39;s manual page goes here
@@ -128,7 +128,7 @@ your program&#39;s manual page goes here
128
128
  &quot;&quot;&quot;
129
129
  </code></pre>
130
130
  <p>You can also specify your program&#39;s source file encoding above the manual:</p>
131
- <pre><code>#!/usr/bin/env python
131
+ <pre><code class="python">#!/usr/bin/env python
132
132
  # -*- coding: utf-8 -*-
133
133
  &quot;&quot;&quot;
134
134
  =begin
@@ -137,7 +137,7 @@ your program&#39;s manual page goes here
137
137
  &quot;&quot;&quot;
138
138
  </code></pre>
139
139
  <h3 id="inside-an-awk-script"><a name="inside-an-awk-script" href="#inside-an-awk-script" class="md2man-permalink" title="permalink"></a>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>
140
- <pre><code>#!/usr/bin/awk -f
140
+ <pre><code class="awk">#!/usr/bin/awk -f
141
141
  # your program&#39;s manual page goes here
142
142
 
143
143
  # OPTION 1: show manual and exit if ARGV has -h or --help except after --
@@ -149,7 +149,7 @@ BEGIN {getline c &lt;&quot;/proc/self/cmdline&quot;; sub(&quot;.*-f\0&quot;,&quo
149
149
  system(&quot;binman show&quot; c)}
150
150
  </code></pre>
151
151
  <h3 id="inside-a-tcl-script"><a name="inside-a-tcl-script" href="#inside-a-tcl-script" class="md2man-permalink" title="permalink"></a>Inside a Tcl script</h3>
152
- <pre><code>#!/usr/bin/env tclsh
152
+ <pre><code class="tcl">#!/usr/bin/env tclsh
153
153
  # your program&#39;s manual page goes here
154
154
 
155
155
  # OPTION 1: show manual and exit if ARGV has -h or --help except after --
@@ -159,7 +159,7 @@ if {![catch {exec -- &gt;/dev/tty binman help $argv0 {*}$argv}]} {exit}
159
159
  exec &gt;/dev/tty binman show $argv0
160
160
  </code></pre>
161
161
  <p>You can also write the manual as a multi-line Ruby comment inside an <code>if 0</code>:</p>
162
- <pre><code>#!/usr/bin/env tclsh
162
+ <pre><code class="tcl">#!/usr/bin/env tclsh
163
163
  if 0 {
164
164
  =begin
165
165
  your program&#39;s manual page goes here
@@ -167,7 +167,7 @@ your program&#39;s manual page goes here
167
167
  }
168
168
  </code></pre>
169
169
  <h3 id="inside-a-node-js-script"><a name="inside-a-node-js-script" href="#inside-a-node-js-script" class="md2man-permalink" title="permalink"></a>Inside a Node.js script</h3>
170
- <pre><code>/*
170
+ <pre><code class="javascript">/*
171
171
  =begin
172
172
  your program&#39;s manual page goes here
173
173
  =end
@@ -183,22 +183,22 @@ join(&#39; &#39;), <a class="md2man-reference">function(error)</a>{ if (error ==
183
183
  exec([&#39;&gt;/dev/tty&#39;, &#39;binman&#39;, &#39;show&#39;, __filename].join(&#39; &#39;));
184
184
  </code></pre>
185
185
  <h2 id="packaging"><a name="packaging" href="#packaging" class="md2man-permalink" title="permalink"></a>Packaging</h2><h3 id="building-man-pages"><a name="building-man-pages" href="#building-man-pages" class="md2man-permalink" title="permalink"></a>Building man pages</h3><h4 id="at-the-command-line-1"><a name="at-the-command-line-1" href="#at-the-command-line-1" class="md2man-permalink" title="permalink"></a>At the command line</h4><p>See <a class="md2man-reference" href="../man1/binman-rake.1.html">binman-rake(1)</a> manual:</p>
186
- <pre><code>binman-rake --help
186
+ <pre><code class="sh">binman-rake --help
187
187
  </code></pre>
188
188
  <h4 id="inside-a-ruby-script-1"><a name="inside-a-ruby-script-1" href="#inside-a-ruby-script-1" class="md2man-permalink" title="permalink"></a>Inside a Ruby script</h4><p>Add this snippet to your gemspec file:</p>
189
- <pre><code>s.files += Dir[&#39;man/man?/*.?&#39;] # UNIX man pages
189
+ <pre><code class="ruby">s.files += Dir[&#39;man/man?/*.?&#39;] # UNIX man pages
190
190
  s.files += Dir[&#39;man/**/*.{html,css,js}&#39;] # HTML man pages
191
191
  s.add_development_dependency &#39;md2man&#39;, &#39;~&gt; 3.0&#39;
192
192
  </code></pre>
193
193
  <p>Add the following line to your Rakefile:</p>
194
- <pre><code>require &#39;binman/rakefile&#39;
194
+ <pre><code class="ruby">require &#39;binman/rakefile&#39;
195
195
  </code></pre>
196
196
  <p>You now have a <code>rake binman</code> task that pre-builds UNIX manual page files for
197
197
  your <code>bin/</code> scripts into a <code>man/</code> directory so that your end-users do not need
198
198
  <a href="https://github.com/sunaku/md2man">md2man</a> installed in order to view the manual pages you&#39;ve embedded therein!
199
199
  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
200
200
  ensures that your UNIX manual pages are pre-built and packaged into your gem:</p>
201
- <pre><code>bundle exec rake build
201
+ <pre><code class="shell">bundle exec rake build
202
202
  gem spec pkg/*.gem | fgrep man/man
203
203
  </code></pre>
204
204
  <h2 id="license"><a name="license" href="#license" class="md2man-permalink" title="permalink"></a>License</h2><p>Released under the ISC license. See the LICENSE file for details.</p></div></body>
data/man/man0/README.markdown CHANGED
@@ -2,10 +2,10 @@
2
2
 
3
3
  [binman] produces UNIX manual pages for executable scripts using [md2man].
4
4
 
5
- * Package: <https://rubygems.org/gems/binman>
6
- * Manuals: <https://sunaku.github.io/binman>
5
+ * Manuals: <https://sunaku.github.io/binman/man>
7
6
  * Sources: <https://github.com/sunaku/binman>
8
7
  * Support: <https://github.com/sunaku/binman/issues>
8
+ * Package: <https://rubygems.org/gems/binman>
9
9
 
10
10
  ## Features
11
11
 
@@ -17,7 +17,7 @@
17
17
 
18
18
  * Individual extraction, conversion, and display commands.
19
19
 
20
- * Implemented in roughly 130 lines of pure Ruby code! :-)
20
+ * Implemented in roughly 150 lines of pure Ruby code! :-)
21
21
 
22
22
  ### Demonstration
23
23
 
@@ -30,11 +30,15 @@ For examples in other scripting languages, see the "Usage" section below!
30
30
 
31
31
  If you only want to view pre-built manual pages:
32
32
 
33
- gem install binman
33
+ ```sh
34
+ gem install binman
35
+ ```
34
36
 
35
37
  If you also want to build your own manual pages:
36
38
 
37
- gem install md2man -v '~> 3.0'
39
+ ```sh
40
+ gem install md2man -v '~> 3.0'
41
+ ```
38
42
 
39
43
  ### Prerequisites
40
44
 
@@ -42,11 +46,13 @@ If you also want to build your own manual pages:
42
46
 
43
47
  ### Development
44
48
 
45
- git clone git://github.com/sunaku/binman
46
- cd binman
47
- bundle install
48
- bundle exec binman --help # run it directly
49
- bundle exec rake --tasks # packaging tasks
49
+ ```sh
50
+ git clone git://github.com/sunaku/binman
51
+ cd binman
52
+ bundle install
53
+ bundle exec binman --help # run it directly
54
+ bundle exec rake --tasks # packaging tasks
55
+ ```
50
56
 
51
57
  ## Usage
52
58
 
@@ -54,112 +60,136 @@ If you also want to build your own manual pages:
54
60
 
55
61
  See binman(1) manual:
56
62
 
57
- binman --help
63
+ ```sh
64
+ binman --help
65
+ ```
58
66
 
59
67
  ### Inside a Ruby script
60
68
 
61
- #!/usr/bin/env ruby
62
- # your program's manual page goes here
69
+ ```ruby
70
+ #!/usr/bin/env ruby
71
+ # your program's manual page goes here
63
72
 
64
- require 'binman'
73
+ require 'binman'
65
74
 
66
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
67
- BinMan.help
75
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
76
+ BinMan.help
68
77
 
69
- # OPTION 2: show manual unconditionally
70
- BinMan.show
78
+ # OPTION 2: show manual unconditionally
79
+ BinMan.show
80
+ ```
71
81
 
72
82
  You can also specify your program's source file encoding above the manual:
73
83
 
74
- #!/usr/bin/env ruby
75
- # -*- coding: utf-8 -*-
76
- # your program's manual page goes here
84
+ ```ruby
85
+ #!/usr/bin/env ruby
86
+ # -*- coding: utf-8 -*-
87
+ # your program's manual page goes here
88
+ ```
77
89
 
78
90
  You can also write the manual as a multi-line Ruby comment:
79
91
 
80
- #!/usr/bin/env ruby
81
- =begin
82
- your program's manual page goes here
83
- =end
92
+ ```ruby
93
+ #!/usr/bin/env ruby
94
+ =begin
95
+ your program's manual page goes here
96
+ =end
97
+ ```
84
98
 
85
99
  You can also specify your program's source file encoding above the manual:
86
100
 
87
- #!/usr/bin/env ruby
88
- # -*- coding: utf-8 -*-
89
- =begin
90
- your program's manual page goes here
91
- =end
101
+ ```ruby
102
+ #!/usr/bin/env ruby
103
+ # -*- coding: utf-8 -*-
104
+ =begin
105
+ your program's manual page goes here
106
+ =end
107
+ ```
92
108
 
93
109
  See the [API documentation][binman-api] for even more possibilities!
94
110
 
95
111
  ### Inside a shell script
96
112
 
97
- #!/usr/bin/sh
98
- # your program's manual page goes here
113
+ ```ruby
114
+ #!/usr/bin/sh
115
+ # your program's manual page goes here
99
116
 
100
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
101
- binman help "$0" "$@" && exit
117
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
118
+ binman help "$0" "$@" && exit
102
119
 
103
- # OPTION 2: show manual unconditionally
104
- binman show "$0"
120
+ # OPTION 2: show manual unconditionally
121
+ binman show "$0"
122
+ ```
105
123
 
106
124
  ### Inside a Perl script
107
125
 
108
- #!/usr/bin/env perl
109
- # your program's manual page goes here
126
+ ```perl
127
+ #!/usr/bin/env perl
128
+ # your program's manual page goes here
110
129
 
111
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
112
- system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
130
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
131
+ system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
113
132
 
114
- # OPTION 2: show manual unconditionally
115
- system('binman', 'show', __FILE__);
133
+ # OPTION 2: show manual unconditionally
134
+ system('binman', 'show', __FILE__);
135
+ ```
116
136
 
117
137
  You can also write the manual as a multi-line Ruby comment after `__END__`:
118
138
 
119
- #!/usr/bin/env perl
120
- print "your program's code goes here";
121
- __END__
122
- =begin
123
- your program's manual page goes here
124
- =end
139
+ ```perl
140
+ #!/usr/bin/env perl
141
+ print "your program's code goes here";
142
+ __END__
143
+ =begin
144
+ your program's manual page goes here
145
+ =end
146
+ ```
125
147
 
126
148
  ### Inside a Python script
127
149
 
128
- #!/usr/bin/env python
129
- # your program's manual page goes here
150
+ ```python
151
+ #!/usr/bin/env python
152
+ # your program's manual page goes here
130
153
 
131
- import sys, subprocess
154
+ import sys, subprocess
132
155
 
133
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
134
- subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
156
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
157
+ subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
135
158
 
136
- # OPTION 2: show manual unconditionally
137
- subprocess.call(['binman', 'show', __file__])
159
+ # OPTION 2: show manual unconditionally
160
+ subprocess.call(['binman', 'show', __file__])
161
+ ```
138
162
 
139
163
  You can also specify your program's source file encoding above the manual:
140
164
 
141
- #!/usr/bin/env python
142
- # -*- coding: utf-8 -*-
143
- # your program's manual page goes here
165
+ ```python
166
+ #!/usr/bin/env python
167
+ # -*- coding: utf-8 -*-
168
+ # your program's manual page goes here
169
+ ```
144
170
 
145
171
  You can also write the manual as a multi-line Ruby comment inside a docstring:
146
172
 
147
- #!/usr/bin/env python
148
- """
149
- =begin
150
- your program's manual page goes here
151
- =end
152
- """
173
+ ```python
174
+ #!/usr/bin/env python
175
+ """
176
+ =begin
177
+ your program's manual page goes here
178
+ =end
179
+ """
180
+ ```
153
181
 
154
182
  You can also specify your program's source file encoding above the manual:
155
183
 
156
- #!/usr/bin/env python
157
- # -*- coding: utf-8 -*-
158
- """
159
- =begin
160
- your program's manual page goes here
161
- =end
162
- """
184
+ ```python
185
+ #!/usr/bin/env python
186
+ # -*- coding: utf-8 -*-
187
+ """
188
+ =begin
189
+ your program's manual page goes here
190
+ =end
191
+ """
192
+ ```
163
193
 
164
194
  ### Inside an AWK script
165
195
 
@@ -167,53 +197,61 @@ The technique for determining current AWK script file name [comes from here](
167
197
  http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html
168
198
  ).
169
199
 
170
- #!/usr/bin/awk -f
171
- # your program's manual page goes here
200
+ ```awk
201
+ #!/usr/bin/awk -f
202
+ # your program's manual page goes here
172
203
 
173
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
174
- BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
175
- if(system("binman help" c) == 0){ exit }}
204
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
205
+ BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
206
+ if(system("binman help" c) == 0){ exit }}
176
207
 
177
- # OPTION 2: show manual unconditionally
178
- BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
179
- system("binman show" c)}
208
+ # OPTION 2: show manual unconditionally
209
+ BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
210
+ system("binman show" c)}
211
+ ```
180
212
 
181
213
  ### Inside a Tcl script
182
214
 
183
- #!/usr/bin/env tclsh
184
- # your program's manual page goes here
215
+ ```tcl
216
+ #!/usr/bin/env tclsh
217
+ # your program's manual page goes here
185
218
 
186
- # OPTION 1: show manual and exit if ARGV has -h or --help except after --
187
- if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
219
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
220
+ if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
188
221
 
189
- # OPTION 2: show manual unconditionally
190
- exec >/dev/tty binman show $argv0
222
+ # OPTION 2: show manual unconditionally
223
+ exec >/dev/tty binman show $argv0
224
+ ```
191
225
 
192
226
  You can also write the manual as a multi-line Ruby comment inside an `if 0`:
193
227
 
194
- #!/usr/bin/env tclsh
195
- if 0 {
196
- =begin
197
- your program's manual page goes here
198
- =end
199
- }
228
+ ```tcl
229
+ #!/usr/bin/env tclsh
230
+ if 0 {
231
+ =begin
232
+ your program's manual page goes here
233
+ =end
234
+ }
235
+ ```
200
236
 
201
237
  ### Inside a Node.js script
202
238
 
203
- /*
204
- =begin
205
- your program's manual page goes here
206
- =end
207
- */
239
+ ```javascript
240
+ /*
241
+ =begin
242
+ your program's manual page goes here
243
+ =end
244
+ */
208
245
 
209
- var exec = require('child_process').exec;
246
+ var exec = require('child_process').exec;
210
247
 
211
- // OPTION 1: show manual and exit if ARGV has -h or --help except after --
212
- exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
213
- join(' '), function(error){ if (error === null){ process.exit(); } });
248
+ // OPTION 1: show manual and exit if ARGV has -h or --help except after --
249
+ exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
250
+ join(' '), function(error){ if (error === null){ process.exit(); } });
214
251
 
215
- // OPTION 2: show manual unconditionally
216
- exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
252
+ // OPTION 2: show manual unconditionally
253
+ exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
254
+ ```
217
255
 
218
256
  ## Packaging
219
257
 
@@ -223,19 +261,25 @@ You can also write the manual as a multi-line Ruby comment inside an `if 0`:
223
261
 
224
262
  See binman-rake(1) manual:
225
263
 
226
- binman-rake --help
264
+ ```sh
265
+ binman-rake --help
266
+ ```
227
267
 
228
268
  #### Inside a Ruby script
229
269
 
230
270
  Add this snippet to your gemspec file:
231
271
 
232
- s.files += Dir['man/man?/*.?'] # UNIX man pages
233
- s.files += Dir['man/**/*.{html,css,js}'] # HTML man pages
234
- s.add_development_dependency 'md2man', '~> 3.0'
272
+ ```ruby
273
+ s.files += Dir['man/man?/*.?'] # UNIX man pages
274
+ s.files += Dir['man/**/*.{html,css,js}'] # HTML man pages
275
+ s.add_development_dependency 'md2man', '~> 3.0'
276
+ ```
235
277
 
236
278
  Add the following line to your Rakefile:
237
279
 
238
- require 'binman/rakefile'
280
+ ```ruby
281
+ require 'binman/rakefile'
282
+ ```
239
283
 
240
284
  You now have a `rake binman` task that pre-builds UNIX manual page files for
241
285
  your `bin/` scripts into a `man/` directory so that your end-users do not need
@@ -245,8 +289,10 @@ There are also sub-tasks to build manual pages individually as [roff] or HTML.
245
289
  If you're using Bundler, this task also hooks into its gem packaging tasks and
246
290
  ensures that your UNIX manual pages are pre-built and packaged into your gem:
247
291
 
248
- bundle exec rake build
249
- gem spec pkg/*.gem | fgrep man/man
292
+ ```shell
293
+ bundle exec rake build
294
+ gem spec pkg/*.gem | fgrep man/man
295
+ ```
250
296
 
251
297
  ## License
252
298