add --cited_in_order option

see discussion at #44 for details

features/citation.feature

@@ -278,7 +278,7 @@ Feature: Citations
     And the "_site/scholar.html" file should exist
     And I should see "Flanagan" in "_site/scholar.html"
 
-  @tags @cite @variables @data @wip
+  @tags @cite @variables @data
   Scenario: Multiple Citations in a list using liquid variables
     Given I have a scholar configuration with:
       | key          | value             |

features/sorting.feature

@@ -150,3 +150,43 @@ Feature: Sorting BibTeX Bibliographies
     Then "Ruby Programming" should come before "Smalltalk" in "_site/scholar.html"
     And I should not see "<i>Ruby Not Cited</i>" in "_site/scholar.html"
 
+  @tags @sorting @cited_in_order
+  Scenario: Sort By Year Cited in Order
+    Given I have a scholar configuration with:
+      | key     | value             |
+      | sort_by | year              |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{ruby1,
+        title     = {The Ruby Programming Language},
+        author    = {Flanagan, David and Matsumoto, Yukihiro},
+        year      = {2008},
+        publisher = {O'Reilly Media}
+      }
+      @book{ruby2,
+        title     = {Ruby Not Cited},
+        author    = {Flanagan, David and Matsumoto, Yukihiro},
+        year      = {2007},
+        publisher = {O'Reilly Media}
+      }
+      @book{smalltalk,
+        title     = {Smalltalk Best Practice Patterns},
+        author    = {Kent Beck},
+        year      = {1996},
+        publisher = {Prentice Hall}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% cite ruby1 %}
+      {% cite smalltalk %}
+      {% bibliography --cited_in_order %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    Then "Ruby Programming" should come before "Smalltalk" in "_site/scholar.html"
+    And I should not see "<i>Ruby Not Cited</i>" in "_site/scholar.html"

lib/jekyll/scholar/tags/bibliography.rb

@@ -15,15 +15,23 @@ module Jekyll
       def render(context)
         set_context_to context
 
-        references = entries
-
-        references.select! do |e|
-          cited_references.include? e.key
-        end if cited_only?
+        items = entries
+
+        if cited_only?
+          items = if skip_sort?
+            cited_references.uniq.map do |key|
+              items.detect { |e| e.key == key }
+            end
+          else
+            entries.select do |e|
+              cited_references.include? e.key
+            end
+          end
+        end
 
-        references = references.take(max.to_i) if limit_entries?
+        items = items.take(max.to_i) if limit_entries?
 
-        bibliography = references.each_with_index.map { |entry, index|
+        bibliography = items.each_with_index.map { |entry, index|
           reference = bibliography_tag(entry, index + 1)
 
           if generate_details?

lib/jekyll/scholar/utilities.rb

@@ -35,6 +35,10 @@ module Jekyll
             @cited = true
           end
 
+          opts.on('-C', '--cited_in_order') do |cited|
+            @cited, @skip_sort = true, true
+          end
+
           opts.on('-f', '--file FILE') do |file|
             @bibtex_files ||= []
             @bibtex_files << file
@@ -69,7 +73,7 @@ module Jekyll
           end
         end
 
-        argv = arguments.split(/(\B-[cfqptTslm]|\B--(?:cited|file|query|prefix|text|style|template|locator|max|))/)
+        argv = arguments.split(/(\B-[cCfqptTslm]|\B--(?:cited(_in_order)?|file|query|prefix|text|style|template|locator|max|))/)
 
         parser.parse argv.map(&:strip).reject(&:empty?)
       end
@@ -128,7 +132,7 @@ module Jekyll
       end
 
       def sort(unsorted)
-        return unsorted if config['sort_by'] == 'none'
+        return unsorted if skip_sort?
 
         sorted = unsorted.sort_by { |e| e[config['sort_by']].to_s }
         sorted.reverse! if config['order'] =~ /^(desc|reverse)/i
@@ -167,6 +171,10 @@ module Jekyll
         !!@cited
       end
 
+      def skip_sort?
+        @skip_sort || config['sort_by'] == 'none'
+      end
+
       def extend_path(name)
         if name.nil? || name.empty?
           name = config['bibliography']
@@ -327,9 +335,6 @@ module Jekyll
 
       def cite(keys)
         items = keys.map do |key|
-          # dereference variables in current scope
-          key = context.scopes.last[key] || key
-
           if bibliography.key?(key)
             entry = bibliography[key]
             entry = entry.convert(*bibtex_filters) unless bibtex_filters.empty?
@@ -375,6 +380,8 @@ module Jekyll
 
       def keys
         # De-reference keys (in case they are variables)
+        # We need to do this every time, to support for loops,
+        # where the context can change for each invocation.
         Array(@keys).map do |key|
           context.send(:resolve, key) || key
         end