asciidoctor-csl 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ce78146d55d20de4621859574c6bbdc2cefa673f8712c7149c0370bc121cf12
-  data.tar.gz: be41bf38def6db2dc0608d6e5d0dbedf50f2abeaa439e78429dc7bf4db11aff0
+  metadata.gz: 91d11025bf31c30262f9edf298ebf53b5039c458d3d8415e782ee69778a0b2e5
+  data.tar.gz: 3f06bc987a676662545763a41483833e86a2eaade05cb4eb8aa7dff773171208
 SHA512:
-  metadata.gz: 9449c142d9f2b667a8cd73e569eb61b889957ce49ceb9ad9221720f40e0e6870eb4154f9b2bffcd07b8b4db94ce203e0dccdd135781a1418f73358ea57d191cd
-  data.tar.gz: af718af924f6876712b042a24e40112327fddf1ceac50c51cea26c0f3e1e7e3b09139059fca5592189cd24d8a5dde028503def04bd49dbbd83b99409b35eb1eb
+  metadata.gz: 75b1473dd6047b43cab042abc3d5cc1ea1cb3f0ec515342afa4db5f17a3d922b79a6a14b8abb22413b4d6ca0680c9bf580bb3ccd4819cddf6a02a9602010d1a3
+  data.tar.gz: ae2b790ba2d632736f6b1f9d61335b69ea86610f431623f5896f0e2b308d9fdc0da8023579cc0ca5ae716cd48bf9045bca8546c43f4924f2707da1938e5e03ce

data/README.adoc

@@ -46,6 +46,11 @@ Defaults to `ieee`.
 The language used for terms such as "p." or "and".
 Defaults to the `lang` attribute of the document, or `en` if that is not set.
 
+`csl-link-title`::
+If set, the title of each entry links to the source's DOI or URL.
+Citations are not affected.
+Override it per macro with the `link-title` attribute of `bibliography::[]` and `bibitem:key[]`.
+
 === Citations
 
 `cite:key[]` cites a source.
@@ -87,12 +92,15 @@ Citations in section titles are not supported.
 By default, it only renders the cited sources.
 Use `bibliography::[select=all]` to include everything in the bibliography.
 
+Use `bibliography::[link-title=true]` or `bibliography::[link-title=false]` to override the `csl-link-title` setting for this bibliography.
+
 Each entry gets an anchor with the source's key as ID, like `<<smith2020>>`.
 
 === Single entries
 
 `bibitem:key[]` renders the entry of a single source inline.
 It does not count as a citation: the source is not added to the bibliography and does not affect the numbering.
+Like the bibliography, it accepts `link-title=true` or `link-title=false` to override the `csl-link-title` setting.
 
 == Citation Style Language support
 

data/lib/asciidoctor-csl/bibitem_macro.rb

@@ -7,7 +7,7 @@ require 'citeproc'
 module AsciidoctorCsl
   # BibitemMacro
   #
-  # The `bibitem:key1[]` macro.
+  # The `bibitem:key1[link-title=false]` macro.
   class BibitemMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
     include ::Asciidoctor::Logging
 
@@ -17,14 +17,17 @@ module AsciidoctorCsl
 
     attr_accessor :processor
 
-    def process(parent, target, _attributes)
-      entry = processor&.render_entry(target)
+    def process(parent, target, attributes)
+      options = attributes.key?('link-title') ? { link_titles: attributes['link-title'] != 'false' } : {}
+      entry = processor&.render_entry(target, **options)
       if entry.nil?
         logger.warn "bibitem: unknown reference: #{target}"
         return create_inline parent, :quoted, "[#{target}]"
       end
 
-      create_inline parent, :quoted, entry, attributes: { 'subs' => :normal }
+      # Asciidoctor scans the output of inline macros for URLs again, linking those already linked.
+      # Encoding the colon of `://` hides them from that scan; it renders the same.
+      create_inline parent, :quoted, parent.apply_subs(entry).gsub('://', '&#58;//')
     end
   end
 end

data/lib/asciidoctor-csl/bibliography_macro.rb

@@ -6,7 +6,7 @@ require 'asciidoctor/extensions'
 module AsciidoctorCsl
   # BibliographyBlockMacro
   #
-  # Provides the bibliography block macro. (bibliography::[select=cited])
+  # Provides the bibliography block macro. (bibliography::[select=cited, link-title=false])
   class BibliographyBlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
     include ::Asciidoctor::Logging
 
@@ -30,6 +30,7 @@ module AsciidoctorCsl
       end
 
       block = create_block parent, :open, nil, { 'role' => 'bibliography' }
+      block.set_attr 'link-title', attrs['link-title'] if attrs.key?('link-title')
       blocks << block
       block
     end

data/lib/asciidoctor-csl/citation_macro.rb

@@ -50,10 +50,20 @@ module AsciidoctorCsl
 
       csl.engine.format.link_citations = @bibliography && attributes['link'] != 'false'
       text = csl.render(:citation, items)
-      # Support footnote styles
-      text = "footnote:[#{text.gsub(']', '\\]')}]" if csl.engine.style.info.citation_format == :note
+      return create_footnote parent, text if csl.engine.style.info.citation_format == :note
 
       create_inline parent, :quoted, text, attributes: { 'subs' => :normal }
     end
+
+    private
+
+    # Create the footnote like the footnote macro does, so the citation is not escaped to fit in `footnote:[]`.
+    def create_footnote(parent, text)
+      document = parent.document
+      content = parent.apply_subs text
+      index = document.counter 'footnote-number'
+      document.register :footnotes, ::Asciidoctor::Document::Footnote.new(index, nil, content)
+      create_inline parent, :footnote, content, attributes: { 'index' => index }
+    end
   end
 end

data/lib/asciidoctor-csl/citation_processor.rb

@@ -11,6 +11,7 @@ module AsciidoctorCsl
       csl_file = (document.attr 'csl-file').to_s
       csl_style = ((document.attr 'csl-style') || 'ieee').to_s
       csl_lang = (document.attr('csl-lang') || document.attr('lang') || 'en').to_s
+      csl_link_title = document.attr? 'csl-link-title'
 
       return if csl_file.empty?
 
@@ -19,7 +20,7 @@ module AsciidoctorCsl
       bibitem = document.extensions.inline_macros.map(&:instance).find { |m| m.name == :bibitem }
 
       path_to_csl = document.normalize_system_path csl_file, document.base_dir
-      processor = Processor.new path_to_csl, csl_style, csl_lang
+      processor = Processor.new path_to_csl, csl_style, csl_lang, link_titles: csl_link_title
 
       # Collect all cited keys, in appearance order.
       document.find_by(traverse_documents: true) { |b| prose?(b) }.each do |block|
@@ -39,7 +40,10 @@ module AsciidoctorCsl
       cite.bibliography = !bibliography.blocks.empty?
       bibitem.processor = processor
 
-      bibliography.blocks.each { |block| parse_content block, processor.build_bibliography_list }
+      bibliography.blocks.each do |block|
+        link_titles = block.attr?('link-title') ? block.attr('link-title') != 'false' : csl_link_title
+        parse_content block, processor.build_bibliography_list(link_titles:)
+      end
 
       nil
     end

data/lib/asciidoctor-csl/citeproc_patches.rb

@@ -21,13 +21,66 @@ module AsciidoctorCsl
 
         item.suppress! 'author' if item.suppress_author?
 
-        text = render_layout(item, node)
+        text = in_xref { render_layout(item, node) }
         text = "<<#{item.id},#{text}>>" unless text.empty?
         join [item.prefix, text, item.suffix].compact
       end
+
+      private
+
+      def in_xref
+        format.in_xref = true
+        yield
+      ensure
+        format.in_xref = false
+      end
+    end
+
+    # Support for linking URLs in the title.
+    module LinkTitles
+      def render_bibliography(item, node)
+        return super unless format.respond_to?(:link_titles) && format.link_titles
+
+        target = link_target(item.data)
+        return super unless target
+
+        doi = item.data[:DOI]
+        url = item.data[:URL]
+        suppressed = item.data.suppressed.dup
+
+        format.title_link = target
+        # Blank DOI/URL so the style renders the entry as if it had neither:
+        # groups around them collapse as for any missing variable.
+        item.data[:DOI] = nil
+        item.data[:URL] = nil
+
+        result = super
+        return result unless format.title_link
+
+        # The style rendered no title: render the entry as usual.
+        format.title_link = nil
+        item.data[:DOI] = doi
+        item.data[:URL] = url
+        # Rendering suppresses variables used as substitutes; undo that too.
+        item.data.suppressed.replace suppressed
+        super
+      ensure
+        format.title_link = nil if format.respond_to?(:title_link=)
+      end
+
+      private
+
+      def link_target(data)
+        doi = data[:DOI].to_s.strip
+        return doi.match?(%r{\Ahttps?://}i) ? doi : "https://doi.org/#{doi}" unless doi.empty?
+
+        url = data[:URL].to_s.strip
+        url unless url.empty?
+      end
     end
   end
 end
 
 CiteProc::Item.prepend AsciidoctorCsl::CiteprocPatches::SeparateSuppression
 CiteProc::Ruby::Renderer.prepend AsciidoctorCsl::CiteprocPatches::LinkCitations
+CiteProc::Ruby::Renderer.prepend AsciidoctorCsl::CiteprocPatches::LinkTitles

data/lib/asciidoctor-csl/csl_renderer.rb

@@ -7,10 +7,20 @@ module AsciidoctorCsl
 
     PROTECTED_RX = /<<[^,>]+,|\{[\w-]+}|\b[a-z][\w-]*:\S*?\[[^\]]*\]|\[[^\]]*\](?=#)|\+\+\+.*?\+\+\+|\+[^+]+\+/
     PLACEHOLDER_RX = /\u0000(\d+)\u0000/
+    URL_VARIABLES = %w[URL DOI].freeze
 
     # Whether rendered citations link to their bibliography entry.
     attr_accessor :link_citations
 
+    # Whether bibliography titles link.
+    attr_accessor :link_titles
+
+    # The target for the next rendered title, set per entry by the renderer.
+    attr_accessor :title_link
+
+    # Whether we are rendering inside a citation's cross-reference, where links cannot nest.
+    attr_accessor :in_xref
+
     def bibliography(bibliography, _locale = nil)
       bibliography.connector = "\n\n"
       bibliography
@@ -77,5 +87,55 @@ module AsciidoctorCsl
     ensure
       output.gsub!(PLACEHOLDER_RX) { protected[Regexp.last_match(1).to_i] } if protected
     end
+
+    # An affix that became part of a link is not added again.
+    def prefix
+      @prefix_in_link ? '' : super
+    end
+
+    protected
+
+    # Escape URLs and DOIs before any formatting, so AsciiDoc does not parse them.
+    def setup!
+      super
+      escape_url if node.is_a?(CSL::Style::Text) && URL_VARIABLES.include?(node.variable)
+    end
+
+    def cleanup!
+      super
+      @prefix_in_link = nil
+    end
+
+    def finalize_content!
+      super
+
+      return unless title_link && node.is_a?(CSL::Style::Text) && node.variable == 'title'
+
+      output.replace "link:#{passthrough title_link}[#{output.gsub(']', '\]')}]"
+      self.title_link = nil # link only the first rendered title
+    end
+
+    private
+
+    # Link the value if it is a URL, or becomes one with its prefix (as in prefix="https://doi.org/");
+    # a value that already is a URL ignores such a prefix. Anything else is passed through as text.
+    def escape_url
+      url = if url?(output) then output
+            elsif url?(prefix + output) then prefix + output
+            end
+      @prefix_in_link = url && url?(prefix)
+
+      text = passthrough(url || output)
+      output.replace(url && !in_xref ? "link:#{text}[]" : text)
+    end
+
+    # Not `++text++`, which cannot contain `++`.
+    def passthrough(text)
+      "pass:c[#{text.gsub(']', '\]')}]"
+    end
+
+    def url?(text)
+      text.match?(%r{\Ahttps?://}i)
+    end
   end
 end

data/lib/asciidoctor-csl/processor.rb

@@ -35,12 +35,14 @@ module AsciidoctorCsl
     def initialize(
       bibliography_file,
       style = 'ieee',
-      locale = 'en'
+      locale = 'en',
+      link_titles: false
     )
       raise "File '#{bibliography_file}' is not found" unless FileTest.file? bibliography_file
 
       @style = style
       @locale = locale
+      @link_titles = link_titles
 
       # Citations in the order they appear in the document
       @citations = []
@@ -54,10 +56,11 @@ module AsciidoctorCsl
       @citations.concat keys.map(&:strip)
     end
 
-    def render_entry(key)
+    # Render a single entry; link_titles overrides the document default.
+    def render_entry(key, link_titles: @link_titles)
       return nil unless @bibliography.key?(key)
 
-      entries.render(:bibliography, id: key).first
+      render_bibliography_with(entries, link_titles) { entries.render(:bibliography, id: key).first }
     end
 
     # Finalize citation macro processing and build internal citation list.
@@ -70,16 +73,16 @@ module AsciidoctorCsl
       keys = render_all ? @citations | @bibliography.keys : @citations
       @citeproc.import(keys.filter_map { |key| @bibliography[key] })
 
-      @rendered = @citeproc.bibliography
-
-      @rendered.ids.each_with_index do |id, i|
+      @citeproc.bibliography.ids.each_with_index do |id, i|
         @citeproc[id][:'citation-number'] = i + 1
       end
       nil
     end
 
-    def build_bibliography_list
-      @rendered.ids.zip(@rendered.references).flat_map do |id, reference|
+    # Render the bibliography; link_titles overrides the document default.
+    def build_bibliography_list(link_titles: @link_titles)
+      rendered = render_bibliography_with(@citeproc, link_titles) { @citeproc.bibliography }
+      rendered.ids.zip(rendered.references).flat_map do |id, reference|
         ["[[#{id}]]#{reference}", '']
       end
     end
@@ -101,10 +104,25 @@ module AsciidoctorCsl
 
     def new_citeproc
       citeproc = CiteProc::Processor.new style: @style, format: :asciidoc, locale: @locale
+      citeproc.engine.format.link_titles = @link_titles
       use_asciidoc_quotes citeproc
       citeproc
     end
 
+    # Render bibliography entries with the given title link setting.
+    #
+    # Also forget earlier bibliography renders: subsequent-author-substitute
+    # compares against the last rendered entry, even from a previous render.
+    def render_bibliography_with(citeproc, link_titles)
+      format = citeproc.engine.format
+      previous = format.link_titles
+      format.link_titles = link_titles
+      citeproc.engine.renderer.state.history.memory.delete('bibliography')
+      yield
+    ensure
+      format.link_titles = previous
+    end
+
     # Override the quote handling by inserting dynamic AsciiDoc quotes.
     # That way, AsciiDoc handles the quotes, and it is consistent with the rest of the document.
     def use_asciidoc_quotes(processor)

data/lib/asciidoctor-csl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciidoctorCsl
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-csl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Niko Strijbol