doc/math_engine: Usage notes and comparison KaTeX vs SsKaTeX

doc/math_engine/katex.page

@@ -5,10 +5,24 @@ title: KaTeX
 ## Math Engine KaTeX
 
 This math engine uses [KaTeX] via the [katex rubygem][katex-gem] to convert TeX math formulas into
-KaTeX HTML (using [ExecJS] under the hood).
+KaTeX HTML, using [ExecJS] under the hood. This eliminates the need for client-side math-rendering
+Javascript. This engine is somewhat similar to the [SsKaTeX] math engine, but easier to use and
+suitable for kramdown input from untrusted users.
 
-This eliminates the need for client-side math-rendering JavaScript. Your HTML templates still need
-to include the KaTeX CSS (see the [gem's documentation][katex-gem#assets] on this).
+Requirements for running kramdown with math engine KaTeX:
+
+- Ruby gem [`katex`][katex-gem],
+- Ruby gem [`execjs`][ExecJS],
+- A Javascript engine supported by ExecJS, e.g. via one of
+  - Ruby gem [`therubyracer`][therubyracer],
+  - Ruby gem [`therubyrhino`][therubyrhino],
+  - Ruby gem [`duktape`][duktape],
+  - [Node.js].
+
+All these requirements need to be met only if KaTeX is actually used. Note that the [`katex`
+gem][katex-gem] includes [KaTeX]'s Javascript, CSS, and fonts; those do not need to be installed
+separately. Your HTML templates still need to reference the KaTeX CSS. Consult the [`katex` gem's
+documentation][katex-gem#assets] on how to do that.
 
 A typical KaTeX configuration looks like this:
 
@@ -22,8 +36,13 @@ for more information.
 
 If you need to sanitize the output, see [this example][sanitize-example] for inspiration.
 
+[duktape]: https://github.com/judofyr/duktape.rb#duktaperb
+[ExecJS]: https://github.com/rails/execjs#execjs
 [KaTeX]: https://khan.github.io/KaTeX/
-[ExecJS]: https://github.com/rails/execjs
 [katex-gem]: https://github.com/glebm/katex-ruby
 [katex-gem#assets]: https://github.com/glebm/katex-ruby#assets
 [sanitize-example]: https://github.com/thredded/thredded-markdown_katex/blob/2f5e748c90265526171a6da99557f637d2b717ec/lib/thredded/markdown_katex.rb#L48-L91
+[SsKaTeX]: sskatex.html
+[therubyracer]: https://github.com/cowboyd/therubyracer#therubyracer
+[therubyrhino]: https://github.com/cowboyd/therubyrhino#therubyrhino
+[Node.js]: https://nodejs.org/

doc/math_engine/sskatex.page

@@ -5,8 +5,9 @@ title: SsKaTeX
 ## Math Engine SsKaTeX
 
 This math engine uses a server-side installation of [KaTeX] to convert TeX math formulas into
-HTML+MathML. This eliminates the need for client-side math-rendering JavaScript. Consider this a
-lightweight alternative to [Mathjax-Node](mathjaxnode.html).
+HTML+MathML. This eliminates the need for client-side math-rendering Javascript. Consider this a
+flexible for-trusted-users-only [alternative](#differences-to-the-katex-math-engine) to the [KaTeX
+math engine] and a lightweight efficient alternative to [Mathjax-Node](mathjaxnode.html).
 
 Your HTML templates need no longer include Javascripts for Math (neither `katex.js` nor any
 search-and-replace script). Your HTML templates should continue referencing the KaTeX CSS. If you
@@ -104,10 +105,41 @@ The options with `js` in their names can be used to achieve arbitrary Javascript
 the privileges of the kramdown process. If kramdown is part of a service that allows file uploads
 and user-specified math engine selection and options, the service should therefore be sandboxed
 (which is recommended practice), or the user-specified options filtered, or SsKaTeX kept unavailable
-e.g. by not installing the `sskatex` gem.
+e.g. by not installing the `sskatex` gem. Consider using the [KaTeX math engine] instead.
+
+### Differences to the KaTeX math engine
+
+Both the KaTeX and the SsKaTeX engine operate in similar ways with similar efficiency and produce
+equivalent output if the underlying `katex.min.js` versions are the same. Differences are mostly in
+configuration and usage scenarios. The following table gives an overview.
+
+| Usage aspect | KaTeX | SsKaTeX |
+|:-|:-|:-|
+| Usability | easy to use | all JS details configurable |
+| Target users | untrusted users | trusted users |
+| Target usage | web services | personal pages |
+| Required Ruby gem | `katex` | `sskatex` |
+| KaTeX JS/CSS/fonts | included | not included |
+| Math language depends on | `katex` gem version | `katex_js` option |
+| KaTeX options | in `math_engine_opts` | in `katex_opts` sub-dict |
+| Default error handling | catches errors | throws on errors |
+
+Therefore:
+
+* If in doubt, try the [KaTeX math engine]. It should work out of the box.
+* If you need more control and are trusted (i.e. you are allowed to run arbitrary code), try
+  SsKaTeX. Example uses:
+  - Work around issues in the current KaTeX version or in the default JS interpreter
+  - Try a more recent KaTeX version when you want it, and not until then
+  - Try interfacing with other JS-based math renderers
+  - Try another Javascript interpreter. E.g. `Duktape` is fast, but `Spidermonkey` may give better
+    error diagnostics and backtraces.
+* Web services processing kramdown input from untrusted users should not make the `sskatex` gem
+  available, as explained in the [Security](#security) section.
 
 [duktape]: https://github.com/judofyr/duktape.rb#duktaperb
 [execjs]: https://github.com/rails/execjs#execjs
+[KaTeX math engine]: katex.html
 [KaTeX]: https://khan.github.io/KaTeX/
 [KaTeXopts]: https://github.com/Khan/KaTeX#rendering-options
 [sskatex]: https://github.com/ccorn/sskatex/