asciidoctor-foodogsquared-extensions 1.0.0

data/lib/asciidoctor/github-raw-content-include-processor/extension.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'open-uri'
+require 'uri'
+
+class GitHubRawIncludeProcessor < 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

data/lib/asciidoctor/gitlab-link-inline-macro/README.adoc

@@ -0,0 +1,37 @@
+= GitLab link inline macro
+:toc:
+
+
+An inline macro for easily linking objects from GitLab instances.
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+gitlab:$OWNER/$REPO[$CAPTION]
+----
+
+
+== Attributes
+
+- `domain` is the base domain of the GitLab instance.
+By default, it points to the official instance of `gitlab.com`.
+
+- `rev` is the commit of the repo.
+By default. it doesn't point to anything which should be in the default branch of the repository.
+
+- `path` is the filepath to be linked.
+
+There are settings that is enabled with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
+
+- `repo` sets the default caption to be the repo part.
+
+
+== Example usage
+
+- `gitlab:gitlab-org/gitlab[]` will link to link:https://gitlab.com/gitlab-org/gitlab[the GitLab's source code with the default domain].
+
+- `gitlab:gitlab-org/gitlab[rev=0c9f77389424b6c5fd8e96b227e9125a13a07cb3, path=README.md]` should link to the link:https://gitlab.com/gitlab-org/gitlab/-/blob/0c9f77389424b6c5fd8e96b227e9125a13a07cb3/README.md[GitLab's README from 3 years ago].
+
+- `gitlab:GNOME/mutter[domain=gitlab.gnome.org, rev=df653b95adf6462fc731998eb53b0860baa7253c, path=meson.build]` should link to link:https://gitlab.gnome.org/GNOME/mutter/-/blob/df653b95adf6462fc731998eb53b0860baa7253c/meson.build[Mutter v44.beta `meson.build` from GNOME GitLab instance].

data/lib/asciidoctor/gitlab-link-inline-macro/extension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+class GitLabLinkInlineMacro < 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})
+
+    uri.path += %(/-/tree/#{attrs['rev']}) if attrs['rev']
+    uri.path += %(/#{attrs['path']}) if attrs['path']
+
+    target = uri.to_s
+
+    doc.register :links, target
+    create_anchor parent, text, type: :link, target: target
+  end
+end

data/lib/asciidoctor/gitlab-raw-content-include-processor/README.adoc

@@ -0,0 +1,44 @@
+= GitLab raw content include processor
+:toc:
+
+
+It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]
+----
+
+
+== Extra notes
+
+A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.
+Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.
+
+
+== Attributes
+
+There are some attributes required to be passed.
+
+- `rev` is the commit to be checked out.
+- `path` is the file path to be included.
+
+Aside from the required attributes, there are optional attributes to configured further.
+
+- `domain` is the domain of the GitLab instance.
+By default, it points to the `gitlab.com` official instance.
+
+- `version` is the version string of the API to be used.
+By default, it uses version `v4`.
+
+
+== Example usage
+
+- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].
+
+- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].
+
+- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.

