binman 0.1.2 → 1.0.0

data/HISTORY.markdown

@@ -1,3 +1,31 @@
+------------------------------------------------------------------------------
+Version 1.0.0 (2011-10-13)
+------------------------------------------------------------------------------
+
+Incompatible changes:
+
+* The `BinMan::dump()` method and corresponding `binman dump` command now
+  extract the leading comment header from their input before returning the
+  markdown to roff conversion thereof.
+
+* The `BinMan::read()` method and corresponding `binman read` command have
+  been renamed to `BinMan::load()` and `binman load` respectively.
+
+New features:
+
+* Added `BinMan::conv()` method and corresponding `binman conv` command to
+  encapsulate the markdown to roff conversion process.
+
+Bug fixes:
+
+* Pre-built man pages included alongside a `bin/` script were not displayed.
+  Instead, binman was (incorrectly) always trying to convert the leading
+  comment header from the `bin/` script into a UNIX man page for display.
+
+Housekeeping:
+
+* README: explain dev deps and `man/` dir packaging.
+
 ------------------------------------------------------------------------------
 Version 0.1.2 (2011-10-13)
 ------------------------------------------------------------------------------
@@ -10,6 +38,9 @@ Housekeeping:
 
 * Forgot to introduce leading comment headers in binman(1) man page.
 
+[Redcarpet2]: https://github.com/tanoku/redcarpet
+[redcarpet-manpage]: http://rdoc.info/github/sunaku/redcarpet-manpage
+
 ------------------------------------------------------------------------------
 Version 0.1.1 (2011-10-13)
 ------------------------------------------------------------------------------

data/README.markdown

@@ -33,10 +33,14 @@ Prerequisites
 Installation
 ------------------------------------------------------------------------------
 
-As a Ruby gem:
+As a Ruby gem (without markdown to roff converter):
 
     gem install binman
 
+As a Ruby gem (with extra cheese and everything please):
+
+    gem install binman --development
+
 As a Git clone:
 
     git clone git://github.com/sunaku/binman
@@ -81,6 +85,16 @@ Add the following line to your `Rakefile` and you've got a `binman` task!
 
     require 'binman/rake_tasks'
 
+It will pre-build UNIX man page files for your `bin/` scripts into a `man/`
+directory so that your end-users do not need the markdown to roff converter
+installed in order to view your man pages!  Just remember to add the `man/`
+directory's contents to your gemspec or release package:
+
+    Gem::Specification.new do |s|
+      # ... your stuff ...
+      s.files += Dir['man/**/*']
+    end
+
 ------------------------------------------------------------------------------
 License
 ------------------------------------------------------------------------------

data/bin/binman

@@ -2,7 +2,7 @@
 # encoding: utf-8
 =begin
 
-BINMAN 1 "2011-10-13" "0.1.2" "Ruby User Manuals"
+BINMAN 1 "2011-10-13" "1.0.0" "Ruby User Manuals"
 =================================================
 
 NAME
@@ -60,16 +60,20 @@ OPTIONS
 COMMANDS
 --------
 
-`read` [*FILE*]
-  Print the leading comment header extracted from the given *FILE* or stdin.
+`show` [*FILE*]
+  Use man(1) to display the roff(7) conversion of the leading comment header
+  extracted from the given *FILE* or STDIN.
+
+`load` [*FILE*]
+  Print the leading comment header extracted from the given *FILE* or STDIN.
 
 `dump` [*FILE*]
   Print the roff(7) conversion of the leading comment header extracted from
-  the given *FILE* or stdin.
+  the given *FILE* or STDIN.
 
-`show` [*FILE*]
-  Use man(1) to display the roff(7) conversion of the leading comment header
-  extracted from the given *FILE* or stdin.
+`conv` [*FILE*]
+  Print the roff(7) conversion of the markdown(7) document read from the given
+  *FILE* or STDIN.
 
 SEE ALSO
 --------
@@ -84,12 +88,15 @@ man(1), roff(7), markdown(7)
 require 'binman'
 BinMan.help
 
-command, file = ARGV
-file ||= STDIN
+command, source = ARGV
+source ||= STDIN
 
 case command
-when 'read' then puts BinMan.read(file)
-when 'dump' then puts BinMan.dump(BinMan.read(file))
-when 'show' then BinMan.show(file)
-else raise ArgumentError, 'bad command; try --help'
+when 'show'
+  BinMan.show source
+when 'load', 'dump', 'conv'
+  puts BinMan.send(command, source)
+else
+  warn 'bad command; try --help'
+  exit!
 end

data/lib/binman.rb

@@ -3,8 +3,7 @@ require "binman/version"
 module BinMan
   extend self
 
-  ##
-  # Returns content of leading comment header (which can be one of the
+  # Extracts content of leading comment header (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
@@ -15,51 +14,48 @@ module BinMan
   #
   # Comment markers and shebang/encoding comments are omitted from result.
   #
-  def read source=nil
-    source = source.read if source.respond_to? :read
-    source ||=
-      if first_caller = caller.find {|f| not f.start_with? __FILE__ }
-        first_caller.sub(/:\d+.*$/, '')
-      end
-    source = File.read(source) if File.exist? source
-
-    string = source.to_s
+  def load source=nil
+    header = read(source)
 
     # strip shebang and encoding comments
     [/\A#!.+$/, /\A#.*coding:.+$/].each do |comment|
-      string = $'.lstrip if string =~ comment
+      header = $'.lstrip if header =~ comment
     end
 
-    if string =~ /\A#/
-      string.split(/^\s*$/, 2).first.gsub(/^# ?/, '')
+    if header =~ /\A#/
+      header.split(/^\s*$/, 2).first.gsub(/^# ?/, '')
     else
-      string[/^=begin\b.*?$(.*?)^=end\b.*?$/m, 1]
+      header[/^=begin\b.*?$(.*?)^=end\b.*?$/m, 1]
     end.strip
   end
 
-  ##
-  # Converts given leading comment header (produced by #read) into roff(7).
-  #
-  def dump header
+  # Converts given markdown(7) source into roff(7).
+  def conv source=nil
+    header = read(source)
     require 'redcarpet-manpage'
     RedcarpetManpage::RENDERER.render(header)
   rescue LoadError
-    raise 'Run `gem install binman --development` to use dump().'
+    raise 'Run `gem install binman --development` to use BinMan::conv().'
   end
 
-  ##
-  # Shows leading comment header from given source as UNIX man page.
-  #
+  # Extracts leading comment header content from given
+  # source and returns the roff(7) conversion thereof.
+  def dump source=nil
+    conv load(source)
+  end
+
+  # Shows leading comment header from given source as UNIX man page if
+  # possible, else falls back to showing leading comment header as-is.
   def show source=nil
     # try showing existing man page files for given source
-    return if source and File.exist? source and
-      File.exist? man_path = File.expand_path('../../man', source) and
-      system 'man', '-M', man_path, '-a', File.basename(source)
+    return if file = find(source) and File.exist? file and
+      File.exist? man_path = File.expand_path('../../man', file) and
+      system 'man', '-M', man_path, '-a', File.basename(file)
 
-    header = read(source)
+    header = load(source)
 
     begin
-      roff = dump(header)
+      roff = conv(header)
       IO.popen('man -l -', 'w') {|man| man.puts roff }
     rescue => error
       warn "binman: #{error}"
@@ -67,13 +63,31 @@ module BinMan
     end
   end
 
-  ##
   # Shows leading comment header from given source as UNIX man page and exits.
-  #
   def help source=nil, argv=ARGV
     unless argv.grep(/^(-h|--help)$/).empty?
       show source
       exit
     end
   end
+
+private
+
+  # Returns contents of given source I/O, file name, or string.
+  def read source=nil
+    if source.respond_to? :read
+      source.read
+    elsif file = find(source) and File.exist? file
+      File.read file
+    else
+      source
+    end
+  end
+
+  # Resolves given source into first caller's file name if nil.
+  def find source=nil
+    source || if first_caller = caller.find {|f| not f.start_with? __FILE__ }
+      first_caller.sub(/:\d+.*$/, '')
+    end
+  end
 end

data/lib/binman/rake_tasks.rb

@@ -7,7 +7,7 @@ mans = bins.pathmap("#{path}/%n.1")
 bins.zip(mans).each do |bin, man|
   file man => [bin, path] do
     require 'binman'
-    roff = BinMan.dump(BinMan.read(bin))
+    roff = BinMan.dump(bin)
     File.open(man, 'w') {|f| f << roff }
   end
 end

data/lib/binman/version.rb

@@ -1,3 +1,3 @@
 module BinMan
-  VERSION = "0.1.2"
+  VERSION = "1.0.0"
 end

data/man/man1/binman.1

@@ -1,4 +1,4 @@
-.TH BINMAN 1 "2011-10-13" "0.1.2" "Ruby User Manuals"
+.TH BINMAN 1 "2011-10-13" "1.0.0" "Ruby User Manuals"
 .SH NAME
 .PP
 binman \- UNIX man pages for Ruby \fBbin/\fP scripts
@@ -55,22 +55,30 @@ Display this help manual using
 .BR man (1).
 .SH COMMANDS
 .TP
-\fBread\fP [\fIFILE\fP]
-Print the leading comment header extracted from the given \fIFILE\fP or stdin.
+\fBshow\fP [\fIFILE\fP]
+Use 
+.BR man (1) 
+to display the 
+.BR roff (7) 
+conversion of the leading comment header
+extracted from the given \fIFILE\fP or STDIN.
+.TP
+\fBload\fP [\fIFILE\fP]
+Print the leading comment header extracted from the given \fIFILE\fP or STDIN.
 .TP
 \fBdump\fP [\fIFILE\fP]
 Print the 
 .BR roff (7) 
 conversion of the leading comment header extracted from
-the given \fIFILE\fP or stdin.
+the given \fIFILE\fP or STDIN.
 .TP
-\fBshow\fP [\fIFILE\fP]
-Use 
-.BR man (1) 
-to display the 
+\fBconv\fP [\fIFILE\fP]
+Print the 
 .BR roff (7) 
-conversion of the leading comment header
-extracted from the given \fIFILE\fP or stdin.
+conversion of the 
+.BR markdown (7) 
+document read from the given
+\fIFILE\fP or STDIN.
 .SH SEE ALSO
 .PP
 .BR man (1), 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binman
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet-manpage
-  requirement: &21068040 !ruby/object:Gem::Requirement
+  requirement: &19205100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 0.0.1
   type: :development
   prerelease: false
-  version_requirements: *21068040
+  version_requirements: *19205100
 description: ''
 email:
 - sunaku@gmail.com