asciidoctor-foodogsquared-extensions 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 903ca29ce450d3aad60571b57c851fbfcf11524f9fcda8ae3ba388e9c619fdf0
-  data.tar.gz: 405bfafa852a1bc66ebf46c1242bee986cc949c78289d699c987dacda17feac0
+  metadata.gz: 49db0995b8f1dd14e46463b687e10114fd1a86498b47f61bd3c9b6a17cb32651
+  data.tar.gz: 286296368f012d16bf94dd66e2f1847866fc2c67d948179eb8e45d550da90e14
 SHA512:
-  metadata.gz: 63bc0807247b017729d2b4177796a32ffa34635fb373020552028827ff3b4cfdcea22c958e1abeb084f2c6f6d3e44a5bd154b6e5c479af94425e86c69aeed067
-  data.tar.gz: bed6effd30c18654a20582ddb383c249ed6f6ddf83ee751c10e4f1f01c98ab0551b7e3fcb095997893a16bf6bfa05e91f28d37986923c59b7fb6190882c5997f
+  metadata.gz: b5f9b29ae1e1c10a4642e8470610db3c37bdde4af49a230b0a7a77299c651436ae58c3b70b425f203b080bb9acc17637b1d02e0acab511de0d32f52322030689
+  data.tar.gz: 4cdb81ddbb0490e6082257044e64b732b962ca1169bc56f66cccbbbca1cd40b41cb6eaa84a40d95909a6de94b6d6389bcfab9fe1b957f0fb245ed8a043ddd9ad

data/CHANGELOG.adoc

@@ -6,6 +6,27 @@
 
 
 The guidelines for writing this changelog is based from link:https://common-changelog.org[Common Changelog].
+Although, this project doesn't follow the Semantic Versioning convention.
+Versioning mostly happens on a whim.
+
+
+== [1.2.0] - 2023-11-08
+
+=== Added
+
+* Add `subpath` option for man inline macro.
+This enables making links to other versions of the online manpage service such as in Debian (i.e., `man:ls[1, subpath=/bookworm]`) ({commit-url}/69c8015292ceb9fab03250109b2c5009605a9a8f[`69c8015`]) (Gabriel Arazas)
+
+* Create an extended converter for HTML5.
+This is to handle new blocks with context such as the revamped chat block. ({commit-url}/6291f3b36d44c271a66a5ad88906cb707e291b3d[`6291f3b`])
+
+=== Updated
+
+* Restructure the modules.
+There should be no difference in using unless you're using the Asciidoctor API which makes it a complete breaking change. footnote:[So far, no one is aware this extension exists so it shouldn't be. If no user uses the project, is it really a breaking change? :)] ({commit-url}/95e7bc12ecd1e573c94b1322ef1b03dec17e8c70[`95e7bc1`]) (Gabriel Arazas)
+
+* Update the chat block to have its own context.
+This makes it configurable with a template. ({commit-url}/6291f3b36d44c271a66a5ad88906cb707e291b3d[`6291f3b`]) (Gabriel Arazas)
 
 
 == [1.1.0] - 2023-11-01

data/asciidoctor-foodogsquared-extensions.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'asciidoctor-foodogsquared-extensions'
-  s.version       = '1.1.0'
+  s.version       = '1.2.1'
   s.licenses      = ['MIT']
   s.summary       = "foo-dogsquared's custom Asciidoctor extensions"
   s.description   = <<-DESC

