jekyll-scholar 5.8.5 → 5.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a066765a98ef88cac6bde9f73aa707cdb71e938
-  data.tar.gz: d342a9115b68215869dc61cd4ceb10a012db0526
+  metadata.gz: aa155858171a28430fabd6809b18b61b34afae48
+  data.tar.gz: 5b92a94a4abedb754108a1b8f5d7bdd5da7b5cdf
 SHA512:
-  metadata.gz: dbb7afaca8fcfc7a51d1328ada1b8425f8f7240be048ee2b7f7dfde3b87365d75482ec1eef947f75ae69bcd6933f7e87498f4b20828ad65f0bc813348eab33f4
-  data.tar.gz: 2c7c4e0857fa6bd5854954265faf2d495f0aebaafc710a5a4ee4b6e6e0d9f3c38089d5521d428b77198e996a670b5b42d0faf23b7cf8f30bec35735b41f50b72
+  metadata.gz: e72d369a92f0be6a3cbd7e931149b365437bc204a5d19b046fb987fbd0122e6f048fc8471f5bb3910328f325f2a51153869dc6cde4d2ae84b3c87dc7aa552344
+  data.tar.gz: 8f31ed291d15017d72d5d3772ff6aee88e90e73195ae971c62973f082ebf7662edc87ba0a6c0bb2cbce7d1a0ce8d75c774185d63960bb73125f97a148706dc0c

data/README.md

@@ -53,92 +53,32 @@ configuration:
 
     gems: ['jekyll/scholar']
 
-In your configuration you can now adjust the Jekyll-Scholar settings. The
-default configuration is as follows:
+### Configuration
+
+In your Jekyll configuration file you can adjust the Jekyll-Scholar settings
+using the `scholar` key. For example, the following sets the bibliography style
+to `mla`.
 
     scholar:
