github-markup 1.4.4 → 1.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34d4258d2fea37a26fca212a6250c43851199c5b
-  data.tar.gz: 6a239388e5cfb1d1236dc2a12207aae4325ccc22
+  metadata.gz: 8e03f4fced75d3a7c35f4cffd733122b04c48f10
+  data.tar.gz: 97ebb3c12cd2a27ad1cd89aadb87f01b2104776a
 SHA512:
-  metadata.gz: 4a6bdc8bfc40c80d48b09cf36b7f585a5370fe891d96670b43dd28392064f69b1207517745672f592ed7073333adb867bb7861dc6d4fe69a7c5e665e57b1c921
-  data.tar.gz: 18a49abef17b35df811e67a5ed3b8d5c95cf43e401001b8c53d4f5b1c50f7f9c810c2144f10591b1f2f7f06bef5bb493070edcd30d8e8f09bbb7f35fb819a59e
+  metadata.gz: de17c773fbdac007a4bbddffc9751956ce4438ecac99e3bdad17bfec7190b3f988c800537fe98156d291dd1935893b73bf7c0f24b9caadf0ad11caac004dc9ab
+  data.tar.gz: 12fa22759e16ad09e1d98b72019e745635aeb82b2f61cd06896ec1f763b56b8068d6750c4d01dae6a19f52e162b7866a7f8b5bceefbf235aad6d271e795acb79

data/.gitignore

@@ -3,3 +3,5 @@ pkg/
 .bundle
 Gemfile.lock
 vendor/
+.project
+.buildpath

data/.travis.yml

@@ -9,7 +9,11 @@ notifications:
   email: false
 git:
   depth: 10
-before_install: sudo pip install docutils
+before_install:
+  - sudo apt-get install perl
+  - curl -L http://cpanmin.us | perl - --sudo App::cpanminus
+  - sudo cpanm --installdeps --notest Pod::Simple
+  - sudo pip install docutils
 cache:
   - bundler
   - pip

data/Gemfile

@@ -8,7 +8,8 @@ gem "RedCloth"
 gem "rdoc", "~>3.6"
 gem "org-ruby", "= 0.9.9"
 gem "creole", "~>0.3.6"
-gem "wikicloth", "=0.8.1", :platforms => :ruby
+gem "wikicloth", "=0.8.3"
 gem "asciidoctor", "= 1.5.2"
 gem "rake"
 gem "rinku", '~> 1'
+gem "github-linguist", ">= 5.0.7"

data/README.md

@@ -19,14 +19,15 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a
 
 * [.markdown, .mdown, .mkdn, .md](http://daringfireball.net/projects/markdown/) -- `gem install redcarpet` (https://github.com/vmg/redcarpet)
 * [.textile](http://www.textism.com/tools/textile/) -- `gem install RedCloth`
-* [.rdoc](http://rdoc.sourceforge.net/) -- `gem install rdoc -v 3.6.1`
+* [.rdoc](https://rdoc.github.io/rdoc/) -- `gem install rdoc -v 3.6.1`
 * [.org](http://orgmode.org/) -- `gem install org-ruby`
 * [.creole](http://wikicreole.org/) -- `gem install creole`
 * [.mediawiki, .wiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth`
-* [.rst](http://docutils.sourceforge.net/rst.html) -- `easy_install docutils`
+* [.rst](http://docutils.sourceforge.net/rst.html) -- `python3 -m pip install sphinx`
 * [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org)
-* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML`
-  comes with Perl >= 5.10. Lower versions should install [Pod::Simple](http://search.cpan.org/~dwheeler/Pod-Simple-3.28/lib/Pod/Simple.pod) from CPAN.
+* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML`
+  comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
+
 
 Installation
 -----------
@@ -38,18 +39,31 @@ gem install github-markup
 Usage
 -----
 
+Basic form:
+
 ```ruby
 require 'github/markup'
-GitHub::Markup.render('README.markdown', "* One\n* Two")
+
+GitHub::Markup.render('README.markdown', '* One\n* Two')
 ```
 
-Or, more realistically:
+More realistic form:
 
 ```ruby
 require 'github/markup'
+
 GitHub::Markup.render(file, File.read(file))
 ```
 
+And a convenience form:
+
+```ruby
+require 'github/markup'
+
+GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, '* One\n* Two')
+```
+
+
 Contributing
 ------------
 

data/bin/github-markup

@@ -1,10 +1,28 @@
 #!/usr/bin/env ruby
 
-$LOAD_PATH.unshift File.dirname(__FILE__) + "/../lib"
+$LOAD_PATH.unshift File.dirname(File.realpath(__FILE__)) + "/../lib"
 require 'github/markup'
 
-if ARGV[0] && File.exists?(file = ARGV[0])
-  puts GitHub::Markup.render(file)
-else
-  puts "usage: #$0 FILE"
+if ARGV.size < 1
+  print "usage: #$0 FILE [ FILES ... ]\n"
+  exit 1
 end
+
+sources = []
+
+ARGV.each { |s|
+  begin
+    file = File.open( s, "r" )
+    sources.push [ s, file ]
+  rescue Exception => e
+    $stderr.print "error: #{e.message}\n"
+    exit 1
+  ensure
+  end
+}
+
+sources.each { |name, file|
+  print GitHub::Markup.render( name, file.read )
+  file.close
+}
+

data/lib/github-markup.rb

@@ -1,6 +1,6 @@
 module GitHub
   module Markup
-    VERSION = '1.4.4'
+    VERSION = '1.4.6'
     Version = VERSION
   end
 end

data/lib/github/commands/pod2html

@@ -0,0 +1,15 @@
+#!/usr/bin/env perl
+
+use strict;
+use Pod::Simple::XHTML 3.11;
+
+my $p = Pod::Simple::XHTML->new;
+$p->html_header('');
+$p->html_footer('');
+$p->perldoc_url_prefix('http://metacpan.org/search?q=');
+$p->strip_verbatim_indent(sub {
+    my $lines = shift;
+    (my $indent = $lines->[0]) =~ s/\S.*//;
+    return $indent;
+});
+$p->parse_from_file(shift);

data/lib/github/commands/rest2html

@@ -31,9 +31,11 @@ import sys
 import os
 
 # This fixes docutils failing with unicode parameters to CSV-Table. The -S
-# switch and the following 2 lines can be removed after upgrading to python 3.
-reload(sys)
-sys.setdefaultencoding('utf-8')
+# switch and the following 3 lines can be removed after upgrading to python 3.
+if sys.version_info[0] < 3:
+    reload(sys)
+    sys.setdefaultencoding('utf-8')
+
 import site
 
 try:
@@ -43,12 +45,80 @@ except:
     pass
 
 import codecs
+import io
 
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
 from docutils.parsers.rst.directives.body import CodeBlock
 from docutils.core import publish_parts
 from docutils.writers.html4css1 import Writer, HTMLTranslator
+from docutils.parsers.rst.states import Body
+from docutils import nodes
+
+# By default, docutils provides two choices for unknown directives:
+#  - Show errors if the reporting level is high enough
+#  - Silently do not display them otherwise
+# Comments are not displayed, either.
+
+# This code monkey-patches docutils to show preformatted lines
+# in both these cases.
+
+# Recommended practice for repositories with rst files:
+#  - If github is the preferred viewer for the rst files (e.g. README.rst),
+#    then design the files to properly display for github.  E.g., do not
+#    include unknown directives or restructuredText comments.
+#  - If github is NOT the preferred viewer for the rst files (e.g.
+#    the files are designed to be used with sphinx extensions at readthedocs)
+#    then include a restructuredText comment at the top of the file
+#    explaining that the document will display much more nicely with its
+#    preferred viewer, e.g. at readthedocs.
+
+original_behavior = False  # Documents original docutils behavior
+github_display = True
+
+def unknown_directive(self, type_name):
+    lineno = self.state_machine.abs_line_number()
+    indented, indent, offset, blank_finish = \
+        self.state_machine.get_first_known_indented(0, strip_indent=False)
+    text = '\n'.join(indented)
+    if original_behavior:
+        error = self.reporter.error(
+              'Unknown directive type "%s".' % type_name,
+              nodes.literal_block(text, text), line=lineno)
+        return [error], blank_finish
+    elif github_display:
+        cls = ['unknown_directive']
+        result = [nodes.literal_block(text, text, classes=cls)]
+        return result, blank_finish
+    else:
+        return [nodes.comment(text, text)], blank_finish
+
+def comment(self, match):
+    if not match.string[match.end():].strip() \
+            and self.state_machine.is_next_line_blank(): # an empty comment?
+        return [nodes.comment()], 1 # "A tiny but practical wart."
+    indented, indent, offset, blank_finish = \
+            self.state_machine.get_first_known_indented(match.end())
+    while indented and not indented[-1].strip():
+        indented.trim_end()
+    if not original_behavior:
+        firstline = ''.join(indented[:1]).split()
+        if ' '.join(firstline[:2]) == 'github display':
+            if len(firstline) == 3 and firstline[2] in ('on', 'off'):
+                global github_display
+                github_display = firstline[2] == 'on'
+            if len(indented) == 1:
+                return [nodes.comment()], 1
+            text = '\n'.join(indented[1:])
+            cls = ['github_comment']
+            result = [nodes.literal_block(text, text, classes=cls)]
+            return result, blank_finish
+    text = '\n'.join(indented)
+    return [nodes.comment(text, text)], blank_finish
+
+Body.comment = comment
+Body.unknown_directive = unknown_directive
+
 
 SETTINGS = {
     'cloak_email_addresses': False,
@@ -56,7 +126,6 @@ SETTINGS = {
     'raw_enabled': True,
     'strip_comments': True,
     'doctitle_xform': True,
-    'sectsubtitle_xform': True,
     'initial_header_level': 2,
     'report_level': 5,
     'syntax_highlight': 'none',
@@ -105,6 +174,9 @@ class GitHubHTMLTranslator(HTMLTranslator):
         else:
             self.body.append(self.starttag(node, 'pre'))
 
+    def visit_doctest_block(self, node):
+        self.body.append(self.starttag(node, 'pre', lang='pycon'))
+
     # always wrap two-backtick rst inline literals in <code>, not <tt>
     # this also avoids the generation of superfluous <span> tags
     def visit_literal(self, node):
@@ -139,9 +211,9 @@ class GitHubHTMLTranslator(HTMLTranslator):
 
             # toss off `object` tag
             self.body.pop()
-        # add on `img` with attributes
+            # add on `img` with attributes
             self.body.append(self.starttag(node, 'img', **atts))
-        self.body.append(self.context.pop())
+        HTMLTranslator.depart_image(self, node)
 
 
 def kbd(name, rawtext, text, lineno, inliner, options=None, content=None):
@@ -162,7 +234,11 @@ def main():
     except IOError:  # given filename could not be found
         return ''
     except IndexError:  # no filename given
-        text = sys.stdin.read()
+        if sys.version_info[0] < 3: # python 2.x
+            text = sys.stdin.read()
+        else: # python 3
+            input_stream = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8')
+            text = input_stream.read()
 
     writer = Writer()
     writer.translator_class = GitHubHTMLTranslator
@@ -185,5 +261,9 @@ def main():
     return ''
 
 if __name__ == '__main__':
-    sys.stdout.write("%s%s" % (main(), "\n"))
+    if sys.version_info[0] < 3: # python 2.x
+        sys.stdout.write("%s%s" % (main(), "\n"))
+    else: # python 3
+        output_stream = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+        output_stream.write("%s%s" % (main(), "\n"))
     sys.stdout.flush()

data/lib/github/markup.rb

@@ -2,16 +2,34 @@ require "github/markup/command_implementation"
 require "github/markup/gem_implementation"
 
 module GitHub
+  module Markups
+    # all of supported markups:
+    MARKUP_ASCIIDOC = :asciidoc
+    MARKUP_CREOLE = :creole
+    MARKUP_MARKDOWN = :markdown
+    MARKUP_MEDIAWIKI = :mediawiki
+    MARKUP_ORG = :org
+    MARKUP_POD = :pod
+    MARKUP_RDOC = :rdoc
+    MARKUP_RST = :rst
+    MARKUP_TEXTILE = :textile
+  end
+  
   module Markup
     extend self
-    @@markups = []
+    
+    @@markups = {}
 
     def markups
       @@markups
     end
+    
+    def markup_impls
+      markups.values
+    end
 
     def preload!
-      markups.each do |markup|
+      markup_impls.each do |markup|
         markup.load
       end
     end
@@ -19,35 +37,58 @@ module GitHub
     def render(filename, content = nil)
       content ||= File.read(filename)
 
-      if impl = renderer(filename)
+      if impl = renderer(filename, content)
         impl.render(content)
       else
         content
       end
     end
+    
+    def render_s(symbol, content)
+      if content.nil?
+        raise ArgumentError, 'Can not render a nil.'
+      elsif markups.has_key?(symbol)
+        markups[symbol].render(content)
+      else
+        content
+      end
+    end
 
-    def markup(file, pattern, opts = {}, &block)
-      markups << GemImplementation.new(pattern, file, &block)
+    def markup(symbol, gem_name, pattern, opts = {}, &block)
+      markup_impl(symbol, GemImplementation.new(pattern, gem_name, &block))
+    end
+    
+    def markup_impl(symbol, impl)
+      if markups.has_key?(symbol)
+        raise ArgumentError, "The '#{symbol}' symbol is already defined."
+      end
+      markups[symbol] = impl
     end
 
-    def command(command, regexp, name, &block)
+    def command(symbol, command, languages, name, &block)
       if File.exist?(file = File.dirname(__FILE__) + "/commands/#{command}")
         command = file
       end
 
-      markups << CommandImplementation.new(regexp, command, name, &block)
+      markup_impl(symbol, CommandImplementation.new(languages, command, name, &block))
     end
 
-    def can_render?(filename)
-      !!renderer(filename)
+    def can_render?(filename, content)
+      !!renderer(filename, content)
     end
 
-    def renderer(filename)
-      markups.find { |impl|
-        impl.match?(filename)
+    def renderer(filename, content)
+      language = language(filename, content)
+      markup_impls.find { |impl|
+        impl.match?(language)
       }
     end
 
+    def language(filename, content)
+      blob = Linguist::Blob.new(filename, content)
+      return Linguist.detect(blob, allow_empty: true)
+    end
+
     # Define markups
     markups_rb = File.dirname(__FILE__) + '/markups.rb'
     instance_eval File.read(markups_rb), markups_rb

data/lib/github/markup/command_implementation.rb

@@ -6,6 +6,7 @@ end
 
 require "github/markup/implementation"
 
+
 module GitHub
   module Markup
     class CommandError < RuntimeError
@@ -14,8 +15,8 @@ module GitHub
     class CommandImplementation < Implementation
       attr_reader :command, :block, :name
 
-      def initialize(regexp, command, name, &block)
-        super regexp
+      def initialize(languages, command, name, &block)
+        super languages
         @command = command.to_s
         @block = block
         @name = name

data/lib/github/markup/gem_implementation.rb

@@ -5,8 +5,8 @@ module GitHub
     class GemImplementation < Implementation
       attr_reader :gem_name, :renderer
 
-      def initialize(regexp, gem_name, &renderer)
-        super regexp
+      def initialize(languages, gem_name, &renderer)
+        super languages
         @gem_name = gem_name.to_s
         @renderer = renderer
       end

data/lib/github/markup/implementation.rb

@@ -1,10 +1,10 @@
 module GitHub
   module Markup
     class Implementation
-      attr_reader :regexp
+      attr_reader :languages
 
-      def initialize(regexp)
-        @regexp = regexp
+      def initialize(languages)
+        @languages = languages
       end
 
       def load
@@ -15,13 +15,8 @@ module GitHub
         raise NotImplementedError, "subclasses of GitHub::Markup::Implementation must define #render"
       end
 
-      def match?(filename)
-        file_ext_regexp =~ filename
-      end
-
-    private
-      def file_ext_regexp
-        @file_ext_regexp ||= /\.(#{regexp})\z/
+      def match?(language)
+        languages.include? language
       end
     end
   end

data/lib/github/markup/markdown.rb

@@ -28,7 +28,7 @@ module GitHub
       }
 
       def initialize
-        super(/md|rmd|mkdn?|mdwn|mdown|markdown|litcoffee/i)
+        super([Linguist::Language["Markdown"], Linguist::Language["RMarkdown"], Linguist::Language["Literate CoffeeScript"]])
       end
 
       def load

data/lib/github/markup/rdoc.rb

@@ -6,7 +6,7 @@ module GitHub
   module Markup
     class RDoc < Implementation
       def initialize
-        super /rdoc/
+        super([Linguist::Language["RDoc"]])
       end
 
       def render(content)

data/lib/github/markups.rb

@@ -1,50 +1,43 @@
 require "github/markup/markdown"
 require "github/markup/rdoc"
 require "shellwords"
+require "linguist"
 
-markups << GitHub::Markup::Markdown.new
+markup_impl(::GitHub::Markups::MARKUP_MARKDOWN, ::GitHub::Markup::Markdown.new)
 
-markup(:redcloth, /textile/) do |content|
+markup(::GitHub::Markups::MARKUP_TEXTILE, :redcloth, [Linguist::Language["Textile"]]) do |content|
   RedCloth.new(content).to_html
 end
 
-markups << GitHub::Markup::RDoc.new
+markup_impl(::GitHub::Markups::MARKUP_RDOC, GitHub::Markup::RDoc.new)
 
-markup('org-ruby', /org/) do |content|
+markup(::GitHub::Markups::MARKUP_ORG, 'org-ruby', [Linguist::Language["Org"]]) do |content|
   Orgmode::Parser.new(content, {
                         :allow_include_files => false,
                         :skip_syntax_highlight => true
                       }).to_html
 end
 
-markup(:creole, /creole/) do |content|
+markup(::GitHub::Markups::MARKUP_CREOLE, :creole, [Linguist::Language["Creole"]]) do |content|
   Creole.creolize(content)
 end
 
-markup(:wikicloth, /mediawiki|wiki/) do |content|
+markup(::GitHub::Markups::MARKUP_MEDIAWIKI, :wikicloth, [Linguist::Language["MediaWiki"]]) do |content|
   wikicloth = WikiCloth::WikiCloth.new(:data => content)
   WikiCloth::WikiBuffer::HTMLElement::ESCAPED_TAGS << 'tt' unless WikiCloth::WikiBuffer::HTMLElement::ESCAPED_TAGS.include?('tt')
   wikicloth.to_html(:noedit => true)
 end
 
-markup(:asciidoctor, /adoc|asc(iidoc)?/) do |content|
+markup(::GitHub::Markups::MARKUP_ASCIIDOC, :asciidoctor, [Linguist::Language["AsciiDoc"]]) do |content|
   Asciidoctor::Compliance.unique_id_start_index = 1
   Asciidoctor.convert(content, :safe => :secure, :attributes => %w(showtitle=@ idprefix idseparator=- env=github env-github source-highlighter=html-pipeline))
 end
 
 command(
+  ::GitHub::Markups::MARKUP_RST,
   "python2 -S #{Shellwords.escape(File.dirname(__FILE__))}/commands/rest2html",
-  /re?st(\.txt)?/,
+  [Linguist::Language["reStructuredText"]],
   "restructuredtext"
 )
 
-# pod2html is nice enough to generate a full-on HTML document for us,
-# so we return the favor by ripping out the good parts.
-#
-# Any block passed to `command` will be handed the command's STDOUT for
-# post processing.
-command('/usr/bin/env perl -MPod::Simple::HTML -e Pod::Simple::HTML::go', /pod/, "pod") do |rendered|
-  if rendered =~ /<!-- start doc -->\s*(.+)\s*<!-- end doc -->/mi
-    $1
-  end
-end
+command(::GitHub::Markups::MARKUP_POD, :pod2html, [Linguist::Language["Pod"]], "pod")

data/test/markup_test.rb

@@ -75,33 +75,37 @@ class MarkupTest < Minitest::Test
 message
     end
   end
-
+  
   def test_knows_what_it_can_and_cannot_render
-    assert_equal false, GitHub::Markup.can_render?('README.html')
-    assert_equal true, GitHub::Markup.can_render?('README.markdown')
-    assert_equal true, GitHub::Markup.can_render?('README.rmd')
-    assert_equal true, GitHub::Markup.can_render?('README.Rmd')
-    assert_equal false, GitHub::Markup.can_render?('README.cmd')
-    assert_equal true, GitHub::Markup.can_render?('README.litcoffee')
+    assert_equal false, GitHub::Markup.can_render?('README.html', '<h1>Title</h1>')
+    assert_equal true, GitHub::Markup.can_render?('README.markdown', '=== Title')
+    assert_equal true, GitHub::Markup.can_render?('README.rmd', '=== Title')
+    assert_equal true, GitHub::Markup.can_render?('README.Rmd', '=== Title')
+    assert_equal false, GitHub::Markup.can_render?('README.cmd', 'echo 1')
+    assert_equal true, GitHub::Markup.can_render?('README.litcoffee', 'Title')
   end
 
   def test_each_render_has_a_name
-    assert_equal "markdown", GitHub::Markup.renderer('README.md').name
-    assert_equal "redcloth", GitHub::Markup.renderer('README.textile').name
-    assert_equal "rdoc", GitHub::Markup.renderer('README.rdoc').name
-    assert_equal "org-ruby", GitHub::Markup.renderer('README.org').name
-    assert_equal "creole", GitHub::Markup.renderer('README.creole').name
-    assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki').name
-    assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc').name
-    assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst').name
-    assert_equal "pod", GitHub::Markup.renderer('README.pod').name
+    assert_equal "markdown", GitHub::Markup.renderer('README.md', '=== Title').name
+    assert_equal "redcloth", GitHub::Markup.renderer('README.textile', '* One').name
+    assert_equal "rdoc", GitHub::Markup.renderer('README.rdoc', '* One').name
+    assert_equal "org-ruby", GitHub::Markup.renderer('README.org', '* Title').name
+    assert_equal "creole", GitHub::Markup.renderer('README.creole', '= Title =').name
+    assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki', '<h1>Title</h1>').name
+    assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name
+    assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name
+    assert_equal "pod", GitHub::Markup.renderer('README.pod', '=begin').name
+  end
+  
+  def test_rendering_by_symbol
+    assert_equal '<p><code>test</code></p>', GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, '`test`').strip
   end
 
   def test_raises_error_if_command_exits_non_zero
-    GitHub::Markup.command('test/fixtures/fail.sh', /fail/, 'fail')
-    assert GitHub::Markup.can_render?('README.fail')
+    GitHub::Markup.command(:doesntmatter, 'test/fixtures/fail.sh', [Linguist::Language['Java']], 'fail')
+    assert GitHub::Markup.can_render?('README.java', 'stop swallowing errors')
     begin
-      GitHub::Markup.render('README.fail', "stop swallowing errors")
+      GitHub::Markup.render('README.java', "stop swallowing errors")
     rescue GitHub::Markup::CommandError => e
       assert_equal "failure message", e.message
     else

data/test/markups/README.directives.rst

@@ -0,0 +1,103 @@
+==================================================
+restructuredText (rst) directives and comments
+==================================================
+
+Introduction
+=================
+
+An rst directive starts with two periods, and has a keyword
+followed by two colons, like this::
+
+    .. MyDirective::
+
+The rst parser is quite flexible and configurable.  Directives
+may be added for specialized operations.  Sphinx is a system
+that was designed for writing documentation, and, for example,
+readthedocs.org uses sphinx.
+
+Display of rst files at github needs to cover two distinct
+use-cases:
+
+- The github display is the primary method for displaying
+  the file (e.g. for README.rst files)
+
+- The github display is incidental to the primary method
+  for displaying the file (e.g. for readthedocs documentation)
+
+Currently, github handles the first case fine, but could
+confuse viewers for the second case, because sometimes
+content is missing from the github display.
+
+It would seem that one possibility for distinguishing these
+two cases is to add a github directive to control the display.
+
+Unfortunately, this would place a burden on every other rst
+parser to ignore the github directive (some of them will error
+on unknown directives).
+
+Instead, we can assign semantic content to specific comments.
+
+This is a fairly ugly hack, but it has the benefit of not
+requiring any document changes that would create problems with
+any conformant parser.
+
+
+The proposed special comment is::
+
+  .. github display [on | off]
+
+
+If you pass this the "on" value, then all unknown directives
+will be displayed as literal code blocks.  If you pass this
+the "off" value, then unknown directives will not be displayed.
+
+In addition to controlling the display of literal code blocks,
+this also allows you to show comments specifically for github.
+
+For example, somebody could place this at the top of their file::
+
+  .. github display
+
+    This file was designed to be viewed at readthedocs.  Some
+    content will not display properly when viewing using the
+    github browser.
+
+Tests
+==========
+
+By default, unknown directives should be displayed.
+
+.. UnknownDirective::  This is an unknown directive
+
+      it has a lot of stuff underneath it
+
+But we can turn this off, and the next directive should
+not be displayed.
+
+.. github display off
+
+.. UnknownDirective::  This is an unknown directive
+
+      it has a lot of stuff underneath it
+
+Or we can turn it back on...
+
+.. github display on
+
+.. UnknownDirective::  This is an unknown directive (3)
+
+      it has a lot of stuff underneath it
+
+Here is a comment that should display at github
+
+.. github display
+
+    YOU SHOULD SEE THIS!
+
+And here is a comment that should not display at github
+
+.. foobar
+
+    YOU SHOULD NOT SEE THIS!
+
+This concludes the tests.

data/test/markups/README.directives.rst.html

@@ -0,0 +1,74 @@
+<h1>restructuredText (rst) directives and comments</h1>
+<a name="introduction"></a>
+<h2>Introduction</h2>
+<p>An rst directive starts with two periods, and has a keyword
+followed by two colons, like this:</p>
+<pre>
+.. MyDirective::
+</pre>
+<p>The rst parser is quite flexible and configurable.  Directives
+may be added for specialized operations.  Sphinx is a system
+that was designed for writing documentation, and, for example,
+readthedocs.org uses sphinx.</p>
+<p>Display of rst files at github needs to cover two distinct
+use-cases:</p>
+<ul>
+<li>The github display is the primary method for displaying
+the file (e.g. for README.rst files)</li>
+<li>The github display is incidental to the primary method
+for displaying the file (e.g. for readthedocs documentation)</li>
+</ul>
+<p>Currently, github handles the first case fine, but could
+confuse viewers for the second case, because sometimes
+content is missing from the github display.</p>
+<p>It would seem that one possibility for distinguishing these
+two cases is to add a github directive to control the display.</p>
+<p>Unfortunately, this would place a burden on every other rst
+parser to ignore the github directive (some of them will error
+on unknown directives).</p>
+<p>Instead, we can assign semantic content to specific comments.</p>
+<p>This is a fairly ugly hack, but it has the benefit of not
+requiring any document changes that would create problems with
+any conformant parser.</p>
+<p>The proposed special comment is:</p>
+<pre>
+.. github display [on | off]
+</pre>
+<p>If you pass this the "on" value, then all unknown directives
+will be displayed as literal code blocks.  If you pass this
+the "off" value, then unknown directives will not be displayed.</p>
+<p>In addition to controlling the display of literal code blocks,
+this also allows you to show comments specifically for github.</p>
+<p>For example, somebody could place this at the top of their file:</p>
+<pre>
+.. github display
+
+  This file was designed to be viewed at readthedocs.  Some
+  content will not display properly when viewing using the
+  github browser.
+</pre>
+<a name="tests"></a>
+<h2>Tests</h2>
+<p>By default, unknown directives should be displayed.</p>
+<pre>
+.. UnknownDirective::  This is an unknown directive
+
+      it has a lot of stuff underneath it
+
+</pre>
+<p>But we can turn this off, and the next directive should
+not be displayed.</p>
+<p>Or we can turn it back on...</p>
+<pre>
+.. UnknownDirective::  This is an unknown directive (3)
+
+      it has a lot of stuff underneath it
+
+</pre>
+<p>Here is a comment that should display at github</p>
+<pre>
+
+YOU SHOULD SEE THIS!
+</pre>
+<p>And here is a comment that should not display at github</p>
+<p>This concludes the tests.</p>

data/test/markups/README.pod

@@ -12,7 +12,7 @@ Primary goals are:
 
 =over 4
 
-=item* Create a working compiler that understands the majority of the
+=item * Create a working compiler that understands the majority of the
 MATLAB/Octave programming language.
 
 =back
@@ -23,14 +23,14 @@ This project is broken into three primary components:
 
 =over 4
 
-=item* The first is the parser, located in the C<src/parser/> directory. The
+=item * The first is the parser, located in the C<src/parser/> directory. The
 parser proper is composed of three source files, F<grammar.pg> which is a
 Perl6Grammar file, and F<actions.pm> which is the associated actions file
 written in NQP, and F<grammar-oper.pm> which is the operator precidence parser.
 In addition, several helper functions used by the parser are located in
 C<src/internals>.
 
-=item* The second component is the library of builtin functions in the
+=item * The second component is the library of builtin functions in the
 C<src/builtins/> directory. These functions are, currently, written primarily in
 PIR. Function names prefixed with an underscore are "private" functions for use
 with the parser. Other functions should have names which are the same as names
@@ -38,7 +38,7 @@ for regular MATLAB or Octave functions, since they will be available to the
 HLL. These are also separated into different namespaces depending on visibility
 and utility.
 
-=item* A number of library functions are written in M, or mostly M with some
+=item * A number of library functions are written in M, or mostly M with some
 inline PIR code in C<toolbox/>.
 
 =back

data/test/markups/README.pod.html

@@ -1,84 +1,72 @@
-<a name="___top"></a>
+<h1>Matrixy</h1>
 
-<h1><a href="#___top" title="click to go to top of document" name="Matrixy">Matrixy</a></h1>
+<h2>INTRODUCTION</h2>
 
-<h2><a href="#___top" title="click to go to top of document" name="INTRODUCTION">INTRODUCTION</a></h2>
+<p>This is a port of the MATLAB/Octave programming language to Parrot. See the ROADMAP file for more information on the status of this project, and what else needs to be done.</p>
 
-<p>This is a port of the MATLAB/Octave programming language to Parrot.
-See the ROADMAP file for more information on the status of this project,
-and what else needs to be done.</p>
-
-<h2><a href="#___top" title="click to go to top of document" name="ABOUT">ABOUT</a></h2>
+<h2>ABOUT</h2>
 
 <p>Primary goals are:</p>
 
-<blockquote>
-<p>=item* Create a working compiler that understands the majority of the MATLAB/Octave programming language.</p>
-</blockquote>
+<ul>
+
+<li><p>Create a working compiler that understands the majority of the MATLAB/Octave programming language.</p>
 
-<h2><a href="#___top" title="click to go to top of document" name="IMPLEMENTATION">IMPLEMENTATION</a></h2>
+</li>
+</ul>
+
+<h2>IMPLEMENTATION</h2>
 
 <p>This project is broken into three primary components:</p>
 
-<blockquote>
-<p>=item* The first is the parser,
-located in the <code>src/parser/</code> directory.
-The parser proper is composed of three source files,
-<em>grammar.pg</em> which is a Perl6Grammar file,
-and <em>actions.pm</em> which is the associated actions file written in NQP,
-and <em>grammar-oper.pm</em> which is the operator precidence parser.
-In addition,
-several helper functions used by the parser are located in <code>src/internals</code>.</p>
-
-<p>=item* The second component is the library of builtin functions in the <code>src/builtins/</code> directory.
-These functions are,
-currently,
-written primarily in PIR.
-Function names prefixed with an underscore are "private" functions for use with the parser.
-Other functions should have names which are the same as names for regular MATLAB or Octave functions,
-since they will be available to the HLL.
-These are also separated into different namespaces depending on visibility and utility.</p>
-
-<p>=item* A number of library functions are written in M,
-or mostly M with some inline PIR code in <code>toolbox/</code>.</p>
-</blockquote>
-
-<h2><a href="#___top" title="click to go to top of document" name="DEPENDENCIES">DEPENDENCIES</a></h2>
+<ul>
+
+<li><p>The first is the parser, located in the <code>src/parser/</code> directory. The parser proper is composed of three source files, <i>grammar.pg</i> which is a Perl6Grammar file, and <i>actions.pm</i> which is the associated actions file written in NQP, and <i>grammar-oper.pm</i> which is the operator precidence parser. In addition, several helper functions used by the parser are located in <code>src/internals</code>.</p>
+
+</li>
+<li><p>The second component is the library of builtin functions in the <code>src/builtins/</code> directory. These functions are, currently, written primarily in PIR. Function names prefixed with an underscore are &quot;private&quot; functions for use with the parser. Other functions should have names which are the same as names for regular MATLAB or Octave functions, since they will be available to the HLL. These are also separated into different namespaces depending on visibility and utility.</p>
+
+</li>
+<li><p>A number of library functions are written in M, or mostly M with some inline PIR code in <code>toolbox/</code>.</p>
+
+</li>
+</ul>
+
+<h2>DEPENDENCIES</h2>
 
 <p>Matrixy depends on these dependencies:</p>
 
-<h3><a href="#___top" title="click to go to top of document" name="Parrot">Parrot</a></h3>
+<h3>Parrot</h3>
 
-<p>To get a proper version of Parrot to build Matrixy,
-you will need to check out and build Parrot from source:</p>
+<p>To get a proper version of Parrot to build Matrixy, you will need to check out and build Parrot from source:</p>
 
-<pre>    svn co http://svn.parrot.org/parrot/trunk parrot
-    cd parrot
-    perl Configure.pl
-    make &amp;&amp; make test &amp;&amp; make install-dev</pre>
+<pre><code>svn co http://svn.parrot.org/parrot/trunk parrot
+cd parrot
+perl Configure.pl
+make &amp;&amp; make test &amp;&amp; make install-dev</code></pre>
 
-<h3><a href="#___top" title="click to go to top of document" name="Parrot-Linear-Algebra">Parrot-Linear-Algebra</a></h3>
+<h3>Parrot-Linear-Algebra</h3>
 
 <p>The linear algebra package for Parrot is available separately and provides functionality required by Matrixy. This includes matrix data types and matrix manipulation libraries</p>
 
-<h2><a href="#___top" title="click to go to top of document" name="BUILDING">BUILDING</a></h2>
+<h2>BUILDING</h2>
 
 <p>Once all dependencies are in place, you can build Matrixy using this sequence of commands:</p>
 
-<pre>    perl Configure.pl
-    nmake test</pre>
+<pre><code>perl Configure.pl
+nmake test</code></pre>
 
-<h2><a href="#___top" title="click to go to top of document" name="TODO">TODO</a></h2>
+<h2>TODO</h2>
 
-<pre>    * Parser
-    * Standard Builtins
-    * Test against Octave Test Suite.</pre>
+<pre><code>* Parser
+* Standard Builtins
+* Test against Octave Test Suite.</code></pre>
 
-<h2><a href="#___top" title="click to go to top of document" name="BUGS">BUGS</a></h2>
+<h2>BUGS</h2>
 
 <p>Lots!</p>
 
-<h2><a href="#___top" title="click to go to top of document" name="CONTACT">CONTACT</a></h2>
+<h2>CONTACT</h2>
 
 <p>If you need to contact the Matrixy team, go to the project home page at:</p>
 

data/test/markups/README.rst

@@ -44,6 +44,9 @@ The UTF-8 quote character in this table used to cause python to go boom. Now doc
 	>>> some_function()
 	'result'
 
+>>> some_function()
+'result'
+
 ==============  ==========================================================
 Travis          http://travis-ci.org/tony/pullv
 Docs            http://pullv.rtfd.org

data/test/markups/README.rst.html

@@ -26,6 +26,10 @@ python.code('hooray')
 >>> some_function()
 'result'
 </pre>
+<pre lang="pycon">
+&gt;&gt;&gt; some_function()
+'result'
+</pre>
 <table>
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: github-markup
 version: !ruby/object:Gem::Version
-  version: 1.4.4
+  version: 1.4.6
 platform: ruby
 authors:
 - Chris Wanstrath
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-15 00:00:00.000000000 Z
+date: 2017-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -114,6 +114,7 @@ files:
 - bin/github-markup
 - github-markup.gemspec
 - lib/github-markup.rb
+- lib/github/commands/pod2html
 - lib/github/commands/rest2html
 - lib/github/markup.rb
 - lib/github/markup/command_implementation.rb
@@ -130,6 +131,8 @@ files:
 - test/markups/README.asciidoc.html
 - test/markups/README.creole
 - test/markups/README.creole.html
+- test/markups/README.directives.rst
+- test/markups/README.directives.rst.html
 - test/markups/README.litcoffee
 - test/markups/README.litcoffee.html
 - test/markups/README.markdown
@@ -187,6 +190,8 @@ test_files:
 - test/markups/README.asciidoc.html
 - test/markups/README.creole
 - test/markups/README.creole.html
+- test/markups/README.directives.rst
+- test/markups/README.directives.rst.html
 - test/markups/README.litcoffee
 - test/markups/README.litcoffee.html
 - test/markups/README.markdown