data/lib/asciidoctor/foodogsquared/converter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# foodogsquared's custom converter that is an extended version of the built-in
+# HTML5 converter. It features custom blocks as well as their preferred output
+# for certain blocks.
+module Asciidoctor::Foodogsquared::Converter
+  class Html5Custom < (Asciidoctor::Converter.for 'html5')
+    register_for 'html5'
+
+    def convert_chat(node)
+      attributes = []
+      attributes << %(id="#{node.id}") if node.id
+      attributes << %(class="#{node.role}") if node.role
+
+      avatar_sticker = node.attributes['avatarsticker']
+      avatar_uri = node.parent.image_uri avatar_sticker, 'avatarsdir'
+
+      <<~HTML
+        <div role="figure" #{attributes.join ' '}>
+          <div class="dialogblock-avatar">
+            <img src="#{avatar_uri}" alt="#{node.attributes['name']}">
+          </div>
+          <div class="dialogblock-text">
+            <small>#{node.attributes['name']}</small>
+            #{node.content}
+          </div>
+        </div>
+      HTML
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/chat-block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Foodogsquared::Extensions
+  class ChatBlock < Asciidoctor::Extensions::BlockProcessor
+    use_dsl
+
+    named :chat
+    on_context :example
+    name_positional_attributes 'avatar', 'state'
+    default_attributes 'state' => 'default'
+
+    def process(parent, reader, attrs)
+      attrs['name'] ||= attrs['avatar']
+
+      # Configuring the avatar-related attributes.
+      attrs['avatarsdir'] ||= File.expand_path('./avatars', attrs['iconsdir'])
+      attrs['avatarstype'] ||= parent.attributes['avatarstype'] || 'avif'
+      attrs['avatarsticker'] = "#{attrs['avatar'].to_kebab}/#{attrs['state'].to_kebab}.#{attrs['avatarstype']}"
+
+      block = create_block parent, :chat, nil, attrs, content_model: :compound
+      block.add_role 'dialogblock'
+
+      block
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/fdroid-inline-macro.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'open-uri'
+require 'yaml'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class FDroidInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :fdroid
+    name_positional_attributes 'caption'
+    default_attributes 'lang' => 'en'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+
+      app_id = target
+      app_metadata_uri = %(https://gitlab.com/fdroid/fdroiddata/-/raw/master/metadata/#{app_id}.yml)
+
+      metadata = OpenURI.open_uri(app_metadata_uri) { |f| YAML.safe_load(f.read) }
+      attrs['caption'] ||= metadata['AutoName']
+
+      url = %(https://f-droid.org/#{attrs['lang']}/packages/#{app_id})
+      doc.register :links, url
+      create_anchor parent, attrs['caption'], type: :link, target: url
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/flathub-inline-macro.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open-uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class FlathubInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :flathub
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+
+      # FlatHub API seems to have no documentation aside from the source code.
+      # You can easily infer the API with its source code at
+      # https://github.com/flathub/website.
+      app_id = target
+      app_metadata_uri = %(https://flathub.org/api/v2/appstream/#{app_id})
+
+      headers = {
+        'Accept' => 'application/json',
+        'User-Agent' => ::Asciidoctor::Foodogsquared::USER_AGENT
+      }
+
+      metadata = OpenURI.open_uri(app_metadata_uri, headers) { |f| JSON.parse(f.read) }
+      attrs['caption'] ||= metadata['name']
+
+      url = %(https://flathub.org/apps/#{app_id})
+      doc.register :links, url
+      create_anchor parent, attrs['caption'], type: :link, target: url
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/git-blob-include-processor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'rugged'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class GitBlobIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+    def handles?(target)
+      target.start_with? 'git:'
+    end
+
+    def process(doc, reader, target, attrs)
+      attrs['gitrepo'] ||= doc.attributes['gitrepo'] || doc.base_dir
+      repo = Rugged::Repository.discover(attrs['gitrepo'])
+
+      git_object_ref = target.delete_prefix 'git:'
+      git_object_ref = doc.attributes['doccontentref'] if git_object_ref.empty?
+
+      begin
+        git_object = repo.rev_parse git_object_ref
+
+        if attrs.key? 'diff-option'
+          options = {}
+
+          options[:paths] = attrs['path'].split(';') if attrs.key? 'path'
+          options[:context_lines] = attrs['context-lines'] if attrs.key? 'context-lines'
+          options[:reverse] = true if attrs.key? 'reverse-option'
+
+          if attrs.key? 'other'
+            other = repo.rev_parse attrs['other'] || nil
+            reader.push_include git_object.diff(other, **options).patch
+          else
+            reader.push_include git_object.diff(**options).patch
+          end
+        else
+          inner_entry = case git_object.type
+                        when :blob
+                          git_object
+                        when :commit
+                          git_object.tree.path attrs['path']
+                        when :tree
+                          git_object.path attrs['path']
+                        when :tag
+                          git_object.target.tree.path attrs['path']
+                        end
+
+          content = repo.lookup(inner_entry[:oid]).content
+
+          if attrs.key? 'lines'
+            content_lines = content.lines
+            new_content = +''
+            doc.resolve_lines_to_highlight(content, attrs['lines']).each do |line_no|
+              new_content << content_lines.at(line_no - 1)
+            end
+
+            content = new_content
+          end
+
+          reader.push_include content
+        end
+      rescue StandardError => e
+        reader.push_include "Unresolved directive for '#{target}' with the following error:\n#{e}"
+        warn e
+      end
+
+      reader
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/github-include-processor.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'open-uri'
+require 'uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class GitHubIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+    def handles?(target)
+      target.start_with? 'github:'
+    end
+
+    def warn_or_raise(doc, warning)
+      if (doc.safe > Asciidoctor::SafeMode::SERVER) && !(doc.attr? 'allow-uri-read')
+        raise warning
+      else
+        warn warning
+      end
+    end
+
+    def process(doc, reader, target, attrs)
+      src = target.delete_prefix('github:').split('/', 3)
+      owner = src.at 0
+      repo = src.at 1
+      namespaced_repo = "#{owner}/#{repo}"
+
+      path = attrs['path'] || ''
+
+      # For more information, see https://docs.github.com/en/rest/repos/contents.
+      uri = URI.parse %(https://api.github.com/repos/#{owner}/#{repo}/contents/#{path})
+
+      if attrs['rev']
+        query = { ref: attrs['rev'] }
+        uri.query = URI.encode_www_form query
+      end
+
+      begin
+        headers = {
+          'Header' => 'application/vnd.github+json',
+          'X-GitHub-Api-Version' => '2022-11-28'
+        }
+
+        headers['Authorization'] = "Token #{ENV['GITHUB_API_BEARER_TOKEN']}" if ENV['GITHUB_API_BEARER_TOKEN']
+
+        OpenURI.open_uri(uri, headers) do |f|
+          response = JSON.parse(f.read)
+
+          # If the response is an array, it is likely to be a directory. In this
+          # usecase, we'll just list them.
+          content = if response.is_a? Array
+                      warning = %(given path '#{path}' from GitHub repo '#{repo}' is a directory)
+                      warn_or_raise doc, warning
+                      warning
+                    elsif response.is_a? Object
+                      Base64.decode64 response['content'] if response['content'] && response['encoding'] == 'base64'
+                    end
+
+          reader.push_include content, target, target, 1, attrs
+        end
+      rescue OpenURI::HTTPError => e
+        warning = %(error while getting '#{path}' in GitHub repo '#{namespaced_repo}: #{e}')
+        warn_or_raise doc, warning
+        reader.push_include warning, target, target, 1, attrs
+      end
+
+      reader
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/github-inline-macro.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class GitHubInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :github
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+
+      default_caption = if attrs.key?('repo-option')
+                          target.split('/').at(1)
+                        else
+                          target
+                        end
+      text = attrs['caption'] || default_caption
+      uri = URI.parse %(https://github.com/#{target})
+
+      if attrs.key? 'issue'
+        uri.path += %(/issues/#{attrs['issue']})
+        text << "##{attrs['issue']}" if text == target
+      else
+        uri.path += %(/tree/#{attrs['rev']}) if attrs.key? 'rev'
+        uri.path += %(/#{attrs['path']}) if attrs.key? 'path'
+        text << "@#{attrs['rev']}" if attrs.key?('rev') && text == target
+      end
+
+      target = uri.to_s
+
+      doc.register :links, target
+      create_anchor parent, text, type: :link, target: target
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/gitlab-include-processor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'open-uri'
+require 'uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class GitLabIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+    def handles?(target)
+      target.start_with? 'gitlab:'
+    end
+
+    def process(doc, reader, target, attrs)
+      src = target.delete_prefix('gitlab:').split('/', 2)
+      owner = src.at 0
+      repo = src.at 1
+      namespaced_repo = "#{owner}/#{repo}"
+
+      raise %(there is no 'path' attribute given for GitLab repo '#{namespaced_repo}') unless attrs.key? 'path'
+      raise %(no given ref for getting file in '#{namespaced_repo}') unless attrs.key? 'rev'
+
+      path = attrs['path']
+      rev = attrs['rev']
+
+      domain = attrs['domain'] || 'gitlab.com'
+      version = attrs['version'] || 'v4'
+
+      uri = URI.parse %(https://#{domain}/api/#{version})
+
+      # Set the project.
+      uri += %(/projects/#{URI.encode_www_form_component namespaced_repo})
+
+      # Then the filename.
+      uri += %(/repository/files/#{URI.encode_www_form_component path})
+
+      # Then the revision.
+      query = { ref: rev }
+      uri.query = URI.encode_www_form query
+
+      content = begin
+        headers = { 'Content-Type' => 'application-json' }
+        header['PRIVATE-TOKEN'] = ENV['GITLAB_API_PERSONAL_ACCESS_TOKEN'] if ENV['GITLAB_API_PERSONAL_ACCESS_TOKEN']
+
+        OpenURI.open_uri(uri, headers) do |f|
+          response = JSON.parse(f.read)
+
+          Base64.decode64 response['content'] if response['content'] && response['encoding'] == 'base64'
+        end
+      rescue OpenURI::HTTPError => e
+        warning = %(error while getting '#{path}' in GitLab repo '#{repo}': #{e})
+        warn_or_raise doc, warning
+        warning
+      end
+
+      reader.push_include content, target, target, 1, attrs
+      reader
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/gitlab-inline-macro.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class GitLabInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :gitlab
+    name_positional_attributes 'caption'
+    default_attributes 'domain' => 'gitlab.com'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+
+      default_caption = if attrs.key?('repo-option')
+                          target.split('/').at(1)
+                        else
+                          target
+                        end
+      text = attrs['caption'] || default_caption
+      uri = URI.parse %(https://#{attrs['domain']}/#{target})
+
+      if attrs.key? 'issue'
+        uri.path += %(/-/issues/#{attrs['issue']})
+        text << "##{attrs['issue']}" if text == target
+      else
+        uri.path += %(/-/tree/#{attrs['rev']}) if attrs.key? 'rev'
+        uri.path += %(/#{attrs['path']}) if attrs.key? 'path'
+        text << "@#{attrs['rev']}" if attrs.key?('rev') && text == target
+      end
+
+      target = uri.to_s
+
+      doc.register :links, target
+      create_anchor parent, text, type: :link, target: target
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/ietf-rfc-inline-macro.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Foodogsquared::Extensions
+  class IETFRFCInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :rfc
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      url = %(https://datatracker.ietf.org/doc/html/#{target})
+      attrs['caption'] ||= "RFC#{target}"
+      doc.register :links, url
+      create_anchor parent, attrs['caption'], type: :link, target: url
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/man-inline-macro.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Foodogsquared::Extensions
+  class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :man
+    name_positional_attributes 'volnum'
+    default_attributes 'service' => 'debian', 'subpath' => ''
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      manname = target
+
+      text = %(#{manname}(#{attrs['volnum']}))
+
+      if doc.basebackend? 'html'
+        domain = case attrs['service']
+                 when 'debian'
+                   'https://manpages.debian.org'
+                 when 'ubuntu'
+                   'https://manpages.ubuntu.org'
+                 when 'arch'
+                   'https://man.archlinux.org/man'
+                 when 'opensuse'
+                   'https://manpages.opensuse.org'
+                 when 'voidlinux'
+                   'https://man.voidlinux.org'
+                 when 'openbsd'
+                   'https://man.openbsd.org'
+                 when 'none'
+                   nil
+                 else
+                   raise "no available manpage service #{attrs['service']}"
+                 end
+
+        subpath = "#{attrs['subpath'].delete_prefix('/').delete_suffix('/')}/" if !attrs['subpath'].empty?
+        if !domain.nil?
+          target = %(#{domain}/#{subpath}#{manname}.#{attrs['volnum']})
+          doc.register :links, target
+          node = create_anchor parent, text, type: :link, target: target
+        else
+          node = create_inline parent, :quoted, text
+        end
+      elsif doc.backend == 'manpage'
+        node = create_inline parent, :quoted, text, type: :strong
+      else
+        node = create_inline parent, :quoted, text
+      end
+
+      node
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/musicbrainz-inline-macro.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open-uri'
+require 'uri'
+
+module Asciidoctor::Foodogsquared::Extensions
+  class MusicBrainzInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :musicbrainz
+    name_positional_attributes 'caption', 'type'
+    default_attributes 'type' => 'release'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      root_endpoint = 'https://musicbrainz.org/ws/2'
+
+      begin
+        headers = {
+          'Accept' => 'application/json',
+          'User-Agent' => ::Asciidoctor::Foodogsquared::USER_AGENT
+        }
+
+        uri = %(#{root_endpoint}/#{attrs['type']}/#{target})
+
+        metadata = OpenURI.open_uri(uri, headers) { |f| JSON.parse(f.read) }
+        attrs['caption'] ||= case attrs['type']
+                             when 'artist', 'area', 'events', 'genre', 'instrument', 'label', 'place', 'series'
+                               metadata['name']
+                             when 'recording', 'release-group', 'release', 'cdstub', 'work'
+                               metadata['title']
+                             when 'url'
+                               metadata['resource']
+                             end
+
+        target = %(https://musicbrainz.org/#{attrs['type']}/#{target})
+        doc.register :links, target
+        create_anchor parent, attrs['caption'], type: :link, target: target
+      rescue StandardError
+        warning = %(error while getting Musicbrainz database object '#{target}: #{e}')
+        warn_or_raise doc, warning
+        reader.push_include warning, target, target, 1, attrs
+      end
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/package-indices-macro.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# I'm fairly sure this could be programmed since Ruby has nice metaprogramming
+# capabilities. Though, we'll be keeping it manually defining classes for now
+# for initial versions since there could be additional features for each macro.
+
+module Asciidoctor::Foodogsquared::Extensions
+  class CtanInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :ctan
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      text = attrs['caption'] || target
+      url = %(https://ctan.org/pkg/#{target})
+
+      doc.register :links, url
+
+      create_anchor parent, text, type: :link, target: url
+    end
+  end
+
+  class PypiInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :pypi
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      text = attrs['caption'] || target
+      url = %(https://pypi.org/project/#{target})
+
+      doc.register :links, url
+
+      create_anchor parent, text, type: :link, target: url
+    end
+  end
+
+  class CratesIOInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :cratesio
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      text = attrs['caption'] || target
+      url = %(https://crates.io/crates/#{target})
+
+      doc.register :links, url
+
+      create_anchor parent, text, type: :link, target: url
+    end
+  end
+end

data/lib/asciidoctor/foodogsquared/extensions/repology-inline-macro.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Foodogsquared::Extensions
+  class RepologyInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+
+    named :repology
+    name_positional_attributes 'caption'
+
+    def process(parent, target, attrs)
+      doc = parent.document
+      text = attrs['caption'] || target
+      url = %(https://repology.org/project/#{target})
+
+      doc.register :links, url
+
+      create_anchor parent, text, type: :link, target: url
+    end
+  end
+end