rdoc2md 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5711a7aad65981183498edc0cd6469b353d722d4
+  data.tar.gz: 35ea58f1409f79a4c4b2ca7d751e271b5468259b
+SHA512:
+  metadata.gz: 613c9d061f4a9162d81bfb299bb8cf2091981a26f7835578e430a064d01c94e5f13c9f37e556c9cdecac424b85fb1a819fc5c5dfa416ad28f1966a1061d5acec
+  data.tar.gz: cfeedd93ee77f415e409246764bd90cdbeca55ca9f9bcc43d3f52adaa794994fd2221cd09717d09bab31d47389af19faa99f926d4887b68e6ba881b71826f4de

data/.autotest

@@ -0,0 +1,4 @@
+# -*- ruby -*-
+
+require "autotest/restart"
+

data/History.txt

@@ -0,0 +1,6 @@
+=== 0.1.0 / 2014-03-03
+
+* First iteration at this gem.  Quick and dirty.  Probably doesn't cover all possible
+  scenarios exhaustively, but it works for converting a typical README.txt file created
+  by hoe into a README.md file that github expects.
+

data/Manifest.txt

@@ -0,0 +1,8 @@
+.autotest
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/rdoc2md
+lib/rdoc2md.rb
+test/test_rdoc2md.rb

data/README.txt

@@ -0,0 +1,68 @@
+= rdoc2md
+
+https://github.com/kirkbowers/rdoc2md
+
+== Description
+
++rdoc2md+ is a utility for converting Rdoc style documents into markdown.  The primary
+motivation is to make a Hoe gem project more github friendly.  Hoe depends on a README.txt
+file in Rdoc format.  Github expects a README.md file to display nicely on the webpage.
+This utility lets you make the .txt file the master and autogenerate the .md version
+without Repeating Yourself.
+
+== Usage
+
+To use +rdoc2md+, first install it:
+
+    [sudo] gem install rdoc2md
+    
+Most likely you will want to run it on the command line, like so:
+
+    rdoc2md README.txt > README.md
+    
+You can use it inside of a Ruby program by passing a +String+ to the initializer of the 
++Rdoc2md::Document+ object and calling +to_md+:
+
+    require 'rdoc2md'
+
+    result = Rdoc2md::Document.new(text).to_md
+    
+I tried for the life of me to make it work as a Hoe plugin, but no luck.  That may be a
+future feature.  In the meantime, add +require 'rdoc2md'+ near the top of your
++Rakefile+ and add this near the bottom:
+
+    task :readme do
+      readme = File.open("README.txt").read
+      File.open('README.md', 'w') do |file| 
+        file.write(Rdoc2md::Document.new(readme).to_md)
+      end
+    end
+
+This will allow you to run +rake readme+ before you commit to github and generate a
+markdown version of your README.
+
+== Dependencies
+
++rdoc2md+ does not depend on any other gem in order to run.
+
+It does, however, depend on by hoe[https://github.com/seattlerb/hoe] and
+shoulda[https://github.com/thoughtbot/shoulda] for development and testing.
+
+== Developers/Contributing
+
+After checking out the source, run:
+
+    rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+This first pass is very ad-hoc.  I make no claims that it exhaustively covers all 
+situations where Rdoc could be converted to an equivalent markdown notation.  If you 
+find a shortcoming, by all means, feel free to upgrade it.  I welcome all contributions.
+
+I do prefer that such shortcomings be documented first in the Issues.  I may be working on a fix already.  No sense in two people fixing the same thing....
+
+== License
+
++rdoc2md+ is released under the MIT license.  

data/Rakefile

@@ -0,0 +1,32 @@
+# -*- ruby -*-
+
+require "rubygems"
+require "hoe"
+require "rdoc2md"
+
+# Hoe.plugin :compiler
+# Hoe.plugin :gem_prelude_sucks
+# Hoe.plugin :inline
+# Hoe.plugin :minitest
+# Hoe.plugin :racc
+# Hoe.plugin :rcov
+# Hoe.plugin :rubyforge
+
+Hoe.spec "rdoc2md" do
+  developer("Kirk Bowers", "kirkbowers@yahoo.com")
+
+  license "MIT" # this should match the license in the README
+end
+
+task :readme do
+  readme = File.open("README.txt").read
+  File.open('README.md', 'w') do |file| 
+    file.write(Rdoc2md::Document.new(readme).to_md)
+  end
+end
+
+task :md2html, [:readme] do
+  `Markdown.pl README.md > README.html`
+end
+
+# vim: syntax=ruby

data/bin/rdoc2md

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require 'rdoc2md'
+
+def usage
+  puts <<EOF
+rdoc2md <infile>
+
+    Converts the input file from an Rdoc style text file to a markdown file.  
+    The results are sent to stdout.
+    It expects the input file to be a "README" type file with no hash marks 
+    preceding the Rdoc mark ups.
+EOF
+
+  abort
+end
+
+usage unless ARGV.length == 1
+  
+text = File.open(ARGV[0]).read
+# Protect against goofy carriage returns on non-unix systems
+text.gsub!(/\r\n?/, "\n")
+
+print Rdoc2md::Document.new(text).to_md
+

data/lib/rdoc2md.rb

@@ -0,0 +1,67 @@
+
+module Rdoc2md
+  VERSION = "0.1.0"
+  
+  # Rdoc2md::Document takes a String representing a document in Rdoc format (sans leading
+  # hashmark comments) and converts it into a similar markdown document.
+  #
+  # Author:: Kirk Bowers (mailto:kirkbowers@yahoo.com)
+  # Copyright:: Copyright (c) 2014 Frabjous Apps LLC
+  # License:: MIT License
+  class Document
+    # The text is the document to be converted from rdoc style to markdown.
+    # It should be a String.
+    attr_accessor :text
+    
+    # The initializer takes an optional text, which is the document to be converted from
+    # rdoc style to markdown.
+    def initialize(text = "")
+      @text = text
+    end
+    
+    # Convert the existing document to markdown.  The result is returned as a String.
+    def to_md
+      # Usually ruby is extremely readable, but I think "-1" means "give me all the 
+      # trailing blank lines" is surprisingly opaque.  That's what the -1 does...
+      lines = @text.split("\n", -1)
+      lines.collect do |line|
+        result = line
+ 
+        # Leave lines that start with 4 spaces alone.  These are code blocks and
+        # should pass through unchanged.
+        unless result =~ /^\s{4,}/
+ 
+          # Convert headers
+          result.sub!(/^(=){1,6}/) { |s| "#" * s.length} unless result =~ /^={7,}/
+ 
+          # Convert strong to have two stars
+          # The matching pair of stars should start with a single star that is either at
+          # the beginning of the line or not following a backslash, have at least one
+          # non-star and non-backslash in between, then end in one star
+          result.gsub!(/(\A|[^\\\*])\*([^\*]*[^\*\\])\*/, '\1**\2**')
+
+          # Convert inline code spans to use backticks
+          result.gsub!(/(\A|[^\\])\+([^\+]*)\+/, '\1`\2`')
+
+          # Convert bare http:, mailto: and ftp: links
+          result.gsub!(/(\A|\s)(http:|https:|mailto:|ftp:)(\S*)/, '\1[\2\3](\2\3)')
+
+          # Convert bare www to an http: link
+          result.gsub!(/(\A|\s)www\.(\S*)/, '\1[www.\2](http://www.\2)')
+
+          # Convert link: links to refer to local files
+          result.gsub!(/(\A|\s)link:(\S*)/, '\1[\2](\2)')
+
+          # Convert multi word labels surrounded by {} with a url
+          result.gsub!(/\{([^\}]*)\}\[(\S*)\]/, '[\1](\2)')
+
+          # Convert one word labels with a url
+          result.gsub!(/(\A|\s)([^\{\s]\S*)\[(\S*)\]/, '\1[\2](\3)')
+
+        end
+        
+        result
+      end.join("\n")
+    end
+  end
+end

data/test/test_rdoc2md.rb

@@ -0,0 +1,317 @@
+require "shoulda-context"
+require "rdoc2md"
+
+class TestRdoc2md < Test::Unit::TestCase
+  context "When converting non-commented text" do
+    should "leave dashed bulleted lists untouched" do
+      text = <<EOF
+- This is a bulleted list item
+- So is this
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "leave starred bulleted lists untouched" do
+      text = <<EOF
+* This is a starred list item
+* So is this
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "leave numbered lists untouched" do
+      text = <<EOF
+1. This is a numbered list item
+2. So is this
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "leave paragraphs untouched" do
+      text = <<EOF
+This is a paragraph.
+
+This is a second paragraph that
+continues on more than one line.
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "convert equal signs for headings to hashes" do
+      text = <<EOF
+= Level 1 heading
+
+== Level 2
+
+=== Level 3
+
+==== Level 4
+
+===== Level 5
+
+====== Level 6
+
+======= Not a heading
+EOF
+
+      expected = <<EOF
+# Level 1 heading
+
+## Level 2
+
+### Level 3
+
+#### Level 4
+
+##### Level 5
+
+###### Level 6
+
+======= Not a heading
+EOF
+      
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+    should "leave emphasized untouched" do
+      text = <<EOF
+This is _emphasized_ text.
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+    should "convert strong to have two stars in the middle of the line" do
+      text = <<EOF
+This is *strong* text.
+EOF
+
+      expected = <<EOF
+This is **strong** text.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert strong to have two stars at the start of the line" do
+      text = <<EOF
+*strong* text at the beginning.
+EOF
+
+      expected = <<EOF
+**strong** text at the beginning.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "leave double stars untouched" do
+      text = <<EOF
+This is **double starred** text.
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "leave backslashed stars untouched" do
+      text = <<EOF
+This is \\*escaped starred* text.
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "convert typewriter to have backticks in the middle of the line" do
+      text = <<EOF
+This is +code+ text.
+EOF
+
+      expected = <<EOF
+This is \`code\` text.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert typewriter to have backticks at the start of the line" do
+      text = <<EOF
++code+ text at the beginning.
+EOF
+
+      expected = <<EOF
+`code` text at the beginning.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "leave backslashed typewriter untouched" do
+      text = <<EOF
+This is \\+escaped code+ text.
+EOF
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal text, result
+    end
+
+
+    should "convert typewriter and allow backslashes inside code span" do
+      text = <<EOF
++code\\+ containing a backslash.
+EOF
+
+      expected = <<EOF
+`code\\` containing a backslash.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert bare http reference to square bracketed with url as label" do
+      text = <<EOF
+Ruby : http://www.ruby-lang.org
+EOF
+
+      expected = <<EOF
+Ruby : [http://www.ruby-lang.org](http://www.ruby-lang.org)
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert bare http reference at beginning of line" do
+      text = <<EOF
+http://www.ruby-lang.org is the url to follow
+EOF
+
+      expected = <<EOF
+[http://www.ruby-lang.org](http://www.ruby-lang.org) is the url to follow
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert bare https reference to square bracketed with url as label" do
+      text = <<EOF
+https://github.com/kirkbowers/rdoc2md
+EOF
+
+      expected = <<EOF
+[https://github.com/kirkbowers/rdoc2md](https://github.com/kirkbowers/rdoc2md)
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert bare mailto reference to square bracketed with url as label" do
+      text = <<EOF
+Email me at mailto:someone@example.com
+EOF
+
+      expected = <<EOF
+Email me at [mailto:someone@example.com](mailto:someone@example.com)
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert bare ftp reference to square bracketed with url as label" do
+      text = <<EOF
+Download at ftp://phonyurl.com today!
+EOF
+
+      expected = <<EOF
+Download at [ftp://phonyurl.com](ftp://phonyurl.com) today!
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert www reference to square bracketed with url as label and http protocol" do
+      text = <<EOF
+Get more details at www.ruby-lang.org
+EOF
+
+      expected = <<EOF
+Get more details at [www.ruby-lang.org](http://www.ruby-lang.org)
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert link: reference to square bracketed with local link as label" do
+      text = <<EOF
+Check the link:faq.html file for more info.
+EOF
+
+      expected = <<EOF
+Check the [faq.html](faq.html) file for more info.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert label[url] references where label is one word" do
+      text = <<EOF
+Visit the Ruby[http://www.ruby-lang.com] site.
+EOF
+
+      expected = <<EOF
+Visit the [Ruby](http://www.ruby-lang.com) site.
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+    should "convert {label}[url] references where label can be multiple words" do
+      text = <<EOF
+Visit the {Ruby website}[http://www.ruby-lang.com]
+EOF
+
+      expected = <<EOF
+Visit the [Ruby website](http://www.ruby-lang.com)
+EOF
+
+      result = Rdoc2md::Document.new(text).to_md
+      assert_equal expected, result
+    end
+
+
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rdoc2md
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kirk Bowers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.9'
+description: |-
+  +rdoc2md+ is a utility for converting Rdoc style documents into markdown.  The primary
+  motivation is to make a Hoe gem project more github friendly.  Hoe depends on a README.txt
+  file in Rdoc format.  Github expects a README.md file to display nicely on the webpage.
+  This utility lets you make the .txt file the master and autogenerate the .md version
+  without Repeating Yourself.
+email:
+- kirkbowers@yahoo.com
+executables:
+- rdoc2md
+extensions: []
+extra_rdoc_files:
+- History.txt
+- Manifest.txt
+- README.txt
+files:
+- .autotest
+- .gemtest
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/rdoc2md
+- lib/rdoc2md.rb
+- test/test_rdoc2md.rb
+homepage: https://github.com/kirkbowers/rdoc2md
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --main
+- README.txt
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: rdoc2md
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: +rdoc2md+ is a utility for converting Rdoc style documents into markdown
+test_files:
+- test/test_rdoc2md.rb