binman 3.3.3 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 25bbee995392523cf64aadd135db92cd22ade470
-  data.tar.gz: 343bb4ab6fb0e9856b6a06b9d829a026287b84e8
+  metadata.gz: 727b7b3c6721e902b36563fd5330fe05fa5707a9
+  data.tar.gz: 94d7d927939cb06625b4423f8358370b8a69e8aa
 SHA512:
-  metadata.gz: 4492b09a30bab9b6b608a691720b554a4c9af34bc2d77c502da19a264b3f4ff80628284417cd932c96e4f3082d5b351aeff0708add2a662c9738f1a0df3680ba
-  data.tar.gz: baf68d5e678bd5e90057976f97cdb865f67e58df4c8471161b611d2f291e9d1db389bb4745bf56cd6f3b357b0e9774eb52f7e321f9358d876a7fbf113ab25bcc
+  metadata.gz: 96478840dc759fb9b9f62083ab9656a433d20c19be07fece5f3f4f62e55d05fa7d877fe49faddc00ba42fda7b25be693bc3404a56fcb0e84db8041a5b19d2e7b
+  data.tar.gz: a987be972eabdcb0521ae9ba85ccd9172f4cbdfe8e72cbf7d92c300a82ab33b9c659c5b8a4d293af3214f3de39571f3a7c97baf42556f139482aa95a62b9a0ed

data/README.markdown

@@ -2,10 +2,10 @@
 
 [binman] produces UNIX manual pages for executable scripts using [md2man].
 
-* Package: <https://rubygems.org/gems/binman>
-* Manuals: <https://sunaku.github.io/binman>
+* Manuals: <https://sunaku.github.io/binman/man>
 * Sources: <https://github.com/sunaku/binman>
 * Support: <https://github.com/sunaku/binman/issues>
+* Package: <https://rubygems.org/gems/binman>
 
 ## Features
 
@@ -17,7 +17,7 @@
 
   * Individual extraction, conversion, and display commands.
 
-  * Implemented in roughly 130 lines of pure Ruby code! :-)
+  * Implemented in roughly 150 lines of pure Ruby code! :-)
 
 ### Demonstration
 
@@ -30,11 +30,15 @@ For examples in other scripting languages, see the "Usage" section below!
 
 If you only want to view pre-built manual pages:
 
-    gem install binman
+```sh
+gem install binman
+```
 
 If you also want to build your own manual pages:
 
-    gem install md2man -v '~> 3.0'
+```sh
+gem install md2man -v '~> 3.0'
+```
 
 ### Prerequisites
 
@@ -42,11 +46,13 @@ If you also want to build your own manual pages:
 
 ### Development
 
-    git clone git://github.com/sunaku/binman
-    cd binman
-    bundle install
-    bundle exec binman --help # run it directly
-    bundle exec rake --tasks  # packaging tasks
+```sh
+git clone git://github.com/sunaku/binman
+cd binman
+bundle install
+bundle exec binman --help # run it directly
+bundle exec rake --tasks  # packaging tasks
+```
 
 ## Usage
 
@@ -54,112 +60,136 @@ If you also want to build your own manual pages:
 
 See binman(1) manual:
 
-    binman --help
+```sh
+binman --help
+```
 
 ### Inside a Ruby script
 
-    #!/usr/bin/env ruby
-    # your program's manual page goes here
+```ruby
+#!/usr/bin/env ruby
+# your program's manual page goes here
 
-    require 'binman'
+require 'binman'
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    BinMan.help
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+BinMan.help
 
-    # OPTION 2: show manual unconditionally
-    BinMan.show
+# OPTION 2: show manual unconditionally
+BinMan.show
+```
 
 You can also specify your program's source file encoding above the manual:
 
-    #!/usr/bin/env ruby
-    # -*- coding: utf-8 -*-
-    # your program's manual page goes here
+```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:
 
-    #!/usr/bin/env ruby
-    =begin
-    your program's manual page goes here
-    =end
+```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:
 
-    #!/usr/bin/env ruby
-    # -*- coding: utf-8 -*-
-    =begin
-    your program's manual page goes here
-    =end
+```ruby
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+=begin
+your program's manual page goes here
+=end
+```
 
 See the [API documentation][binman-api] for even more possibilities!
 
 ### Inside a shell script
 
-    #!/usr/bin/sh
-    # your program's manual page goes here
+```ruby
+#!/usr/bin/sh
+# your program's manual page goes here
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    binman help "$0" "$@" && exit
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+binman help "$0" "$@" && exit
 
-    # OPTION 2: show manual unconditionally
-    binman show "$0"
+# OPTION 2: show manual unconditionally
+binman show "$0"
+```
 
 ### Inside a Perl script
 
-    #!/usr/bin/env perl
-    # your program's manual page goes here
+```perl
+#!/usr/bin/env perl
+# your program's manual page goes here
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
 
-    # OPTION 2: show manual unconditionally
-    system('binman', 'show', __FILE__);
+# OPTION 2: show manual unconditionally
+system('binman', 'show', __FILE__);
+```
 
 You can also write the manual as a multi-line Ruby comment after `__END__`:
 
-    #!/usr/bin/env perl
-    print "your program's code goes here";
-    __END__
-    =begin
-    your program's manual page goes here
-    =end
+```perl
+#!/usr/bin/env perl
+print "your program's code goes here";
+__END__
+=begin
+your program's manual page goes here
+=end
+```
 
 ### Inside a Python script
 
-    #!/usr/bin/env python
-    # your program's manual page goes here
+```python
+#!/usr/bin/env python
+# your program's manual page goes here
 
-    import sys, subprocess
+import sys, subprocess
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
 
-    # OPTION 2: show manual unconditionally
-    subprocess.call(['binman', 'show', __file__])
+# OPTION 2: show manual unconditionally
+subprocess.call(['binman', 'show', __file__])
+```
 
 You can also specify your program's source file encoding above the manual:
 
-    #!/usr/bin/env python
-    # -*- coding: utf-8 -*-
-    # your program's manual page goes here
+```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:
 
-    #!/usr/bin/env python
-    """
-    =begin
-    your program's manual page goes here
-    =end
-    """
+```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:
 
-    #!/usr/bin/env python
-    # -*- coding: utf-8 -*-
-    """
-    =begin
-    your program's manual page goes here
-    =end
-    """
+```python
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+=begin
+your program's manual page goes here
+=end
+"""
+```
 
 ### Inside an AWK script
 
@@ -167,53 +197,61 @@ The technique for determining current AWK script file name [comes from here](
 http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html
 ).
 
-    #!/usr/bin/awk -f
-    # your program's manual page goes here
+```awk
+#!/usr/bin/awk -f
+# your program's manual page goes here
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
-           if(system("binman help" c) == 0){ exit }}
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
+       if(system("binman help" c) == 0){ exit }}
 
-    # OPTION 2: show manual unconditionally
-    BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
-           system("binman show" c)}
+# OPTION 2: show manual unconditionally
+BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
+       system("binman show" c)}
+```
 
 ### Inside a Tcl script
 
-    #!/usr/bin/env tclsh
-    # your program's manual page goes here
+```tcl
+#!/usr/bin/env tclsh
+# your program's manual page goes here
 
-    # OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
+# OPTION 1: show manual and exit if ARGV has -h or --help except after --
+if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
 
-    # OPTION 2: show manual unconditionally
-    exec >/dev/tty binman show $argv0
+# OPTION 2: show manual unconditionally
+exec >/dev/tty binman show $argv0
+```
 
 You can also write the manual as a multi-line Ruby comment inside an `if 0`:
 
-    #!/usr/bin/env tclsh
-    if 0 {
-    =begin
-    your program's manual page goes here
-    =end
-    }
+```tcl
+#!/usr/bin/env tclsh
+if 0 {
+=begin
+your program's manual page goes here
+=end
+}
+```
 
 ### Inside a Node.js script
 
