binman 0.0.1 → 0.1.1

data/HISTORY.markdown

@@ -1,3 +1,28 @@
+------------------------------------------------------------------------------
+Version 0.1.1 (2011-10-13)
+------------------------------------------------------------------------------
+
+New features:
+
+* `BinMan.read()` now supports embedded document (=begin/=end) comments also.
+  See binman(1) for the new, complete description of leading comment headers.
+
+Bug fixes:
+
+* Ignore encoding comment line after shebang line.
+
+* roff: fix first paragraphs inside list items.
+
+Housekeeping:
+
+* gemspec: build man page files before building gem.
+
+* binman: raise error and suggest --help option.
+
+* README: add link to example of binman markdown.
+
+* README: add obligatory screenshot! >:-)
+
 ------------------------------------------------------------------------------
 Version 0.0.1 (2011-10-12)
 ------------------------------------------------------------------------------

data/README.markdown

@@ -4,8 +4,13 @@ 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).
 
+![Obligatory Screen-shot of binman(1) in action!](http://ompldr.org/vYXNlNg)
+
+Here is [an example bin/ script][binman-bin] to help get you started!
+
 [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
 [Redcarpet2]: https://github.com/tanoku/redcarpet
 
 ------------------------------------------------------------------------------
@@ -16,7 +21,7 @@ Features
 
 * Individual extraction, conversion, and display commands.
 
-* Implemented in less than 100 lines of pure Ruby code! :-)
+* Implemented in roughly 100 lines of pure Ruby code! :-)
 
 ------------------------------------------------------------------------------
 Prerequisites

data/bin/binman

@@ -1,67 +1,74 @@
 #!/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
-#
+# encoding: utf-8
+=begin
+
+BINMAN 1 "2011-10-13" "0.1.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.  It can extract
+their leading comment headers (defined below), convert them from markdown(7)
+into roff(7) using [Redcarpet2], and display them using man(1).
+
+### Leading Comment Headers
+
+1. A contiguous sequence of single-line comments starting at the
+   beginning of the file (after shebang and encoding comments plus
+   optional blank lines) and ending at the first single blank line.
+
+2. First embedded document delimited by `=begin` and `=end` lines.
+
+### 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 help manual 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
+
+=end =========================================================================
 
 require 'binman'
 BinMan.help
@@ -73,5 +80,5 @@ 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!
+else raise ArgumentError, 'bad command; try --help'
 end

data/binman.gemspec

@@ -2,6 +2,10 @@
 $:.push File.expand_path("../lib", __FILE__)
 require "binman/version"
 
+# pre-build man page files
+require 'binman/rake_tasks'
+Rake::Task[:binman].invoke
+
 Gem::Specification.new do |s|
   s.name        = "binman"
   s.version     = BinMan::VERSION

data/lib/binman.rb

@@ -4,11 +4,16 @@ 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).
+  # Returns content of leading comment header (which can be one of the
+  # following two choices) from given source (IO, file name, or string).
   #
-  # Comment markers and shebang line (if any) are removed from result.
+  # (1) A contiguous sequence of single-line comments starting at the
+  #     beginning of the file (after shebang and encoding comments plus
+  #     optional blank lines) and ending at the first single blank line.
+  #
+  # (2) First embedded document delimited by `=begin` and `=end` lines.
+  #
+  # Comment markers and shebang/encoding comments are omitted from result.
   #
   def read source=nil
     source = source.read if source.respond_to? :read
@@ -19,7 +24,17 @@ module BinMan
     source = File.read(source) if File.exist? source
 
     string = source.to_s
-    string.split(/^\s*$/, 2).first.sub(/\A#!.+$/, '').gsub(/^# ?/, '').strip
+
+    # strip shebang and encoding comments
+    [/\A#!.+$/, /\A#.*coding:.+$/].each do |comment|
+      string = $'.lstrip if string =~ comment
+    end
+
+    if string =~ /\A#/
+      string.split(/^\s*$/, 2).first.gsub(/^# ?/, '')
+    else
+      string[/^=begin\b.*?$(.*?)^=end\b.*?$/m, 1]
+    end.strip
   end
 
   ##

data/lib/binman/renderer.rb

@@ -29,6 +29,9 @@ module BinMan
         # squeeze blank lines to prevent double-spaced output
         gsub(/^\n/, '').
 
+        # first paragraphs inside list items
+        gsub(/^(\.IP.*)\n\.PP/, '\1').
+
         # 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').

data/lib/binman/version.rb

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

data/man/man1/binman.1

@@ -1,4 +1,4 @@
-.TH BINMAN 1 "2011-01-12" "0.0.1" "Ruby User Manuals"
+.TH BINMAN 1 "2011-10-13" "0.1.1" "Ruby User Manuals"
 .SH NAME
 .PP
 binman \- UNIX man pages for Ruby \fBbin/\fP scripts
@@ -7,18 +7,21 @@ binman \- UNIX man pages for Ruby \fBbin/\fP scripts
 \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 
+\fBbinman\fP \fIhttps://github.com/sunaku/binman\fP produces UNIX man pages for your Ruby \fBbin/\fP scripts.  It can extract
+their leading comment headers (defined below), convert them from 
+.BR markdown (7)
+into 
 .BR roff (7) 
-using \fBRedcarpet2\fP \fIhttps://github.com/tanoku/redcarpet\fP for
-display using 
+using \fBRedcarpet2\fP \fIhttps://github.com/tanoku/redcarpet\fP, and display them using 
 .BR man (1).
-.PP
-See for more information and resources.
+.SS Leading Comment Headers
+.nr step 0 1
+.IP \n+[step]
+A contiguous sequence of single-line comments starting at the
+beginning of the file (after shebang and encoding comments plus
+optional blank lines) and ending at the first single blank line.
+.IP \n+[step]
+First embedded document delimited by \fB=begin\fP and \fB=end\fP lines.
 .SS Markdown Processing Extensions
 .PP
 Although your leading comment headers are written in 
@@ -34,7 +37,7 @@ the subsequent two-space indented lines are the definition body.
 .SH OPTIONS
 .TP
 \fB-h\fP, \fB--help\fP
-Display this manual page using 
+Display this help manual using 
 .BR man (1).
 .SH COMMANDS
 .TP

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binman
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &14739920 !ruby/object:Gem::Requirement
+  requirement: &19851600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 2.0.0b5
   type: :runtime
   prerelease: false
-  version_requirements: *14739920
+  version_requirements: *19851600
 description: ''
 email:
 - sunaku@gmail.com