asciidoctor-csl 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ce78146d55d20de4621859574c6bbdc2cefa673f8712c7149c0370bc121cf12
-  data.tar.gz: be41bf38def6db2dc0608d6e5d0dbedf50f2abeaa439e78429dc7bf4db11aff0
+  metadata.gz: 3b880f935d5f43d4ccfb97b46ff5622cd61aeea3bc71f6b97a18cb010ca68d32
+  data.tar.gz: 64a474f6dd9e279f965687eb3296aed7a4a27c0f30b1396020c4a6ced437bfbb
 SHA512:
-  metadata.gz: 9449c142d9f2b667a8cd73e569eb61b889957ce49ceb9ad9221720f40e0e6870eb4154f9b2bffcd07b8b4db94ce203e0dccdd135781a1418f73358ea57d191cd
-  data.tar.gz: af718af924f6876712b042a24e40112327fddf1ceac50c51cea26c0f3e1e7e3b09139059fca5592189cd24d8a5dde028503def04bd49dbbd83b99409b35eb1eb
+  metadata.gz: a5d3e789eb43329656c173d70668e30d1aa456066a61debb33c1da10c163b2f888d3548afcc14b9e31bcd6a9330bc0e89197ce41e0370e5480fe9b7184770e9e
+  data.tar.gz: 0e323c23f6adea8c4c701626971ee37a5a9af23475ef345b26802440e2605c6c663513d6c94f0062ebbd62a430dc89f349a34a6e80bc99e2b4021e0c972612d1

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.
@@ -75,6 +80,10 @@ Other values are `book`, `column`, `figure`, `folio`, `issue`, `line`, `note`, `
 |`link`
 |If the document has a bibliography, each cited item links to its entry.
 Use `link=false` to disable this for a single citation.
+
+|`parens`
+|Use `parens=false` to leave out the parentheses around the citation, e.g. to write "(see Smith, 2020, or the appendix)" yourself.
+This removes the prefix and suffix the style puts around the whole citation; it does not affect brackets around each item, as in IEEE.
 |===
 
 With multiple keys, the locator and suffix apply to the last source, and the prefix to the first.
@@ -87,12 +96,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

@@ -7,7 +7,7 @@ require 'citeproc'
 module AsciidoctorCsl
   # CitationMacro
   #
-  # The `cite:key1,key2[locator, label, prefix=..., suffix=..., link=false]` macro.
+  # The `cite:key1,key2[locator, label, prefix=..., suffix=..., link=false, parens=false]` macro.
   class CitationMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
     include ::Asciidoctor::Logging
 
@@ -43,17 +43,23 @@ module AsciidoctorCsl
 
       items.last[:suffix] = ", #{attributes['suffix']}" if attributes['suffix']
 
-      if csl.nil?
-        logger.warn 'cite: CSL style not found'
-        return nil
-      end
-
       csl.engine.format.link_citations = @bibliography && attributes['link'] != 'false'
+      csl.engine.format.bare_citations = attributes['parens'] == '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,25 @@ module AsciidoctorCsl
 
     PROTECTED_RX = /<<[^,>]+,|\{[\w-]+}|\b[a-z][\w-]*:\S*?\[[^\]]*\]|\[[^\]]*\](?=#)|\+\+\+.*?\+\+\+|\+[^+]+\+/
     PLACEHOLDER_RX = /\u0000(\d+)\u0000/
+    URL_VARIABLES = %w[URL DOI].freeze
+    BLOCK_EDGE = "\u0001"
+    LINE_BREAK = " +\n{empty}" # {empty} keeps the next line from starting a list, comment, etc.
 
     # 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
+
+    # Whether citations leave out the affixes of their layout.
+    attr_accessor :bare_citations
+
     def bibliography(bibliography, _locale = nil)
       bibliography.connector = "\n\n"
       bibliography
@@ -66,6 +81,18 @@ module AsciidoctorCsl
       end
     end
 
+    # Blocks get their own line.
+    # AsciiDoc has no margins, so the margin column stays inline.
+    def apply_display
+      case options[:display]
+      when 'block', 'indent' then output.replace "#{BLOCK_EDGE}#{output}#{BLOCK_EDGE}"
+      when 'left-margin' then output << ' '
+      when 'right-inline' then nil
+      else
+        logger.warn "csl: unsupported display '#{options[:display]}'"
+      end
+    end
+
     # Replace the AsciiDoc syntax by placeholders without letters, so we only transform actual text.
     def apply_text_case
       protected = []
@@ -77,5 +104,67 @@ 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, and bare citations have no layout affixes.
+    def prefix
+      @prefix_in_link || bare_citation_layout? ? '' : super
+    end
+
+    def suffix
+      bare_citation_layout? ? '' : super
+    end
+
+    protected
+
+    # Before formatting, escape URLs and DOIs, so AsciiDoc does not parse them,
+    # and turn block edges into line breaks, so the layout's affixes stay on the first and last line.
+    def setup!
+      super
+      if node.is_a?(CSL::Style::Layout)
+        output.replace output.split(BLOCK_EDGE).map(&:strip).reject(&:empty?).join(LINE_BREAK)
+      end
+      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 bare_citation_layout?
+      bare_citations && node.is_a?(CSL::Style::Layout) && node.parent.is_a?(CSL::Style::Citation)
+    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.4.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.4.0
 platform: ruby
 authors:
 - Niko Strijbol