Enhancement: Mathjax format for Doxygen

[Aeon512]

Hi,

we are writing our doxygen documentation with markdown and mathjax.

However, the way formulas are treated by Doxygen differs from the way formulas are treated by markdown-preview-plus, as seen here

Would it be possible to add a configuration option to be able to switch between those two variants?

As a workaround I hacked in markdown-it-helper.coffee and changed

inlineOpen: '\\f$'
inlineClose: '\\f$'
blockOpen: '\\f['
blockClose: '\\f]'

which helps a bit, but for \f{eqnarray} it needs some more tweaking and I got lost.

Moreover, since we have already installed MathJax on a local server in the intranet, it would be a nice option to specify the URL to use this MathJax installation instead of downloading the mathjax-wrapper package.

[Galadirith]

@Aeon512 Really glad your giving MPP a runaround, and thanks so much for using it. On your two feature requests:

1. User defined maths delimiters
   This should definitely possible, once I have a permanent internet connection restored tomorrow I will spin this out into an enhancement issue and hopefully publish it with our next release.

2. Use users MathJax installation
   So again there's no reason I can see why we couldn't do this.

   However with our up coming release (hopefully being published tomorrow), we've replaced mathjax-wrapper with an explicit node dependency 2.4.0-electron.0.2.0 that is <3MB in size; the point is that it will add a very minor <30sec increase to install time for MPP, but you'll no longer need mathjax-wrapper.

   While adding this wouldn't be a high priority, I really appreciate the desire to use your own installation and I'd be happy to guide you through the changes if you would need to make to make MPP use your installation. Please let me know.

Thanks again @Aeon512.

[Aeon512]

@Galadirith Thanks a lot for your answer. Regarding the feature requests

1. User defined math delimiters
   It's not just about the actual delimiters, there's a bit more to consider. E.g. \f{eqnarray}{ ... \f} should be mapped into $$ \begin{eqnarray} .. \end{eqnarray} $$ (where eqnarray can be any valid latex math environment - a check for a valid math environment is however not really necessary)
2. Use users MathJax installation
   The new approach looks promising. If this works well, that it's definitely a non-high-priority issue.

Let me know if I should test or verify something, or if you need further input.

[Galadirith]

It's not just about the actual delimiters, there's a bit more to consider. E.g. \f{eqnarray}{ ... \f} should be mapped into $$ \begin{eqnarray} .. \end{eqnarray} $$

@Aeon512 Ah ok I understand, I really apologise I didn't have time earlier to properly go over your link to the Doxygen syntax. So its still possible, although a little harder than I had previously thought.

I've had a quick go at doing this specifically for eqnarray which you can see at this gist; you should be able to just drop that in as a replacement for lib/markdown-it-helper.coffee although I am afraid I haven't been able to test it yet. The lines that have been added are 9, 27-33, 56 and the rest is unchanged.

This would need a little tweaking to get it to work for any valid environment, but its definitely possible.

I really apologise for not being able to give a more constructive solution right now, but I will be able to take a proper look at this over the weekend. Thanks @Aeon512.

[Aeon512]

@Galadirith Sorry for the delay. You absolutely do not have to apologize. I'm much more impressed how fast I've got your answer. Moreover already a patch which guides me into the right direction. Will check it out over the weekend and let you know. The workaround for eqnarray certainly solves the biggest pain-point at the moment....

Thanks a lot for your great support @Galadirith

[Aeon512]

@Galadirith Thanks a lot for the gist, it works without any problems

Off-Topic:
Since Doxygen has some issue, can I patch markdown-preview-plus in such a way to replace \code{.<something>} by ~~~<something> and \endcode by ~~~. The reason for this hack is, that Doxygen does not correctly detect fenced blocks correctly and hence parses "some" stuff (like @file) inside fenced blocks which looks strange or even leads to an error. Using the doxygen-fenced-blocks (\code{...} and \encode) works fine though. By this hack we could nevertheless use markdown-preview-plus for this use cases as well.

[Galadirith]

Thanks a lot for the gist, it works without any problems

Thanks @Aeon512. So I had an opportunity to briefly test it myself and I did actually notice a problem. When I added this line I didn't realise that this actually overwrites the previous functionality on this line (please don't worry if that means nothing to you, it's more for my own reference). I've updated the gist (now at version 5) that I believe fixes this and also now allows you to use any environment, not just eqnarray.

I realise this is not a permanent solution, but I hope for now this does fulfil what you wanted, and please let me know how it works. I need to spend some more time thinking on how (if at all) this feature could be generalized and how to fit it in with the rest of the package to provide a good user experience.

Since Doxygen has some issue, can I patch markdown-preview-plus in such a way to replace \code{.<something>} by ~~~<something> and \endcode by ~~~.

Again, most definitely possible.

My thoughts would be we can write a simple plugin for our markdown parser markdown-it to handle this, and it will be based on fence.js. I afraid I'm not sure yet when I'll have the time to do that (I just started my PhD last monday) but please let me know if you have any further thoughts on this, feel free to open this up as a separate issue which would help encapsulate the discussion.

Thanks again @Aeon512.

[Galadirith]

For later reference, I think this issue should be covered by a more general issue providing the ability for end users to add and manage their own markdown-it plugins.

@Aeon512 Just to ping you and let you know this hasn't been forgotten. As always please ping us if you have any questions, issues or thoughts.

[lierdakil]

Looking into it, this seems out of scope to me. If anyone wants to make markdown-it plug-ins to support Doxygen syntax, feel free to do so, I will be happy to include those with MPP. I have neither resources nor motivation to write those myself though.