binman 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in binman.gemspec
+gemspec

data/HISTORY.markdown

@@ -0,0 +1,5 @@
+------------------------------------------------------------------------------
+Version 0.0.1 (2011-10-12)
+------------------------------------------------------------------------------
+
+* First release!  Happy birthday!  Woohoo!  :-)

data/LICENSE

@@ -0,0 +1,15 @@
+(the ISC license)
+
+Copyright 2011 Suraj N. Kurapati <sunaku@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.markdown

@@ -0,0 +1,83 @@
+binman - UNIX man pages for Ruby bin/ scripts
+==============================================================================
+
+[binman] produces UNIX man pages for your Ruby `bin/` scripts using
+markdown(7), roff(7), [Redcarpet2] for conversion thereof, and man(1).
+
+[binman]: https://github.com/sunaku/binman
+[binman-api]: http://rdoc.info/github/sunaku/binman
+[Redcarpet2]: https://github.com/tanoku/redcarpet
+
+------------------------------------------------------------------------------
+Features
+------------------------------------------------------------------------------
+
+* Includes both a Ruby library and a command-line client.
+
+* Individual extraction, conversion, and display commands.
+
+* Implemented in less than 100 lines of pure Ruby code! :-)
+
+------------------------------------------------------------------------------
+Prerequisites
+------------------------------------------------------------------------------
+
+* Ruby 1.9.2 or newer.  It might work with 1.8.7 but I haven't tried. :-P
+
+------------------------------------------------------------------------------
+Installation
+------------------------------------------------------------------------------
+
+As a Ruby gem:
+
+    gem install binman
+
+As a Git clone:
+
+    git clone git://github.com/sunaku/binman
+    cd binman
+    bundle install
+
+------------------------------------------------------------------------------
+Invocation
+------------------------------------------------------------------------------
+
+If installed as a Ruby gem:
+
+    binman
+
+If installed as a Git clone:
+
+    bundle exec ruby -Ilib bin/binman
+
+Just pass `--help` to see its man page.
+
+------------------------------------------------------------------------------
+Usage
+------------------------------------------------------------------------------
+
+### In your bin/ scripts
+
+Add the following lines to your bin/ script and you've got `--help` options!
+
+    require 'binman'
+    BinMan.help # show man page and exit if ARGV has -h or --help
+
+Or, if you're on a diet:
+
+    require 'binman'
+    BinMan.show # just show the man page; no fancy extras, please!
+
+See the [API documentation][binman-api] for more delicious recipes.
+
+### In your Rakefile
+
+Add the following line to your `Rakefile` and you've got a `binman` task!
+
+    require 'binman/rake_tasks'
+
+------------------------------------------------------------------------------
+License
+------------------------------------------------------------------------------
+
+Released under the ISC license.  See the LICENSE file for details.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+require "binman/rake_tasks"

data/bin/binman

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+#
+# BINMAN 1 "2011-10-12" "0.0.1" "Ruby User Manuals"
+# =================================================
+#
+# NAME
+# ----
+#
+# binman - UNIX man pages for Ruby `bin/` scripts
+#
+# SYNOPSIS
+# --------
+#
+# `binman` [*OPTION*]... *COMMAND*
+#
+# DESCRIPTION
+# -----------
+#
+# [binman] produces UNIX man pages for your Ruby `bin/` scripts by extracting
+# their leading comment header (a contiguous sequence of single-line comments
+# starting at beginning of file and ending at first single blank line) and
+# then converting them from markdown(7) to roff(7) using [Redcarpet2] for
+# display using man(1).
+#
+# See for more information and resources.
+#
+# ### Markdown Processing Extensions
+#
+# Although your leading comment headers are written in markdown(7), `binman`
+# introduces the following additional conventions to simplify common tasks:
+#
+# 1. Paragraphs beginning with bold/italic and followed by at least
+#    one two-space indented line are considered to be definitions.
+#    The first line of such a paragraph is the term being defined and
+#    the subsequent two-space indented lines are the definition body.
+#
+# OPTIONS
+# -------
+#
+# `-h`, `--help`
+#   Display this manual page using man(1).
+#
+# COMMANDS
+# --------
+#
+# `read` [*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.
+#
+# `show` [*FILE*]
+#   Use man(1) to display the roff(7) conversion of the leading comment header
+#   extracted from the given *FILE* or stdin.
+#
+# SEE ALSO
+# --------
+#
+# man(1), roff(7), markdown(7)
+#
+# [binman]: https://github.com/sunaku/binman
+# [Redcarpet2]: https://github.com/tanoku/redcarpet
+#
+
+require 'binman'
+BinMan.help
+
+command, file = ARGV
+file ||= 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 warn "binman: unknown command: #{command}"; exit!
+end

data/binman.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "binman/version"
+
+Gem::Specification.new do |s|
+  s.name        = "binman"
+  s.version     = BinMan::VERSION
+  s.authors,
+  s.email       = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
+  s.homepage    = "http://github.com/sunaku/binman"
+  s.summary     = "UNIX man pages for Ruby bin/ scripts"
+  s.description = nil
+
+  s.files         = `git ls-files`.split("\n").concat(Dir['man/**/*'])
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "redcarpet", ">= 2.0.0b5"
+end

data/lib/binman.rb

