asciidoctor-bibliography 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 60349740c0d584e5373c9f81c67d97a938eb1f87
-  data.tar.gz: 50fd0f1d8577a54664f9a8e9efdecdb268809edc
+  metadata.gz: ec220969b63ad6811daffac07fbf41eaec5a382d
+  data.tar.gz: '089f60f0d33c8737b6308b7ab7a494dae7b93803'
 SHA512:
-  metadata.gz: cfab5b8627b11ccd161641fc0ff126a30bfc080fbf75e8740aa4341732a205c31992b237f53e67f1d544dbc32f5612a79dfdf717f438c2c966b940f94e3683c2
-  data.tar.gz: 2f19a9de392c561bf9ad961271b174db27639bdb98ce1c02dcaf1df22f6e2687ae2bd0c4b4311f23018203a6effc4aac96ea4e7ab5b9fd2bafc808d7399d672a
+  metadata.gz: 8697d604dd13e6aa72fb652b6e8c61a1bbeef82ab4240d2de96fc0e15d02343646e9494e119baad65269a3802c5b32078e8c233aad864cb707d9943173704d0d
+  data.tar.gz: 69704a0dc0dbd0a99142adc00752b904ad5a082baadd755f03b8e49a3b4871e49fdd7fc14bf88011f6eb6e723909791f9b1c986fff1b00e4a5800bb39fcf5964

data/README.adoc

@@ -16,7 +16,7 @@ Citation styling leverages the popular http://citationstyles.org/[CSL] language
 so you have direct access to thousands of crowdsourced styles including IEEE,
 APA, Chicago, DIN and ISO 690.
 
-The `bibliography:[]` command generates a full reference list that adheres to
+The `bibliography::[]` command generates a full reference list that adheres to
 your configured citation style.
 
 On top of that you also have a formatter derived from the `Bib(La)TeX` world,
@@ -28,7 +28,7 @@ Its syntax is designed to be "`native-asciidoctor`":
 * contextual cite `cite[key, page=3]`;
 * multiple cites `cite:[key1]+[key2]`;
 * full cite `fullcite:[key]`; and
-* TeX-compatible macros including `citep:[key]`, `citet:[]key` and friends.
+* TeX-compatible macros including `citep:[key]`, `citet:[key]` and friends.
 
 
 == Installation
@@ -180,6 +180,18 @@ or searching through the friendly http://editor.citationstyles.org/[style editor
 You can also simply use the filename of a CSL file on your machine if you need more customization.
 
 
+=== Localization
+
+Citation styles can be localized using the following option:
+
+[source,asciidoc]
+----
+:bibliography-locale: en-US
+----
+
+The default is `en-US`. Here is an exhaustive list of recognized locales: `af-ZA`, `ar`, `bg-BG`, `ca-AD`, `cs-CZ`, `cy-GB`, `da-DK`, `de-AT`, `de-CH`, `de-DE`, `el-GR`, `en-GB`, `en-US`, `es-CL`, `es-ES`, `es-MX`, `et-EE`, `eu`, `fa-IR`, `fi-FI`, `fr-CA`, `fr-FR`, `he-IL`, `hr-HR`, `hu-HU`, `id-ID`, `is-IS`, `it-IT`, `ja-JP`, `km-KH`, `ko-KR`, `lt-LT`, `lv-LV`, `mn-MN`, `nb-NO`, `nl-NL`, `nn-NO`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sl-SI`, `sr-RS`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, `vi-VN`, `zh-CN` and `zh-TW`.
+
+
 === Hyperlinks
 
 By default, citations include hyperlinks to their entry in the bibliography.
@@ -250,7 +262,7 @@ To use them effectively you'll need to know its implementation.
 
 This task is not daunting at all, as the http://editor.citationstyles.org/[style editor] allows you to quickly list them and understand their role.
 
-As for the `sort` option, the valid values are `ascending` (default) and `descending` as you'd exect.
+As for the `sort` option, the valid values are `ascending` (default) and `descending` as you'd expect.
 
 
 === TeX-mode
@@ -267,12 +279,17 @@ While the `cite` macro is reserved for CSL styling, all traditional Bib(La)TeX m
 * `citealp*`
 * `citeauthor`
 * `citeauthor*`
-* `citeyear` and `citeyearpar`.
+* `citeyear`
+* `citeyearpar`
 
 NOTE: no macros are missing since `\cite` is equivalent to `\citet`!
 
 To cite multiple items you can concatenate them just like with `cite`.
 
+All macros accept standard locators, `locator`, `suffix` and `prefix`.
+The behaviour of these parameters is designed to reproduce the one expected
+from the traditional `TeX` citation macros `\cite...[prefix][suffix]{key}`.
+
 You can set their style in the header:
 
 [source,asciidoc]
@@ -282,6 +299,8 @@ You can set their style in the header:
 
 Accepted values are `authoryear` (default) and `numeric`.
 
+Furthermore, `fullcite` is also available and accepts no parameters except a single reference key.
+
 == Development
 
 We follow Sandi Metz's Rules for this gem, you can read the

data/asciidoctor-bibliography.gemspec

@@ -4,7 +4,7 @@ lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "asciidoctor-bibliography/version"
 
-Gem::Specification.new do |spec|
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.name          = "asciidoctor-bibliography"
   spec.version       = AsciidoctorBibliography::VERSION
   spec.authors       = ["Ribose Inc."]
@@ -19,11 +19,11 @@ Gem::Specification.new do |spec|
     * contextual cite `cite[key, page=3]`;
     * multiple cites `cite:[key1]+[key2]`;
     * full cite `fullcite:[key]`; and
-    * TeX-compatible macros including `citep:[key]`, `citet:[]key` and friends.
+    * TeX-compatible macros including `citep:[key]`, `citet:[key]` and friends.
 
     Citation output styles are fully bridged to the CSL library, supporting formats such as IEEE, APA, Chicago, DIN and ISO 690.
 
-    The `bibliography:[]` command generates a full reference list that adheres to your configured citation style.
+    The `bibliography::[]` command generates a full reference list that adheres to your configured citation style.
 END
   spec.homepage      = "https://github.com/riboseinc/asciidoctor-bibliography"
   spec.license       = "MIT"
@@ -33,11 +33,11 @@ END
   spec.test_files    = `git ls-files -- {spec}/*`.split("\n")
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
-  spec.add_dependency "asciidoctor"
-  spec.add_dependency "citeproc-ruby"
-  spec.add_dependency "csl-styles", "~> 1"
-  spec.add_dependency "latex-decode", "~> 0.2"
-  spec.add_dependency "bibtex-ruby"
+  spec.add_dependency "asciidoctor", "~> 1.5.6"
+  spec.add_dependency "citeproc-ruby", "~> 1.1.7"
+  spec.add_dependency "csl-styles", "~> 1.0.1"
+  spec.add_dependency "latex-decode", "~> 0.2.2"
+  spec.add_dependency "bibtex-ruby", "~> 4.4.4"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "byebug"

data/lib/asciidoctor-bibliography.rb

@@ -4,3 +4,9 @@ rescue LoadError
 end
 
 require_relative "asciidoctor-bibliography/asciidoctor"
+
+module AsciidoctorBibliography
+  def self.root
+    File.dirname __dir__
+  end
+end

data/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb

@@ -1,6 +1,5 @@
 require "asciidoctor"
 
-require_relative "../helpers"
 require_relative "../database"
 require_relative "../citation"
 require_relative "../index"
@@ -13,40 +12,53 @@ module AsciidoctorBibliography
         document.bibliographer.options =
           ::AsciidoctorBibliography::Options.new_from_reader reader
 
-        # Load database(s).
-        document.bibliographer.database = Database.new(document.bibliographer.options.database)
+        document.bibliographer.database =
+          ::AsciidoctorBibliography::Database.new document.bibliographer.options.database
 
-        # Find, store and replace citations with uuids.
-        processed_lines = reader.read_lines.map do |line|
-          line.gsub(Citation::REGEXP) do
-            citation = Citation.new(*Regexp.last_match.captures)
-            document.bibliographer.add_citation(citation)
-            citation.uuid
-          end
-        end
+        process_reader reader, document.bibliographer
+      end
+
+      private
+
+      def process_reader(reader, bibliographer)
+        # First we fetch citations and replace them with uuids,
+        processed_lines = fetch_citations reader.lines, bibliographer
+        reader = ::Asciidoctor::Reader.new processed_lines
+        # then we render them
+        processed_lines = render_citations reader.lines, bibliographer
         reader = ::Asciidoctor::Reader.new processed_lines
+        # and finally we render indices.
+        processed_lines = render_indices reader.lines, bibliographer
+        ::Asciidoctor::Reader.new processed_lines
+      end
+
+      def fetch_citations(lines, bibliographer)
+        lines.join("\n").gsub!(Citation::REGEXP) do
+          citation = Citation.new(*Regexp.last_match.captures)
+          bibliographer.add_citation(citation)
+          citation.uuid
+        end.lines.map(&:chomp)
+      end
 
-        # Find and replace uuids with formatted citations.
-        processed_lines = reader.lines.join("\n") # for quicker matching
-        document.bibliographer.citations.each do |citation|
+      def render_citations(lines, bibliographer)
+        processed_lines = lines.join("\n")
+        bibliographer.citations.each do |citation|
           processed_lines.sub!(citation.uuid) do
-            citation.render document.bibliographer
+            citation.render bibliographer
           end
         end
-        processed_lines = processed_lines.lines.map(&:chomp)
-        reader = ::Asciidoctor::Reader.new processed_lines
+        processed_lines.lines.map(&:chomp)
+      end
 
-        # Find and format indices.
-        processed_lines = reader.read_lines.map do |line|
+      def render_indices(lines, bibliographer)
+        lines.map do |line|
           if line =~ Index::REGEXP
             index = Index.new(*Regexp.last_match.captures)
-            index.render document.bibliographer
+            index.render bibliographer
           else
             line
           end
-        end
-        processed_lines.flatten!
-        ::Asciidoctor::Reader.new processed_lines
+        end.flatten
       end
     end
   end

data/lib/asciidoctor-bibliography/bibliographer.rb

@@ -22,20 +22,5 @@ module AsciidoctorBibliography
     def appearance_index_of(id)
       @occurring_keys.index(id) + 1
     end
-
-    def sort
-      return unless options["order"] == "alphabetical"
-      @occurring_keys = @occurring_keys.sort_by do |target|
-        first_author_family_name(target)
-      end
-    end
-
-    private
-
-    def first_author_family_name(key)
-      authors = database.find_entry_by_id(key)["author"]
-      return "" if authors.nil?
-      authors.map { |h| h["family"] }.compact.first # TODO: is the first also alphabetically the first?
-    end
   end
 end

data/lib/asciidoctor-bibliography/citation.rb

@@ -1,11 +1,15 @@
 require "securerandom"
-require_relative "formatters/csl"
-require_relative "formatters/tex"
+require_relative "formatter"
 require_relative "citation_item"
 
+require "csl/styles"
+
 module AsciidoctorBibliography
   class Citation
-    MACRO_NAME_REGEXP = Formatters::TeX::MACROS.keys.concat(%w[cite fullcite]).
+    TEX_MACROS = %w[citet citet* citealt citealt* citep citep* citealp citealp*
+                    citeauthor citeauthor* citeyear citeyearpar].freeze
+
+    MACRO_NAME_REGEXP = TEX_MACROS.dup.concat(%w[cite fullcite]).
       map { |s| Regexp.escape s }.join("|").freeze
     REGEXP = /\\?(#{MACRO_NAME_REGEXP}):(?:(\S*?)?\[(|.*?[^\\])\])(?:\+(\S*?)?\[(|.*?[^\\])\])*/
     REF_ATTRIBUTES = %i[chapter page section clause].freeze
