kramdown-man 0.1.3

data/.document

@@ -0,0 +1,4 @@
+- 
+ChangeLog.md
+LICENSE.txt
+man/kramdown-man.1.md

data/.gitignore

@@ -0,0 +1,2 @@
+doc/
+pkg/

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+before_install:
+  - gem install ffi rubygems-tasks rspec yard kramdown
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+script: rake spec

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --markup-provider kramdown --title "kramdown-man Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,20 @@
+### 0.1.3 / 2013-05-05
+
+* Initial release:
+  * Converts markdown to [roff]:
+    * Supports codespans, emphasis and strong fonts.
+    * Supports normal and tagged paragraphs.
+    * Supports bullet lists.
+    * Supports multi-paragraph list items and blockquotes.
+    * Supports horizontal rules.
+    * Supports converting `[bash](man:bash(1))` links into man page references.
+  * Provides Rake task for converting `man/*.md` into man pages.
+  * Uses the pure-Ruby [Kramdown][kramdown] markdown parser.
+  * Supports [Ruby] 1.8.x, 1.9.x, 2.0.x, [JRuby], [Rubinius].
+
+[kramdown]: http://kramdown.rubyforge.org/
+[roff]: http://en.wikipedia.org/wiki/Roff
+
+[Ruby]: http://www.ruby-lang.org/
+[JRuby]: http://jruby.org/
+[Rubinius]: http://rubini.us/

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# kramdown-man
+
+* [Homepage](https://github.com/postmodern/kramdown-man#readme)
+* [Issues](https://github.com/postmodern/kramdown-man/issues)
+* [Documentation](http://rubydoc.info/gems/kramdown-man/frames)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+[![Build Status](https://secure.travis-ci.org/postmodern/kramdown-man.png?branch=master)](https://travis-ci.org/postmodern/kramdown-man)
+
+## Description
+
+A [Kramdown][kramdown] convert for converting Markdown files into man pages.
+
+## Features
+
+* Converts markdown to [roff]:
+  * Supports codespans, emphasis and strong fonts.
+  * Supports normal and tagged paragraphs.
+  * Supports bullet lists.
+  * Supports multi-paragraph list items and blockquotes.
+  * Supports horizontal rules.
+  * Supports converting `[bash](man:bash(1))` links into man page references.
+* Provides Rake task for converting `man/*.md` into man pages.
+* Uses the pure-Ruby [Kramdown][kramdown] markdown parser.
+* Supports [Ruby] 1.8.x, 1.9.x, 2.0.x, [JRuby], [Rubinius].
+
+## Synopsis
+
+Render a man page from markdown:
+
+    $ kramdown-man <man/myprog.1.md >man/myprog.1
+
+## Examples
+
+Render a man page from a markdown file:
+
+    require 'kramdown/man'
+
+    doc = Kramdown::Document.new(File.read('man/kramdown-man.1.md'))
+    File.write('man/kramdown-man.1',doc.to_man)
+
+    system 'man', 'man/kramdown-man.1'
+
+Define a `man` and file tasks which render all `*.md` files within the
+`man/` directory:
+
+    require 'kramdown/man/task'
+    Kramdown::Man::Task.new
+
+## Syntax
+
+### Formatting
+
+    `code`
+
+`code`
+
+    *emphasis*
+
+*emphasis*
+
+    **strong**
+
+**strong**
+
+### Paragraphs
+
+    Normal paragraph.
+
+Normal paragraph.
+
+    `--tagged`
+      Text here.
+
+`--tagged`
+  Text here.
+
+### Links
+
+    [website](http://example.com/)
+
+[website](http://example.com/)
+
+    [bash](man:bash(1))
+
+[bash](man:bash(1))
+
+    Email <bob@example.com>
+
+Email <bob@example.com>
+
+### Lists
+
+    * one
+    * two
+    * three
+    
+      extra paragraph
+    
+
+* one
+* two
+* three
+
+  extra paragraph
+
+    1. one
+    2. two
+    3. three
+    
+       extra paragraph
+    
+1. one
+2. two
+3. three
+
+   extra paragraph
+
+### Horizontal Rule
+
+    -------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+
+### Blockquotes
+
+    > Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
+    >
+    > --Antoine de Saint-Exupéry
+
+> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
+>
+> --Antoine de Saint-Exupéry
+
+### Code Blocks
+
+        #include <stdio.h>
+    
+        int main()
+        {
+    	    printf("hello world\n");
+    	    return 0;
+        }
+
+    #include <stdio.h>
+
+    int main()
+    {
+	    printf("hello world\n");
+	    return 0;
+    }
+
+## Requirements
+
+* [kramdown] ~> 1.0
+
+## Install
+
+    $ gem install kramdown-man
+
+## Alternatives
+
+* [Redcarpet::Render::ManPage](http://rubydoc.info/gems/redcarpet/Redcarpet/Render/ManPage)
+* [ronn](https://github.com/rtomayko/ronn#readme)
+* [md2man](https://github.com/sunaku/md2man#readme)
+
+## Copyright
+
+Copyright (c) 2013 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[kramdown]: http://kramdown.rubyforge.org/
+[roff]: http://en.wikipedia.org/wiki/Roff
+
+[Ruby]: http://www.ruby-lang.org/
+[JRuby]: http://jruby.org/
+[Rubinius]: http://rubini.us/

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  gem 'rubygems-tasks', '~> 0.2'
+  require 'rubygems/tasks'
+
+  Gem::Tasks.new
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install rubygems-tasks` to install Gem::Tasks."
+end
+
+begin
+  gem 'rspec', '~> 2.4'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
+end
+
+task :test    => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.8'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end
+task :doc => :yard
+
+$LOAD_PATH.unshift(File.expand_path('lib'))
+
+require 'kramdown/man/tasks'
+Kramdown::Man::Tasks.new

data/bin/kramdown-man

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.expand_path('../lib',File.dirname(__FILE__))
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'kramdown'
+require 'kramdown/man'
+
+case ARGV[0]
+when '-h', '--help'
+  warn "usage: #{File.dirname($0)} <INPUT.md >OUTPUT"
+  exit
+end
+
+doc = Kramdown::Document.new(ARGF.read)
+puts doc.to_man

data/gemspec.yml

@@ -0,0 +1,15 @@
+name: kramdown-man
+summary: Converts markdown to man pages
+description: A Kramdown converter for converting Markdown files into man pages.
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/kramdown-man#readme
+
+dependencies:
+  kramdown: ~> 1.0
+
+development_dependencies:
+  rspec: ~> 2.4
+  rubygems-tasks: ~> 0.2
+  yard: ~> 0.8

data/kramdown-man.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'kramdown/man/version'
+                  Kramdown::Man::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/lib/kramdown/converter/man.rb

@@ -0,0 +1,439 @@
+# encoding: utf-8
+require 'kramdown/man/version'
+
+require 'kramdown/converter/base'
+
+module Kramdown
+  module Converter
+    #
+    # Converts markdown into a roff man-page.
+    #
+    class Man < Base
+
+      # Comment header
+      HEADER = [
+        ".\\\" Generated by kramdown-man #{::Kramdown::Man::VERSION}",
+        ".\\\" https://github.com/postmodern/kramdown-roff#readme"
+      ].join("\n")
+
+      # Typographic Symbols and their UTF8 chars
+      TYPOGRAPHIC_SYMS = {
+        :ndash       => "--",
+        :mdash       => "—",
+        :hellip      => "…",
+        :laquo       => "«",
+        :raquo       => "»",
+        :laquo_space => "«",
+        :raquo_space => "»"
+      }
+
+      # Smart Quotes and their UTF8 chars
+      SMART_QUOTES = {
+        :lsquo => "‘",
+        :rsquo => "’",
+        :ldquo => "“",
+        :rdquo => "”"
+      }
+
+      #
+      # Initializes the converter.
+      #
+      # @param [Kramdown::Element] root
+      #   The root of the markdown document.
+      #
+      # @param [Hash] options
+      #   Markdown options.
+      #
+      def initialize(root,options)
+        super(root,options)
+
+        @ol_index = 0
+      end
+
+      #
+      # Converts the markdown document into a man-page.
+      #
+      # @param [Kramdown::Element] root
+      #   The root of a markdown document.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert(root)
+        "#{HEADER}\n#{convert_root(root)}"
+      end
+
+      #
+      # Converts the root of a markdown document.
+      #
+      # @param [Kramdown::Element] root
+      #   The root of the markdown document.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_root(root)
+        root.children.map { |child|
+          convert_element(child)
+        }.compact.join("\n")
+      end
+
+      #
+      # Converts an element.
+      #
+      # @param [Kramdown::Element] element
+      #   An arbitrary element within the markdown document.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_element(element)
+        method = "convert_#{element.type}"
+        send(method,element) if respond_to?(method)
+      end
+
+      #
+      # Converts a `kd:blank` element.
+      #
+      # @param [Kramdown::Element] blank
+      #   A `kd:blank` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_blank(blank)
+        '.LP'
+      end
+
+      #
+      # Converts a `kd:text` element.
+      #
+      # @param [Kramdown::Element] text
+      #   A `kd:text` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_text(text)
+        escape(text.value)
+      end
+
+      #
+      # Converts a `kd:typographic_sym` element.
+      #
+      # @param [Kramdown::Element] sym
+      #   A `kd:typographic_sym` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_typographic_sym(sym)
+        TYPOGRAPHIC_SYMS[sym.value]
+      end
+
+      #
+      # Converts a `kd:smart_quote` element.
+      #
+      # @param [Kramdown::Element] quote
+      #   A `kd:smart_quote` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_smart_quote(quote)
+        SMART_QUOTES[quote.value]
+      end
+
+      #
+      # Converts a `kd:header` element.
+      #
+      # @param [Kramdown::Element] header
+      #   A `kd:header` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_header(header)
+        text = header.options[:raw_text]
+
+        case header.options[:level]
+        when 1 then ".TH #{text}"
+        when 2 then ".SH #{text}"
+        else        ".SS #{text}"
+        end
+      end
+
+      #
+      # Converts a `kd:hr` element.
+      #
+      # @param [Kramdown::Element] hr
+      #   A `kd:hr` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_hr(hr)
+        ".ti 0\n\\l'\\n(.lu'"
+      end
+
+      #
+      # Converts a `kd:ul` element.
+      #
+      # @param [Kramdown::Element] ul
+      #   A `kd:ul` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_ul(ul)
+        content = ul.children.map { |li| convert_ul_li(li) }.join("\n")
+
+        return ".RS\n#{content}\n.RE"
+      end
+
+      #
+      # Converts a `kd:li` element within a `kd:ul` list.
+      #
+      # @param [Kramdown::Element] li
+      #   A `kd:li` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_ul_li(li)
+        li.children.each_with_index.map { |child,index|
+          if child.type == :p
+            content = convert_children(child.children)
+
+            if index == 0 then ".IP \\(bu 2\n#{content}"
+            else               ".IP \\( 2\n#{content}"
+            end
+          end
+        }.compact.join("\n")
+      end
+
+      #
+      # Converts a `kd:ol` element.
+      #
+      # @param [Kramdown::Element] ol
+      #   A `kd:ol` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_ol(ol)
+        @ol_index += 1
+
+        header  = ".nr step#{@ol_index} 0 1"
+        content = ol.children.map { |li| convert_ol_li(li) }.join("\n")
+
+        return "#{header}\n.RS\n#{content}\n.RE"
+      end
+
+      #
+      # Converts a `kd:li` element within a `kd:ol` list.
+      #
+      # @param [Kramdown::Element] li
+      #   A `kd:li` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_ol_li(li)
+        li.children.each_with_index.map { |child,index|
+          if child.type == :p
+            content = convert_children(child.children)
+
+            if index == 0 then ".IP \\n+[step#{@ol_index}]\n#{content}"
+            else               ".IP \\n\n#{content}"
+            end
+          end
+        }.compact.join("\n")
+      end
+
+      #
+      # Converts a `kd:abbreviation` element.
+      #
+      # @param [Kramdown::Element] abbr
+      #   A `kd:abbreviation` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_abbreviation(abbr)
+        escape(abbr.value)
+      end
+
+      #
+      # Converts a `kd:blockquote` element.
+      #
+      # @param [Kramdown::Element] blockquote
+      #   A `kd:blockquote` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_blockquote(blockquote)
+        content = blockquote.children.map { |child|
+          case child.type
+          when :p then convert_children(child.children)
+          else         convert_element(child)
+          end
+        }.join("\n")
+
+        return ".PP\n.RS\n#{content}\n.RE"
+      end
+
+      #
+      # Converts a `kd:codeblock` element.
+      #
+      # @param [Kramdown::Element] codeblock
+      #   A `kd:codeblock` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_codeblock(codeblock)
+        ".nf\n#{escape(codeblock.value).rstrip}\n.fi"
+      end
+
+      #
+      # Converts a `kd:comment` element.
+      #
+      # @param [Kramdown::Element] comment
+      #   A `kd:comment` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_comment(comment)
+        comment.value.lines.map { |line|
+          ".\\\" #{line}"
+        }.join("\n")
+      end
+
+      #
+      # Converts a `kd:p` element.
+      #
+      # @param [Kramdown::Element] p
+      #   A `kd:p` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_p(p)
+        children = p.children
+
+        if (children.length >= 2) &&
+           (children[0].type == :em   || children[0].type == :codespan) &&
+           (children[1].type == :text && children[1].value =~ /^(  |\t)/)
+          [
+            '.TP',
+            convert_element(children[0]),
+            convert_text(children[1]).lstrip,
+            convert_children(children[2..-1])
+          ].join("\n").rstrip
+        else
+          ".PP\n#{convert_children(children)}"
+        end
+      end
+
+      #
+      # Converts a `kd:em` element.
+      #
+      # @param [Kramdown::Element] em
+      #   A `kd:em` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_em(em)
+        "\\fI#{convert_children(em.children)}\\fP"
+      end
+
+      #
+      # Converts a `kd:strong` element.
+      #
+      # @param [Kramdown::Element] strong
+      #   A `kd:strong` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_strong(strong)
+        "\\fB#{convert_children(strong.children)}\\fP"
+      end
+
+      #
+      # Converts a `kd:codespan` element.
+      #
+      # @param [Kramdown::Element] codespan
+      #   A `kd:codespan` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_codespan(codespan)
+        "\\fB\\fC#{codespan.value}\\fR"
+      end
+
+      #
+      # Converts a `kd:a` element.
+      #
+      # @param [Kramdown::Element] a
+      #   A `kd:a` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_a(a)
+        href = a.attr['href']
+        text = convert_children(a.children)
+
+        case href
+        when /^mailto:/
+          email = href[7..-1]
+
+          unless text == email then "#{text}\n.MT #{email}\n.ME"
+          else                      "\n.MT #{email}\n.ME"
+          end
+        when /^man:/
+          match = href.match(/man:([A-Za-z0-9_-]+)(?:\((\d[a-z]?)\))?/)
+
+          if match[2] then "\n.BR #{match[1]} (#{match[2]})"
+          else             "\n.BR #{match[1]}"
+          end
+        else
+          "#{text}\n.UR #{href}\n.UE"
+        end
+      end
+
+      #
+      # Converts the children of an element.
+      #
+      # @param [Array<Kramdown::Element>] children
+      #   The children of an element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_children(children)
+        children.map { |child| convert_element(child) }.join.strip
+      end
+
+      #
+      # Escapes text for roff.
+      #
+      # @param [String] text
+      #   The unescaped text.
+      #
+      # @return [String]
+      #   The escaped text.
+      #
+      def escape(text)
+        text.gsub('\\','\&\&').gsub('-','\\-')
+      end
+
+    end
+  end
+end