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.
- checksums.yaml +4 -4
- data/README.markdown +155 -109
- data/VERSION.markdown +15 -0
- data/bin/binman +10 -7
- data/bin/binman-rake +1 -1
- data/lib/binman.rb +32 -8
- data/lib/binman/version.rb +1 -1
- data/man/man0/README.html +26 -26
- data/man/man0/README.markdown +155 -109
- data/man/man0/VERSION.html +12 -1
- data/man/man0/VERSION.markdown +15 -0
- data/man/man1/binman-rake.1 +1 -1
- data/man/man1/binman-rake.1.html +1 -1
- data/man/man1/binman.1 +14 -9
- data/man/man1/binman.1.html +9 -6
- metadata +2 -2
data/bin/binman-rake
CHANGED
data/lib/binman.rb
CHANGED
@@ -1,4 +1,5 @@
|
|
1
|
-
require
|
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
|
46
|
-
#
|
47
|
-
|
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
|
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
|
-
|
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
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>
|
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
|
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 "Usage" 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 '~> 3.0'
|
31
|
+
<pre><code class="sh">gem install md2man -v '~> 3.0'
|
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's manual page goes here
|
50
50
|
|
51
51
|
require 'binman'
|
@@ -57,25 +57,25 @@ BinMan.help
|
|
57
57
|
BinMan.show
|
58
58
|
</code></pre>
|
59
59
|
<p>You can also specify your program'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'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's manual page goes here
|
68
68
|
=end
|
69
69
|
</code></pre>
|
70
70
|
<p>You can also specify your program'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'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'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 "$0" "$@" && exit
|
|
85
85
|
binman show "$0"
|
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'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('binman', 'help', __FILE__, @ARGV) == 0 and exit;
|
|
95
95
|
system('binman', 'show', __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 "your program's code goes here";
|
100
100
|
__END__
|
101
101
|
=begin
|
@@ -103,7 +103,7 @@ your program'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's manual page goes here
|
108
108
|
|
109
109
|
import sys, subprocess
|
@@ -115,12 +115,12 @@ subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 an
|
|
115
115
|
subprocess.call(['binman', 'show', __file__])
|
116
116
|
</code></pre>
|
117
117
|
<p>You can also specify your program'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'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
|
"""
|
125
125
|
=begin
|
126
126
|
your program's manual page goes here
|
@@ -128,7 +128,7 @@ your program's manual page goes here
|
|
128
128
|
"""
|
129
129
|
</code></pre>
|
130
130
|
<p>You can also specify your program'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
|
"""
|
134
134
|
=begin
|
@@ -137,7 +137,7 @@ your program's manual page goes here
|
|
137
137
|
"""
|
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'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 <"/proc/self/cmdline"; sub(".*-f\0",&quo
|
|
149
149
|
system("binman show" 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'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 -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
|
|
159
159
|
exec >/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's manual page goes here
|
@@ -167,7 +167,7 @@ your program'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's manual page goes here
|
173
173
|
=end
|
@@ -183,22 +183,22 @@ join(' '), <a class="md2man-reference">function(error)</a>{ if (error ==
|
|
183
183
|
exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
|
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['man/man?/*.?'] # UNIX man pages
|
189
|
+
<pre><code class="ruby">s.files += Dir['man/man?/*.?'] # UNIX man pages
|
190
190
|
s.files += Dir['man/**/*.{html,css,js}'] # HTML man pages
|
191
191
|
s.add_development_dependency 'md2man', '~> 3.0'
|
192
192
|
</code></pre>
|
193
193
|
<p>Add the following line to your Rakefile:</p>
|
194
|
-
<pre><code>require 'binman/rakefile'
|
194
|
+
<pre><code class="ruby">require 'binman/rakefile'
|
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'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'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
|
-
*
|
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
|
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
|
-
|
33
|
+
```sh
|
34
|
+
gem install binman
|
35
|
+
```
|
34
36
|
|
35
37
|
If you also want to build your own manual pages:
|
36
38
|
|
37
|
-
|
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
|
-
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
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
|
-
|
63
|
+
```sh
|
64
|
+
binman --help
|
65
|
+
```
|
58
66
|
|
59
67
|
### Inside a Ruby script
|
60
68
|
|
61
|
-
|
62
|
-
|
69
|
+
```ruby
|
70
|
+
#!/usr/bin/env ruby
|
71
|
+
# your program's manual page goes here
|
63
72
|
|
64
|
-
|
73
|
+
require 'binman'
|
65
74
|
|
66
|
-
|
67
|
-
|
75
|
+
# OPTION 1: show manual and exit if ARGV has -h or --help except after --
|
76
|
+
BinMan.help
|
68
77
|
|
69
|
-
|
70
|
-
|
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
|
-
|
75
|
-
|
76
|
-
|
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
|
-
|
81
|
-
|
82
|
-
|
83
|
-
|
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
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
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
|
-
|
98
|
-
|
113
|
+
```ruby
|
114
|
+
#!/usr/bin/sh
|
115
|
+
# your program's manual page goes here
|
99
116
|
|
100
|
-
|
101
|
-
|
117
|
+
# OPTION 1: show manual and exit if ARGV has -h or --help except after --
|
118
|
+
binman help "$0" "$@" && exit
|
102
119
|
|
103
|
-
|
104
|
-
|
120
|
+
# OPTION 2: show manual unconditionally
|
121
|
+
binman show "$0"
|
122
|
+
```
|
105
123
|
|
106
124
|
### Inside a Perl script
|
107
125
|
|
108
|
-
|
109
|
-
|
126
|
+
```perl
|
127
|
+
#!/usr/bin/env perl
|
128
|
+
# your program's manual page goes here
|
110
129
|
|
111
|
-
|
112
|
-
|
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
|
-
|
115
|
-
|
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
|
-
|
120
|
-
|
121
|
-
|
122
|
-
|
123
|
-
|
124
|
-
|
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
|
-
|
129
|
-
|
150
|
+
```python
|
151
|
+
#!/usr/bin/env python
|
152
|
+
# your program's manual page goes here
|
130
153
|
|
131
|
-
|
154
|
+
import sys, subprocess
|
132
155
|
|
133
|
-
|
134
|
-
|
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
|
-
|
137
|
-
|
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
|
-
|
142
|
-
|
143
|
-
|
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
|
-
|
148
|
-
|
149
|
-
|
150
|
-
|
151
|
-
|
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
|
-
|
157
|
-
|
158
|
-
|
159
|
-
|
160
|
-
|
161
|
-
|
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
|
-
|
171
|
-
|
200
|
+
```awk
|
201
|
+
#!/usr/bin/awk -f
|
202
|
+
# your program's manual page goes here
|
172
203
|
|
173
|
-
|
174
|
-
|
175
|
-
|
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
|
-
|
178
|
-
|
179
|
-
|
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
|
-
|
184
|
-
|
215
|
+
```tcl
|
216
|
+
#!/usr/bin/env tclsh
|
217
|
+
# your program's manual page goes here
|
185
218
|
|
186
|
-
|
187
|
-
|
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
|
-
|
190
|
-
|
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
|
-
|
195
|
-
|
196
|
-
|
197
|
-
|
198
|
-
|
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
|
-
|
205
|
-
|
206
|
-
|
207
|
-
|
239
|
+
```javascript
|
240
|
+
/*
|
241
|
+
=begin
|
242
|
+
your program's manual page goes here
|
243
|
+
=end
|
244
|
+
*/
|
208
245
|
|
209
|
-
|
246
|
+
var exec = require('child_process').exec;
|
210
247
|
|
211
|
-
|
212
|
-
|
213
|
-
|
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
|
-
|
216
|
-
|
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
|
-
|
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
|
-
|
233
|
-
|
234
|
-
|
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
|
-
|
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
|
-
|
249
|
-
|
292
|
+
```shell
|
293
|
+
bundle exec rake build
|
294
|
+
gem spec pkg/*.gem | fgrep man/man
|
295
|
+
```
|
250
296
|
|
251
297
|
## License
|
252
298
|
|