Process inline stem macros inside AsciiDoc table cells

[mojavelinux]

Process inline stem macros inside of AsciiDoc table cells. This is just a matter of getting the extension to run on the embedded Document object that holds the content for an AsciiDoc table cell.

Currently, Asciidoctor core does not propagate extensions to nested documents (see asciidoctor/asciidoctor#1300), so the top-level Treeprocessor will need to register itself as an extension on the nested Document object.

[mojavelinux]

I did some research and it turns out that the best way to handle this is to simply pass the embedded document instance to the process method of the current Treeprocessor. In other words, invoke the Treeprocessor manually.

table_blocks.each do |table|
  [:body, :foot].each do |tsec|
    table.rows[tsec].each do |row|
      row.each do |cell|
        if cell.style == :asciidoc
          process cell.inner_document
        end
      end
    end
  end
end

[oddhack]

The issue @mojavelinux closed above referred to problems seen with asciidoctor-pdf, and you commented "This is an upstream issue (either the responsibility of asciidoctor core or asciidoctor-mathematical) so I'm going to close the issue here."

I'll note we're not having the problem with HTML output in the simplistic example given in my issue. I don't know what that might tell you in terms of which toolchain component is responsible, but we're only seeing the problem with asciidoctor-pdf, so that seemed like the right place to file it.

Maybe it would be good to note in the asciidoctor-pdf documentation that the block-in-cell support being introduced in the new update does not extend to stem blocks or inlines?

N.b. our actual documents use KaTeX instead of the built-in MathJax-based support, due to the ginormous performance difference and the lack of the horrible rerendering-and-scrolling behavior of MathJax - something you might consider as well - but my example just uses the built-in support.

[mojavelinux]

Here's the full script you'd need to use to patch Asciidoctor Mathematical from outside the gem:

require 'asciidoctor/extensions'

Asciidoctor::Extensions.register do
  treeprocessor do
    process do |doc|
      mathematicalProcessor = MathematicalTreeprocessor.new
      (table_blocks = doc.find_by context: :table).each do |table|
        (table.rows[:body] + table.rows[:foot]).each do |row|
          row.each do |cell|
            mathematicalProcessor.process cell.inner_document if cell.style == :asciidoc
          end
        end
      end
    end
  end
end

[mojavelinux]

I'll note we're not having the problem with HTML output in the simplistic example given in my issue.

That's because STEM replacements in HTML are handled by the client (i.e., the browser). When converting to PDF, we have to handle absolutely everything since PDF is a "baked" format.

[mojavelinux]

but we're only seeing the problem with asciidoctor-pdf, so that seemed like the right place to file it.

Correct, though asciidoctor-mathematical exists primarily to convert to STEM where we can't use MathJax, which is formats that don't target the browser. Hence why you see these two gems often used together.

[mojavelinux]

but we're only seeing the problem with asciidoctor-pdf, so that seemed like the right place to file it.

That has been discussed in Asciidoctor and might get considered again in the future. The heavy users rejected KaTeX at the time (more than a year ago) because it was incomplete.

[mojavelinux]

Maybe it would be good to note in the asciidoctor-pdf documentation that the block-in-cell support being introduced in the new update does not extend to stem blocks or inlines?

We don't mention stem at all right now in the README, so this would go along with it. I'll add a note to the related issue.

[oddhack]

Re KaTeX, we wouldn't have been able to use it a year ago, either. It has considerably better coverage now, and an extremely responsive dev team. So maybe worth revisiting, at least as an option. The performance difference is stunning for equation-heavy documents.

[ProgramFan]

@mojavelinux The proposed method does not work, at least in asciidoctor-pdf, neither as the patch nor embeded in MathematicalTreeProcessor.

Furthur investigation shows that the stem blocks and macros are handled and processed correctly and cell.inner_document.blocks are changed accordingly. But the cell.text is not changed and the final render of the cell seems to follow cell.text.

Are there any clues on this? I was thinking that changing the blocks shall be sufficient but it turns out false.

[mojavelinux]

@oddhack I'm definitely open to considering a switch to KaTeX in Asciidoctor core. I have no allegiance to MathJax other than it does what we need. If you are interested, please follow-up in the following issue: asciidoctor/asciidoctor#1735.

[mojavelinux]

@ProgramFan You have to be using the unreleased version of Asciidoctor PDF. I'm about to release it, so in the next 12 hours you'll be able to use 1.5.0.alpha.14 and it will work.

[ProgramFan]

OK. I will try it. When the code works, I will make a commit to resolve this issue. 😄

[mojavelinux]

The release is ready!

[ProgramFan]

The fix is ready and it works on both html and pdf backends.

[sjaeckel]

Is there a release available with this patch?

$ gem list --local | grep math
asciidoctor-mathematical (0.2.2)

as of https://rubygems.org/gems/asciidoctor-mathematical 0.2.2 is from January 09, 2017 and this commit is done in February 2017 ...