md2man 1.1.0 → 1.2.0

data/HISTORY.markdown

@@ -1,13 +1,27 @@
-------------------------------------------------------------------------------
-Version 1.1.0 (2012-02-02)
-------------------------------------------------------------------------------
+## Version 1.2.0 (2012-02-06)
 
-Improvements:
+Minor:
+
+  * The `Md2Man::Document` module now handles paragraph() nodes and dispatches
+    their content accordingly to hook methods for indented, tagged, and normal
+    paragraphs.  A Redcarpet markdown parser need only include that module and
+    implement those hook methods in order to benefit from md2man's extensions
+    to markdown syntax programmatically.
+
+Other:
+
+  * README: mention features; revise markdown; cleanup.
+
+  * LICENSE: @tanoku created initial Manpage renderer.
+
+## Version 1.1.0 (2012-02-02)
+
+Minor:
 
   * Add `Md2Man::Document` module for programmatic processing of
     cross-references to other UNIX manual pages within Redcarpet.
 
-Housekeeping:
+Other:
 
   * README: not all systems support `man -l` option.
 
@@ -19,17 +33,15 @@ Housekeeping:
 
   * README: simplify project slogan to be more memorable.
 
-------------------------------------------------------------------------------
-Version 1.0.2 (2012-01-09)
-------------------------------------------------------------------------------
+## Version 1.0.2 (2012-01-09)
 
-Corrections:
+Patch:
 
   * Blockquote's leading paragraph regexp was not anchored.
 
   * Freezing internal constants prevents monkey patching.
 
-Housekeeping:
+Other:
 
   * Upgraded to Binman 3 for better interoperability with Bundler.
 
@@ -37,11 +49,9 @@ Housekeeping:
 
   * Forgot to change project slogan in the gem package.
 
-------------------------------------------------------------------------------
-Version 1.0.1 (2011-12-06)
-------------------------------------------------------------------------------
+## Version 1.0.1 (2011-12-06)
 
-Divergences:
+Major:
 
   * Renamed the project from "redcarpet-manpage" to "md2man".
 
@@ -52,7 +62,7 @@ Divergences:
   * 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.
 
-Improvements:
+Minor:
 
   * Added md2man(1) executable for command-line usage.
 
@@ -64,12 +74,10 @@ Improvements:
 
   * Improved README with some new and revised documentation.
 
-Housekeeping:
+Other:
 
   * Rewrote entire Markdown to Roff conversion from scratch while doing TDD.
 
-------------------------------------------------------------------------------
-Version 0.0.1 (2011-10-13)
-------------------------------------------------------------------------------
+## Version 0.0.1 (2011-10-13)
 
 First release! Happy birthday! Woohoo! :-)

data/LICENSE

@@ -1,6 +1,7 @@
 (the ISC license)
 
 Copyright 2011 Suraj N. Kurapati <sunaku@gmail.com>
+Thanks to 2011 Vicent Marti <tanoku@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

data/README.markdown

@@ -1,27 +1,40 @@
-md2man - markdown to manpage
-==============================================================================
+# md2man - markdown to manpage
 
 md2man is a Ruby library and command-line program that converts [Markdown]
-documents into UNIX man pages (really [Roff] documents) using [Redcarpet2].
+documents into UNIX manual pages (really [Roff] documents) using [Redcarpet].
 
-[Roff]: http://troff.org
-[Markdown]: http://daringfireball.net/projects/markdown/
-[Redcarpet2]: https://github.com/tanoku/redcarpet
-[example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
+## Features
+
+  * Formats tagged and indented paragraphs (see "document format" below).
 
-------------------------------------------------------------------------------
-Demonstration
-------------------------------------------------------------------------------
+  * Translates all HTML4 and XHTML1 entities into native Roff equivalents.
 
-Try converting [this example Markdown file][example] into a UNIX man page:
+  * Supports markdown extensions such as [PHP Markdown Extra tables][tables].
 
-    md2man EXAMPLE.markdown > EXAMPLE.man && man ./EXAMPLE.man
+  * Usable from the command line as a filter in a UNIX pipeline.
+
+### Demonstration
+
+Try converting [this example Markdown file][example] into a UNIX manual page:
+
+    md2man EXAMPLE.markdown > EXAMPLE.1
+    man EXAMPLE.1
 
 ![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
 
-------------------------------------------------------------------------------
-Installation
-------------------------------------------------------------------------------
+### Limitations
+
+At present, md2man does not translate the following [Redcarpet] node types:
+
+  * `block_html`
+  * `strikethrough`
+  * `superscript`
+  * `image`
+  * `raw_html`
+
+It issues a warning when it encounters these instead.  Patches are welcome!
+
+## Installation
 
     gem install md2man
 
@@ -33,15 +46,13 @@ Installation
     bundle_bin/md2man --help  # run it directly
     bundle exec rake -T       # packaging tasks
 
-------------------------------------------------------------------------------
-Usage
-------------------------------------------------------------------------------
+## Usage
 
 ### At the command line
 
     md2man --help
 
-### In your Ruby scripts
+### Inside a Ruby script
 
 Use the default renderer:
 
@@ -77,14 +88,10 @@ Mix-in your own renderer:
     engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
     your_roff_output = engine.render(your_markdown_input)
 
-------------------------------------------------------------------------------
-Document format
-------------------------------------------------------------------------------
-
-md2man attaches the following additional semantics to its [Markdown] input:
+### Document format
 
-  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
-    in the [Roff] output, specifying the UNIX man page's header and footer.
+md2man extends [Markdown] syntax in the following ways, as provisioned in the
+`Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
 
   * Paragraphs whose lines are all uniformly indented by two spaces are
     considered to be "indented paragraphs".  They are unindented accordingly
@@ -94,22 +101,17 @@ md2man attaches the following additional semantics to its [Markdown] input:
     indented by two spaces are considered to be a "tagged paragraphs".  They
     are unindented accordingly before emission as `.TP` in the [Roff] output.
 
-------------------------------------------------------------------------------
-Known issues
-------------------------------------------------------------------------------
-
-At present, md2man does not translate the following [Redcarpet2] node types:
-
-  * `block_html`
-  * `strikethrough`
-  * `superscript`
-  * `image`
-  * `raw_html`
+md2man extends [Markdown] semantics in the following ways:
 
-It issues a warning when it encounters these instead.  Patches are welcome!
+  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
+    in the [Roff] output, defining the UNIX manual page's header and footer.
 
-------------------------------------------------------------------------------
-License
-------------------------------------------------------------------------------
+## License
 
 Released under the ISC license.  See the LICENSE file for details.
+
+[Roff]: http://troff.org
+[Markdown]: http://daringfireball.net/projects/markdown/
+[Redcarpet]: https://github.com/tanoku/redcarpet
+[example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
+[tables]: http://michelf.com/projects/php-markdown/extra/#table

data/bin/md2man

@@ -1,32 +1,26 @@
 #!/usr/bin/env ruby
-=begin
+=begin =======================================================================
 
-MD2MAN 1 "2012-02-02" "1.1.0"
-=============================
+# MD2MAN 1 2012-02-06 1.2.0
 
-NAME
-----
+## NAME
 
 md2man - convert markdown(7) into roff(7)
 
-SYNOPSIS
---------
+## SYNOPSIS
 
 `md2man` [*OPTION*]... [*FILE*]
 
-DESCRIPTION
------------
+## DESCRIPTION
 
 [md2man] converts markdown(7) input from the given *FILE* into roff(7) using
-[Redcarpet2] and then prints the result to the standard output stream.  If
+[Redcarpet] and then prints the result to the standard output stream.  If
 *FILE* is not given, then the standard input stream is read in its place.
 
-### Document Format
+### Document format
 
-The following additional semantics are attached to markdown(7):
-
-  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
-    in the roff(7) output, specifying the UNIX man page's header and footer.
+md2man extends markdown(7) syntax in the following ways, as provisioned in the
+`Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
 
   * Paragraphs whose lines are all uniformly indented by two spaces are
     considered to be "indented paragraphs".  They are unindented accordingly
@@ -36,30 +30,33 @@ The following additional semantics are attached to markdown(7):
     indented by two spaces are considered to be a "tagged paragraphs".  They
     are unindented accordingly before emission as `.TP` in the roff(7) output.
 
-### Markdown Extensions
+md2man extends markdown(7) semantics in the following ways:
+
+  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
+    in the roff(7) output, defining the UNIX manual page's header and footer.
+
+### Markdown extensions
 
-The following [Redcarpet2] extensions for markdown(7) are enabled:
+The following [Redcarpet] extensions are enabled while processing markdown(7):
 
-* tables
-* autolink
-* superscript
-* strikethrough
-* no_intra_emphasis
-* fenced_code_blocks
+  * tables
+  * autolink
+  * superscript
+  * strikethrough
+  * no_intra_emphasis
+  * fenced_code_blocks
 
-OPTIONS
--------
+## OPTIONS
 
 `-h`, `--help`
-  Display this help manual using man(1).
+  Show this help manual.
 
-SEE ALSO
---------
+## SEE ALSO
 
 markdown(7), roff(7)
 
 [md2man]: https://github.com/sunaku/md2man
-[Redcarpet2]: https://github.com/tanoku/redcarpet
+[Redcarpet]: https://github.com/tanoku/redcarpet
 
 =end =========================================================================
 

data/lib/md2man/document.rb

@@ -10,5 +10,36 @@ module Document
     warn "md2man/document: reference not implemented: #{page}(#{section})"
   end
 
+  PARAGRAPH_INDENT = /^\s*$|^  (?=\S)/
+
+  def paragraph text
+    head, *body = text.lines.to_a
+    head_indented = head =~ PARAGRAPH_INDENT
+    body_indented = !body.empty? && body.all? {|s| s =~ PARAGRAPH_INDENT }
+
+    if head_indented || body_indented
+      text = text.gsub(PARAGRAPH_INDENT, '')
+      if head_indented && body_indented
+        indented_paragraph text
+      else
+        tagged_paragraph text
+      end
+    else
+      normal_paragraph text.chomp
+    end
+  end
+
+  def indented_paragraph text
+    warn "md2man/document: indented_paragraph not implemented: #{text.inspect}"
+  end
+
+  def tagged_paragraph text
+    warn "md2man/document: tagged_paragraph not implemented: #{text.inspect}"
+  end
+
+  def normal_paragraph text
+    warn "md2man/document: normal_paragraph not implemented: #{text.inspect}"
+  end
+
 end
 end

data/lib/md2man/roff.rb

@@ -29,22 +29,16 @@ module Roff
   # block-level processing
   #---------------------------------------------------------------------------
 
-  PARAGRAPH_INDENT = /^\s*$|^  (?=\S)/
-
-  def paragraph text
-    head, *body = text.lines.to_a
-    head_indented = head =~ PARAGRAPH_INDENT
-    body_indented = !body.empty? && body.all? {|s| s =~ PARAGRAPH_INDENT }
+  def indented_paragraph text
+    "\n.IP\n#{text}\n"
+  end
 
-    if head_indented || body_indented
-      macro = if head_indented && body_indented then :IP else :TP end
-      text.gsub! PARAGRAPH_INDENT, ''
-    else
-      macro = :PP
-      text.chomp!
-    end
+  def tagged_paragraph text
+    "\n.TP\n#{text}\n"
+  end
 
-    "\n.#{macro}\n#{text}\n"
+  def normal_paragraph text
+    "\n.PP\n#{text}\n"
   end
 
   def block_code code, language

data/lib/md2man/version.rb

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

data/man/man1/md2man.1

@@ -1,4 +1,4 @@
-.TH MD2MAN 1 "2012\-02\-02" "1.1.0"
+.TH MD2MAN 1 2012\-02\-06 1.2.0
 .SH NAME
 .PP
 md2man \- convert 
@@ -18,22 +18,19 @@ converts
 input from the given \fIFILE\fP into 
 .BR roff (7) 
 using
-Redcarpet2
+Redcarpet
 .UR https://github.com/tanoku/redcarpet
 .UE
 and then prints the result to the standard output stream.  If
 \fIFILE\fP is not given, then the standard input stream is read in its place.
-.SS Document Format
+.SS Document format
 .PP
-The following additional semantics are attached to 
-.BR markdown (7):
+md2man extends 
+.BR markdown (7) 
+syntax in the following ways, as provisioned in the
+\fB\fCMd2Man::Document\fR module and defined in its derivative \fB\fCMd2Man::Roff\fR module:
 .RS
 .IP \(bu 2
-There can be at most one top\-level heading (H1).  It is emitted as \fB\fC.TH\fR
-in the 
-.BR roff (7) 
-output, specifying the UNIX man page's header and footer.
-.IP \(bu 2
 Paragraphs whose lines are all uniformly indented by two spaces are
 considered to be "indented paragraphs".  They are unindented accordingly
 before emission as \fB\fC.IP\fR in the 
@@ -46,14 +43,24 @@ are unindented accordingly before emission as \fB\fC.TP\fR in the
 .BR roff (7) 
 output.
 .RE
-.SS Markdown Extensions
 .PP
-The following Redcarpet2
+md2man extends 
+.BR markdown (7) 
+semantics in the following ways:
+.RS
+.IP \(bu 2
+There can be at most one top\-level heading (H1).  It is emitted as \fB\fC.TH\fR
+in the 
+.BR roff (7) 
+output, defining the UNIX manual page's header and footer.
+.RE
+.SS Markdown extensions
+.PP
+The following Redcarpet
 .UR https://github.com/tanoku/redcarpet
 .UE
-extensions for 
-.BR markdown (7) 
-are enabled:
+extensions are enabled while processing 
+.BR markdown (7):
 .RS
 .IP \(bu 2
 tables
@@ -71,8 +78,7 @@ fenced_code_blocks
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
-Display this help manual using 
-.BR man (1).
+Show this help manual.
 .SH SEE ALSO
 .PP
 .BR markdown (7), 

data/md2man.gemspec

@@ -1,20 +1,20 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "md2man/version"
+$:.push File.expand_path('../lib', __FILE__)
+require 'md2man/version'
 
 Gem::Specification.new do |s|
-  s.name          = "md2man"
+  s.name          = 'md2man'
   s.version       = Md2Man::VERSION
   s.authors,
   s.email         = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
-  s.homepage      = "http://github.com/sunaku/md2man"
-  s.summary       = "Markdown to manpage."
-  s.description   = "Write UNIX man pages in Markdown."
+  s.homepage      = 'http://github.com/sunaku/md2man'
+  s.summary       = 'markdown to manpage'
+  s.description   = 'Converts markdown documents into UNIX manual pages.'
 
-  s.files         = `git ls-files`.split("\n") + Dir["man/**/*"]
+  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.require_paths = ['lib']
 
   s.add_runtime_dependency 'binman', '~> 3'
   s.add_runtime_dependency 'redcarpet', '>= 2.1.0', '< 3'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-03 00:00:00.000000000 Z
+date: 2012-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
-  requirement: &24893480 !ruby/object:Gem::Requirement
+  requirement: &10700940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3'
   type: :runtime
   prerelease: false
-  version_requirements: *24893480
+  version_requirements: *10700940
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &24892820 !ruby/object:Gem::Requirement
+  requirement: &10729140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -35,10 +35,10 @@ dependencies:
         version: '3'
   type: :runtime
   prerelease: false
-  version_requirements: *24892820
+  version_requirements: *10729140
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &24891000 !ruby/object:Gem::Requirement
+  requirement: &10749980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -49,10 +49,10 @@ dependencies:
         version: '3'
   type: :development
   prerelease: false
-  version_requirements: *24891000
+  version_requirements: *10749980
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &24888980 !ruby/object:Gem::Requirement
+  requirement: &10742800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -63,8 +63,8 @@ dependencies:
         version: '1'
   type: :development
   prerelease: false
-  version_requirements: *24888980
-description: Write UNIX man pages in Markdown.
+  version_requirements: *10742800
+description: Converts markdown documents into UNIX manual pages.
 email:
 - sunaku@gmail.com
 executables:
@@ -103,7 +103,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -102355908338846194
+      hash: -3638600068202015028
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -112,13 +112,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -102355908338846194
+      hash: -3638600068202015028
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: Markdown to manpage.
+summary: markdown to manpage
 test_files:
 - test/md2man/roff_test.rb
 - test/test_helper.rb