README.markdown in binman-3.0.1 vs README.markdown in binman-3.1.0
- old
+ new
@@ -1,99 +1,241 @@
-binman - UNIX man pages for Ruby bin/ scripts
-==============================================================================
+# binman - man pages for bin scripts
-[binman] produces UNIX man pages for your Ruby `bin/` scripts using
-markdown(7), roff(7), [md2man] for conversion thereof, and man(1).
+[binman] produces UNIX manual pages for executable scripts using [md2man].
-
+## Features
-Here is [an example bin/ script][binman-bin] to help you get started!
+ * Supports any scripting language that has multi-line
+ comments or uses `#` for single-line comments: Ruby,
+ Perl, Python, Node.js, Tcl, AWK, UNIX shell, and more!
-[binman]: https://github.com/sunaku/binman
-[binman-api]: http://rdoc.info/github/sunaku/binman
-[binman-bin]: https://raw.github.com/sunaku/binman/master/bin/binman
-[md2man]: https://github.com/sunaku/md2man
+ * Provides a Ruby library and a command-line client too.
-------------------------------------------------------------------------------
-Features
-------------------------------------------------------------------------------
+ * Individual extraction, conversion, and display commands.
-* Includes both a Ruby library and a command-line client.
+ * Implemented in roughly 100 lines of pure Ruby code! :-)
-* Individual extraction, conversion, and display commands.
+### Demonstration
-* Implemented in roughly 100 lines of pure Ruby code! :-)
+
-------------------------------------------------------------------------------
-Prerequisites
-------------------------------------------------------------------------------
+Here is [a complete example in Ruby][binman-bin] to help you get started.
+For examples in other scripting languages, see the "Usage" section below!
-* Ruby 1.9.2 or newer. It might work with 1.8.7 but I haven't tried. :-P
+## Installation
-------------------------------------------------------------------------------
-Installation
-------------------------------------------------------------------------------
+If you only want to view pre-built manual pages:
-As a Ruby gem (without markdown to roff converter):
-
gem install binman
-As a Ruby gem (with extra cheese and everything please):
+If you also want to build your own manual pages:
- gem install binman --development
+ gem install md2man -v '~> 1'
+### Prerequisites
+
+ * Ruby 1.8.7 or 1.9.2 or newer.
+
### Development
git clone git://github.com/sunaku/binman
cd binman
bundle install --binstubs=bundle_bin
bundle_bin/binman --help # run it directly
bundle exec rake -T # packaging tasks
-------------------------------------------------------------------------------
-Usage
-------------------------------------------------------------------------------
+## Usage
### At the command line
binman --help
-### In your bin/ scripts
+### Inside a Ruby script
-Add the following lines to your bin/ script and you've got `--help` options!
+ #!/usr/bin/env ruby
+ # your program's manual page goes here
require 'binman'
- BinMan.help # show man page and exit if ARGV has -h or --help
-Or, if you're on a diet:
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ BinMan.help
- require 'binman'
- BinMan.show # just show the man page; no fancy extras, please!
+ # OPTION 2: show manual unconditionally
+ BinMan.show
-See the [API documentation][binman-api] for more delicious recipes.
+You can also specify your program's source file encoding above the manual:
+ #!/usr/bin/env ruby
+ # -*- coding: utf-8 -*-
+ # your program's manual page goes here
+
+You can also write the manual as a multi-line Ruby comment:
+
+ #!/usr/bin/env ruby
+ =begin
+ your program's manual page goes here
+ =end
+
+You can also specify your program's source file encoding above the manual:
+
+ #!/usr/bin/env ruby
+ # -*- coding: utf-8 -*-
+ =begin
+ your program's manual page goes here
+ =end
+
+See the [API documentation][binman-api] for even more possibilities!
+
+### Inside a shell script
+
+ #!/usr/bin/sh
+ # your program's manual page goes here
+
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ binman help "$0" "$@" && exit
+
+ # OPTION 2: show manual unconditionally
+ binman show "$0"
+
+### Inside a Perl script
+
+ #!/usr/bin/env perl
+ # your program's manual page goes here
+
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ system('binman', 'help', __FILE__, @ARGV) == 0 and exit;
+
+ # OPTION 2: show manual unconditionally
+ system('binman', 'show', __FILE__);
+
+You can also write the manual as a multi-line Ruby comment after `__END__`:
+
+ #!/usr/bin/env perl
+ print "your program's code goes here";
+ __END__
+ =begin
+ your program's manual page goes here
+ =end
+
+### Inside a Python script
+
+ #!/usr/bin/env python
+ # your program's manual page goes here
+
+ import sys, subprocess
+
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ subprocess.call(['binman', 'help', __file__] + sys.argv) == 0 and sys.exit()
+
+ # OPTION 2: show manual unconditionally
+ subprocess.call(['binman', 'show', __file__])
+
+You can also specify your program's source file encoding above the manual:
+
+ #!/usr/bin/env python
+ # -*- coding: utf-8 -*-
+ # your program's manual page goes here
+
+You can also write the manual as a multi-line Ruby comment inside a docstring:
+
+ #!/usr/bin/env python
+ """
+ =begin
+ your program's manual page goes here
+ =end
+ """
+
+You can also specify your program's source file encoding above the manual:
+
+ #!/usr/bin/env python
+ # -*- coding: utf-8 -*-
+ """
+ =begin
+ your program's manual page goes here
+ =end
+ """
+
+### Inside an AWK script
+
+The technique for determining current AWK script file name [comes from here](
+http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html
+).
+
+ #!/usr/bin/awk -f
+ # your program's manual page goes here
+
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
+ if(system("binman help" c) == 0){ exit }}
+
+ # OPTION 2: show manual unconditionally
+ BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); sub("\0.*","",c);
+ system("binman show" c)}
+
+### Inside a Tcl script
+
+ #!/usr/bin/env tclsh
+ # your program's manual page goes here
+
+ # OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ if {![catch {exec -- >/dev/tty binman help $argv0 {*}$argv}]} {exit}
+
+ # OPTION 2: show manual unconditionally
+ exec >/dev/tty binman show $argv0
+
+You can also write the manual as a multi-line Ruby comment inside an `if 0`:
+
+ #!/usr/bin/env tclsh
+ if 0 {
+ =begin
+ your program's manual page goes here
+ =end
+ }
+
+### Inside a Node.js script
+
+ /*
+ =begin
+ your program's manual page goes here
+ =end
+ */
+
+ var exec = require('child_process').exec;
+
+ // OPTION 1: show manual and exit if ARGV has -h or --help except after --
+ exec(['>/dev/tty', 'binman', 'help', __filename].concat(process.argv).
+ join(' '), function(error){ if (error === null){ process.exit(); } });
+
+ // OPTION 2: show manual unconditionally
+ exec(['>/dev/tty', 'binman', 'show', __filename].join(' '));
+
+## Packaging
+
### Pre-building man pages
Add the following lines to your gemspec:
- s.files += Dir["man/**/*"]
+ s.files += Dir['man/**/*']
s.add_development_dependency 'md2man', '~> 1'
Add the following line to your Rakefile:
require 'binman/rakefile'
-You now have a `rake binman` task that pre-builds UNIX man page files for your
-`bin/` scripts into a `man/` directory so that your end-users do not need
-[md2man] installed in order to view the man pages you've embedded therein!
+You now have a `rake binman` task that pre-builds UNIX manual page files for
+your `bin/` scripts into a `man/` directory so that your end-users do not need
+[md2man] installed in order to view the manual pages you've embedded therein!
If you're using Bundler, this task also hooks into its gem packaging tasks and
-ensures that your UNIX man page files are pre-built and included in your gem:
+ensures that your UNIX manual pages are pre-built and packaged into your gem:
bundle exec rake build
gem spec pkg/*.gem | fgrep man/man
-------------------------------------------------------------------------------
-License
-------------------------------------------------------------------------------
+## License
Released under the ISC license. See the LICENSE file for details.
+
+[binman]: https://github.com/sunaku/binman
+[binman-api]: http://rubydoc.info/gems/binman/frames
+[binman-bin]: https://raw.github.com/sunaku/binman/master/bin/binman
+[md2man]: https://github.com/sunaku/md2man