@@ -31,18 +35,17 @@ module AsciidoctorBibliography
         render_citation_with_csl(bibliographer)
       when "fullcite"
         render_fullcite_with_csl(bibliographer)
-      when *Formatters::TeX::MACROS.keys
-        formatter = Formatters::TeX.new(bibliographer.options.tex_style)
-        formatter.import bibliographer.database
-        formatter.render bibliographer, self
+      when *TEX_MACROS
+        filename = ["tex", macro.tr("*", "s"), bibliographer.options.tex_style].join("-")
+        filepath = File.join AsciidoctorBibliography.root, "lib/csl/styles", filename
+        render_citation_with_csl(bibliographer, style: filepath, tex: true)
       end
     end
 
     def render_fullcite_with_csl(bibliographer)
-      formatter = Formatters::CSL.new(bibliographer.options.style)
+      formatter = Formatter.new(bibliographer.options.style, locale: bibliographer.options.locale)
       prepare_fullcite_item bibliographer, formatter
       formatted_citation = formatter.render(:bibliography, id: citation_items.first.key).join
-      formatted_citation = Helpers.html_to_asciidoc formatted_citation
       # We prepend an empty interpolation to avoid interferences w/ standard syntax (e.g. block role is "\n[foo]")
       "{empty}" + formatted_citation
     end
@@ -51,9 +54,9 @@ module AsciidoctorBibliography
       formatter.import([bibliographer.database.find_entry_by_id(citation_items.first.key)])
     end
 
-    def render_citation_with_csl(bibliographer)
-      formatter = Formatters::CSL.new(bibliographer.options.style)
-      items = prepare_items bibliographer, formatter
+    def render_citation_with_csl(bibliographer, style: bibliographer.options.style, tex: false)
+      formatter = Formatter.new(style, locale: bibliographer.options.locale)
+      items = prepare_items bibliographer, formatter, tex: tex
       formatted_citation = formatter.engine.renderer.render(items, formatter.engine.style.citation)
       escape_brackets_inside_xref! formatted_citation
       # We prepend an empty interpolation to avoid interferences w/ standard syntax (e.g. block role is "\n[foo]")
@@ -66,25 +69,29 @@ module AsciidoctorBibliography
       end
     end
 
-    def prepare_items(bibliographer, formatter)
-      cites_with_local_attributes = citation_items.map { |cite| prepare_metadata bibliographer, cite }
+    def prepare_items(bibliographer, formatter, tex: false)
+      # NOTE: when we're using our custom TeX CSL styles prefix/suffix are used as
+      #   varieables for metadata instead of as parameters for citations.
+      cites_with_local_attributes = citation_items.map { |cite| prepare_metadata bibliographer, cite, affix: tex }
       formatter.import cites_with_local_attributes
-      formatter.sort(mode: :citation)
-      formatter.data.map(&:cite).each { |item| prepare_item bibliographer.options, item }
+      formatter.force_sort!(mode: :citation)
+      formatter.data.map(&:cite).each { |item| prepare_item bibliographer.options, item, affix: !tex }
     end
 
-    def prepare_metadata(bibliographer, cite)
+    def prepare_metadata(bibliographer, cite, affix: false)
       bibliographer.database.find_entry_by_id(cite.key).
-        merge('citation-number': bibliographer.appearance_index_of(cite.key)).
-        merge('citation-label': cite.key). # TODO: smart label generators
-        merge('locator': cite.locator.nil? ? nil : " ")
+        merge 'citation-number': bibliographer.appearance_index_of(cite.key),
+              'citation-label': cite.key, # TODO: smart label generators
+              'locator': cite.locator.nil? ? nil : " ",
+              'prefix': affix ? cite.prefix : nil,
+              'suffix': affix ? cite.suffix : nil
       # TODO: why is a non blank 'locator' necessary to display locators set at a later stage?
     end
 
-    def prepare_item(options, item)
+    def prepare_item(options, item, affix: true)
       # TODO: hyperlink, suppress_author and only_author options
       ci = citation_items.detect { |c| c.key == item.id }
-      wrap_item item, ci.prefix, ci.suffix
+      wrap_item item, ci.prefix, ci.suffix if affix
       wrap_item item, "xref:#{xref_id(item.id)}{{{", "}}}" if options.hyperlinks?
       item.label, item.locator = ci.locator
     end

data/lib/asciidoctor-bibliography/databases/bibtex.rb

@@ -17,13 +17,15 @@ module AsciidoctorBibliography
         ::BibTeX.open(filename, filter: [LatexFilter]).to_citeproc
       end
 
+      # NOTE: the class below comes from asciidoctor-bibtex
+
       # 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)
+        def apply(value) # rubocop:disable Metrics/MethodLength; keep this a list, though!
           text = value.to_s
           LaTeX::Decode::Base.normalize(text)
           LaTeX::Decode::Maths.decode!(text)
@@ -32,6 +34,7 @@ module AsciidoctorBibliography
           LaTeX::Decode::Punctuation.decode!(text)
           LaTeX::Decode::Symbols.decode!(text)
           LaTeX::Decode::Greek.decode!(text)
+          # TODO: could we be doing something smarter with some macros, e.g. \url?
           text.gsub!(/\\url\{(.+?)\}/, ' \\1 ')
           text.gsub!(/\\\w+(?=\s+\w)/, "")
           text.gsub!(/\\\w+(?:\[.+?\])?\s*\{(.+?)\}/, '\\1')

data/lib/asciidoctor-bibliography/formatter.rb

@@ -0,0 +1,28 @@
+require "citeproc"
+require "csl/styles"
+require "yaml"
+
+require_relative "../citeproc/ruby/formats/adoc"
+
+module AsciidoctorBibliography
+  class Formatter < ::CiteProc::Processor
+    def initialize(style, locale: "en-US")
+      super style: style, format: :adoc, locale: locale
+    end
+
+    def replace_bibliography_sort(array)
+      new_keys = array.map(&::CSL::Style::Sort::Key.method(:new))
+      new_sort = ::CSL::Style::Sort.new.add_children(*new_keys)
+
+      bibliography = engine.style.find_child("bibliography")
+      bibliography.find_child("sort")&.unlink
+
+      bibliography.add_child new_sort
+    end
+
+    def force_sort!(mode:)
+      # Valid modes are :citation and :bibliography
+      engine.sort! data, engine.style.send(mode).sort_keys if engine.style.send(mode).sort?
+    end
+  end
+end

data/lib/asciidoctor-bibliography/index.rb

@@ -1,7 +1,5 @@
 require "asciidoctor/attribute_list"
-require_relative "formatters/csl"
-
-require_relative "helpers"
+require_relative "formatter"
 
 module AsciidoctorBibliography
   class Index
@@ -16,23 +14,13 @@ module AsciidoctorBibliography
     end
 
     def render(bibliographer)
-      formatter = Formatters::CSL.new(bibliographer.options.style)
-
-      unless bibliographer.options.sort.nil?
-        formatter.replace_bibliography_sort bibliographer.options.sort
-      end
-
-      filtered_db = bibliographer.occurring_keys.
-        map { |id| bibliographer.database.find_entry_by_id(id) }.
-        map { |entry| prepare_entry_metadata bibliographer, entry }
-      formatter.import filtered_db
-      formatter.sort(mode: :bibliography)
+      formatter = setup_formatter bibliographer
 
       lines = []
       formatter.bibliography.each_with_index do |reference, index|
         line = "{empty}"
         line << "anchor:#{anchor_id(formatter.data[index].id)}[]"
-        line << Helpers.html_to_asciidoc(reference)
+        line << reference
         lines << line
       end
 
@@ -40,6 +28,26 @@ module AsciidoctorBibliography
       lines.join("\n\n").lines.map(&:strip)
     end
 
+    private
+
+    def setup_formatter(bibliographer)
+      formatter = Formatter.new(bibliographer.options.style, locale: bibliographer.options.locale)
+
+      formatter.replace_bibliography_sort bibliographer.options.sort unless bibliographer.options.sort.nil?
+
+      filtered_db = prepare_filtered_db bibliographer
+      formatter.import filtered_db
+      formatter.force_sort!(mode: :bibliography)
+
+      formatter
+    end
+
+    def prepare_filtered_db(bibliographer)
+      bibliographer.occurring_keys.
+        map { |id| bibliographer.database.find_entry_by_id(id) }.
+        map { |entry| prepare_entry_metadata bibliographer, entry }
+    end
+
     def prepare_entry_metadata(bibliographer, entry)
       entry.
         merge('citation-number': bibliographer.appearance_index_of(entry["id"])).
@@ -51,7 +59,7 @@ module AsciidoctorBibliography
     end
 
     def render_entry_label(target, formatter)
-      Helpers.html_to_asciidoc formatter.render(:bibliography, id: target).join
+      formatter.render(:bibliography, id: target).join
     end
 
     def render_entry(target, formatter)