asciidoctor-bibtex 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89fbb2a41ee997771d88259c171820124f17653e1c98ae047713a6fae009c2bd
-  data.tar.gz: 2b9016dc63a94c2e2127977d3af7771daa92e8e07fc68043b7af609e8c6a7907
+  metadata.gz: cad05b0990309ce242e6f8e83a5a5c0122f07f5a23130d77f740d8c635611162
+  data.tar.gz: '01323158119adf765dfa92c09e0e4a4da63a3bf4ca2b7390a47d687c1b4b2855'
 SHA512:
-  metadata.gz: 418685ec3a7539d86f932fff5d206b688cd42cbf8305f62d2aa7772fcfce7550ec4c2b7c3d1d1c2459623e046ce72bbe4bcbbd7babf9867513168cc5fb92aa2e
-  data.tar.gz: 757ad6e419e4067800ecfa0fec230b5d8d5e99de8af2710d5cd7b955daf05bd826b43d8347031824a5f01c0a0476a06539c82e51ae5daa5a456802bad5b29460
+  metadata.gz: c52687565a3ac2de6a25cf020eabcf3a13732b693ec34bcc0d60c17cd2e526c53e528a08fe7a809a89604f88a027a362e526d769537e363b7de841ed7018178b
+  data.tar.gz: bdd90bb7544d361890da697587c0d2be118a03f7b894e579fd80bdea3d85eefa124f58e605dfcfdf895bde8ef7acc6cfaad4b41838ac9e5d13c005c540794cde

data/README.md

@@ -6,11 +6,10 @@ replaced with formatted inline texts, and reference lists are automatically
 generated and inserted into where `bibliography::[]` is placed. 
 
 asciidoctor-bibtex is designed to be used as an extension to
