From d07b784be2fc374b71b20312e5e9e539aff5a4fe Mon Sep 17 00:00:00 2001
From: Gabriel Arazas <foodogsquared@foodogsquared.one>
Date: Sun, 5 Mar 2023 09:47:44 +0800
Subject: [PATCH] Add SWHID link inline macro

---
 .../asciidoctor/foodogsquared-extensions.rb   |  2 +
 .../swhid-inline-macro/README.adoc            | 43 +++++++++++++++++++
 .../swhid-inline-macro/extension.rb           | 21 +++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 gems/lib/asciidoctor/swhid-inline-macro/README.adoc
 create mode 100644 gems/lib/asciidoctor/swhid-inline-macro/extension.rb

diff --git a/gems/lib/asciidoctor/foodogsquared-extensions.rb b/gems/lib/asciidoctor/foodogsquared-extensions.rb
index 2b0afab..f3930d0 100644
--- a/gems/lib/asciidoctor/foodogsquared-extensions.rb
+++ b/gems/lib/asciidoctor/foodogsquared-extensions.rb
@@ -1,7 +1,9 @@
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 require_relative 'man-inline-macro/extension'
+require_relative 'swhid-inline-macro/extension'
 
 Asciidoctor::Extensions.register do
   inline_macro ManInlineMacro
+  inline_macro SWHInlineMacro
 end
diff --git a/gems/lib/asciidoctor/swhid-inline-macro/README.adoc b/gems/lib/asciidoctor/swhid-inline-macro/README.adoc
new file mode 100644
index 0000000..2071d8d
--- /dev/null
+++ b/gems/lib/asciidoctor/swhid-inline-macro/README.adoc
@@ -0,0 +1,43 @@
+= SWHID inline macro extension
+:toc:
+
+
+An inline macro for easily linking link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHIDs].
+
+[source, asciidoc]
+----
+swh:$SWHID[$CAPTION]
+----
+
+If no caption is given, the link text will be the core identifier of the SWHID.
+
+
+== Extra notes
+
+You would use like in the following form `swh:swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]` but you could also cut off `swh:` from the SWHID if you want to (i.e., `swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]`) to make it aesthetically pleasing.
+
+Whatever your preference is, the best practice for dealing with linking SWHIDs with this macro is setting attributes containing the SWHIDs.
+
+[source, asciidoc]
+----
+= doctitle
+:swhid-nixpkgs: swh:1:dir:2885ecf76632a83610d8e95f0eb3383109a7c90a
+
+{swhid-nixpkgs}[this revision of nixpkgs]
+or
+swh:{swhid-nixpkgs}[that revision of nixpkgs]
+----
+
+
+== Example usage
+
+This should work with the following types of SWHIDs.
+
+- A SWHID with only the core identifier: `swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]`.
+
+- A SWHID with only one qualifier: `swh:1:cnt:ce4dd1988d2d5dfcec48252757a6fea94339ac38;lines=3-4[]`
+
+- A SWHID with full contextual information.
+This is as depicted from the recommended practice for writings (i.e., blog posts, technical documentation, research papers) when referring to one of the objects in the archive.
++
+`swh:1:dir:2885ecf76632a83610d8e95f0eb3383109a7c90a;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:b7ee21d0ced814d07b7d5aca334dfe018ceafaa5[]`
diff --git a/gems/lib/asciidoctor/swhid-inline-macro/extension.rb b/gems/lib/asciidoctor/swhid-inline-macro/extension.rb
new file mode 100644
index 0000000..8e3afaf
--- /dev/null
+++ b/gems/lib/asciidoctor/swhid-inline-macro/extension.rb
@@ -0,0 +1,21 @@
+class SWHInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+  use_dsl
+
+  named :swh
+  name_positional_attributes 'caption'
+
+  def process parent, target, attrs
+    doc = parent.document
+
+    # We're only considering `swh:` starting with the scheme version. Also, it
+    # looks nice aesthetically.
+    swhid = (target.start_with? 'swh:') ? target : %(swh:#{target})
+    swhid_core_identifier = (swhid.split ';').at 0
+
+    text = attrs['caption'] || swhid_core_identifier
+    target = %(https://archive.softwareheritage.org/#{swhid})
+
+    doc.register :links, target
+    create_anchor parent, text, type: :link, target: target
+  end
+end