What do we do with Mathjax macro vs Formula macro in XS?

Development
#1

Hi devs,

Now that we have a client-side PDF that properly exports the mathjax macro, we need to decide whether we want to promote the mathjax macro or continue promoting the formula one.

Some considerations:

  • The mathjax macro was developed because it produces better rendering than the formula macro
  • The formula macro is not very easy to setup since there are several renderers. Also some user is reporting problems about using the formula macro that breaks his wiki in some cases (I don’t have the details).
  • With the latest macro discovery feature from Thomas/FASTEN, it’s slightly less important to have macros bundled in XS to be discovered.
  • AFAICS the mathjax macro supports more feature than the formula one (including references) and is a superset of it.

I see the following options:

  • Option 1: both macros at same level
    • Extract the formula macro outside of XS (into xwiki-contrib) and let users decide what extension to install in their wiki.
    • We’ll need to recommend one extension or if both have value, then at least do a comparison table and explain when to use one over another
    • We probably also need to make the mathjax macro recommended
  • Option 2: mathjax macro over formula macro
    • Extract the formula macro outside of XS (into xwiki-contrib)
    • Add the mathjax macro inside XS in replacement of the formula macro
  • Option 3: formula macro FTW
    • Deprecate the mathjax macro
    • Add a new mathjax “renderer” in the formula macro and make it the default one. Note that when using mathjax you specify the font size in the content and not in the macro parameter as it’s done in the formula macro (but I guess it could be ignored in this case). Similarly mathjax doesn’t produce images so the imageType macro param would also need to be ignored.
    • Optional: Also extract the formula macro outside of XS (into xwiki-contrib)

My preference would go to option 1 and recommend the mathjax macro. The rationale for not having it in XS is that I don’t think every user needs a formula macro, it’s a pretty specific case.

WDYT?

Thanks

#2

+1 for Option 1 too

I feel Option 3 is actually pretty much Option 1 but with one more step (make the formula macro support also mathjax) so we can start with Option 1 and see later if someone wants to work on the extra step (but I don’t think it worth it for the same reason people are generally choosing between {{groovy}} and {{python}} and not between {{script language="groovy"}} and {{script language="python"}}).

#3

+1 for option 1 also.

Thanks,
Marius

#4

Tasked in [XWIKI-20023] Move the Formula macro to XWiki Contrib - XWiki.org JIRA

#5

+1 too for option 1 (sorry for late answer)

#6

It’s more complicated than anticipated since:

  1. some classes located on the formula modules were reused in other places (ImageData, ImageStorage). However these other places are related to supporting formula-generated images in the PDF export
  2. The default ImageStorage impl is based on infinispan and thus on a config in config.xml
  3. There’s a /tex/ action (TexAction) class that serves the images generated by the Formula Macro that also needs to be handled.
  4. There’s an entry for /tex/ in `robots.txt``

My proposal to handle all this:

  • Deprecate the TexAction class and move it to a legacy module
  • Deprecate the ImageData & ImageStorage classes and move them to that legacy module too.
  • Re-Implement CachedImageStorage with a TemporaryImageStorage component using the Temporary Resource and also put it in that legacy module.
  • Modify the Formula Macro in the contrib repo to use the Temporary Resource API. This means no need for a new action and no need for an infinispan config.
  • Modify PDFResourceResolver to use the Temporary Resource API. Add an overriding component impl in legacy that also handles the now deprecated /tex action (by overriding getResource() from PDFResourceResolver).
  • Don’t change PDFURIResolver, but make sure it has access to ImageData&ImageStorage` classes in legacy.
  • Remove the text entry from robots.txt.
  • Remove the cache entry in config.xml in platform

WDYT?

#7

After discussion with Thomas on matrix yesterday and some local POC, here’s a new proposal:

  • Keep ImageData and ImageStorage in the contrib extension but implement ImageStorage using a tmp resource (serializing ImageData using java serialization, this is needed to save the image type, without having to change the public API)
  • Move TexAction to the contrib extension, and mark it deprecated
  • Modify the Formula Macro to use the tmp resource (thus making TexAction unused)
  • Remove the cache entry in config.xml in platform
  • Modify PDFResourceResolver to use the Temporary Resource API. Add an overriding component impl in legacy that also handles the now deprecated /tex action (by overriding getResource() from PDFResourceResolver).
  • Modify PDFURIResolver to use the Temporary Resource API. Keep the /tex support there.
  • Remove the text entry from robots.txt.

Devs who had extensions using classes from inside xwiki-platform-formula-renderer would need to depend on the new macro-formula-renderer dep if they need/want to upgrade the dep version.

Note: we’ll see how and if we want to improve further the formula macro in the future. Right now, the future goes more in the direction of using mathjax.

Remove TexAction component
#8

Changes: