asciidoctor-bibtex 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d66291de5bde00c8773c279133b29d5c2a70735
-  data.tar.gz: a86cb9606d51b1ce9110d2a93c64fa0aa19c92c4
+  metadata.gz: b1b51427daaa173649801301b8eec0d06c9d1f33
+  data.tar.gz: 77424fb797d99b1f89f43b0f2f0120c62f9eb6fa
 SHA512:
-  metadata.gz: e7c0a804b7ce6f69df4a80bccb8ad22f62a1b946ca5eeba9840b93563311f5efe5ba3c32d236e829b0ce98d685a3e070ca677fbec92b46ecf9fbd3f5c1083b5b
-  data.tar.gz: 76e579bd5924ed9c38d6c0142b9bfa4ca4b29b36bf5a573817d72de911ebe430d009d182b9878dd51911b3290cdd425f05a574a98c73b4b50d90b6e8edd32f41
+  metadata.gz: eb4354f3d0bb64ca209c47734697c82a57e5284f943b2c6d3187b873a8346532eed91c33746bc08375bd86ac699a8e549aa6c816b8f8cb841404bbb00417be94
+  data.tar.gz: c21d7fda35a0fa9f5b941efe31684d814403fc5c2df434cd2d01e34abf48e1e4e050fd37625ab9aa09b60916cf605faab1a8f2375ae159d32f66287873435a0f

data/README.md

@@ -0,0 +1,128 @@
+# asciidoctor-bibtex: add bibtex functionality to asciidoc
+
+asciidoctor-bibtex is a fork of [asciidoc-bib](https://github.com/petercrlane/asciidoc-bib) It generates in-text references and a reference list for an asciidoc file, using a bibtex file as a source of citation information. However, asciidoctor-bibtex proposes a different citation and reference grammar, which resembles the bibtex grammar in LaTeX. The grammar follows asciidoc inline and block macro semantics.
+
+## Why a fork
+
+When I began switching from latex/word to asciidoc, I searched for an easy way to integrate bibtex like references into asciidoc. Then I came across asciidoc-bib, which nearly meet my needs. I can insert citations, generate automatically a complete reference list. But there are aspects in asciidoc-bib that are not pleasing to work with.
+
+The first is the overriding of `[bibliography]`. Asciidoctor introduces `[xxx]` as an mechanism to customize block styles, roles, etc.  `[bibliography]` is reserved for the bibliography section style. asciidoc-bib breaks it and there is no apparent way to fix it.
+
+The second is the grammar inconsistency with the rest of asciidoc. The `[cite:xxx]` is actually an inline macro but it does not follow the grammar of inline macros. This makes asciidoc-bib not that confortable to write with since it breaks the semantic memory.
+
+The last is asciidoc-bib does not support asciidoctor arguments and extensions. So I can not use asciidoctor-pdf with it.
+
+To accommodate the above problems, I create this fork. This fork tries to be as consistent with asciidoctor as possible. 
+
+## Features
+
+- bibtex-like syntax for adding a citation within text and placing bibliography
+- formatting of references and reference list according to range of styles supported by citeproc-ruby
+- supports some styling of citation text (page numbers, bracket placement)
+- can be used as an asciidoctor extension
+
+## Install
+
+    gem install asciidoctor-bibtex
+
+Installs two executable programs:
+
+- 'asciidoc-bibtex' for transforming source text into asciidoc 
+- 'asciidoctor-bibtex' uses asciidoctor extension for single-pass output
+
+asciidoctor-bibtex depends on [bibtex-ruby](http://github.com/inukshuk/bibtex-ruby), [citeproc-ruby](http://github.com/inukshuk/citeproc-ruby) and [csl-styles](http://github.com/inukshuk/csl-styles).  (Ensure 'ruby-dev' and 'libxslt1-dev' are installed, so the dependencies will compile.)
+
+[asciidoctor](https://github.com/asciidoctor/asciidoctor) must also be installed for 'asciidoctor-bibtex' to work. asciidoctor version 1.5.2 or higher is required.
+
+## Usage
+
+There are three ways of using asciidoctor-bibtex.
+
+The first is required if using _asciidoc_.  'asciidoc-bibtex' works by transforming an asciidoc document containing syntax to include citations and a bibliography. The transformed document will contain a complete reference and bibliography list where indicated, and can then be processed further by asciidoc's toolchain to produce a completed document.
+
+The second is to use 'asciidoctor-bibtex' to transform your bibtex-enabled documents directly to any backend format supported by asciidoctor. It uses the asciidoctor extension mechanism to hook in the asciidoctor preprocessing process. It support all asciidoctor command-line options.
+
+The third is to use asciidoctor-bibtex as an asciidoctor extension. It works the same way as the second approach. In addition, one can use other extensions together to provides even richer functionality. 
+
+Styles must be one of those supported by CSL: https://github.com/citation-style-language/styles
+
+### Citation syntax
+
+Syntax for inserting a citation is the following inline macro:
+
+    cite|citenp:[ref(pages)]
+
+where '(pages)' is optional.  The ref and optional pages may be repeated multiple times, separated by ','.  A citation _must_ be complete on a single line of text.
+
+Examples of "chicago-author-date" style:
+
+`cite:[Lane12]` becomes "(Lane 2012)"
+
+`citenp:[Lane12]` becomes "Lane (2012)"
+
+`cite:[Lane12(59)]` becomes "(Lane 2012, 59)"
+
+For *apa* (Harvard-like) style:
+
+`cite:[Lane12]` becomes "(Lane, 2012)"
+
+`citenp:[Lane12]` becomes "Lane (2012)"
+
+`cite:[Lane12(59)]` becomes "(Lane, 2012, p.59)"
+
+For *ieee*, a numeric style:
+
+`cite:[Lane12,Lane11]` becomes "[1, 2]"
+
+### Place bibliography in text
+
+`bibliography::[]` on a line by itself.
+
+### Processing Text: Asciidoctor
+
+    asciidoctor-bibtex [OPTIONS] filename
+
+Looks for a bib file in current folder and in ~/Documents.
+
+Outputs an html file, including all citations and references.
+
+asciidoctor-bibtex support all command-line options of asciidoctor, for example, use the follow command to output docbook file:
+
+    asciidoctor-bibtex -b docbook filename
+
+One may also use as an asciidoctor extension, for example:
+
+    asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf filename
+
+Options are set through the command-line using the asciidoctor attributes
+setting syntax:
+
+  > asciidoctor-bibtex -h
+
+  ...
+  AsciidoctorBibtex related options:
+
+      -a bib-file=FILENAME    Set BibTex filename (default: auto-find)
+      -a bib-style=STYLE      Set BibTex items style (default: apa)
+      -a bib-numeric-order=<alphabetical|appearance>
+                            Set citation order scheme (default: alphabetical)
+      -a bib-no-links=1       Do not use links (default: use links)
+
+### Processing text: Asciidoc
+
+    asciidoc-bibtex filename.txt
+
+Looks for a bib file in current folder and in ~/Documents.
+
+Outputs a new file: filename-ref.txt which includes your references.
+
+asciidoc-bibtex supports the same command-line options as asciidoc-bib. The only difference is the citation and bibliography syntex.
+
+## License
+
+The files within this project may be distributed under the terms of 
+the Open Works License: http://owl.apotheon.org
+
+## Links
+
+See https://github.com/petercrlane/asciidoc-bib for the original asciidoc-bib.

data/bin/asciidoctor-bibtex

@@ -35,11 +35,10 @@ if not (ARGV & ['-h', '--help']).empty?
   puts ""
   puts "AsciidoctorBibtex related options:"
   puts ""
-  puts "    -a bib-file=FILENAME    Set BibTex filename (default: auto-find)"
-  puts "    -a bib-style=STYLE      Set BibTex items style (default: apa)"
-  puts "    -a bib-numeric-order=<alphabetical|appearance>"
+  puts "    -a bibtex-file=FILENAME    Set BibTex filename (default: auto-find)"
+  puts "    -a bibtex-style=STYLE      Set BibTex items style (default: apa)"
+  puts "    -a bibtex-order=<alphabetical|appearance>"
   puts "                            Set citation order scheme (default: alphabetical)"
-  puts "    -a bib-no-links=1       Do not use links (default: use links)"
   puts ""
   exit 0
 end

data/lib/asciidoctor-bibtex/asciidoctor.rb

@@ -2,5 +2,6 @@ require 'asciidoctor/extensions'
 require_relative 'bibextension'
 
 Asciidoctor::Extensions.register do
-  preprocessor AsciidoctorBibtex::Asciidoctor::AsciidoctorBibtexExtension
+  block_macro AsciidoctorBibtex::Asciidoctor::BibliographyBlockMacro
+  treeprocessor AsciidoctorBibtex::Asciidoctor::CitationProcessor
 end

data/lib/asciidoctor-bibtex/bibextension.rb

@@ -1,65 +1,138 @@
-# Uses Asciidoctor extension mechanism to insert asciidoc-bib processing
-# as a preprocessor step.  This provides single-pass compilation of 
-# documents, including citations and references.
 #
-# Copyright (c) Peter Lane, 2013.
-# Released under Open Works License, 0.9.2
+# Treeprocessor extension for asciidoctor
+#
 
 require 'asciidoctor'
 require 'asciidoctor/extensions'
-require 'asciidoctor/cli'
-require_relative 'options'
+require 'asciidoctor/reader'
+require 'asciidoctor/parser'
+require_relative 'styles'
+require_relative 'filehandlers'
 
 module AsciidoctorBibtex
   module Asciidoctor
+    BibliographyBlockMacroPlaceholder = %(BIBLIOGRAPHY BLOCK MACRO PLACEHOLDER)
+
+    # This macro processor does only half the work. It just parse the macro
+    # and set bibtex file and style if found in the macro. The macro is then
+    # expanded to a special paragraph, which is then replaced with generated
+    # references by the treeprocessor.
+    class BibliographyBlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
+      use_dsl
+      named :bibliography
+      positional_attributes :style
+
+      def process parent, target, attrs
+        # NOTE: bibtex-file and bibtex-style set by this macro shall be
+        # overridable by document attributes and commandline arguments. So we
+        # respect the convention here.
+        if target and not parent.document.attr? 'bibtex-file'
+          parent.document.set_attribute 'bibtex-file', target
+        end
+        if attrs.key? :style and not parent.document.attr? 'bibtex-style'
+          parent.document.set_attribute 'bibtex-style', attrs[:style]
+        end
+        create_paragraph parent, BibliographyBlockMacroPlaceholder, {}
+      end
+    end
 
-    class AsciidoctorBibtexExtension < ::Asciidoctor::Extensions::Preprocessor
-
-      def process document, reader
-        return reader if reader.eof?
-
-        options = Options.new
-        options.parse_attributes document.attributes
-
-        # -- read in all lines from reader, processing the lines
+    # This processor scans the document, generates a list of citations,
+    # replace each citation with correct text and the reference block macro
+    # placeholder with the final reference list. It relys on the block macro
+    # processor to generate the place holder.
+    class CitationProcessor < ::Asciidoctor::Extensions::Treeprocessor
 
-        lines = reader.readlines
-        biblio = BibTeX.open options.bibfile
+      def process document
+        bibtex_file = (document.attr 'bibtex-file').to_s
+        bibtex_style = ((document.attr 'bibtex-style') || 'ieee').to_s
+        bibtex_order = ((document.attr 'bibtex-order') || 'alphabetical').to_sym
+        bibtex_output = ((document.attr 'bibtex-output') || 'asciidoc').to_sym
 
-        processor = Processor.new biblio, options.links, options.style
-        lines.each do |line|
-          processor.citations.add_from_line line
+        if bibtex_file.empty?
+          bibtex_file = AsciidoctorBibtex::FileHandlers.find_bibliography "."
+        end
+        if bibtex_file.empty?
+          bibtex_file = AsciidoctorBibtex::FileHandlers.find_bibliography "#{ENV['HOME']}/Documents"
+        end
+        if bibtex_file.empty?
+          puts "Error: bibtex-file is not set and automatic search failed"
+          exit
         end
 
-        # -- replace cites with correct text
+        bibtex = BibTeX.open bibtex_file
+        processor = Processor.new bibtex, true, bibtex_style, bibtex_order == :appearance, bibtex_output
+
+        prose_blocks = document.find_by {|b| b.content_model == :simple or b.context == :list_item}
+        prose_blocks.each do |block|
+          if block.context == :list_item
+            line = block.instance_variable_get :@text
+            processor.citations.add_from_line line
+          else
+            block.lines.each do |line|
+              processor.citations.add_from_line line
+            end
+          end
+        end
 
-        lines.each do |line|
-          processor.citations.retrieve_citations(line).each do |citation|
-            line.gsub!(citation.original, processor.complete_citation(citation))
+        prose_blocks.each do |block|
+          if block.context == :list_item
+            line = block.instance_variable_get :@text
+            processor.citations.retrieve_citations(line).each do |citation|
+              line.gsub!(citation.original, processor.complete_citation(citation))
+            end
+            block.instance_variable_set :@text, line
+          else
+            block.lines.each do |line|
+              processor.citations.retrieve_citations(line).each do |citation|
+                line.gsub!(citation.original, processor.complete_citation(citation))
+              end
+            end
           end
         end
 
-        # -- add in bibliography
+        references_asciidoc = []
+        if bibtex_output == :latex
+          references_asciidoc << %(+++\\bibliography{#{bibtex_file}}{}+++)
+          references_asciidoc << %(+++\\bibliographystyle{#{bibtex_style}}+++)
+        else
+          processor.cites.each do |ref|
+            references_asciidoc << processor.get_reference(ref)
+            references_asciidoc << ''
+          end
+        end
 
-        biblio_index = lines.index do |line|
-          # find bibliography macro on line by itself, with or without newline
-          (line =~ BIBMACRO_FULL) != nil
+        biblio_blocks = document.find_by do |b|
+          # for fast search (since most searches shall fail)
+          b.content_model == :simple and b.lines.size == 1 \
+            and b.lines[0] == BibliographyBlockMacroPlaceholder
         end
-        unless biblio_index.nil?
-          lines.delete_at biblio_index
-          processor.sorted_cites.reverse.each do |ref|
-            lines.insert biblio_index, "\n"
-            lines.insert biblio_index, processor.get_reference(ref)
-            lines.insert biblio_index, "[normal]\n" # ? needed to force paragraph breaks
+        biblio_blocks.each do |block|
+          block_index = block.parent.blocks.index do |b|
+            b == block
+          end
+          reference_blocks = parse_asciidoc block.parent, references_asciidoc
+          reference_blocks.reverse.each do |b|
+            block.parent.blocks.insert block_index, b
           end
+          block.parent.blocks.delete_at block_index + reference_blocks.size
         end
 
-        reader.unshift_lines lines
+        nil
+      end
 
-        return reader
+      # This is an adapted version of Asciidoctor::Extension::parse_content,
+      # where resultant blocks are returned as a list instead of attached to
+      # the parent.
+      def parse_asciidoc parent, content, attributes = {}
+        result = []
+        reader = ::Asciidoctor::Reader.new content
+        while reader.has_more_lines?
+          block = ::Asciidoctor::Parser.next_block reader, parent, attributes
+          result << block if block
+        end
+        result
       end
 
-      BIBMACRO_FULL = /bibliography::(.*?)\[(\w+)?\]/
     end
 
   end

data/lib/asciidoctor-bibtex/options.rb

@@ -8,7 +8,7 @@ require 'optparse'
 
 module AsciidoctorBibtex
   class Options
-    attr_reader :bibfile, :filename, :links, :style
+    attr_reader :bibfile, :filename, :links, :style, :output
 
     def initialize(program_name = 'asciidoc-bibtex')
       @bibfile = ''
@@ -16,6 +16,7 @@ module AsciidoctorBibtex
       @numeric_order = :alphabetical
       @style = AsciidoctorBibtex::Styles.default_style
       @program_name = program_name
+      @output = "asciidoc"
     end
 
     # Public: Parse options from commandline.
@@ -47,6 +48,9 @@ module AsciidoctorBibtex
         opts.on("-s", "--style STYLE", "reference style") do |v|
           @style = v
         end
+        opts.on("--output-style OUTPUT_STYLE", "Output style (asciidoc or latex)") do |v|
+          @output = v
+        end
         opts.on("-v", "--version", "show version") do |v|
           puts "#{@program_name} version #{AsciidoctorBibtex::VERSION}"
           exit!
@@ -86,30 +90,50 @@ module AsciidoctorBibtex
       puts "Reading biblio: #{@bibfile}"
       puts "Reference style: #{@style}"
       puts "Numerical order: #{@numeric_order}"
+      puts "Output style: #{@output}"
     end
     
     # Public: Parse values given `attrs`
     # This function is used by asciidoctor preprocessor to determine options
-    # from document attributes.
-    def parse_attributes(attrs)
-      if attrs['bib-style']
-        @style = attrs['bib-style']
+    # from document attributes. According to the attribute preccedence rule,
+    # attrs_cli > attrs_src > default
+    def parse_attributes(attrs_cli, attrs_src)
+      if attrs_cli['bib-style']
+        @style = attrs_cli['bib-style']
+      elsif attrs_src['bib-style']
+        @style = attrs_src['bib-style']
       end
-      if attrs['bib-file']
-        @bibfile = attrs['bib-file']
+      if attrs_cli['bib-file']
+        @bibfile = attrs_cli['bib-file']
+      elsif attrs_src['bib-file']
+        @bibfile = attrs_src['bib-file']
       end
-      if attrs['bib-numeric-order']
-        order = attrs['bib-numeric-order']
-        if order == "appearance"
-          @numeric_order = :appearance
-        elsif order == "alphabetical"
-          @numeric_order = :alphabetical
-        else
-          raise RuntimeError.new "Unknown numeric order: #{order}"
-        end
+      order = nil
+      if attrs_cli['bib-numeric-order']
+        order = attrs_cli['bib-numeric-order']
+      elsif attrs_src['bib-numeric-order']
+        order = attrs_src['bib-numeric-order']
+      end
+      if order == nil
+        @numeric_order = :appearance
+      elsif order == "appearance"
+        @numeric_order = :appearance
+      elsif order == "alphabetical"
+        @numeric_order = :alphabetical
+      else
+        raise RuntimeError.new "Unknown numeric order: #{order}"
       end
-      if attrs['bib-no-links']
+      if attrs_cli['bib-no-links']
         @links = false
+      elsif attrs_src['bib-no-links']
+        @links = false
+      end
+      if attrs_cli['bib-output']
+        @output = attrs_cli['bib-output']
+      elsif attrs_src['bib-output']
+        @output = attrs_src["bib-output"]
+      else
+        @output = "asciidoc"
       end
 
       # unless specified by caller, try to find the bibliography
@@ -118,6 +142,9 @@ module AsciidoctorBibtex
         if @bibfile.empty?
           @bibfile = AsciidoctorBibtex::FileHandlers.find_bibliography "#{ENV['HOME']}/Documents"
         end
+      elsif not File.file? @bibfile
+        puts "Error: bibliography file '#{@bibfile}' does not exist"
+        exit
       end
       if @bibfile.empty?
         puts "Error: could not find a bibliography file"
@@ -131,6 +158,7 @@ module AsciidoctorBibtex
       puts "Reading biblio: #{@bibfile}"
       puts "Reference style: #{@style}"
       puts "Numerical order: #{@numeric_order}"
+      puts "Output style: #{@output}"
     end
 
     def numeric_in_appearance_order?
@@ -138,4 +166,3 @@ module AsciidoctorBibtex
     end
   end
 end
-

data/lib/asciidoctor-bibtex/processor.rb

@@ -1,36 +1,40 @@
 #
-# Manage the current set of citations, the document settings, 
+# Manage the current set of citations, the document settings,
 # and main operations.
 #
 
 module AsciidoctorBibtex
 
-  # Class used through utility method to hold data about citations for 
-  # current document, and run the different steps to add the citations 
+  # Class used through utility method to hold data about citations for
+  # current document, and run the different steps to add the citations
   # and bibliography
   class Processor
     include ProcessorUtils
 
     # Top-level method to include citations in given asciidoc file
     def Processor.run options
-      processor = Processor.new BibTeX.open(options.bibfile), options.links, options.style, options.numeric_in_appearance_order?
+      processor = Processor.new BibTeX.open(options.bibfile), options.links, options.style, options.numeric_in_appearance_order?, options.output, options.bibfile
       processor.read_filenames options.filename
-      processor.read_citations 
+      processor.read_citations
       processor.add_citations
     end
 
     attr_reader :biblio, :links, :style, :citations
 
-    def initialize biblio, links, style, numeric_in_appearance_order = false
+    def initialize biblio, links, style, numeric_in_appearance_order = false, output = :asciidoc, bibfile = ""
       @biblio = biblio
       @links = links
       @numeric_in_appearance_order = numeric_in_appearance_order
       @style = style
       @citations = Citations.new
       @filenames = Set.new
+      @output = output
+      @bibfile = bibfile
 
-      @citeproc = CiteProc::Processor.new style: @style, format: :html
-      @citeproc.import @biblio.to_citeproc
+      if output != :latex
+        @citeproc = CiteProc::Processor.new style: @style, format: :html
+        @citeproc.import @biblio.to_citeproc
+      end
     end
 
     # Given an asciidoc filename, reads in all dependent files based on 'include::' statements
@@ -45,7 +49,7 @@ module AsciidoctorBibtex
           if line.include?("include::")
             line.split("include::").drop(1).each do |filetxt|
               file = File.expand_path(filetxt.partition(/\s|\[/).first)
-                files_to_process << file unless @filenames.include?(file)
+              files_to_process << file unless @filenames.include?(file)
             end
           end
         end
@@ -53,12 +57,12 @@ module AsciidoctorBibtex
     end
 
     # Scans each filename and extracts citations
-    def read_citations 
+    def read_citations
       @filenames.each do |file|
         IO.foreach(file) do |line|
           @citations.add_from_line line
         end
-      end 
+      end
     end
 
     # Read given text to add cites and biblio to a new file
@@ -66,15 +70,15 @@ module AsciidoctorBibtex
     # If no author present, then use editor field.
     # Links indicates if internal links to be added.
     # Assumes @filenames has been set to list of filenames to process.
-    def add_citations 
+    def add_citations
       @filenames.each do |curr_file|
         ref_filename = FileHandlers.add_ref(curr_file)
-        puts "Writing file:	#{ref_filename}"
+        puts "Writing file: #{ref_filename}"
         output = File.new(ref_filename, "w")
 
         IO.foreach(curr_file) do |line|
           begin # catch any errors, and ensure the lines of text are written
-            case 
+            case
             when line.include?('include::')
               output_include_line output, line
             when (line =~ BIBMACRO_FULL) != nil
@@ -88,26 +92,31 @@ module AsciidoctorBibtex
         end
 
         output.close
-      end 
+      end
     end
 
     # Output bibliography to given output
     def output_bibliography output
-      cites = if Styles.is_numeric?(@style) and @numeric_in_appearance_order
-                @citations.cites_used 
-              else 
-                sorted_cites 
-              end
-      cites.each do |ref|
-        output.puts get_reference(ref)
-        output.puts
+      if @output == :asciidoc
+        cites = if Styles.is_numeric?(@style) and @numeric_in_appearance_order
+                  @citations.cites_used
+                else
+                  sorted_cites
+                end
+        cites.each do |ref|
+          output.puts get_reference(ref)
+          output.puts
+        end
+      else
+        output.puts "++\\bibliography{#{@bibfile}}++"
+        output.puts "++\\bibliographystyle{#{@style}}++"
       end
     end
 
     def output_include_line output, line
       line.split("include::").drop(1).each do |filetxt|
         ifile = filetxt.partition(/\s|\[/).first
-        file = File.expand_path ifile 
+        file = File.expand_path ifile
         # make sure included file points to the -ref version
         line.gsub!("include::#{ifile}", "include::#{FileHandlers.add_ref(file)}")
       end
@@ -125,38 +134,58 @@ module AsciidoctorBibtex
 
     # Return the complete citation text for given cite_data
     def complete_citation cite_data
-      result = ''
-      ob, cb = '(', ')'
-
-      cite_data.cites.each_with_index do |cite, index|
-        # before all items apart from the first, insert appropriate separator
-        result << "#{separator} " unless index.zero?
-
-        # @links requires adding hyperlink to reference
-        result << "<<#{cite.ref}," if @links
-
-        # if found, insert reference information
-        unless biblio[cite.ref].nil?
-          item = biblio[cite.ref].clone
-          cite_text, ob, cb = make_citation item, cite.ref, cite_data, cite
-        else
-          puts "Unknown reference: #{cite.ref}"
-          cite_text = "#{cite.ref}"
+
+      if @output == :latex
+        result = '+++'
+        cite_data.cites.each do |cite|
+          # NOTE: xelatex does not support "\citenp", so we output all
+          # references as "cite" here.
+          # result << "\\" << cite_data.type
+          result << "\\" << 'cite'
+          if cite.pages != ''
+            result << "[p. " << cite.pages << "]"
+          end
+          result << "{" << "#{cite.ref}" << "},"
+        end
+        if result[-1] == ','
+          result = result[0..-2]
         end
+        result << "+++"
+        return result
+      else
+        result = ''
+        ob, cb = '(', ')'
+
+        cite_data.cites.each_with_index do |cite, index|
+          # before all items apart from the first, insert appropriate separator
+          result << "#{separator} " unless index.zero?
+
+          # @links requires adding hyperlink to reference
+          result << "<<#{cite.ref}," if @links
+
+          # if found, insert reference information
+          unless biblio[cite.ref].nil?
+            item = biblio[cite.ref].clone
+            cite_text, ob, cb = make_citation item, cite.ref, cite_data, cite
+          else
+            puts "Unknown reference: #{cite.ref}"
+            cite_text = "#{cite.ref}"
+          end
 
-        result << cite_text.html_to_asciidoc
-        # @links requires finish hyperlink
-        result << ">>" if @links
-      end
+          result << cite_text.html_to_asciidoc
+          # @links requires finish hyperlink
+          result << ">>" if @links
+        end
 
-      unless @links
-        # combine numeric ranges
-        if Styles.is_numeric? @style
-          result = combine_consecutive_numbers result
+        unless @links
+          # combine numeric ranges
+          if Styles.is_numeric? @style
+            result = combine_consecutive_numbers result
+          end
         end
-      end
 
-      include_pretext result, cite_data, ob, cb
+        return include_pretext result, cite_data, ob, cb
+      end
     end
 
     # Retrieve text for reference in given style
@@ -218,14 +247,14 @@ module AsciidoctorBibtex
 
       if Styles.is_numeric? @style
         "#{pretext}#{ob}#{result}#{cb}"
-      elsif cite_data.type == "cite" 
+      elsif cite_data.type == "cite"
         "#{ob}#{pretext}#{result}#{cb}"
-      else 
+      else
         "#{pretext}#{result}"
       end
     end
 
-    # Numeric citations are handled by computing the position of the reference 
+    # Numeric citations are handled by computing the position of the reference
     # in the list of used citations.
     # Other citations are formatted by citeproc.
     def make_citation item, ref, cite_data, cite
@@ -250,19 +279,27 @@ module AsciidoctorBibtex
       elsif cite_data.type == "citenp"
         cite_text.gsub!(item.year, "#{fc}#{item.year}#{page_str(cite)}#{lc}")
         cite_text.gsub!(", #{fc}", " #{fc}")
-      else 
+      else
         cite_text << page_str(cite)
       end
 
       cite_text.gsub!(",", "&#44;") if @links # replace comma
 
-        return cite_text, fc, lc
+      return cite_text, fc, lc
     end
 
     def sorted_cites
       @citations.sorted_cites @biblio
     end
 
+    def cites
+      if Styles.is_numeric?(@style) and @numeric_in_appearance_order
+        @citations.cites_used
+      else
+        sorted_cites
+      end
+    end
+
     BIBMACRO_FULL = /bibliography::(.*?)\[(\w+)?\]/
   end
 end

data/lib/asciidoctor-bibtex/version.rb

@@ -1,3 +1,3 @@
 module AsciidoctorBibtex
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/samples/biblio.bib

@@ -6,7 +6,7 @@
 }
 
 @book{Lane12b,
-	author = {P. Lane and D. Smith},
+	author = {K. Mane and D. Smith},
 	title =	 {Book title},
 	publisher = {Publisher},
 	year =	 {2000}

data/samples/sample-1.adoc

@@ -0,0 +1,38 @@
+= Sample of using asciidoctor-bibtex
+:bibtex-file: biblio.bib
+:bibtex-order: alphabetical
+:bibtex-style: ieee
+
+The bibliography is searched in the folder of the document, and then in
+~/Documents.
+
+Author-year references can use different styles such as: cite:[Lane12b] or
+citenp:[Lane12a].
+
+Page numbers can be added: cite:[Lane12a(89)] or citenp:[Lane12a(89-93)].
+
+A bit of pretext can be included too: See cite:[Lane12a(89)]
+
+We can include other files, which are also processed:
+
+include::sample-2.adoc[]
+
+To include the reference list, use the section template before title, to
+prevent problems with a2x.
+
+References can be inserted in lists, too:
+
+1. See cite:[Lane12a].
+2. See cite:[Anderson98].
+3. See cite:[Anderson04].
+
+Also works for unordered list:
+
+* See cite:[Lane12a].
+* See cite:[Anderson98].
+* See cite:[Anderson04].
+
+[sect2] 
+== Bibliography
+
+bibliography::biblio.bib[ieee]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-bibtex
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Zhang YANG
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-25 00:00:00.000000000 Z
+date: 2016-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bibtex-ruby
@@ -16,78 +16,60 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.11
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.11
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: citeproc-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.5
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.5
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: csl-styles
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.1.6
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.1.6
+        version: '1'
 description: |
   asciidoctor-bibtex is a fork of asciidoc-bib. It generates in-text references
-  and a reference list for an asciidoc file, using a bibtex file as a source of
-  citation information. The citation syntax tries to assemble asciidoc inline
-  macros and block macros, with `cite:[bibref]` for in-text citation and
-  `bibliography::[]` for reference list. It can be used standalone or as an
-  asciidoctor extension. See the README for more examples and further options.
-  The references are formatted using styles provided by CSL.
+  and reference lists for asciidoc files, using specified bibtex file as
+  ciatation source.  The citation syntax follows asciidoc inline and block macro
+  idiom and resembles bibtex macros, with `cite:[bibref]` or `citenp:[bibref]`
+  for in-text citation and `bibliography::[]` for reference list. It can be used
+  standalone or as an asciidoctor extension. See the README for more examples
+  and further options.  The references are formatted using styles provided by
+  CSL.
 email: zyangmath@gmail.com
 executables:
 - asciidoctor-bibtex
 - asciidoc-bibtex
 extensions: []
-extra_rdoc_files:
-- README.rdoc
+extra_rdoc_files: []
 files:
 - LICENSE.txt
-- README.rdoc
+- README.md
 - bin/asciidoc-bibtex
 - bin/asciidoctor-bibtex
 - lib/asciidoctor-bibtex.rb
@@ -105,8 +87,8 @@ files:
 - lib/asciidoctor-bibtex/styles.rb
 - lib/asciidoctor-bibtex/version.rb
 - samples/biblio.bib
-- samples/sample-1.txt
-- samples/sample-2.txt
+- samples/sample-1.adoc
+- samples/sample-2.adoc
 homepage: https://github.com/ProgramFan/asciidoctor-bibtex
 licenses:
 - OWL
@@ -127,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.6.6
 signing_key: 
 specification_version: 4
 summary: asciidoctor-bibtex adds bibtex references to an asciidoc file.

data/README.rdoc

@@ -1,166 +0,0 @@
-= asciidoctor-bibtex: add bibtex functionality to asciidoc
-
-asciidoctor-bibtex is a fork of
-{asciidoc-bib}[https://github.com/petercrlane/asciidoc-bib] It generates in-text
-references and a reference list for an asciidoc file, using a bibtex file as a
-source of citation information. However, asciidoctor-bibtex proposes a
-different citation and reference grammar, which resembles the bibtex grammar
-in LaTeX. The grammar follows asciidoc inline and block macro semantics.
-
-== Why a fork
-
-When I began switching from latex/word to asciidoc, I searched for an easy way
-to integrate bibtex like references into asciidoc. Then I came across
-asciidoc-bib, which nearly meet my needs. I can insert citations, generate
-automatically a complete reference list. But there are aspects in asciidoc-bib
-that are not pleasing to work with.
-
-The first is the overriding of `[bibliography]`. Asciidoctor introduces
-`[xxx]` as an mechanism to customize block styles, roles, etc.
-`[bibliography]` is reserved for the bibliography section style. asciidoc-bib
-breaks it and there is no apparent way to fix it.
-
-The second is the grammar inconsistency with the rest of asciidoc. The
-`[cite:xxx]` is actually an inline macro but it does not follow the grammar of
-inline macros. This makes asciidoc-bib not that confortable to write with
-since it breaks the semantic memory.
-
-The last is asciidoc-bib does not support asciidoctor arguments and
-extensions. So I can not use asciidoctor-pdf with it.
-
-To accommodate the above problems, I create this fork. This fork tries to be
-as consistent with asciidoctor as possible. 
-
-== Features
-
-- bibtex-like syntax for adding a citation within text and placing bibliography
-- formatting of references and reference list according to range of styles supported by citeproc-ruby
-- supports some styling of citation text (page numbers, bracket placement)
-- can be used as an asciidoctor extension
-
-== Install
-
- > gem install asciidoctor-bibtex
-
-Installs two executable programs:
-
-- 'asciidoc-bibtex' for transforming source text into asciidoc 
-- 'asciidoctor-bibtex' uses asciidoctor extension for single-pass output
-
-asciidoctor-bibtex depends on bibtex-ruby[http://github.com/inukshuk/bibtex-ruby],
-citeproc-ruby[http://github.com/inukshuk/citeproc-ruby] and
-csl-styles[http://github.com/inukshuk/csl-styles].
-(Ensure 'ruby-dev' and 'libxslt1-dev' are installed, so the dependencies will 
-compile.)
-
-asciidoctor[https://github.com/asciidoctor/asciidoctor] must also be installed
-for 'asciidoctor-bibtex' to work. asciidoctor version 1.5.2 or higher is
-required.
-
-== Use 
-
-There are three ways of using asciidoctor-bibtex.
-
-The first is required if using _asciidoc_.
-'asciidoc-bibtex' works by transforming an asciidoc document containing syntax 
-to include citations and a bibliography. The transformed document will 
-contain a complete reference and bibliography list where indicated, and 
-can then be processed further by asciidoc's toolchain to produce a completed 
-document.
-
-The second is to use 'asciidoctor-bibtex' to transform your bibtex-enabled
-documents directly to any backend format supported by asciidoctor. It uses the
-asciidoctor extension mechanism to hook in the asciidoctor preprocessing
-process. It support all asciidoctor command-line options.
-
-The third is to use asciidoctor-bibtex as an asciidoctor extension. It works
-the same way as the second approach. In addition, one can use other extensions
-together to provides even richer functionality. 
-
-Styles must be one of those supported by CSL: https://github.com/citation-style-language/styles
-
-=== Citation syntax
-
-Syntax for inserting a citation is the following inline macro:
-
-    cite|citenp:[ref(pages)]
-
-where '(pages)' is optional.  The ref and optional pages may be repeated
-multiple times, separated by ','.  A citation _must_ be complete on a single
-line of text.
-
-Examples of +chicago-author-date+ style:
-
-[cite:[Lane12]] becomes "(Lane 2012)"
-
-[citenp:[Lane12]] becomes "Lane (2012)"
-
-[cite:[Lane12(59)]] becomes "(Lane 2012, 59)"
-
-For +apa+ (Harvard-like) style:
-
-[cite:[Lane12]] becomes "(Lane, 2012)"
-
-[citenp:[Lane12]] becomes "Lane (2012)"
-
-[cite:[Lane12(59)]] becomes "(Lane, 2012, p.59)"
-
-For +ieee+, a numeric style:
-
-[cite:[Lane12,Lane11]] becomes "[1, 2]"
-
-=== Place bibliography in text
-
-[bibliography::[]] on a line by itself.
-
-=== Processing Text: Asciidoctor
-
-  > asciidoctor-bibtex [OPTIONS] filename
-
-Looks for a bib file in current folder and in ~/Documents.
-
-Outputs an html file, including all citations and references.
-
-asciidoctor-bibtex support all command-line options of asciidoctor, for
-example, use the follow command to output docbook file:
-
-  asciidoctor-bibtex -b docbook filename
-
-One may also use as an asciidoctor extension, for example:
-
-  asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf filename
-
-Options are set through the command-line using the asciidoctor attributes
-setting syntax:
-
-  > asciidoctor-bibtex -h
-
-  ...
-  AsciidoctorBibtex related options:
-
-      -a bib-file=FILENAME    Set BibTex filename (default: auto-find)
-      -a bib-style=STYLE      Set BibTex items style (default: apa)
-      -a bib-numeric-order=<alphabetical|appearance>
-                            Set citation order scheme (default: alphabetical)
-      -a bib-no-links=1       Do not use links (default: use links)
-
-=== Processing text: Asciidoc
-
- > asciidoc-bibtex filename.txt
-
-Looks for a bib file in current folder and in ~/Documents.
-
-Outputs a new file: filename-ref.txt
-which includes your references.  
-
-asciidoc-bibtex supports the same command-line options as asciidoc-bib. The
-only difference is the citation and bibliography syntex.
-
-== License
-
-The files within this project may be distributed under the terms of 
-the Open Works License: http://owl.apotheon.org
-
-== Links
-
-See [https://github.com/petercrlane/asciidoc-bib] for the original asciidoc-bib.

data/samples/sample-1.txt

@@ -1,23 +0,0 @@
-= Sample of using asciidoc-bib =
-
-The bibliography is searched in the folder of the document, and then 
-in ~/Documents.
-
-Author-year references can use different styles such as: cite:[Lane12a] or
-citenp:[Lane12a].
-
-Page numbers can be added: cite:[Lane12a(89)] or citenp:[Lane12a(89-93)].
-
-A bit of pretext can be included too: See cite:[Lane12a(89)]
-
-We can include other files, which are also processed:
-
-include::sample-2.txt[]
-
-To include the reference list, use the section template before
-title, to prevent problems with a2x.
-
-[sect2] 
-== Bibliography ==
-
-bibliography::[]