@@ -0,0 +1,61 @@
+require "binman/version"
+
+module BinMan
+  extend self
+
+  ##
+  # Returns content of leading comment header (a contiguous sequence of
+  # single-line comments starting at beginning of file and ending at first
+  # single blank line) from given source (IO, file name, or string).
+  #
+  # Comment markers and shebang line (if any) are removed 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
+    string.split(/^\s*$/, 2).first.sub(/\A#!.+$/, '').gsub(/^# ?/, '').strip
+  end
+
+  ##
+  # Converts given leading comment header (produced by #read) into roff(7).
+  #
+  def dump header
+    require 'binman/renderer'
+    RENDERER.render(header)
+  end
+
+  ##
+  # Shows leading comment header from given source as UNIX man page.
+  #
+  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)
+
+    header = read(source)
+
+    begin
+      roff = dump(header)
+      IO.popen('man -l -', 'w') {|man| man.puts roff }
+    rescue
+      puts header
+    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
+end

data/lib/binman/rake_tasks.rb

@@ -0,0 +1,18 @@
+require 'rake'
+
+path = 'man/man1'
+bins = FileList['bin/*']
+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))
+    File.open(man, 'w') {|f| f << roff }
+  end
+end
+
+
+desc 'Build UNIX man pages for bin/ scripts.'
+task :binman => mans
+directory path

data/lib/binman/renderer.rb

@@ -0,0 +1,55 @@
+require 'redcarpet'
+require 'redcarpet/render_man'
+
+module BinMan
+  class Renderer < Redcarpet::Render::ManPage
+    def normal_text text
+      text.gsub(/(?<=\W)-(?=\W)/, '\\-') if text
+    end
+
+    def paragraph(text)
+      "\n.PP\n#{text}\n"
+    end
+
+    alias codespan double_emphasis
+    alias triple_emphasis double_emphasis
+
+    def autolink link, link_type
+      emphasis link
+    end
+
+    def link link, title, content
+      "#{triple_emphasis content} #{emphasis link}"
+    end
+
+    DEFINITION_INDENT = '  ' # two spaces
+
+    def postprocess document
+      document.
+        # squeeze blank lines to prevent double-spaced output
+        gsub(/^\n/, '').
+
+        # paragraphs beginning with bold/italic and followed by
+        # at least one definition-indented line are definitions
+        gsub(/^\.PP(?=\n\\f.+\n#{DEFINITION_INDENT}\S)/, '.TP').
+
+        # make indented paragraphs occupy less space on screen:
+        # roff will fit the second line of the paragraph along
+        # side the first line if it has enough room to do so!
+        gsub(/^#{DEFINITION_INDENT}(?=\S)/, '').
+
+        # encode references to other man pages as "hyperlinks"
+        gsub(/(\w+)(\([1-9nol]\)[[:punct:]]?\s*)/, "\n.BR \\1 \\2\n").
+        # keep the SEE ALSO sequence of references in-line
+        gsub(/(?:^\.BR.+\n)+/m){ |sequence| sequence.squeeze("\n") }
+    end
+  end
+
+  RENDERER = Redcarpet::Markdown.new(Renderer,
+                                     #:tables => true,
+                                     :autolink => true,
+                                     #:superscript => true,
+                                     :no_intra_emphasis => true,
+                                     :fenced_code_blocks => true,
+                                     :space_after_headers => true)
+end

data/lib/binman/version.rb

@@ -0,0 +1,3 @@
+module BinMan
+  VERSION = "0.0.1"
+end

data/man/man1/binman.1

@@ -0,0 +1,61 @@
+.TH BINMAN 1 "2011-01-12" "0.0.1" "Ruby User Manuals"
+.SH NAME
+.PP
+binman \- UNIX man pages for Ruby \fBbin/\fP scripts
+.SH SYNOPSIS
+.PP
+\fBbinman\fP [\fIOPTION\fP]... \fICOMMAND\fP
+.SH DESCRIPTION
+.PP
+\fBbinman\fP \fIhttps://github.com/sunaku/binman\fP produces UNIX man pages for your Ruby \fBbin/\fP scripts by extracting
+their leading comment header (a contiguous sequence of single-line comments
+starting at beginning of file and ending at first single blank line) and
+then converting them from 
+.BR markdown (7) 
+to 
+.BR roff (7) 
+using \fBRedcarpet2\fP \fIhttps://github.com/tanoku/redcarpet\fP for
+display using 
+.BR man (1).
+.PP
+See for more information and resources.
+.SS Markdown Processing Extensions
+.PP
+Although your leading comment headers are written in 
+.BR markdown (7), 
+\fBbinman\fP
+introduces the following additional conventions to simplify common tasks:
+.nr step 0 1
+.IP \n+[step]
+Paragraphs beginning with bold/italic and followed by at least
+one two-space indented line are considered to be definitions.
+The first line of such a paragraph is the term being defined and
+the subsequent two-space indented lines are the definition body.
+.SH OPTIONS
+.TP
+\fB-h\fP, \fB--help\fP
+Display this manual page using 
+.BR man (1).
+.SH COMMANDS
+.TP
+\fBread\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.
+.TP
+\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.
+.SH SEE ALSO
+.PP
+.BR man (1), 
+.BR roff (7), 
+.BR markdown (7)

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: binman
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Suraj N. Kurapati
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &14739920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.0b5
+  type: :runtime
+  prerelease: false
+  version_requirements: *14739920
+description: ''
+email:
+- sunaku@gmail.com
+executables:
+- binman
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- HISTORY.markdown
+- LICENSE
+- README.markdown
+- Rakefile
+- bin/binman
+- binman.gemspec
+- lib/binman.rb
+- lib/binman/rake_tasks.rb
+- lib/binman/renderer.rb
+- lib/binman/version.rb
+- man/man1/binman.1
+homepage: http://github.com/sunaku/binman
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: UNIX man pages for Ruby bin/ scripts
+test_files: []