-    /*
-    =begin
-    your program's manual page goes here
-    =end
-    */
+```javascript
+/*
+=begin
+your program's manual page goes here
+=end
+*/
 
-    var exec = require('child_process').exec;
+var exec = require('child_process').exec;
 
-    // OPTION 1: show manual and exit if ARGV has -h or --help except after --
-    exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
-    join(' '), function(error){ if (error === null){ process.exit(); } });
+// OPTION 1: show manual and exit if ARGV has -h or --help except after --
+exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
+join(' '), function(error){ if (error === null){ process.exit(); } });
 
-    // OPTION 2: show manual unconditionally
-    exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
+// OPTION 2: show manual unconditionally
+exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
+```
 
 ## Packaging
 
@@ -223,19 +261,25 @@ You can also write the manual as a multi-line Ruby comment inside an `if 0`:
 
 See binman-rake(1) manual:
 
-    binman-rake --help
+```sh
+binman-rake --help
+```
 
 #### Inside a Ruby script
 
 Add this snippet to your gemspec file:
 
-    s.files += Dir['man/man?/*.?']            # UNIX man pages
-    s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
-    s.add_development_dependency 'md2man', '~> 3.0'
+```ruby
+s.files += Dir['man/man?/*.?']            # UNIX man pages
+s.files += Dir['man/**/*.{html,css,js}']  # HTML man pages
+s.add_development_dependency 'md2man', '~> 3.0'
+```
 
 Add the following line to your Rakefile:
 
-    require 'binman/rakefile'
+```ruby
+require 'binman/rakefile'
+```
 
 You now have a `rake binman` task that pre-builds UNIX manual page files for
 your `bin/` scripts into a `man/` directory so that your end-users do not need
@@ -245,8 +289,10 @@ There are also sub-tasks to build manual pages individually as [roff] or HTML.
 If you're using Bundler, this task also hooks into its gem packaging tasks and
 ensures that your UNIX manual pages are pre-built and packaged into your gem:
 
-    bundle exec rake build
-    gem spec pkg/*.gem | fgrep man/man
+```shell
+bundle exec rake build
+gem spec pkg/*.gem | fgrep man/man
+```
 
 ## License
 

data/VERSION.markdown

@@ -1,3 +1,18 @@
+## Version 3.4.0 (2014-06-29)
+
+### Minor:
+
+  * GH-3: add optional regexp argument to `-h`/`--help` to search in man(1).
+
+    The `-h` and `--help` options in `BinMan.help()` can now be optionally
+    followed by a regular expression argument that specifies text to search
+    for and, if found, jump to inside the displayed UNIX man page.  Such a
+    regular expression argument can now also be passed into `BinMan.show()`.
+
+### Other:
+
+  * README: add syntax highlighting to code snippets.
+
 ## Version 3.3.3 (2014-06-22)
 
 This release upgrades to md2man 3.0 for improved HTML manuals.

data/bin/binman

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN 1 2014-06-22 3.3.3
+# BINMAN 1 2014-06-29 3.4.0
 
 ## NAME
 
@@ -64,15 +64,18 @@ The following [Redcarpet] extensions are enabled while processing markdown(7):
 
 ## COMMANDS
 
-`help` *FILE* [*ARGUMENT*]...
-  If the given *ARGUMENT* sequence contains `-h` or `--help` except after
-  `--`, then this program extracts the given *FILE*'s leading comment header,
-  converts it into roff(7), and displays it using man(1) before exiting with
+`help` *FILE* ... [`-h`|`--help` [*REGEXP*]] ... [`--`] ...
+  If the given argument sequence contains `-h` or `--help`, except after
+  `--`, optionally followed by a *REGEXP* regular expression that specifies
+  text to search for and, if found, jump to inside the displayed man page,
+  then this program extracts the given *FILE*'s leading comment header,
+  converts it into roff(7), displays it using man(1), and finally exits with
   status code `0`.  Otherwise, this program exits with status code `111`.
 
-`show` [*FILE*]
+`show` [*FILE*] [*REGEXP*]
   Use man(1) to display the roff(7) conversion of the leading comment header
-  extracted from the given *FILE* or STDIN.
+  extracted from the given *FILE* or STDIN.  If *REGEXP* is given, search for
+  it within the output displayed by man(1) and jump to first match if found.
 
 `load` [*FILE*]
   Print the leading comment header extracted from the given *FILE* or STDIN.