[
https://issues.apache.org/jira/browse/SOLR-11217?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16121014#comment-16121014
]
Cassandra Targett commented on SOLR-11217:
------------------------------------------
I haven't committed anything for this, although the HTML support is relatively
straightforward. It's the PDF support that's going to be a pain.
h3. HTML
We can add a MathJax javascript to our templates that will render stem
notations properly. It supports using {{latexmath}} and {{asciimath}} as macros
or blocks, or a generic {{stem}} macro/block that defaults to asciimath if the
more specific form is not used. There are only a couple minor changes to our
templates for this - add a new JS-based _include file, make sure that's
included in the header, and make sure {{_config.yml}} is updated to allow stem
processing.
h3. PDF
MathJax is browser-based, so won't work for PDFs and another solution is
required.
The Asciidoctor project includes a
[asciidoctor-mathematical|https://github.com/asciidoctor/asciidoctor-mathematical]
project. The PDF tool we use (asciidoctor-pdf) supports this, but there are
several limitations:
* asciidoctor-mathematical has a long list of dependencies and font
requirements. It took a couple tries at getting these worked out, and the list
is different for different OS's. Any one of these could be an issue for
Jenkins, which is subject to INFRA's policies.
* it's not integrated with asciidoctor-ant, which we use for the build. This
means Jenkins and anyone who wants to build on their local machine needs all
the dependencies locally to build the PDF (which is true today for the HTML
version also, but Jekyll has a many fewer dependencies). However,
asciidoctor-ant should support using it as an extension, assuming we put it in
the right place.
* asciidoctor-mathematical makes images for the math and inserts those in the
PDF. These images are also saved as separate .png files (could also support SVG
if preferred). If these are not properly compressed, I suspect they could make
the PDF really large (if there are more than 1 or 2 of these).
* it only supports latexmath, and not asciimath. If you preface any notation
with anything other than {{latexmath}} it doesn't work.
I don't know the extent you and others want to use stem notations in the Ref
Guide, so can't guess if we can live with all of this. There doesn't seem to be
anything in the works for asciimath support, so we will always need to use
latexmath. And we'll be even farther from the goal of figuring out how to allow
anyone to build the Ref Guide without all the dependencies.
> Mathematical notation not supported in Solr Ref Guide
> -----------------------------------------------------
>
> Key: SOLR-11217
> URL: https://issues.apache.org/jira/browse/SOLR-11217
> Project: Solr
> Issue Type: Bug
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Houston Putman
> Priority: Minor
>
> The template used to build the Solr Ref Guide from the asciidoctor pages
> removes the needed javascript for mathematical notation.
> When building the webpage, asciidoctor puts a tag like the one below at the
> bottom of the html
> {code:html}
> <script
> src="#{cdn_base}/mathjax/2.6.0/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script>
> {code}
> and some other tags as well.
> However these are not included in the sections that are inserted into the
> template, so they are left out and the mathematical notation is not converted
> to MathJax that can be viewed in a browser.
> This can be tested by adding any stem notation in an asciidoctor
> solr-ref-page, such as the following text:
> {code}
> asciimath:[sqrt(4) = 2].
> {code}
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
