Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce a STEM adapter facility #4522

Open
mojavelinux opened this issue Nov 29, 2023 · 1 comment
Open

Introduce a STEM adapter facility #4522

mojavelinux opened this issue Nov 29, 2023 · 1 comment
Milestone

Comments

@mojavelinux
Copy link
Member

Currently, the parser treats STEM content as a passthrough (with some newline processing of AsciiMath). The HTML converter decorates it with a set of delimiters and loads MathJax to find the STEM content and render it. The DocBook converter uses the asciimath gem to convert AsciiMath to MathML and relies on support from the toolchain to handle LaTeX.

There have been numerous requests over the years to process STEM blocks and inlines differently, whether that's to use KaTeX in place of MathJax or to convert the expression to MathML to eliminate the use of a rendering library. This situation is similar to what we have with syntax highlighting. Therefore, I think we should follow the same strategy.

Introduce a STEM adapter facility that allows alternate STEM adapters to be integrated into the processing. An adapter should be able to register for a notation (e.g., asciimath) to start and a backend (e.g., html).

Here are the integration points the adapter should be able to control:

  • conversion of content, including added delimiters (method: convert)
  • docinfo insertion (content and location) (method: docinfo)
  • format of enclosing element (to add hints like a CSS class or data attribute) (method: format)

Some adapters may convert the content to an image, so the facility should be able to accommodate that situation.

Note that it is mostly possible to do this today by extending the converter. However, the insertion of the docinfo can be tricky and thus, an adapter is a simpler solution. It can also be distributed as an add-on gem, making it easy for end users to apply.

@mojavelinux
Copy link
Member Author

Consider https://github.com/expeehaa/asciidoctor-mathml as an example use case for an adapter.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant