resolves #4522 introduce stem block adapter

[aw-engineer]

Description

Utilizes a plugin mechanism to convert stem blocks from markup to rendered output.

For example:

.classic behavior

• User writes stem block with latexmath markup
• Asciidoc converts this to mathjax compatible html
• For the html5 backend

.classic behavior

• User writes stem block with asciimath markup
• Asciidoc converts this to mathjax compatible html
• For the html5 backend

.newly supported behavior

• User writes stem block with asciimath markup
• Asciidoc converts this to mathml compatible html
• For the html5 backend

Relationship Diagram

Interface PluginBase
class SharedObjects
class ClassMethods
class TransformStubHtml5
class Factory

class TransformAsciimathMathjaxHtml5 
class TransformAsciimathMathmlHtml5 
class TransformLatexmathMathjaxHtml5 

PluginBase : docinfo? (location)
PluginBase : docinfo (location)
PluginBase : convert (document)

ClassMethods : register_for(in_fmt, out_fmt, backend)
SharedObjects : registry{}
SharedObjects : mutex

Factory : make()

SharedObjects o-- Factory

SharedObjects o-- ClassMethods
ClassMethods o-- PluginBase

PluginBase <|-- TransformStubHtml5
PluginBase <|-- TransformAsciimathMathjaxHtml5
PluginBase <|-- TransformAsciimathMathmlHtml5
PluginBase <|-- TransformLatexmathMathjaxHtml5

Design

Plugin implementation classes include the StemAdapter::PluginBase module. Following the "include and extend" pattern, PluginBase extends the plugin classes with supporting functionality such as 'register_for'. The plugin classes then register themselves for:

1. input format (latexmath, asciimath, ...)
2. output format (mathjax, mathml, ...)
3. backend format (html5, ...)

After registration, the Factory is able to instance a plugin based on those three parameters.

Parsing

This introduces new document attribute :stem-renderer: (default: mathjax) to represent the format of the stem block after conversion. At time of writing, this is mathjax-compatible html, or mathml html.

Conversion

Document conversion of a 'stem' block uses StemAdapter::Factory to instance an adapter plugin. Input format is defined implicitly (default: latexmath) or within the stem block. Output format is defined by document attribute :stem-renderer:. If there is no plugin available, a stub plugin is provided to render a "this is not supported" message suitable for the backend.

Implementation

Discrete plugins are located in stem_adapters/ directory. Support infrastructure is implemented in top-level stem_adapter.rb, and loads the plugins directly.

• stem_adapters/
  • stem_asciimath_mathjax_html5.rb
  • stem_asciimath_mathml_html5.rb
  • stem_latexmath_mathjax_html5.rb
• stem_adapter.rb

Testing

unit testing

• block_test.rb
• document_test.rb

command line

for each in stem-latexmath-mathjax stem-asciimath-mathjax stem-asciimath-mathml; do \
 bundle exec asciidoctor -b html5 -a iconfont-remote! -a webfonts! -a icons! -o /tmp/$each.html test/fixtures/$each.adoc; \
done

Discussion

• document attribute :stem: may be ommitted -- it is implied by the content of document blocks [stem], [asciimath], [latexmath], etc..
• RE: Github Issue 4522, this code interface parallels that of the syntax_highlighter. It may be useful to consolidate the implementations into a more general purpose plugin based architecture for block processing.
• Mixing multiple math markups in one asciidoc document is syntactically supported, however no provision exists to de-conflict output, for example multiple inclusions of the mathjax javascript code.
• this changeset extends an "asset uri" refactor, which is not strictly required for this feature

References

Programming Ruby 3.3 (5th Edition

Metaprogramming Ruby 2

#4522