html-pipeline-cite 0.0.1

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# CHANGELOG
+
+## 0.0.1 - *Initial Version*
+
+* Handles basic [Cite](http://www.mediawiki.org/wiki/Extension:Cite/Cite.php)-style references.  *Does not yet support named references or groups.*
+* Built the basic gem infrastructure.

data/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Adding new features
+
+This section includes advice on how to build new features for the project & what kind of process it includes. 
+
+* This is how we like people to add new features:
+    * Add only one feature at a time each on a new branch
+* Here are some specifics on the coding style we prefer:
+    * Write the code test first
+    * Document the code whether or not it is part of the public API
+        * We use [YARD documentation](http://yardoc.org/)
+        * Documentation comments are in [Markdown](http://daringfireball.net/projects/markdown/) format
+* This is how you send your pull request:
+    * TBD
+* You should include the following tests:
+    * Unit tests (including tests for failure cases and testing exception paths) at a bare minimum
+    * If creating a new chunk of code (rather than changing already existing code) include integration tests as well
+* These are the updates we hope you make to the changelog:
+    * Create a header underneath the current version number with a brief description of the feature
+    * Document any new command-line options
+
+Don’t get discouraged! We estimate that the response time from the maintainers is around: One week, perhaps longer in December.
+
+# Bug triage
+
+This section explains how bug triaging is done for your project. Help beginners by including examples to good bug reports and providing them questions they should look to answer. 
+
+* You can help report bugs by filing them here: [New Issue](https://github.com/lifted-studios/html-pipeline-cite/issues/new)
+* You can look through the existing bugs here: [Issues List](https://github.com/lifted-studios/html-pipeline-cite/issues)
+
+* Look at existing bugs and help us understand if
+    * The bug is reproducible? Is it reproducible in other environments (browsers)? What are the steps to reproduce? 
+
+* You can close fixed bugs by testing old tickets to see if they are happening
+* You can update our change log here
+* You can remove duplicate bug reports
+
+# Translations
+
+This section includes any instructions or translation needs your project has. 
+
+* You can help us translate our project here: 
+
+# Documentation
+
+This section includes any help you need with the documentation and where it can be found. Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. 
+
+* Help us with documentation here
+
+# Community 
+This section includes ideas on how non-developers can help with the project. Here's a few examples:
+
+* You can help us answer questions our users have here: 
+* You can help build and design our website here:
+* You can help write blog posts about the project by: 
+* You can help with newsletters and internal communications by: 
+
+* Create an example of the project in real world by building something or
+showing what others have built. 
+* Write about other people’s projects based on this project. Show how
+it’s used in daily life. Take screenshots and make videos!
+
+
+# Your first bugfix
+This section should help a person get started with their very first bug fix and thinking through the problem.
+
+* If you have further questions, contact:
+
+This contributing file template is from [contribute.md](http://contribute.md/).

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    html-pipeline-cite (0.0.1)
+      html-pipeline (>= 0.0.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (3.2.12)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    escape_utils (0.3.1)
+    gemoji (1.4.0)
+    github-markdown (0.5.3)
+    html-pipeline (0.0.8)
+      activesupport (>= 2)
+      escape_utils (~> 0.2)
+      gemoji (~> 1.0)
+      github-markdown (~> 0.5)
+      nokogiri (~> 1.4)
+      rinku (~> 1.7)
+      sanitize (~> 2.0)
+    i18n (0.6.4)
+    minitest (3.5.0)
+    multi_json (1.6.1)
+    nokogiri (1.5.6)
+    rake (10.0.2)
+    redcarpet (2.1.1)
+    rinku (1.7.2)
+    sanitize (2.0.3)
+      nokogiri (>= 1.4.4, < 1.6)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  html-pipeline-cite!
+  minitest (~> 3.0)
+  rake (~> 10.0)
+  redcarpet
+  yard (~> 0.8)

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 Lee Dohm, Lifted Studios
+
+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,72 @@
+<!-- 
+[![Build Status](NOTE: Use something like Travis CI http://about.travis-ci.org/docs/user/getting-started/)
+ -->
+
+# HTML::Pipeline Cite Gem
+
+An [HTML::Pipeline](https://github.com/jch/html-pipeline) filter for WikiMedia-style Cite references.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'html-pipeline-cite'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install html-pipeline-cite
+```
+
+## Usage
+
+This gem offers an `HTML::Pipeline` filter that collects references in the text and inserts a table of footnotes where instructed.
+
+Example:
+
+    <ref>This is a footnote</ref>
+
+Becomes:
+
+    <sup class="reference" id="wiki-cite_ref-1">[<a href="#wiki-cite_note-1">1</a>]</sup>
+
+It will show up as a bracketed, superscripted and anchored number at that location in the text.  Then when 
+`<references/>` is placed in the text, an ordered list of the references and their text will be placed at that
+location.  The example above would generate a list that looks like this:
+
+    <ol>
+      <li id="wiki-cite_note-1"><b><a href="#wiki-cite_ref-1">^</a></b> This is a footnote.</li>
+    </ol>
+
+<!--
+## Troubleshooting
+-->
+
+## Development
+
+To see what has changed in recent versions of the `html-pipeline-cite` gem, see the [CHANGELOG](https://github.com/lifted-studios/html-pipeline-cite/blob/master/CHANGELOG.md).
+
+## Core Team Members
+
+* [Lee Dohm](https://github.com/lee-dohm/)
+
+## Resources
+
+<!-- ### Other questions
+
+Feel free to chat with the Lifted Wiki core team (and many other users) on IRC in the  [#project](irc://irc.freenode.net/project) channel on Freenode, or via email on the [Project mailing list]().
+ -->
+
+## Copyright
+
+Copyright © 2013 Lee Dohm, Lifted Studios. See [LICENSE](https://github.com/lifted-studios/html-pipeline-cite/blob/master/LICENSE.md) for details.
+
+Project is a member of the [OSS Manifesto](http://ossmanifesto.com/).

data/Rakefile

@@ -0,0 +1,66 @@
+# 
+# Copyright (c) 2013 by Lifted Studios.  All Rights Reserved.
+# 
+
+require 'bundler/gem_tasks'
+require 'html/pipeline/cite/version'
+require 'rake/clean'
+require 'rake/testtask'
+require 'yard'
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  HTML::Pipeline::Cite::VERSION
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+CLEAN.include('.yardoc')
+CLOBBER.include('doc', 'pkg')
+
+task :default => [:test, :yard]
+
+desc "Execute all tests"
+task :test => [:spec]
+
+Rake::TestTask.new('spec') do |spec|
+  spec.libs << 'spec'
+  spec.test_files = Dir['spec/**/*_spec.rb']
+  # spec.warning = true
+end
+
+YARD::Rake::YardocTask.new
+
+desc 'Build gem'
+task :build do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc 'Create a release build'
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git pull"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+task :install => [:build] do
+  sh "gem install pkg/#{gem_file}"
+end

data/html-pipeline-cite.gemspec

@@ -0,0 +1,42 @@
+# 
+# Copyright (c) 2012-2013 by Lifted Studios.  All Rights Reserved.
+# 
+
+require 'date'
+require File.expand_path('../lib/html/pipeline/cite/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+  s.required_ruby_version = ">= 1.9.3"
+
+  s.name    = 'html-pipeline-cite'
+  s.version = HTML::Pipeline::Cite::VERSION
+  s.date    = Date.today.to_s
+
+  s.summary     = "An HTML::Pipeline filter for WikiMedia-style Cite references."
+  s.description = "An HTML::Pipeline filter for WikiMedia-style Cite references."
+
+  s.authors  = ["Lee Dohm"]
+  s.email    = 'lee@liftedstudios.com'
+  s.homepage = 'https://github.com/lifted-studios/html-pipeline-cite'
+  s.license  = 'MIT'
+
+  s.require_paths = ['lib']
+
+  s.add_dependency('html-pipeline', '>= 0.0.8')
+
+  s.add_development_dependency('minitest', '~> 3.0')
+  s.add_development_dependency('rake', '~> 10.0')
+  s.add_development_dependency('redcarpet')
+  s.add_development_dependency('yard', '~> 0.8')
+
+  s.files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }
+
+  s.test_files = s.files.select { |path| path =~ /^spec\/.*_spec\.rb/ }
+end

data/lib/html/pipeline/cite.rb

@@ -0,0 +1,6 @@
+#
+# Copyright (c) 2013 by Lifted Studios.  All Rights Reserved.
+#
+
+require 'html/pipeline/cite/cite_filter.rb'
+require 'html/pipeline/cite/version.rb'

data/lib/html/pipeline/cite/cite_filter.rb

@@ -0,0 +1,123 @@
+# 
+# Copyright (c) 2012-2013 by Lifted Studios.  All Rights Reserved.
+# 
+
+require 'html/pipeline'
+require 'nokogiri'
+
+module HTML
+  class Pipeline
+    # An `HTML::Pipeline` filter that collects references in the text and inserts a table of footnotes where instructed.
+    # 
+    # Example:
+    # 
+    #     <ref>This is a footnote</ref>
+    # 
+    # Becomes:
+    # 
+    #     <sup class="reference" id="wiki-cite_ref-1">[<a href="#wiki-cite_note-1">1</a>]</sup>
+    # 
+    # It will show up as a bracketed, superscripted and anchored number at that location in the text.  Then when 
+    # `<references/>` is placed in the text, an ordered list of the references and their text will be placed at that
+    # location.  The example above would generate a list that looks like this:
+    # 
+    #     <ol>
+    #       <li id="wiki-cite_note-1"><b><a href="#wiki-cite_ref-1">^</a></b> This is a footnote.</li>
+    #     </ol>
+    # 
+    class CiteFilter < Filter
+      # ID of the note
+      NOTE = 'wiki-cite_note'
+
+      # ID of the ref
+      REF = 'wiki-cite_ref'
+
+      # Replaces ref and references tags with the appropriate HTML and returns the result.
+      # 
+      # @return [Nokogiri::HTML::DocumentFragment] Updated HTML document fragment.
+      def call
+        refs = replace_refs
+        replace_references(refs)
+
+        doc
+      end
+
+      private
+
+      # Creates the link text for the ref node.
+      # 
+      # @param [Integer] index Index of the item.
+      # @return [String] Link text for the ref node replacement.
+      def create_ref_link(index)
+        %Q([<a href="##{NOTE}-#{index}">#{index}</a>])
+      end
+
+      # Creates the HTML to replace the ref node in the document.
+      # 
+      # @param [Nokogiri::XML::Node] node  Node in the document we are working with.
+      # @param [Integer]             index Index of the item.
+      # @return [Nokogiri::XML::Node] Node to replace the `ref` node.
+      def create_ref_node(node, index)
+        ref_node = node.document.create_element('sup', :class => 'reference', :id => "#{REF}-#{index}")
+        ref_node.inner_html = create_ref_link(index)
+        ref_node
+      end
+
+      # Creates the list items text.
+      # 
+      # @param [Array] refs Text to place in the list items.
+      # @return [String] List items text.
+      def create_references_list_items(refs)
+        refs.each_with_index.reduce('') do |inner_html, args|
+          note = args.first
+          num = args[1] + 1
+          inner_html << %Q(<li id="#{NOTE}-#{num}"><b><a href="##{REF}-#{num}">^</a></b> #{note}</li>\n)
+        end
+      end
+
+      # Replaces ref tags with the appropriate HTML and returns the set of reference texts.
+      #
+      # @return [Array] List of texts from the `ref` tags.
+      def replace_refs
+        doc.xpath('.//ref').each_with_index.map do |node, index|
+          text = node.inner_html
+
+          ref_node = create_ref_node(node, index + 1)
+          node.replace(ref_node)
+
+          text
+        end
+      end
+
+      # Replaces references tags with the appropriate HTML.
+      # 
+      # @param [Array] refs List of reference texts.
+      # @return [nil]
+      def replace_references(refs)
+        set = doc.xpath('.//references')
+
+        if set
+          inner_html = create_references_list_items(refs)
+          replace_references_node(set, inner_html)
+        end
+
+        nil
+      end
+
+      # Replaces the references nodes with the ordered list.
+      # 
+      # @param [Nokogiri::XML::NodeSet] set        Set of `references` nodes.
+      # @param [String]                 inner_html Inner HTML to use for the list.
+      # @return [nil]
+      def replace_references_node(set, inner_html)
+        set.each do |references_node|
+          ol_node = references_node.document.create_element "ol"
+          ol_node.inner_html = inner_html
+          references_node.parent.replace(ol_node)
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/html/pipeline/cite/version.rb

@@ -0,0 +1,12 @@
+#
+# Copyright (c) 2013 by Lifted Studios.  All Rights Reserved.
+#
+
+module HTML
+  class Pipeline
+    module Cite
+      # Version of the gem.
+      VERSION = '0.0.1'
+    end
+  end
+end

data/spec/cite_filter_spec.rb

@@ -0,0 +1,73 @@
+# 
+# Copyright (c) 2012-2013 by Lifted Studios.  All Rights Reserved.
+# 
+
+gem 'minitest'
+
+require 'minitest/spec'
+require 'minitest/autorun'
+
+require 'helpers'
+require 'nokogiri'
+require 'html/pipeline/cite'
+
+describe HTML::Pipeline::CiteFilter do
+  # Creates a new basic pipeline object.
+  # 
+  # @return Basic HTML::Pipeline initialized to convert Markdown into HTML.
+  def new_pipeline
+    HTML::Pipeline.new([ HTML::Pipeline::MarkdownFilter ])
+  end
+
+  # Creates a new filter for testing using the given `fragment`.
+  # 
+  # @param fragment Markdown text to convert into HTML and process references.
+  # @return Fully-processed HTML.
+  def new_filter(fragment)
+    if fragment.kind_of? String
+      pipeline = new_pipeline
+      fragment = pipeline.call(fragment)[:output].to_s
+    end
+
+    HTML::Pipeline::CiteFilter.new(fragment)
+  end
+
+  it 'can be instantiated' do
+    filter = new_filter('Some fake document text')
+
+    filter.wont_be_nil
+  end
+
+  it 'will pass through a fragment without references unchanged' do
+    filter = new_filter('Some fake document text')
+
+    text = filter.call.to_s
+
+    text.must_equal '<p>Some fake document text</p>'
+  end
+
+  it 'will replace refs with footnote anchors' do
+    filter = new_filter(read_test_file('simple_reference.md'))
+
+    text = filter.call.to_s
+
+    text.node('ref').count.must_equal 0
+    text.node('sup').count.must_equal 1
+    text.node('sup').attribute('class').value.must_equal 'reference'
+    text.node('sup').attribute('id').value.must_equal 'wiki-cite_ref-1'
+    text.node('sup').inner_html.must_equal '[<a href="#wiki-cite_note-1">1</a>]'
+  end
+
+  it 'will replace references with the ordered list of footnotes' do
+    filter = new_filter(read_test_file('full_reference.md'))
+
+    text = filter.call.to_s
+
+    text.node('references').count.must_equal 0
+    text.node('ol').count.must_equal 1
+    text.node('li').count.must_equal 1
+    text.node('li').attribute('id').value.must_equal 'wiki-cite_note-1'
+    text.node('li').inner_html.must_match(/#wiki-cite_ref-1/)
+    text.node('li').inner_html.must_match(/With a footnote\./)
+  end
+end

data/spec/data/full_reference.md

@@ -0,0 +1,3 @@
+First paragraph<ref>With a footnote.</ref>
+
+<references/>

data/spec/data/simple_reference.md

@@ -0,0 +1 @@
+First paragraph<ref>With footnote</ref>

data/spec/helpers.rb

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2013 by Lifted Studios.  All Rights Reserved.
+#
+
+require 'nokogiri'
+
+class String
+  # Creates an HTML document fragment out of the string's contents and returns the nodes with the matching tags.
+  # 
+  # @param [String] tag Tag to search for.
+  # @return Set of nodes that match the given tag.
+  def node(tag)
+    Nokogiri::make("<div>#{self}</div>").xpath(".//#{tag}")
+  end
+end
+
+# Reads a test data file.
+# 
+# The path passed to the function is treated as relative to the `spec/data` directory.
+# 
+# @param path Path to the test file.
+# @return Text in the file.
+def read_test_file(path)
+  path = File.join('spec/data', path)
+  IO.read(path)
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: html-pipeline-cite
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Lee Dohm
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: html-pipeline
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: An HTML::Pipeline filter for WikiMedia-style Cite references.
+email: lee@liftedstudios.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- html-pipeline-cite.gemspec
+- lib/html/pipeline/cite.rb
+- lib/html/pipeline/cite/cite_filter.rb
+- lib/html/pipeline/cite/version.rb
+- spec/cite_filter_spec.rb
+- spec/data/full_reference.md
+- spec/data/simple_reference.md
+- spec/helpers.rb
+homepage: https://github.com/lifted-studios/html-pipeline-cite
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 2
+summary: An HTML::Pipeline filter for WikiMedia-style Cite references.
+test_files:
+- spec/cite_filter_spec.rb
+has_rdoc: