From 3646a7349d0340f5e3b6ba60d98f60292e5428f5 Mon Sep 17 00:00:00 2001
From: Kevin Broch <kbroch@rivosinc.com>
Date: Tue, 21 Jan 2025 17:42:04 -0800
Subject: [PATCH] relates to discussions here:

* https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/abbreviations.20with.20tooltips.20for.20both.20pdf.20and.20html
* https://github.com/asciidoctor/asciidoctor/issues/252
* https://github.com/asciidoctor/asciidoctor/issues/2534
* https://github.com/riscv-admin/docs-sig/issues/31
---
 README.adoc                                 |  3 ++
 lib/abbreviate-inline-macro.rb              |  7 ++++
 lib/abbreviate-inline-macro/extension.rb    | 24 ++++++++++++
 lib/abbreviate-inline-macro/sample-inc.adoc |  7 ++++
 lib/abbreviate-inline-macro/sample.adoc     | 41 +++++++++++++++++++++
 5 files changed, 82 insertions(+)
 create mode 100644 lib/abbreviate-inline-macro.rb
 create mode 100644 lib/abbreviate-inline-macro/extension.rb
 create mode 100644 lib/abbreviate-inline-macro/sample-inc.adoc
 create mode 100644 lib/abbreviate-inline-macro/sample.adoc

diff --git a/README.adoc b/README.adoc
index 5c13da2..49c9a56 100644
--- a/README.adoc
+++ b/README.adoc
@@ -77,6 +77,9 @@ NOTE: The registration file (e.g., emoji-inline-macro.rb) goes in the [path]_lib
 The following extensions are available in the lab.
 When the registration of the extension is in a separate file from the extension code, you require the registration file.
 
+AbbreviateInlineMacro (link:lib/abbreviate-inline-macro.rb[registration], link:lib/abbreviate-inline-macro/extension.rb[extension code])::
+Adds an abbreviation inline macro for inserting html "abbr" tags (pdf just shows full title and abbreviation).
+
 AutoXrefTreeprocessor (link:lib/autoxref-treeprocessor.rb[registration & extension code])::
 Refers images, tables, listings, sections by their numbers.
 
diff --git a/lib/abbreviate-inline-macro.rb b/lib/abbreviate-inline-macro.rb
new file mode 100644
index 0000000..15d77f5
--- /dev/null
+++ b/lib/abbreviate-inline-macro.rb
@@ -0,0 +1,7 @@
+RUBY_ENGINE == 'opal' ? (require 'abbreviate-inline-macro/extension') : (require_relative 'abbreviate-inline-macro/extension')
+
+Asciidoctor::Extensions.register do
+  if @document.backend == 'html5' || @document.backend == 'pdf'
+    inline_macro AbbreviateInlineMacro
+  end
+end
diff --git a/lib/abbreviate-inline-macro/extension.rb b/lib/abbreviate-inline-macro/extension.rb
new file mode 100644
index 0000000..f320356
--- /dev/null
+++ b/lib/abbreviate-inline-macro/extension.rb
@@ -0,0 +1,24 @@
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+include Asciidoctor
+
+class AbbreviateInlineMacro < Extensions::InlineMacroProcessor
+  use_dsl
+
+  named :tla
+  name_positional_attributes 'title'
+
+  def process parent, target, attrs
+    doc= parent.document
+    doc.attributes['seen_abbreviations'] ||= {}
+    seen_abbreviations = doc.attributes['seen_abbreviations']
+    full_form = attrs['title'] || 'Abbreviation'
+      if seen_abbreviations.key?(target) && doc.backend == 'html5'
+        create_inline parent, :quoted, %(<abbr title="#{full_form}">#{target}</abbr>), type: :unquoted
+      else
+        seen_abbreviations[target] = full_form
+        create_inline parent, :quoted, %(#{full_form} (#{target})), type: :unquoted
+      end
+  end
+
+end
\ No newline at end of file
diff --git a/lib/abbreviate-inline-macro/sample-inc.adoc b/lib/abbreviate-inline-macro/sample-inc.adoc
new file mode 100644
index 0000000..92b3e50
--- /dev/null
+++ b/lib/abbreviate-inline-macro/sample-inc.adoc
@@ -0,0 +1,7 @@
+== List of hiking acronyms
+
+Some popular hiking acronyms:
+
+* tla:JMT[John Muir Trail]
+* tla:AT[Appalachian Trail]
+* tla:PCT[Pacific Crest Trail]
\ No newline at end of file
diff --git a/lib/abbreviate-inline-macro/sample.adoc b/lib/abbreviate-inline-macro/sample.adoc
new file mode 100644
index 0000000..689a94a
--- /dev/null
+++ b/lib/abbreviate-inline-macro/sample.adoc
@@ -0,0 +1,41 @@
+= Abbreviation Inline Macro Extension
+:abbr-LNT: tla:LNT[Leave No Trace]
+
+== Directly using macro in source
+
+Climbed to Everest tla:ABC[Advanced Base Camp]!
+
+Everest tla:ABC[Advanced Base Camp] is 6340 meters elevation.
+
+include::sample-inc.adoc[]
+
+== Using document attributes
+
+{abbr-LNT}
+
+I say again, "{abbr-LNT}"
+
+
+== Todos
+
+features/questions to answer that would make this more useful:
+
+* better pdf support
+** currently just repeat every title of the abbreviation
+* generate a list of abbreviations section
+** this could then be linked to in pdf/html form
+* is there programmatic tooltip like functionality in pdf?
+
+== Running
+
+From repo top level dir:
+
+.generate html example:
+```
+asciidoctor  -r ./lib/abbreviate-inline-macro.rb lib/abbreviate-inline-macro/sample.adoc
+```
+
+.generate pdf example:
+```
+asciidoctor-pdf  -r ./lib/abbreviate-inline-macro.rb lib/abbreviate-inline-macro/sample.adoc
+```
\ No newline at end of file