data/lib/asciidoctor/gitlab-raw-content-include-processor/extension.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'open-uri'
+require 'uri'
+
+class GitLabRawIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+  def handles?(target)
+    target.start_with? 'gitlab:'
+  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('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

data/lib/asciidoctor/helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class String
+  def to_kebab
+    self.gsub(/\s+/, '-')           # Replace all spaces with dashes.
+        .gsub(/[^a-zA-Z0-9-]/, '')  # Remove all non-alphanumerical (and dashes) characters.
+        .gsub(/-+/, '-')            # Reduce all dashes into only one.
+        .gsub(/^-|-+$/, '')         # Remove all leading and trailing dashes.
+        .downcase
+  end
+end
+
+module Asciidoctor
+  module FoodogsquaredCustomExtensions
+    NAME = 'asciidoctor-foodogsquared-custom-extensions'
+    VERSION = '1.0.0'
+    CONTACT_EMAIL = 'foodogsquared@foodogsquared.one'
+    USER_AGENT = "#{NAME}/#{VERSION} ( #{CONTACT_EMAIL} )"
+  end
+end

data/lib/asciidoctor/ietf-rfc-link-inline-macro/README.adoc

@@ -0,0 +1,27 @@
+= Flathub link inline macro
+:toc:
+
+
+A shorthand for linking link:https://datatracker.ietf.org/[IETF RFCs].
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+rfc:$RFC[$CAPTION]
+----
+
+Where...
+
+- `$RFC` is the RFC number.
+
+- `$CAPTION` is the link text to be used.
+By default, it will be `RFC$RFC`.
+
+
+== Example usage
+
+- `rfc:2136[]` links to the link:https://datatracker.ietf.org/doc/html/rfc2136[RFC2136 (dynamic update)] with the caption `RFC2136`.
+
+- `rfc:2136[Dynamic DNS updates]` is the same as the previous list item but with the caption text `Dynamic DNS updates`.

data/lib/asciidoctor/ietf-rfc-link-inline-macro/extension.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class IETFRFCLinkInlineMacro < 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

data/lib/asciidoctor/man-inline-macro/README.adoc

@@ -0,0 +1,51 @@
+= Man inline macro
+:toc:
+
+
+It's a link:https://docs.asciidoctor.org/asciidoctorj/latest/extensions/inline-macro-processor/[inline macro] that easily links manual pages from an online manpage service like link:https://manpages.debian.org/[Debian Manpages].
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+man:$MANPAGE[$VOLNUM]
+----
+
+
+== Attributes
+
+There are optional attributes that can be passed.
+
+- `volnum` expects the section number where the manual page belongs to.
+This attribute is another way to indicate the section in case you start to use more attributes.
+The value from `volnum` attribute has higher precedence.
+When both the positional argument and `volnum` attribute is passed, the `volnum` attribute will be used.
+
+- `service` is the domain of the online manpage service.
+Take note this attribute is only used in `html` backend.
++
+--
+This is an attribute that expects certain values:
+
+- `debian` uses https://manpages.debian.org.
+This is also the default service when no value is given.
+
+- `archlinux` uses https://man.archlinux.org.
+
+- `opensuse` uses https://manpages.opensuse.org.
+
+- `voidlinux` use https://man.voidlinux.org.
+
+- `none` uses none at all. :)
+This is useful if the reference is not found anywhere.
+
+Any invalid value raises an error.
+--
+
+
+== Example usage
+
+- `man:crontab[5]` will link to the default manpage service with `crontab(5)` manual page.
+
+- `man:man[volnum=1, service=archlinux]` will link to the link:https://man.archlinux.org/man/man.1[man manpage] from link:https://man.archlinux.org/[man.archlinux.org].

data/lib/asciidoctor/man-inline-macro/extension.rb

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

data/lib/asciidoctor/musicbrainz-link-inline-macro/README.adoc

@@ -0,0 +1,45 @@
+= Musicbrainz link inline macro
+:toc:
+
+
+An inline macro for easily linking objects from link:https://musicbrainz.org/doc/MusicBrainz_Database[Musicbrainz database].
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+musicbrainz:$ID[$CAPTION, $TYPE]
+----
+
+- `$ID` is the database identifier for that object (e.g., `9adcff14-7dba-4ccf-a6a6-298bcde3dd46`).
+
+- `$CAPTION` is the link text.
+By default, it will be the name of the database object (if valid).
+Take note it will use the MusicBrainz API to query the title/name of the object.
+In other words, it costs an additional network request.
+
+- `$TYPE` is the database object type.
+It defaults to 'Release' object type.
+
+
+== Attributes
+
+The macro can also accept some attributes.
+
+- `caption` is the link text to be used.
+This can be used instead of the first positional attribute.
+
+- `type` is the database object type to be queried.
+This can be used instead of the second positional attribute.
+
+
+== Example usage
+
+- `musicbrainz:9adcff14-7dba-4ccf-a6a6-298bcde3dd46[]` should have a link to the link:https://musicbrainz.org/release/9adcff14-7dba-4ccf-a6a6-298bcde3dd46[Musicbrainz page for The Bindings of Isaac Rebirth] with 'The Bindings of Isaac: Rebirth' as the link caption.
+
+- `musicbrainz:9adcff14-7dba-4ccf-a6a6-298bcde3dd46[Ridiculon's Rebirth soundtrack]` same as above but with the link text replaced with 'Ridiculon's Rebirth Soundtrack'.
+
+- `musicbrainz:b7c7f603-4c42-45a4-b364-3ddba82da412[type=release-group]` links to the link:https://musicbrainz.org/release-group/b7c7f603-4c42-45a4-b364-3ddba82da412[Musicbrainz page for The Bindings of Isaac Rebirth release group] with 'The Bindings of Isaac: Rebirth' as the link text.
+
+- `musicbrainz:f07c6afe-ee84-4cd5-9b11-5c541d1dff3b[type=artist]` links to link:https://musicbrainz.org/artist/f07c6afe-ee84-4cd5-9b11-5c541d1dff3b[Musicbrainz page for Ridiculon] with their name as the caption.

