scdoc: adding subsubsection, audio, video, text decoration, some HTML tags, LaTex syntax and MathML syntax

[prko]

Purpose and Motivation

To make the SCDoc (SuperCollider help documents) more user friendly, I added subsubsections (soft-coded), some HTML tags, LaTex and MathML.

• adding subsubsection to the table of contents in schelp documents #6131
• https://scsynth.org/t/scdoc-schelp-style-add-on-latex-mathml-subsubsection-multimedia-file-iframe-sub-sup-small-line-height-hr/9242

Types of changes

• Documentation
• New feature

To-do list

• Code is tested
• All tests are passing
• Updated documentation
• This PR is ready for review, but this PR may change dynamically as other users provide feedback.

[nhthn]

I have my doubts over whether SCDoc should be expanded to keep glomming on new features, but more importantly: I'm afraid modifying the generated HTML with tons of .replace calls isn't the right way to do this. The correct way to extend SCDoc syntax is to modify the SCDoc parser and HTML generator in the SCDoc directory. Unfortunately, as written, this is very fragile and hacky.

[prko]

@nhthn

Thank you for your valuable feedback!

I have my doubts over whether SCDoc should be expanded to keep glomming on new features, but more importantly: I'm afraid modifying the generated HTML with tons of .replace calls isn't the right way to do this. The correct way to extend SCDoc syntax is to modify the SCDoc parser and HTML generator in the SCDoc directory. Unfortunately, as written, this is very fragile and hacky.

• To: I have my doubts over whether SCDoc should be expanded to keep glomming on new features.
  1. With the focus on new features, some of the new features I suggest are not always necessary. I can remove them if one of the reviewers points out the specific feature.
  2. However, I think your thoughts here are more focused on extending SCDoc, there is no way to implement the features I suggest without extending SCDoc, if I understand its system correctly. So I think the core issue is whether or not these features are needed in SuperCollider's help document browser.
  3. My position is that they are necessary if the SC help browser is to be easily readable by newcomers.
  4. Also, some Quarks contain long and complicated documentations, tutorials and guides; I think the new feature proposed here would help to formulate these documents in a reader-friendly and author-friendly way.
• To: I'm afraid modifying the generated HTML with tons of .replace calls isn't the right way to do this. Unfortunately, as written, this is very fragile and hacky.
  In 288a1c8, I reduced the repetition of .replace by adding a method.
  There is one thing I should mention: the previous version, untouched by me, already has .replace:
  

  supercollider/SCClassLibrary/SCDoc/SCDocRenderer.sc

  Lines 50 to 52 in 28a0b12

  	*escapeSpacesInAnchor { |str|
  	^str.replace(" ", "%20")
  	}

  At first glance this appears to be a one-off, but the method is used frequently throughout SCDocRenderer.sc.
• To: The correct way to extend SCDoc syntax is to modify the SCDoc parser and HTML generator in the SCDoc directory.
  Um... I don't know how to do it... Sorry, but I beg you to understand that I spent a lot of time (almost two weeks due to the implementation of replaceRegex with two .*. I finally gave up) trying to solve some implementation problems. If you give me more tips on how to do it, I can learn the way and try to achieve it!

[prko]

PDF of the corresponding documentation (it includes a newly added section):

• HTML.LaTeX.and.MathML.Syntax.in.SCDocs._.SuperCollider.3.14.0-dev.Help.with.custom.css.pdf
• HTML.LaTeX.and.MathML.Syntax.in.SCDocs._.SuperCollider.3.14.0-dev.Help.with.default.css.pdf

[jrsurge]

Thanks for this - I can appreciate how much work has gone into this.

Unfortunately, apart from the concerns already raised, this PR is too big to review - I do not think it can be accepted in its current form.

If this is something you would like to continue with, can you please break it up into smaller, functional PRs, that each add one change?

I understand that this is a lot of work, but it takes as much work to review it effectively, and it is asking a lot of others working on the Project.

If you would like to discuss breaking it up, please let me know - but there is a question that needs to be answered first about whether this is the right direction for the Project, and I'm not sure at this point. I am also more than happy to discuss this as well, so please feel free to contact me if I can help.

[prko]

@jrsurge

If this is something you would like to continue with, can you please break it up into smaller, functional PRs, that each add one change?

Yes, I can do that (even though the implementations are in an SC file SCDocRenderer.sc). Would the following be acceptable?

• subsubsection (soft-coded): SCDocRenderer.sc.
• LaTeX: SCDocRenderer.sc and offline access files.
• HTML tags support (br, small, strong, emphasis, sup, sub, table, hr, audio, video, iframe etc.) as well as MathML*: SCDocRenderer.sc.
  (I have found a way to display mathematical expressions using LaTeX also in teletype. So, I do not need to implement MathML, but MathML seems a standard in HTML.)
• predefined brackets for text body outside code and codeblock: SCDocRenderer.sc.
• Documentation: WritingHelp_HTML_LaTeX_MathML.schelp

Or should it be split into smaller parts?

but there is a question that needs to be answered first about whether this is the right direction for the Project, and I'm not sure at this point.

My general thoughts:
The new features are necessary, even if the implementation is not always ideal.

• I think the integration of LaTeX (and MathML for mathematical expressions in teletype text) is very useful and saves a lot of time (no need to export images in LaTeXiT). The implementation seems OK, but many of the uploaded files for offline access to the MathJax script may be unnecessary.
• The implementation of a subsubsection is also needed to structure large documentation. This should of course be hard coded. However, I do not understand C++, and I raised this issue several years ago, but nothing has changed. For now, and with my current coding skills, a soft-coded implementation is best.
• HTML tag support is not good, because ideally it should be implemented as SCDoc syntax. But SCDoc syntax is hard-coded. I cannot do it... From the point of view of LaTeX integration, mixing HTML syntax is not bad. For now, and with my current programming skills, a soft-coded implementation is the best.

[prko]

I close this, and will make separate PRs.