Help document enhancement using improved scdoc.css and LaTex with additional features (subsubsection, HTML tags and punctuation marks)

[smoge]

I think you only need to have the MathJax.js file, I don’t think you need node or internet. At least in most browsers, let’s test on the scdoc qt window.

[prko]

@mike

Would you mind linking to your SC fork where these changes are implemented (or even open a PR to discuss)?

Here is my PR for this:

Topic/scdoc subsubsection audio video text decoration

@mike

That MathML syntax looks incredibly cumbersome, (e.g. the log_2^2 example), would there a reason to support both MathML and LaTex?

MathML shows mathematical expression also in teletype, while LaTeX via MathJac does not. However, I do not exactly know when teletype is needed. If you think supporting mathematical expression in teletype is not needed, I can completely remove MathML.

@mike

Would MathJax (for LaTeX support) have to ship with SC to be used offline (maintenance, license, future proofing concerns…)?

Currently, I am using Web Integration. With this kind of integration, there seems to be no need to ship MathJax with SC, I believe. However, we also should think about the use case without an internet connection, and then MathJax should be included in SC. Also, it would be better to include SC because the script does not need to be changed when MathJax releases a new version of the script.

MathJax

@scztt

I don’t know how it compares to MathML, but there are markdown math syntaxes that can render “pretty” versions but are also readable in pure text as well, and are reasonable to write without learning a new syntax: Writing mathematical expressions - GitHub Docs
I wonder if this would be helpful?

Thanks for letting me know it! However, if I understand correctly, the link you provided is related to the mathematical expression on GitHub. Unfortunately, I could not find how to integrate it in SC-Doc.

[prko]

@prko

@mike

Would MathJax (for LaTeX support) have to ship with SC to be used offline (maintenance, license, future proofing concerns…)?

Currently, I am using Web Integration. With this kind of integration, there seems to be no need to ship MathJax with SC, I believe. However, we also should think about the use case without an internet connection, and then MathJax should be included in SC. Also, it would be better to include SC because the script does not need to be changed when MathJax releases a new version of the script.

MathJax | Beautiful math in all browsers.

I changed this to be available offline.

[prko]

I have revised the mathematical expression feature in the following separate PR:

SCDoc improvements: 1. added LaTeX and MathML support via MathJax

• MathJax is shipped with SC.
• MathML is still supported because MathJax also supports MathML.
• In this PR, mathematical expressions can also be used in teletype using both LaTeX and MathML.

[smoge]

Another example of MathJax, it is remarkably good:

https://www.w3.org/TR/2021/NOTE-audio-eq-cookbook-20210608/

[prko]

I have finished making five individual PRs related to this thread:

1. SCDoc: add MathJax for rendering math #6260
2. SCDoc improvements: 2. added various punctuation marks (brackets, quotes, ellipses, etc) for non-code text #6263
3. SCDoc improvements: 3. Some HTML tags are enabled. #6265
4. SCDoc improvements: 4. Subsubsection (soft-coded) #6266
5. SCDoc improvements: 5. Update scdoc.css - make SCDoc more eye-friendly on screen and on paper

Advanced SCDoc features _ SuperCollider 3.14.0-dev Help wuthout background.pdf (1.8 MB)
Advanced SCDoc features _ SuperCollider 3.14.0-dev Help.pdf (1.8 MB)

If anyone reading this post thinks it would be useful to implement some of these features in sclang, please reply to the appropriate PR. Thanks for reading!

[smoge]

@scztt

So: anything in SCDoc files must be renderable for non-HTML outputs. I think for something like MathML, it would be reasonable to assume that this might not be supported for all renderers, but at least this would need to be tagged in a way that other renderers could skip it if it was not supported.

I started Bison and Flex SCDoc updates to add math:: :: tokens. It’s available if someone wants to finish this. I don’t feel like working more on it…

It’s on Github and Gist…

(it’s not the only way to do it, btw’)

hope someday we have this nice feature, which is not so complicated and there is no reason not to implement it, despite the drama, so much drama

The libraries are tiny BTW.

[smoge]

Does someone have more information on why it was removed 10 years ago?

@scztt @mike @gusano

[mike]

Breadcrumbs here lead to dead links

Disable mathjax - an unused feature that can cause problems

But that was over a decade ago, and I’m sure the library has evolved a lot since then.

[prko]

@mike Thank you for that! I found more breadcrumbs based on your search result:
https://listarc.cal.bham.ac.uk/lists/sc-dev-2013/msg49910.html

At the time MathJax caused the following problem:

while browsing “SCDoc Syntax” help file, SCDoc hangs with the following error:

“Processing math: 0%”

and then:

“Failed to load: file:///home/gusi/.local/share/SuperCollider/Help/MathJax/jax/output/HTML-CSS”

(although the file is there…)

and then:

“The script on this page appears to have a problem. Do you want to stop the script?”

it also happens if I browse online
SCDoc Syntax | SuperCollider 3.12.2 Help

do we really use MathJax anyway?

When I tried to implement the current version of MathMax using \( ... \) and \[ ...\], I never had any problems.

I suspect that implementing the math:: tag might cause such problems again… However, unless someone tests it after implementing the math:: tag, there is no way of knowing if the same problem from 2013 will reappear in 2024.

[smoge]

@mike

But that was over a decade ago, and I’m sure the library has evolved a lot since then.

Yes, hard to tell if there was a problem with implementation in such a different environment.

The feeling about the feature has changed, nevertheless. And @prko proved it’s perfectly functional and flawless.

[prko]

@scztt
Sorry for the delay in responding to your comment.

@scztt

I don’t know how it compares to MathML, but there are markdown math syntaxes that can render “pretty” versions but are also readable in pure text as well, and are reasonable to write without learning a new syntax: Writing mathematical expressions - GitHub Docs

A couple of years ago, when there was a suggestion on Git-Hub to create new Supercollider documentation, I considered it, but stopped because I believed using GitHub Doc only makes sense if SC developers have agreed to use it and abandon SCDoc.

So I think further implementation of the MathJax implementation depends on the meaning of @scztt’s following mention:

@scztt

So: anything in SCDoc files must be renderable for non-HTML outputs. I think for something like MathML, it would be reasonable to assume that this might not be supported for all renderers, but at least this would need to be tagged in a way that other renderers could skip it if it was not supported.

What you have mentioned here is new to me and I do not understand it.

Sorry, this was the main reason for the delayed reply to your comment, I also do not know how to mark to skip \( ... \) and \[ ... \].

Can you tell me which `.sc’ file I need to change? I would have a look to see if I could do that.

Thanks!

[smoge]

@scztt

I don’t know how it compares to MathML, but there are markdown math syntaxes that can render “pretty” versions but are also readable in pure text as well, and are reasonable to write without learning a new syntax: Writing mathematical expressions - GitHub Docs

It’s all the same engine, guys. @scztt @jordan @mike

GitHub’s math rendering capability uses MathJax; an open-source, JavaScript-based display engine.

MathJax is managed by the American Mathematical Society and the Russian Academy of Sciences… It’s as good as it gets https://www.ams.org Math-Net.Ru

Syntax is just plain old latex. It’s modular, we just really need a few components. It’s not a big deal. It’s lightweight and a safe option. @prko talked to a dev. We got all the information we would ever need. It just needs a reviewer to respectfully work with him, it’s not much work at all.

[cian]

I use MathJax and like it.

It does rely upon JavaScript. I don’t know if that would be a problem for SC’s documentation system.

[smoge]

SCDoc has had JavaScript since the beginning. Is it changing now? (btw, MathJax included int he first version of SCDoc)

[cian]

JavaScript is a moving target, so it depends upon whether the QT component used in SCDocs provides sufficient JavaScript support for MathJax, and what the performance is like.

It’s probably fine, but you can’t assume that it will be. You need to test it.

[smoge]

I think QT has dropped that browser widget for a while. I guess it still works because KDE has adopted it.

SC should be thankful for KDE. SC devs don’t need to have too much anxiety about it while that’s the situation.

[smoge]

@cian

It’s probably fine, but you can’t assume that it will be. You need to test it.

A very motivated user did a proof-of-concept with substantial tests. It’s just a matter of clean up the implementation now.

[prko]

I seem to have successfully restored the removed math:: tag. With the tag math:: inline and block math are available to use as code:: and teletype::.

There seems no problem occurred. As expected user can use math:: tag as well as \( .. \) and \[ .. \].

[smoge]

All it took was for someone to blow the dust off the code, and everything started working again. The bison fix was so easy that I think nobody ever even tried to fix it

Well done @prko

There is a lesson there. Some people were spreading on GitHub that the bison/flex and all that code were “a mess” and totally “broken.” It took me one command, bison SCDoc.y --update, and I compiled everything with GCC. @prko did the same and put the math:: code, and it’s all fine.