[ 
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: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Reply via email to