md2man 1.0.2 → 1.1.0

data/HISTORY.markdown

@@ -1,54 +1,75 @@
+------------------------------------------------------------------------------
+Version 1.1.0 (2012-02-02)
+------------------------------------------------------------------------------
+
+Improvements:
+
+  * Add `Md2Man::Document` module for programmatic processing of
+    cross-references to other UNIX manual pages within Redcarpet.
+
+Housekeeping:
+
+  * README: not all systems support `man -l` option.
+
+  * gemspec: upgrade to redcarpet 2.1.0.
+
+  * bundler suggests moving all dev deps into gemspec.
+
+  * README: fix installation commands for development.
+
+  * README: simplify project slogan to be more memorable.
+
 ------------------------------------------------------------------------------
 Version 1.0.2 (2012-01-09)
 ------------------------------------------------------------------------------
 
-External changes:
+Corrections:
 
-* Blockquote's leading paragraph regexp was not anchored.
+  * Blockquote's leading paragraph regexp was not anchored.
 
-* Added example input file from the Linux Man Page Howto.
+  * Freezing internal constants prevents monkey patching.
 
-Internal changes:
+Housekeeping:
 
-* Upgraded to Binman 3 for better interoperability with Bundler.
+  * Upgraded to Binman 3 for better interoperability with Bundler.
 
-* Freezing internal constants prevents monkeypatching.
+  * Added example input file from the Linux Man Page Howto.
 
-* Forgot to change project slogan in the gem package.
+  * Forgot to change project slogan in the gem package.
 
 ------------------------------------------------------------------------------
 Version 1.0.1 (2011-12-06)
 ------------------------------------------------------------------------------
 
-Breaking changes:
+Divergences:
 
-* Renamed the project from "redcarpet-manpage" to "md2man".
+  * Renamed the project from "redcarpet-manpage" to "md2man".
 
-  * `RedcarpetManpage::Renderer` is now `Md2Man::Engine`.
+    * `RedcarpetManpage::Renderer` is now `Md2Man::Engine`.
 
-  * `RedcarpetManpage::RENDERER` is now `Md2Man::ENGINE`.
+    * `RedcarpetManpage::RENDERER` is now `Md2Man::ENGINE`.
 
-* Tagged paragraphs no longer require the first line to begin with italic or
-  bold styling.  All that matters is that the subsequent lines are indented.
+  * Tagged paragraphs no longer require the first line to begin with italic or
+    bold styling.  All that matters is that the subsequent lines are indented.
 
-External changes:
+Improvements:
 
-* Added md2man(1) executable for command-line usage.
+  * Added md2man(1) executable for command-line usage.
 
-* Added support for all HTML 4.0 and XHTML 1.0 entities.
+  * Added support for all HTML 4.0 and XHTML 1.0 entities.
 
-* Added support for tables, horizontal rules, and more.
+  * Added support for tables, horizontal rules, and more.
 
-* Added `Md2Man::Roff` mixin for advanced Redcarpet2 usage.
+  * Added `Md2Man::Roff` mixin for advanced Redcarpet2 usage.
 
-* Improved README with some new and revised documentation.
+  * Improved README with some new and revised documentation.
 
-Internal changes:
+Housekeeping:
 
-* Rewrote entire Markdown to Roff conversion from scratch while doing TDD.
+  * Rewrote entire Markdown to Roff conversion from scratch while doing TDD.
 
 ------------------------------------------------------------------------------
 Version 0.0.1 (2011-10-13)
 ------------------------------------------------------------------------------
 
-* First release! Happy birthday! Woohoo! :-)
+First release! Happy birthday! Woohoo! :-)

data/README.markdown

@@ -1,4 +1,4 @@
-md2man - write UNIX man pages in Markdown
+md2man - markdown to manpage
 ==============================================================================
 
 md2man is a Ruby library and command-line program that converts [Markdown]
@@ -15,7 +15,7 @@ Demonstration
 
 Try converting [this example Markdown file][example] into a UNIX man page:
 
-    md2man EXAMPLE.markdown | man -l -
+    md2man EXAMPLE.markdown > EXAMPLE.man && man ./EXAMPLE.man
 
 ![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
 
@@ -23,27 +23,25 @@ Try converting [this example Markdown file][example] into a UNIX man page:
 Installation
 ------------------------------------------------------------------------------
 
-As a Ruby gem:
-
     gem install md2man
 
-As a Git clone:
+### Development
 
     git clone git://github.com/sunaku/md2man
     cd md2man
-    bundle install
+    bundle install --binstubs=bundle_bin
+    bundle_bin/md2man --help  # run it directly
+    bundle exec rake -T       # packaging tasks
 
 ------------------------------------------------------------------------------
-Command Usage
+Usage
 ------------------------------------------------------------------------------
 
-Read the manual page:
+### At the command line
 
     md2man --help
 
-------------------------------------------------------------------------------
-Library Usage
-------------------------------------------------------------------------------
+### In your Ruby scripts
 
 Use the default renderer:
 
@@ -80,7 +78,7 @@ Mix-in your own renderer:
     your_roff_output = engine.render(your_markdown_input)
 
 ------------------------------------------------------------------------------
-Document Format
+Document format
 ------------------------------------------------------------------------------
 
 md2man attaches the following additional semantics to its [Markdown] input:
@@ -97,7 +95,7 @@ md2man attaches the following additional semantics to its [Markdown] input:
     are unindented accordingly before emission as `.TP` in the [Roff] output.
 
 ------------------------------------------------------------------------------
-Limitations
+Known issues
 ------------------------------------------------------------------------------
 
 At present, md2man does not translate the following [Redcarpet2] node types:

data/bin/md2man

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin
 
-MD2MAN 1 "2012-01-09" "1.0.2"
+MD2MAN 1 "2012-02-02" "1.1.0"
 =============================
 
 NAME

data/lib/md2man/document.rb

@@ -0,0 +1,14 @@
+module Md2Man
+module Document
+
+  def postprocess document
+    # encode references to other manual pages
+    document.gsub(/(\S+)\(([1-9nol])\)([[:punct:]]?\s*)/){ reference $1,$2,$3 }
+  end
+
+  def reference page, section, addendum
+    warn "md2man/document: reference not implemented: #{page}(#{section})"
+  end
+
+end
+end

data/lib/md2man/roff.rb

@@ -1,6 +1,10 @@
+require 'md2man/document'
+
 module Md2Man
 module Roff
 
+  include Document
+
   #---------------------------------------------------------------------------
   # document-level processing
   #---------------------------------------------------------------------------
@@ -12,14 +16,11 @@ module Roff
   end
 
   def postprocess document
-    document.strip.
+    super.strip.
 
     # ensure that spaces after URLs appear properly
     gsub(/(?<=^\.[UM]E) \s/, "\n").
 
-    # encode references to other man pages as "hyperlinks"
-    gsub(/(\S+)(\([1-9nol]\)[[:punct:]]?\s*)/, "\n.BR \\1 \\2\n").
-
     # squeeze blank lines to prevent double-spaced output
     gsub(/^\n/, '')
   end
@@ -130,6 +131,10 @@ module Roff
   # span-level processing
   #---------------------------------------------------------------------------
 
+  def reference page, section, addendum
+    "\n.BR #{page} (#{section})#{addendum}\n"
+  end
+
   def linebreak
     "\n.br\n"
   end

data/lib/md2man/version.rb

@@ -1,3 +1,3 @@
 module Md2Man
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/man/man1/md2man.1

@@ -1,4 +1,4 @@
-.TH MD2MAN 1 "2012\-01\-09" "1.0.2"
+.TH MD2MAN 1 "2012\-02\-02" "1.1.0"
 .SH NAME
 .PP
 md2man \- convert 
@@ -76,4 +76,4 @@ Display this help manual using
 .SH SEE ALSO
 .PP
 .BR markdown (7), 
-.BR roff (7)
+.BR roff (7)

data/md2man.gemspec

@@ -8,15 +8,16 @@ Gem::Specification.new do |s|
   s.authors,
   s.email         = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
   s.homepage      = "http://github.com/sunaku/md2man"
-  s.summary       = "write UNIX man pages in Markdown"
-  s.description   = nil
+  s.summary       = "Markdown to manpage."
+  s.description   = "Write UNIX man pages in Markdown."
 
   s.files         = `git ls-files`.split("\n") + 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"]
 
-  s.add_runtime_dependency "binman", "~> 3"
-  s.add_runtime_dependency "redcarpet", ">= 2.0.0b5", "< 3"
-  s.add_development_dependency "minitest", ">= 2.7.0", "< 3"
+  s.add_runtime_dependency 'binman', '~> 3'
+  s.add_runtime_dependency 'redcarpet', '>= 2.1.0', '< 3'
+  s.add_development_dependency 'minitest', '>= 2.7.0', '< 3'
+  s.add_development_dependency 'rake', '>= 0.9.2.2', '< 1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-10 00:00:00.000000000 Z
+date: 2012-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
-  requirement: &19172000 !ruby/object:Gem::Requirement
+  requirement: &24893480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,24 +21,24 @@ dependencies:
         version: '3'
   type: :runtime
   prerelease: false
-  version_requirements: *19172000
+  version_requirements: *24893480
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &19171460 !ruby/object:Gem::Requirement
+  requirement: &24892820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.0.0b5
+        version: 2.1.0
     - - <
       - !ruby/object:Gem::Version
         version: '3'
   type: :runtime
   prerelease: false
-  version_requirements: *19171460
+  version_requirements: *24892820
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &19170380 !ruby/object:Gem::Requirement
+  requirement: &24891000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -49,8 +49,22 @@ dependencies:
         version: '3'
   type: :development
   prerelease: false
-  version_requirements: *19170380
-description: ''
+  version_requirements: *24891000
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &24888980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+    - - <
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: *24888980
+description: Write UNIX man pages in Markdown.
 email:
 - sunaku@gmail.com
 executables:
@@ -67,6 +81,7 @@ files:
 - Rakefile
 - bin/md2man
 - lib/md2man.rb
+- lib/md2man/document.rb
 - lib/md2man/engine.rb
 - lib/md2man/roff.rb
 - lib/md2man/version.rb
@@ -86,19 +101,24 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -102355908338846194
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -102355908338846194
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: write UNIX man pages in Markdown
+summary: Markdown to manpage.
 test_files:
 - test/md2man/roff_test.rb
 - test/test_helper.rb
-has_rdoc: