asciidoctor-bibliography 0.2.1 → 0.3.0

data/.rubocop.yml

@@ -1,17 +1,11 @@
+inherit_from: .oss-guides.rubocop.yml
+
 AllCops:
   TargetRubyVersion: 2.3
-  Excludes:
-    - deprecated/**/*.rb
-    - spec/**/*.rb
 
+# TODO: shorten all lines to 80, as per oss-guides.
 Metrics/LineLength:
   Max: 120
 
-FrozenStringLiteralComment:
-  Enabled: false
-
-Style/FileName:
-  Enabled: false
-
-Documentation:
+Rails:
   Enabled: false

data/.travis.yml

@@ -1,3 +1,4 @@
+sudo: false
 language: ruby
 rvm:
-  -  2.4.0
+  -  2.3.0

data/Gemfile

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

data/README.adoc

@@ -1,14 +1,35 @@
-= Citations in AsciiDoc using asciidoctor-bibliography
+= Citations and Bibliography the "asciidoctor-way"
+
+asciidoctor-bibliography lets you handle citations and bibliography the
+"http://asciidoctor.org/[asciidoctor]-way"!
 
 image:https://img.shields.io/gem/v/asciidoctor-bibliography.svg["Gem Version", link="https://rubygems.org/gems/asciidoctor-bibliography"]
 image:https://img.shields.io/travis/riboseinc/asciidoctor-bibliography/master.svg["Build Status", link="https://travis-ci.org/riboseinc/asciidoctor-bibliography"]
 image:https://codeclimate.com/github/riboseinc/asciidoctor-bibliography/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/asciidoctor-bibliography"]
 
-Citations in AsciiDoc using the fantastic http://asciidoctor.org/[asciidoctor].
 
 == Introduction
 
-This gem allows you to add BibTex style Citations to AsciiDoc.
+This gem allows you to add citations to AsciiDoc imported from BibTex files.
+
+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
+your configured citation style.
+
+On top of that you also have a formatter derived from the `Bib(La)TeX` world,
+so all the macros you are familiar with are recognized.
+
+Its syntax is designed to be "`native-asciidoctor`":
+
+* single cite `cite:[key]`;
+* 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.
+
 
 == Installation
 
@@ -33,55 +54,234 @@ Or install it yourself as:
 $ gem install asciidoctor-bibliography
 ----
 
-== Configure
 
-In your document header, define the following below the title.
+== Quick start
 
+In your document header, choose the filename of a `BibTeX` database and a style (e.g. `apa`, `ieee`, `nature` and http://editor.citationstyles.org/searchByName/[others]).
+
+[source,asciidoc]
 ----
-= Latex Macros In Bibtex Items
-:bibliography-database: first.bib
-:bibliography-database: second.bib
-:bibliography-reference-style: ieee
+= My first document using asciidoctor-bibliography
+:bibliography-database: my_database.bib
+:bibliography-style: apa
 ----
 
-== Usage
+In your document body, cite your resources using their keys:
 
-Include asciidoctor-bibliography in your chain:
+[source,asciidoc]
+----
+This will end with a citation cite:[Aa2017].
+----
+
+Then list out the resources you cited:
+
+[source,asciidoc]
+----
+bibliography::[]
+----
+
+When compiling, include `asciidoctor-bibliography` in your chain:
 
 [source,console]
 ----
-$ asciidoctor -r asciidoctor-bibliography main.adoc
+$ asciidoctor -r asciidoctor-bibliography my_first_document.adoc
 ----
 
-Add citation commands within your AsciiDoc:
+That's it!
+
+
+== Usage
+
+`asciidoctor-bibliography` allows for more customizations and macros.
+Let's examine all its features in full detail.
 
+
+=== Citations
+
+To cite a resource you provide its unique database key to an inline macro:
+
+[source,asciidoc]
 ----
-Searching Function (see cite:guo2009[])
+Here comes a citation cite:[Aa2017] and it's gone.
 ----
 
-List out bibliography:
+Referring to a specific location inside a resource can be done providing an extra named attribute:
 
+[source,asciidoc]
 ----
-bibliography::[]
+cite:[Aa2017, page=42]
 ----
 
-== Example
+Allowed locators are `book`, `chapter`, `column`, `figure`, `folio`, `issue`, `line`, `note`, `opus`, `page`, `paragraph`, `part`, `section`, `sub-verbo`, `verse` and `volume`. Their support depends upon which ones your style implements.
+
+An extra `locator` attribute with no custom rendering exists.
+It appears where the ordinary locators would, but you can fully customize it:
 
+[source,asciidoc]
+----
+cite:[Aa2017, locator=" halfway through"]
 ----
-= Latex Macros In Bibtex Items
-:bibliography-database: reference.bib
-:bibliography-reference-style: ieee
 
-== Contents
+Note that all locators except the first one will be ignored.
 
-This is a paper "Validation and Verificaton of Computer Forensic Software
-tools -- Searching Function" (see cite:guo2009[]).
+To `prefix` and `suffix` citations with arbitrary strings you can use the relative attributes:
 
-== Bibliography
+[source,asciidoc]
+----
+cite:[Aa2017, prefix="see ", suffix=" if you will"]
+----
+
+To cite multiple resources you concatenate them as follows:
+
+[source,asciidoc]
+----
+cite:[Aa2017]+[Bb2017]+[Cc2017]
+----
+
+You can apply a different locator to each one.
 
+
+=== Bibliographies
+
+To render the bibliography you simply use the following block macro:
+
+[source,asciidoc]
+----
 bibliography::[]
 ----
 
+
+=== Databases
+
+Specifying a database file is mandatory and it can be done in the header with its filename:
+
+[source,asciidoc]
+----
+:bibliography-database: my_database.bib
+----
+
+Currently only the `BibTeX` format is supported; more will come soon.
+
+
+=== Styling
+
+The default style for citations and bibliographies is `apa`.
+You can change that in the header:
+
+[source,asciidoc]
+----
+:bibliography-style: apa
+----
+
+Valid style names can be found directly in the
+https://github.com/citation-style-language/styles[official repository]
+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.
+
+
+=== Hyperlinks
+
+By default, citations include hyperlinks to their entry in the bibliography.
+You can disable them in the header:
+
+[source,asciidoc]
+----
+:bibliography-hyperlinks: false
+----
+
+
+=== Sorting
+
+You can override the sorting specified by the CSL style you have chosen, if you desire to do so.
+
+The relevant option is `bibliography-sort` and it accepts a YAML string specifying a list of keys to sort the entries with.
+
+Let's explore some of the possibilities.
+
+
+==== No Sort
+
+The simplest option is *no sorting*; an empty list will cause the entries to be in appearance order.
+
+[source,asciidoc]
+----
+:bibliography-sort: []
+----
+
+
+==== Sort By Single Key
+
+To sort in a single key - say, the rendered author name - it's as simple as
+
+[source,asciidoc]
+----
+:bibliography-sort: macro: author
+----
+
+
+==== Reverse Sort
+
+However you might want to reverse the order:
+
+[source,asciidoc]
+----
+:bibliography-sort: { macro: author, sort: descending }
+----
+
+
+==== Sort By Multiple Keys
+
+It is possible to use any number of sorting keys putting them in an array.
+E.g. to sort by issuing date:
+
+[source,asciidoc]
+----
+:bibliography-sort: [{ macro: author, sort: descending }, { variable: issued }]
+----
+
+You might be asking: what is the difference between `variable` s and `macro` s?
+
+The former are metadata fields fixed by the http://docs.citationstyles.org/en/stable/specification.html#appendix-iv-variables[CSL specification].
+
+The latter are combinations of variables defined by your chosen style.
+
+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.
+
+
+=== TeX-mode
+
+While the `cite` macro is reserved for CSL styling, all traditional Bib(La)TeX macros are accessible through the same syntax with their usual names:
+
+* `citet`
+* `citet*`
+* `citealt`
+* `citealt*`
+* `citep`
+* `citep*`
+* `citealp`
+* `citealp*`
+* `citeauthor`
+* `citeauthor*`
+* `citeyear` and `citeyearpar`.
+
+NOTE: no macros are missing since `\cite` is equivalent to `\citet`!
+
+To cite multiple items you can concatenate them just like with `cite`.
+
+You can set their style in the header:
+
+[source,asciidoc]
+----
+:bibliography-tex-style: authoryear
+----
+
+Accepted values are `authoryear` (default) and `numeric`.
+
 == Development
 
 We follow Sandi Metz's Rules for this gem, you can read the

data/Rakefile

@@ -1,5 +1,5 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/asciidoctor-bibliography.gemspec

@@ -1,14 +1,14 @@
 # coding: utf-8
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'asciidoctor-bibliography/version'
+require "asciidoctor-bibliography/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = 'asciidoctor-bibliography'
+  spec.name          = "asciidoctor-bibliography"
   spec.version       = AsciidoctorBibliography::VERSION
-  spec.authors       = ['Ribose Inc.']
-  spec.email         = ['open.source@ribose.com']
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
 
   spec.summary       = 'Citations and bibliography the "asciidoctor-way"'
   spec.description   = <<~END
@@ -25,25 +25,25 @@ Gem::Specification.new do |spec|
 
     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'
+  spec.homepage      = "https://github.com/riboseinc/asciidoctor-bibliography"
+  spec.license       = "MIT"
 
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
   spec.files         = `git ls-files`.split("\n")
   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_development_dependency 'bundler'
-  spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'yard'
-  spec.add_development_dependency 'rubocop'
+  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_development_dependency "bundler"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "rubocop"
 end

data/lib/asciidoctor-bibliography.rb

@@ -1,6 +1,6 @@
 begin
-  require 'byebug'
+  require "byebug"
 rescue LoadError
 end
 
-require_relative 'asciidoctor-bibliography/asciidoctor'
+require_relative "asciidoctor-bibliography/asciidoctor"

data/lib/asciidoctor-bibliography/asciidoctor.rb

@@ -1,8 +1,8 @@
-require 'asciidoctor/extensions'
+require "asciidoctor/extensions"
 
-require_relative 'asciidoctor/bibliographer_preprocessor'
-require_relative 'asciidoctor/document_ext'
-require_relative 'bibliographer'
+require_relative "asciidoctor/bibliographer_preprocessor"
+require_relative "asciidoctor/document_ext"
+require_relative "bibliographer"
 
 Asciidoctor::Document.include AsciidoctorBibliography::Asciidoctor::DocumentExt
 

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

@@ -1,24 +1,20 @@
-require 'asciidoctor'
-require 'pp'
+require "asciidoctor"
 
-require_relative '../helpers'
-require_relative '../database'
-require_relative '../citation'
-require_relative '../index'
+require_relative "../helpers"
+require_relative "../database"
+require_relative "../citation"
+require_relative "../index"
+require_relative "../options"
 
 module AsciidoctorBibliography
   module Asciidoctor
     class BibliographerPreprocessor < ::Asciidoctor::Extensions::Preprocessor
       def process(document, reader)
-        set_bibliographer_options(document, reader)
-
-        if document.bibliographer.options['database'].nil?
-          warn "No bibliographic database was provided: all bibliographic macros will be ignored. You can set it using the 'bibliography-database' option in the document's preamble."
-          return reader
-        end
+        document.bibliographer.options =
+          ::AsciidoctorBibliography::Options.new_from_reader reader
 
         # Load database(s).
-        document.bibliographer.database = Database.new(document.bibliographer.options['database'])
+        document.bibliographer.database = Database.new(document.bibliographer.options.database)
 
         # Find, store and replace citations with uuids.
         processed_lines = reader.read_lines.map do |line|
@@ -30,9 +26,6 @@ module AsciidoctorBibliography
         end
         reader = ::Asciidoctor::Reader.new processed_lines
 
-        # NOTE: retrieval and formatting are separated to allow sorting and numeric styles.
-        # document.bibliographer.sort
-
         # Find and replace uuids with formatted citations.
         processed_lines = reader.lines.join("\n") # for quicker matching
         document.bibliographer.citations.each do |citation|
@@ -55,46 +48,6 @@ module AsciidoctorBibliography
         processed_lines.flatten!
         ::Asciidoctor::Reader.new processed_lines
       end
-
-      private
-
-      OPTIONS_PREFIX = 'bibliography-'.freeze
-
-      OPTIONS_DEFAULTS = {
-        'order' => 'alphabetical',
-        'reference-style' => 'apa',
-        'citation-style' => 'authoryear',
-        'hyperlinks' => 'true',
-        'database' => nil
-      }.freeze
-
-      def set_bibliographer_options(document, reader)
-        # We peek at the document attributes we need, without perturbing the parsing flow.
-        # NOTE: we're in a preprocessor and they haven't been parsed yet; doing it manually.
-        # pp reader
-        header_attributes = extract_header_attributes reader
-        user_options = filter_bibliography_attributes header_attributes
-        document.bibliographer.options = OPTIONS_DEFAULTS.merge user_options
-      end
-
-      def extract_header_attributes(reader)
-        tdoc = ::Asciidoctor::Document.new
-        treader = ::Asciidoctor::PreprocessorReader.new(
-          tdoc,
-          reader.source_lines
-        )
-
-        ::Asciidoctor::Parser
-          .parse(treader, tdoc, header_only: true)
-          .attributes
-      end
-
-      def filter_bibliography_attributes(hash)
-        Helpers
-          .slice(hash, *OPTIONS_DEFAULTS.keys.map { |k| "#{OPTIONS_PREFIX}#{k}" })
-          .map { |k, v| [k[OPTIONS_PREFIX.length..-1], v] }.to_h
-          .reject { |_, value| value.nil? || value.empty? }.to_h
-      end
     end
   end
 end