relates to discussions here:

* https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/abbreviations.20with.20tooltips.20for.20both.20pdf.20and.20html
* asciidoctor/asciidoctor#252
* asciidoctor/asciidoctor#2534
* riscv-admin/docs-sig#31

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.
 

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

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

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]

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
+```