-[asciidoctor](http://asciidoctor.org), although it supports asciidoc to
-asciidoc transformation at the moment. Thus this extension can be used
+[asciidoctor](http://asciidoctor.org). Thus this extension can be used
 together with other asciidoctor extensions such as
 [asciidoctor-mathematical][] and [asciidoctor-pdf][] to enrich your
-asciidoc experience.
+asciidoc experience. Note that asciidoctor-bibtex no longer support asciidoc-to-asciidoc conversion.
 
 [asciidoctor-mathematical]: https://github.com/asciidoctor/asciidoctor-mathematical
 [asciidoctor-pdf]: https://github.com/asciidoctor/asciidoctor-pdf
@@ -29,7 +28,7 @@ documents and produces new asciidoc documents, asciidoctor-bibtex focuses on
 compatibility with asciidoctor and other asciidoctor extensions at the very
 beginning. As time passes, asciidoctor-bibtex diverges significantly from its
 ancesstor. For example, asciidoctor-bibtex now supports generating real bibtex
-ciations and bibliography, so it can be used together with
+citations and bibliography, so it can be used together with
 [asciidoctor-latex][] for native bibtex support.
 
 [asciidoc-bib]: https://github.com/petercrlane/asciidoc-bib
@@ -84,7 +83,8 @@ To add a list of formatted references, place `bibliography::[]` on a line by its
 | bibtex-file    | Bibtex database file                     | any string, or empty                 | Automatic searching |
 | bibtex-style   | Reference formatting style               | any style supported by csl-styles    | ieee                |
 | bibtex-order   | Order of citations                       | `appearance` or `alphabetical`       | `appearance`        |
-| bibtex-format  | Formatting of citations and bibliography | `asciidoc` or `bibtex` or `biblatex` | `asciidoc`          |
+| bibtex-format  | Formatting of citations and bibliography | `asciidoc`, `bibtex` or `biblatex` | `asciidoc`          |
+| bibtex-throw  | Throw an error on unknown references | `true` or `false` | `false`          |
 
 ### Commandline
 

data/lib/asciidoctor-bibtex.rb

@@ -1,21 +1,11 @@
 #  asciidoctor-bibtex.rb
 #
 # Copyright (c) Peter Lane, 2012-13.
+# Copyright (c) Zhang Yang, 2019.
+#
 # Released under Open Works License, 0.9.2
 
-require 'bibtex'
-require 'citeproc'
-require 'csl/styles'
-require 'set'
-
-require_relative 'asciidoctor-bibtex/asciidoctor'
-require_relative 'asciidoctor-bibtex/citation'
-require_relative 'asciidoctor-bibtex/citationdata'
-require_relative 'asciidoctor-bibtex/citationutils'
-require_relative 'asciidoctor-bibtex/citations'
+# Register asciidoctor extensions introduced by this package.
 require_relative 'asciidoctor-bibtex/extensions'
-require_relative 'asciidoctor-bibtex/filehandlers'
-require_relative 'asciidoctor-bibtex/processorutils'
-require_relative 'asciidoctor-bibtex/processor'
-require_relative 'asciidoctor-bibtex/styles'
+# Export the package version
 require_relative 'asciidoctor-bibtex/version'

data/lib/asciidoctor-bibtex/CitationMacro.rb

@@ -0,0 +1,96 @@
+#
+# CitationMacro.rb
+#
+# Copyright (c) Peter Lane, 2013.
+# Copyright (c) Zhang Yang, 2019.
+#
+# Released under Open Works License, 0.9.2
+#
+
+module AsciidoctorBibtex
+  # CitationItem
+  #
+  # A class to hold data for a single citation item.
+  #
+  class CitationItem
+    attr_reader :key, :locator
+
+    def initialize(key, locator)
+      @key = key
+      @locator = locator
+      # clean up locator
+      @locator ||= ''
+      @locator = @locator.gsub('--', '-')
+    end
+
+    def to_s
+      "#{@key}:#{@locator}"
+    end
+  end
+
+  # CitationMacro
+  #
+  # Class to hold information about a citation macro.  A citation macro has
+  # type, text and an array of citation items.
+  #
+  # This class also provides a class method to extract macros from a line of
+  # text.
+  #
+  class CitationMacro
+    #
+    # Grammar for the citation macro: cite|citenp:[Key(locator)]
+    #
+
+    # matches a citation type
+    CITATION_TYPE = /cite|citenp/.freeze
+    # matches a citation item (key + locator), such as 'Dan2012(99-100)'
+    CITATION_ITEM = /([^\s,()\[\]]+)(\([^)]*\))?/.freeze
+    # matches a citation list
+    CITATION_LIST_TAIL = /(\s*,\s*#{CITATION_ITEM})*/.freeze
+    CITATION_LIST = /(?:#{CITATION_ITEM}#{CITATION_LIST_TAIL})/.freeze
+    CITATION_PRETEXT = /[^\[]*/.freeze
+    # matches the full citation macro
+    CITATION_MACRO = /(#{CITATION_TYPE}):(#{CITATION_PRETEXT})\[(#{CITATION_LIST})\]/.freeze
+
+    # Given a line, return a list of CitationData instances
+    # containing information on each set of citation information
+    def self.extract_citations(line)
+      result = []
+      full = CITATION_MACRO.match line
+      while full
+        text = full[0]
+        type = full[1]
+        pretext = full[2]
+        items = []
+        item = CITATION_ITEM.match full[3]
+        while item
+          locator = nil
+          locator = item[2][1...-1] if item[2]
+          items << CitationItem.new(item[1], locator)
+          # look for next ref within citation
+          item = CITATION_ITEM.match item.post_match
+        end
+        result << CitationMacro.new(text, type, pretext, items)
+        # look for next citation on line
+        full = CITATION_MACRO.match full.post_match
+      end
+
+      result
+    end
+
+    attr_reader :text, :type, :pretext, :items
+
+    # Create a CitationMacro object
+    #
+    # text: the full macro text matched by CITATION_MACRO
+    # type: cite or citenp
+    # pretext: some small texts.
+    # items: An array of citation items
+    def initialize(text, type, pretext, items)
+      @text = text
+      @type = type
+      @pretext = pretext
+      @items = items
+    end
+  end
+end

data/lib/asciidoctor-bibtex/CitationUtils.rb

@@ -0,0 +1,34 @@
+#
+# CitationUtils.rb
+#
+# Copyright (c) Peter Lane, 2013.
+# Released under Open Works License, 0.9.2
+#
+
+module AsciidoctorBibtex
+  # Some utility functions used in Citations class
+  module CitationUtils
+    # arrange author string, flag for order of surname/initials
+    def self.arrange_authors(authors, surname_first)
+      return [] if authors.nil?
+
+      authors.split(/\band\b/).collect do |name|
+        if name.include?(', ')
+          parts = name.strip.rpartition(', ')
+          if surname_first
+            "#{parts[0]}, #{parts[2]}"
+          else
+            "#{parts[2]} #{parts[0]}"
+          end
+        else
+          name
+        end
+      end
+    end
+
+    # Arrange given author string into Chicago format
+    def self.author_chicago(authors)
+      arrange_authors authors, true
+    end
+  end
+end

data/lib/asciidoctor-bibtex/PathUtils.rb

@@ -0,0 +1,21 @@
+#
+# PathUtils.rb
+#
+# High-level utilities for files.
+#
+
+module AsciidoctorBibtex
+  module PathUtils
+    # Locate a bibtex file to read in given dir
+    def self.find_bibfile(dir)
+      candidates = Dir.glob("#{dir}/*.bib")
+      if candidates.empty?
+        return ''
+      else
+        return candidates.first
+      end
+    rescue StandardError # catch all errors, and return empty string
+      ''
+    end
+  end
+end

data/lib/asciidoctor-bibtex/Processor.rb

@@ -0,0 +1,281 @@
+#
+# Manage the current set of citations, the document settings,
+# and main operations.
+#
+
+require 'bibtex'
+require 'bibtex/filters'
+require 'citeproc'
+require 'csl/styles'
+require 'latex/decode/base'
+require 'latex/decode/maths'
+require 'latex/decode/accents'
+require 'latex/decode/diacritics'
+require 'latex/decode/punctuation'
+require 'latex/decode/symbols'
+require 'latex/decode/greek'
+require 'set'
+
+require_relative 'CitationMacro'
+require_relative 'CitationUtils'
+require_relative 'StringUtils'
+require_relative 'StyleUtils'
+
+module AsciidoctorBibtex
+  # This filter extends the original latex filter in bibtex-ruby to handle
+  # unknown latex macros more gracefully. We could have used latex-decode
+  # gem together with our custom replacement rules, but latex-decode eats up
+  # all braces after it finishes all decoding. So we hack over the
+  # LaTeX.decode function and insert our rules before `strip_braces`.
+  class LatexFilter < ::BibTeX::Filter
+    def apply(value)
+      text = value.to_s
+      LaTeX::Decode::Base.normalize(text)
+      LaTeX::Decode::Maths.decode!(text)
+      LaTeX::Decode::Accents.decode!(text)
+      LaTeX::Decode::Diacritics.decode!(text)
+      LaTeX::Decode::Punctuation.decode!(text)
+      LaTeX::Decode::Symbols.decode!(text)
+      LaTeX::Decode::Greek.decode!(text)
+      text = text.gsub(/\\url\{(.+?)\}/, ' \\1 ').gsub(/\\\w+(?=\s+\w)/, '').gsub(/\\\w+(?:\[.+?\])?\s*\{(.+?)\}/, '\\1')
+      LaTeX::Decode::Base.strip_braces(text)
+      LaTeX.normalize_C(text)
+    end
+  end
+
+  # 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
+    def initialize(bibfile, links = false, style = 'ieee', locale = 'en-US',
+                   numeric_in_appearance_order = false, output = :asciidoc,
+                   throw_on_unknown = false)
+      raise "File '#{bibfile}' is not found" unless FileTest.file? bibfile
+
+      bibtex = BibTeX.open bibfile, filter: [LatexFilter]
+      @biblio = bibtex
+      @links = links
+      @numeric_in_appearance_order = numeric_in_appearance_order
+      @style = style
+      @locale = locale
+      @citations = []
+      @filenames = Set.new
+      @output = output
+      @throw_on_unknown = throw_on_unknown
+
+      if (output != :latex) && (output != :bibtex) && (output != :biblatex)
+        @citeproc = CiteProc::Processor.new style: @style, format: :html, locale: @locale
+        @citeproc.import @biblio.to_citeproc
+      end
+    end
+
+    # Scan a line and process citation macros.
+    #
+    # As this function being called iteratively on the lines of the document,
+    # processor will build a list of all citation keys in the same order as they
+    # appear in the original document.
+    def process_citation_macros(line)
+      CitationMacro.extract_citations(line).each do |citation|
+        @citations += citation.items.collect(&:key)
+      end
+    end
+
+    # Finalize citation macro processing and build internal citation list.
+    #
+    # As this function being called, processor will clean up the list of
+    # citation keys to form a correct ordered citation list.
+    def finalize_macro_processing
+      @citations = @citations.uniq(&:to_s) # only keep the first occurance
+      return if StyleUtils.is_numeric?(@style) && @numeric_in_appearance_order
+
+      @citations = @citations.sort_by do |ref|
+        bibitem = @biblio[ref]
+        if bibitem.nil?
+          [ref]
+        else
+          # extract the reference, and uppercase.
+          # Remove { } from grouped names for sorting.
+          author = bibitem.author
+          author = bibitem.editor if author.nil?
+          CitationUtils.author_chicago(author).collect { |s| s.upcase.gsub('{', '').gsub('}', '') } + [bibitem.year]
+        end
+      end
+      nil
+    end
+
+    # Replace citation macros with corresponding citation texts.
+    #
+    # Return new text with all macros replaced.
+    def replace_citation_macros(line)
+      CitationMacro.extract_citations(line).each do |citation|
+        line = line.gsub(citation.text, build_citation_text(citation))
+      end
+      line
+    end
+
+    # Build the bibliography list just as bibtex.
+    #
+    # Return an array of texts representing an asciidoc list.
+    def build_bibliography_list
+      result = []
+      @citations.each do |ref|
+        result << build_bibliography_item(ref)
+        result << ''
+      end
+      result
+    end
+
+    #
+    # Internal functions
+    #
+
+    # Build bibliography text for a given reference
+    def build_bibliography_item(key)
+      result = ''
+      result << '. ' if StyleUtils.is_numeric? @style
+
+      begin
+        cptext = @citeproc.render :bibliography, id: key
+      rescue Exception => e
+        puts "Failed to render #{key}: #{e}"
+      end
+      result << "[[#{key}]]" if @links
+      if cptext.nil?
+        return result + key
+      else
+        result << cptext.first
+      end
+
+      StringUtils.html_to_asciidoc(result)
+    end
+
+    # Build the complete citation text for given citation macro
+    def build_citation_text(macro)
+      if (@output == :latex) || (@output == :bibtex) || (@output == :biblatex)
+        result = '+++'
+        macro.items.each do |cite|
+          # NOTE: xelatex does not support "\citenp", so we output all
+          # references as "cite" here unless we're using biblatex.
+          result << '\\' << if @output == :biblatex
+                              if macro.type == 'citenp'
+                                'textcite'
+                              else
+                                'parencite'
+                                                end
+                            else
+                              'cite'
+                            end
+          result << '[p. ' << cite.locator << ']' if cite.locator != ''
+          result << '{' << cite.key.to_s << '},'
+        end
+        result = result[0..-2] if result[-1] == ','
+        result << '+++'
+        result
+      else
+        result = ''
+        if StyleUtils.is_numeric? @style
+          ob = '+[+'
+          cb = '+]+'
+          separator = ','
+        elsif macro.type == 'cite'
+          ob = '('
+          cb = ')'
+          separator = ';'
+        else
+          ob = ''
+          cb = ''
+          separator = ';'
+        end
+
+        macro.items.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.key}," if @links
+
+          # if found, insert reference information
+          if @biblio[cite.key].nil?
+            if @throw_on_unknown
+              raise "Unknown reference: #{cite.ref}"
+            else
+              puts "Unknown reference: #{cite.ref}"
+              cite_text = cite.ref.to_s
+            end
+          else
+            cite_text = citation_text(macro, cite)
+           end
+
+          result << StringUtils.html_to_asciidoc(cite_text)
+          result << '>>' if @links
+        end
+
+        if StyleUtils.is_numeric?(@style) && !@links
+          result = StringUtils.combine_consecutive_numbers(result)
+        end
+
+        include_pretext result, macro, ob, cb
+      end
+    end
+
+    # Format locator with pp/p as appropriate
+    def format_locator(cite)
+      result = ''
+      unless cite.locator.empty?
+        result << ',' unless StyleUtils.is_numeric? @style
+        result << ' '
+        # use p.x for single numerical page and pp.x for all others. This will
+        # produce pp. 1 seq for complex locators, which is the correct behavior.
+        if @style.include? 'chicago'
+          result << cite.locator
+        elsif /^\d+$/ =~ cite.locator
+          result << "p.&#160;#{cite.locator}"
+        else
+          result << "pp.&#160;#{cite.locator}"
+        end
+      end
+
+      result
+    end
+
+    def include_pretext(result, macro, ob, cb)
+      pretext = macro.pretext
+      pretext += ' ' unless pretext.empty? # add space after any content
+
+      if StyleUtils.is_numeric? @style
+        "#{pretext}#{ob}#{result}#{cb}"
+      elsif macro.type == 'cite'
+        "#{ob}#{pretext}#{result}#{cb}"
+      else
+        "#{pretext}#{result}"
+      end
+    end
+
+    # Generate a raw citation text for a single citation item
+    def citation_text(macro, cite)
+      if StyleUtils.is_numeric? @style
+        cite_text = (@citations.index(cite.key) + 1).to_s
+        cite_text << format_locator(cite)
+      else
+        # We generate the citation without locator using citeproc, then strip
+        # the surrounding braces, finally add the locator and add braces for
+        # `citenp`.
+        cite_text = @citeproc.render :citation, id: cite.key
+        cite_text = cite_text.gsub('(', '')
+        cite_text = cite_text.gsub(')', '')
+        cite_text = cite_text + format_locator(cite)
+        year = @biblio[cite.key].year
+        if !year.nil? && macro.type == 'citenp'
+          segs = cite_text.partition(year.to_s)
+          head = segs[0].gsub(', ', ' ')
+          tail = segs[1..-1].join
+          cite_text = "#{head}(#{tail})"
+        end
+        # finally escape some special chars
+        cite_text = cite_text.gsub(',', '&#44;') if @links # replace comma
+      end
+
+      cite_text
+    end
+  end
+end