data/lib/asciidoctor/musicbrainz-link-inline-macro/extension.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open-uri'
+require 'uri'
+
+class MusicBrainzLinkInlineMacro < 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::FoodogsquaredCustomExtensions::USER_AGENT
+      }
+
+      uri = %(#{root_endpoint}/#{attrs['type']}/#{target})
+
+      if attrs['caption'].nil?
+        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
+      end
+
+      target = %(https://musicbrainz.org/#{attrs['type']}/#{target})
+      doc.register :links, target
+      create_anchor parent, attrs['caption'], type: :link, target: target
+    rescue 
+      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

data/lib/asciidoctor/package-indices-link-macro/extension.rb

@@ -0,0 +1,56 @@
+# 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.
+
+class CtanLinkInlineMacro < 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 PypiLinkInlineMacro < 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 CratesIOLinkInlineMacro < 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

data/lib/asciidoctor/repology-link-inline-macro/README.adoc

@@ -0,0 +1,27 @@
+= Repology link inline macro
+:toc:
+
+
+An inline macro for shorthands Repology links.
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+repology:$PROJECT[$CAPTION]
+----
+
+Where...
+
+- `$PROJECT` is the project name listed in link:https://repology.org/projects/[Repology's project list].
+
+- `$CAPTION` is the link text to be used.
+By default, it will use the project name.
+
+
+== Example usage
+
+- `repology:beets[]` should link to the link:https://repology.org/project/beets/[Beets project page in Repology] with `beets` as the link text.
+
+- `repology:beets[widely available in Linux distributions]` is the same as the previous item but with the link text replaced to `widely available in Linux distributions`.

data/lib/asciidoctor/repology-link-inline-macro/extension.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class RepologyLinkInlineMacro < 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

data/lib/asciidoctor/swhid-include-processor/README.adoc

@@ -0,0 +1,44 @@
+= SWHID include processor
+:toc:
+
+
+This is an include processor extension for easily fetching SWHIDs, only with the `cnt` schema type.
+
+
+== Synopsis
+
+[source, asciidoc]
+----
+\include::$SWHID[]
+----
+
+Where `$SWHID` is a link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHID].
+This could accept SWHIDs with qualifiers.
+
+Take note this include processor will only give the raw content with the `cnt` schema type.
+Anything else will be skipped and log a warning instead.
+
+
+
+== Extra notes
+
+[source, asciidoc]
+----
+= doctitle
+:swhid-gpl3: swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2
+
+\include::{swhid-nixpkgs}[]
+----
+
+This include processor also respects the safe mode setting.
+This means in order to permit including by SWHID, you have to permit link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[includes by URIs].
+
+Lastly, this include processor uses the Software Heritage API which includes a limitation.
+You could create authorized requests by setting `SWH_API_BEARER_TOKEN` environment variable with a token.
+
+
+== Example usage
+
+- SWHID with a bare core identifier: `include::swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`.
+
+- SWHID with full contextual information: `include::swh:1:cnt:4c6ad635164b25b9bc2ebe17d2c3b7c0835f6035;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:7f5639fa3b68054ca0b062866dc62b22c3f11505;path=/README.md`.