-      style: apa
-      locale: en
-
-      sort_by: none
-      order: ascending
-
-      group_by: none
-      group_order: ascending
-
-      source: ./_bibliography
-      bibliography: references.bib
-      bibliography_template: "{{reference}}"
-
-      replace_strings: true
-      join_strings:    true
-
-      use_raw_bibtex_entry: true
-      bibtex_filters:
-      - superscript
-      - latex
-
-      details_dir:    bibliography
-      details_layout: bibtex.html
-      details_link:   Details
-
-      query: "@*"
-
-You can use any style that ships with
-[CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby) by name (e.g.,
-apa, mla, chicago-fullnote-bibliography) which is usually the filename as seen
-  [here](https://github.com/citation-style-language/styles)
-sans the `.csl` ending; note that you have to use `dependent/style` if you want
-to use one from that directory.
-Alternatively you can add a link to any CSL style (e.g., you could link to any of the styles available at
-the official [CSL style repository](https://github.com/citation-style-language/styles)).
-
-The `locale` settings defines what language to use when formatting
-your references (this typically applies to localized terms, e.g., 'Eds.' for
-editors in English).
-
-The `source` option indicates where your bibliographies are stored;
-`bibliography` is the name of your default bibliography. For best results,
-please ensure that your Bibliography is encoded as ASCII or UTF-8.
-
-The `use_raw_bibtex_entry` option by default disable parsing of Liquid tags 
-embedded in the Bibtex fields. This option provides a way to circumvent the 
-problem that (the conflicting syntax of) the double braces functionality of 
-BibTex is accidentally parsed by Liquid, while it was intended to keep the 
-exact capitalization style.
-
-The `sort_by` and `order` options specify if and how bibliography
-entries are sorted. Entries can be sorted on multiple fields, by using
-a list of keys, e.g. `sort_by: year,month`. Ordering can be specified
-per sort level, e.g. `order: descending,ascending` will sort the years
-descending, but per year the months are ascending. If there are more
-sort keys than order directives, the last order entry is used for the
-remaining keys.
-
-The `group_by` and `group_order` options specify how bibliography
-items are grouped. Grouping can be multi-level as well,
-e.g. `group_by: type, year` groups entries per publication type, and
-within those groups per year. Ordering for groups is specified in the
-same way as the sort order. Publication types -- specified with group
-key `type`, can be ordered by adding `type_order` to the
-configuration. For example, `type_order: article,techreport` lists
-journal articles before technical reports. Types not mentioned in
-`type_order` are considered smaller than types that are
-mentioned. Types can be merge in one group using the `type_aliases`
-setting. By default `phdthesis` and `mastersthesis` are grouped as
-`thesis`. By using, for example, `type_aliases: { inproceeding =>
-article}`, journal and conference articles appear in a single
-group. The display names for entry types are specified with
-`type_names`. Names for common types are provided, but they can be
-extended or overridden. For example, the default name for `article` is
-*Journal Articles*, but it can be changed to *Papers* using
-`type_name: { article => 'Papers' }`.
-
-The `bibtex_filters` option configures which
-[BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby) formatting filters
-values of entries should be passed through. This defaults to the `latex`
-filter which converts LaTeX character escapes into unicode, and `superscript`
-which converts the `\textsuperscript` command into a HTML `<sup>` tag.
+      style: mla
+
+The table below describes some commonly used configuration options. For a
+description of all options and their defaults, see
+[`defaults.rb`](/lib/jekyll/scholar/defaults.rb).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `style` | `apa` | Indicates the style used for the bibliography and citations. You can use any style that ships with [CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby) by name (e.g., apa, mla, chicago-fullnote-bibliography) which is usually the filename as seen [here](https://github.com/citation-style-language/styles) without the `.csl` ending; note that you have to use `dependent/style` if you want to use one from that directory. Alternatively you can add a link to any CSL  style (e.g., you could link to any of the styles available at the official [CSL style repository](https://github.com/citation-style-language/styles)). | 
+| `locale` | `en` | Defines what language to use when formatting your references (this typically applies to localized terms, e.g., 'Eds.' for editors in English). |
+| `source` | `./_bibliography` |  Indicates where your bibliographies are stored. |
+| `bibliograpy` | `references.bib` | Indicates the name of your default bibliography. For best results, please ensure that your bibliography is encoded as ASCII or UTF-8. |
+| `use_raw_bibtex_entry` | `true` | When `true`, disables parsing of Liquid tags embedded in the Bibtex fields. This option provides a way to circumvent the problem that (the conflicting syntax of) the double braces functionality of BibTex is accidentally parsed by Liquid, while it was intended to keep the exact capitalization style. |
+| `sort_by` | `none` | Specifies if and how bibliography entries are sorted. Entries can be sorted on multiple fields, by using a list of keys, e.g. `year,month`. Ordering can be specified per sort level, e.g. `order: descending,ascending` will sort the years descending, but per year the months are ascending. If there are more sort keys than order directives, the last order entry is used for the remaining keys. |
+| `order` | `ascending` | Specifies order bibliography entries are sorted in. Can be `ascending` or descending. Ordering can be specified per sort level, e.g. `descending,ascending` will sort in descending on the first key then ascending order on the second key. If there are more sort keys than order directives, the last order entry is used for the remaining keys. |
+| `group_by` | `none` | Specifies how bibliography items are grouped. Grouping can be multi-level, e.g. `type, year` groups entries per publication type, and within those groups per year. |
+| `group_order` | `ascending` |  Ordering for groups is specified in the same way as the sort order. Publication types -- specified with group key `type`, can be ordered by adding `type_order` to the configuration. For example, `type_order: article,techreport` lists journal articles before technical reports. Types not mentioned in `type_order` are considered smaller than types that are mentioned. Types can be merge in one group using the `type_aliases` setting. By default `phdthesis` and `mastersthesis` are grouped as `thesis`. By using, for example, `type_aliases: { inproceedings: article}`, journal and conference articles appear in a single group. The display names for entry types are specified with `type_names`. Names for common types are provided, but they can be extended or overridden. For example, the default name for `article` is *Journal Articles*, but it can be changed to *Papers* using `type_names: { article: Papers }`. |
+| `bibtex_filters` | `latex,superscript` | Configures which [BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby) formatting filters values of entries should be passed through. The default `latex` filter converts LaTeX character escapes into unicode, and `superscript` which converts the `\textsuperscript` command into a HTML `<sup>` tag. |
+
 
 ### Bibliographies
 
@@ -352,6 +292,19 @@ of the items you wish to quote separated by spaces. For example,
 
     <a href="#ruby">(Flanagan &amp; Matsumoto 2008; Shaughnessy 2013)</a>
 
+#### Citations when there's more than one bibliography
+
+Let's return to the example above where you have two bibliographies stored 
+in `_bibliography/books.bib` and `_bibliography/papers.bib`. We also must
+have the main bibliography, e.g., `_bibliography/references.bib`. As we
+know from above, it's possible to use bibliographies other than the main
+bibliography by calling `{% bibliography --file books %}` or 
+`{% bibliography --file papers %}`. 
+
+Though what if we want to cite an article that's not in the main bibliography? 
+We use the same approach as above; to cite an article in the `books.bib` 
+bibliography, we simply call `{% cite ruby --file books %}` 
+
 #### Suppressing author names
 
 Sometimes you want to suppress author names in a citation, because the

data/features/bibtex.feature

@@ -369,3 +369,49 @@ Feature: BibTeX
     Then the _site directory should exist
     And the "_site/scholar.html" file should exist
     And I should not see "{%[\w*]raw[\w*]%}" in "_site/scholar.html"
+
+  @config @bibliography @style
+  Scenario: A custom style with Jekyll source directory set
+    Given I have a configuration file with:
+      | key     | value              |
+      | source  | src                |
+    And I have a scholar configuration with:
+      | key     | value              |
+      | source  | _bibliography      |
+      | style   | _styles/custom.csl |
+    And I have a "src" directory
+    And I have a "src/_bibliography" directory
+    And I have a "src/_styles" directory
+    And I have a file "src/_styles/custom.csl":
+      """
+      <style>
+        <citation>
+          <layout>
+            <text variable="title"/>
+          </layout>
+        </citation>
+        <bibliography>
+          <layout>
+            <text variable="title"/>
+          </layout>
+        </bibliography>
+      </style>
+      """
+    And I have a file "src/_bibliography/references.bib":
+      """
+      @book{ruby,
+        title     = {The Ruby Programming Language},
+        author    = {Flanagan, David and Matsumoto, Yukihiro},
+        year      = {2008},
+        publisher = {O'Reilly Media}
+      }
+      """
+    And I have a page "src/scholar.html":
+      """
+      ---
+      ---
+      {% bibliography --style _styles/custom.csl %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And I should see "The Ruby Programming Language" in "_site/scholar.html"

data/features/repository.feature

@@ -98,3 +98,52 @@ Feature: PDF Repository
     And the "_site/papers/ruby.pdf" file should exist
     And I should see "Link: /papers/ruby.pdf" in "_site/scholar.html"
     And I should see "Slides: /papers/ruby.ppt" in "_site/scholar.html"
+
+  @repository
+  Scenario: A bibliography with a single entry and a repository with slides pdf
+    Given I have a scholar configuration with:
+      | key                   | value             |
+      | source                | ./_bibliography   |
+      | repository            | papers            |
+      | bibliography_template | bibliography      |
+      | file_delimit          | '.'               |
+
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{ruby,
+        title     = {The Ruby Programming Language},
+        author    = {Flanagan, David and Matsumoto, Yukihiro},
+        year      = {2008},
+        publisher = {O'Reilly Media}
+      }
+      """
+    And I have a "papers" directory
+    And I have a file "papers/ruby.pdf":
+      """
+      The PDF
+      """
+    And I have a file "papers/ruby.slides.pdf":
+      """
+      The Slides PDF
+      """
+    And I have a "_layouts" directory
+    And I have a file "_layouts/bibliography.html":
+      """
+      ---
+      ---
+      {{ reference }} Link: {{ link }} Slides: {{ links['slides.pdf'] }}
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% bibliography %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/papers/ruby.pdf" file should exist
+    And the "_site/papers/ruby.slides.pdf" file should exist
+    And I should see "The Ruby Programming Language" in "_site/scholar.html"
+    And I should see "Link: /papers/ruby.pdf" in "_site/scholar.html"
+    And I should see "Slides: /papers/ruby.slides.pdf" in "_site/scholar.html"

data/lib/jekyll/scholar/defaults.rb

@@ -1,23 +1,40 @@
 module Jekyll
   class Scholar
     @defaults = {
+      # Style used for citations and bibliographies
       'style'                  => 'apa',
+      # Sets languages used in bibliography
       'locale'                 => 'en',
 
+      # Keys used to sort bibliography
       'sort_by'                => 'none',
+      # Order used to sort biobliography
       'order'                  => 'ascending',
       'group_by'               => 'none',
       'group_order'            => 'ascending',
+      # HTML tags used for bibliography group names
       'bibliography_group_tag' => 'h2,h3,h4,h5',
+      # HTML tag used for list of bibliography entries
       'bibliography_list_tag'  => 'ol',
+      # HTML tag used for individual bibliography entries
       'bibliography_item_tag'  => 'li',
+      # Attributes applied to HTML tag for list of bibliography entries
       'bibliography_list_attributes' => {},
+      # Attributes applied to HTML tag for bibliography entries
       'bibliography_item_attributes' => {},
 
+      # Name of folder references files are stored in
       'source'                 => './_bibliography',
+      # Name of default references file
       'bibliography'           => 'references.bib',
+
+      # The repository folder with your entries' attachemnts, slides, etc.
       'repository'             => nil,
 
+      # Delimiter for files in repositories;
+      # this character may not be part of your entry keys!
+      'repository_file_delimiter' => '.',
+
       'bibtex_options'         => { :strip => false, :parse_months => true },
       'bibtex_filters'         => [ :superscript, :latex ],
       'bibtex_skip_fields'     => [ :abstract, :month_numeric ],
@@ -59,7 +76,8 @@ module Jekyll
       },
       'type_order' => [],
 
-      'month_names' => nil,
+      'month_names' => nil
+
     }.freeze
 
     class << self

data/lib/jekyll/scholar/tags/bibliography.rb

@@ -79,7 +79,7 @@ module Jekyll
         end
         group_renderer(groups,group_keys,group_order,group_tags)
       end
-      
+
       def render_items(items)
         bibliography = items.each_with_index.map { |entry, index|
           reference = bibliography_tag(entry, index + 1)
@@ -96,7 +96,7 @@ module Jekyll
           { :class => config['bibliography_class'] }.merge(config['bibliography_list_attributes'])
 
       end
-      
+
     end
 
   end

data/lib/jekyll/scholar/utilities.rb

@@ -5,12 +5,7 @@ module Jekyll
     # Load styles into static memory.
     # They should be thread safe as long as they are
     # treated as being read-only.
-    STYLES = Hash.new do |h, k|
-      style = CSL::Style.load k
-      style = style.independent_parent unless style.independent?
-      h[k.to_s] = style
-    end
-
+    STYLES = {}
 
     # Utility methods used by several Scholar plugins. The methods in this
     # module may depend on the presence of #config, #bibtex_files, and
@@ -239,6 +234,7 @@ module Jekyll
         grouper(ungrouped, group_keys, group_order)
       end
 
+
       def group_keys
         return @group_keys unless @group_keys.nil?
 
@@ -351,14 +347,15 @@ module Jekyll
         repo = Hash.new { |h,k| h[k] = {} }
 
         return repo unless repository?
-        
-        # ensure that the base directory format is literally 
+
+        # ensure that the base directory format is literally
         # the same as the entries that are in the directory
-        base = Dir[site.source][0] 
-        
+        base = Dir[site.source][0]
+
         Dir[File.join(site.source, repository_path, '**/*')].each do |path|
-          extname = File.extname(path)
-          repo[File.basename(path, extname)][extname[1..-1]] = Pathname(path).relative_path_from(Pathname(base))
+          parts = path.split(repository_file_delimiter, 2)
+          repo[File.basename(parts[0])][parts[1]] =
+            Pathname(path).relative_path_from(Pathname(base))
         end
 
         repo
@@ -368,6 +365,10 @@ module Jekyll
         config['repository']
       end
 
+      def repository_file_delimiter
+        config['repository_file_delimiter']
+      end
+
       def replace_strings?
         config['replace_strings']
       end
@@ -400,7 +401,7 @@ module Jekyll
 
       def scholar_source
         source = config['source']
-        
+
         # Improve by using Pathname from stdlib?
         return source if source.start_with?('/') && File.exists?(source)
 
@@ -455,7 +456,7 @@ module Jekyll
 
       def bibliography_tag(entry, index)
         return missing_reference unless entry
-        
+
         tmp = liquid_template.render(
           reference_data(entry,index)
             .merge(site.site_payload)
@@ -471,7 +472,7 @@ module Jekyll
         # process the generated reference with Liquid, to get the same behaviour as 
         # when it is used on a page
         Liquid::Template.parse(tmp).render(
-          site.site_payload, 
+          site.site_payload,
           {
             :registers => { :site => site },
             :filters => [Jekyll::Filters]
@@ -592,12 +593,12 @@ module Jekyll
           item.label = label unless label.nil?
 
           item
-        }, STYLES[style].citation
+        }, styles(style).citation
       end
 
       def render_bibliography(entry, index = nil)
         renderer.render citation_item_for(entry, index),
-          STYLES[style].bibliography
+          styles(style).bibliography
       end
 
       def citation_item_for(entry, citation_number = nil)
@@ -687,6 +688,29 @@ module Jekyll
         config.merge!(site.config['scholar'] || {})
         self
       end
+
+      def load_style(uri)
+        begin
+          style = CSL::Style.load uri
+        rescue CSL::ParseError => error
+          # Try to resolve local style paths
+          # relative to Jekyll's source directory
+          site_relative_style = File.join(site.source, uri)
+
+          raise error unless File.exist?(site_relative_style)
+          style = CSL::Style.load site_relative_style
+        end
+
+        if style.independent?
+          style
+        else
+          style.independent_parent
+        end
+      end
+
+      def styles(style)
+        STYLES[style] ||= load_style(style)
+      end
     end
 
   end

data/lib/jekyll/scholar/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   class Scholar
-    VERSION = '5.8.5'.freeze
+    VERSION = '5.9.0'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-scholar
 version: !ruby/object:Gem::Version
-  version: 5.8.5
+  version: 5.9.0
 platform: ruby
 authors:
 - Sylvester Keil
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-03 00:00:00.000000000 Z
+date: 2017-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: jekyll-scholar
-rubygems_version: 2.6.3
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Jekyll extensions for the academic blogger.