spec: Math notation

[uetchy]

Goals

Support block and inline math notation.

1. MathJax-style notation

$$
\LaTeX
$$

Inline $\LaTeX$ notation

2. Code block notation

There is no capability to express inline math within code block notation.

```math
\LaTeX

## Prior Art

- MathJax

## Discussion

[tk0miya]

Does math notation support only LaTeX style notation? How about MathML?

[uetchy]

Only LaTeX because MathML seems more of a syntax for machines than humans. However, it would still be nice to have MathML as an export format in HTML.

[tk0miya]

It sounds good to me because I'm not familiar with MathML. Using LaTeX is helpful to me. But, as you said, it has very high affinity with HTML. I suppose it will become standard of Web in future. So it would be better to support it on VFM in future.

[kmuto]

$$ reminds me of '$$ is abuse for LaTeX' https://texwiki.texjp.org/?%E5%8F%A4%E3%81%84%E6%83%85%E5%A0%B1#g5e418af

Though VFM is not LaTeX, it seems abuse notation to write LaTeX equations.

[MurakamiShinyu]

Vivliostyle.js supports MathML, TeX and AsciiMath notations embedded in HTML using MathJax.

See: https://github.com/vivliostyle/vivliostyle.js/issues/523

Test sample: https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html

with Vivliostyle Viewer: https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html

When you write MathML in VFM, the MathML will be kept as-is in HTML, and Vivliostyle.js can render it with MathJax.

To enable TeX and AsciiMath for Vivliostyle.js:

• In a element with data-math-typeset="true" attribute, you can use TeX or AsciiMath mathematics.
• TeX mathematics are indicated by delimiters \(...\) or $$...$$.
• AsciiMath mathematics are indicated by delimiters `...`.

[MurakamiShinyu]

Related: #30, #36

[akabekobeko]

Code block に一票。

[akabekobeko]

$ は汎用的すぎて数式よりも用途が多く、それによる解析事故が起きそうなので。一方、数式が大量に登場する文章 (論文とか) を書くユーザーは MathJax で常用しているので使いたくなるだろう。

なのでオプション指定してその文章が MathJax をサポートしているか否かを明示するのはどうか。

[akabekobeko]

全体のオプションで MathJax などのパーサー処理分岐、Frontmatter でページ単位にそれを上書き、というのが現実的ですかね。

[akabekobeko]

これはオプションの方針として独立した Issue にしたほうがよさそうですね。

[akabekobeko]

議論が途中で止まっています。数式については複数の議論が混在していますね。

@MurakamiShinyu @spring-raining @yamasy1549

記法としての本件は実装済みなので close して残件は個別の数式系 issue で議論しようと考えているのですが、いかがでしょうか？意見をコメントしていだけるとありがたいです。

[yamasy1549]

close して残件は個別の数式系 issue で議論しようと考えているのですが、いかがでしょうか？

良いと思います！

[akabekobeko]

@MurakamiShinyu @spring-raining さんはいかがでしょうか？意見よろしくお願いします。

[MurakamiShinyu]

記法としての本件は実装済みなので close して残件は個別の数式系 issue で議論しようと考えているのですが、いかがでしょうか？

記法について疑問があります。

VFMドキュメントのMath equation https://github.com/vivliostyle/vfm/blob/master/docs/vfm.md#math-equation には次のように書かれてます:

VFM

$$\sum$$

HTML

<p>
  <span class="math math-inline">
    <span class="katex">
…

この記述では、ドル記号2つ $$ で数式を囲むとインライン数式 (<span class="math math-inline">) になると読めます。しかし TeX では、ドル記号2つ $$ で囲むとディスプレイ数式であり、ドル記号1つ $ で囲むとインライン数式です。

どうして $$\sum$$ でインライン数式なのだろうと不思議に思いVFMで使われている https://github.com/remarkjs/remark-math を見てみると、次の例が書かれてます:

Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following
equation.

$$
L = \frac{1}{2} \rho v^2 S C_L
$$

そして $ と $$ に関する次の説明があります:

• remark-math — Parses $ as inlineMath and $$ as math nodes

しかし、次の記述を読むと、 https://github.com/remarkjs/remark-math/tree/main/packages/remark-math#escaping

Markdown escapes don’t work in math, similar to code, but you can use more dollars around the math instead: $$\raisebox{0.25em}{$\frac a b$}$$

どうも remark-math では、$ で囲んでも $$ で囲んでもインライン数式になるようです。そして $$ だけの行で囲まれたブロックがディスプレイ数式となるようです。

現状の vfm で試してもそのようでした。

$ echo -e '$\sum$' | vfm --partial

<p><span class="math math-inline"><span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1.00001em;vertical-align:-0.25001em;"></span><span class="mop op-symbol small-op" style="position:relative;top:-0.0000050000000000050004em;">∑</span></span></span></span></span></p>

$ echo -e '$$\sum$$' | vfm --partial

<p><span class="math math-inline"><span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1.00001em;vertical-align:-0.25001em;"></span><span class="mop op-symbol small-op" style="position:relative;top:-0.0000050000000000050004em;">∑</span></span></span></span></span></p>

$ echo -e '$$\n\sum\n$$' | vfm --partial

<div class="math math-display"><span class="katex-display"><span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1.6000100000000002em;vertical-align:-0.55001em;"></span><span class="mop op-symbol large-op" style="position:relative;top:-0.000004999999999977245em;">∑</span></span></span></span></span></div>

VFMで、このインライン数式とディスプレイ数式の記法を採用するということなら、そのドキュメントが必要です。

[akabekobeko]

ドキュメントに記載されているものと実際の挙動が異なるのは問題ですね。そのうえで対応案としては

• VFM ドキュメントを remark-math にあわせる
• VFM ドキュメントにあう remark-math 代替を検討、または自前で実装する

といったところでしょうか。

[MurakamiShinyu]

VFM ドキュメントを remark-math にあわせるべきでしょう。現状のVFMドキュメントではインライン数式とディスプレイ数式の使い分けの方法が分かりません。

[MurakamiShinyu]

remark-math の記法の定義は https://github.com/micromark/micromark-extension-math/blob/main/readme.md にありました。

これによると、

Math (text) can start with one or more dollar signs, so long as they match:
With one: $\alpha$, two: $$\beta$$, or three: $$$\gamma$$$.

とのことで「Math (text)」（インライン数式）を囲む $ は何個でもよいことになってます。 しかし vfm で試すと、２つまでしかだめなようで $$$\gamma$$$ ではエラーになります。 remark-math の記法が vfm でそのまま使えるわけではないようです（何か処理したあと remark-math に渡しているためか）。

[akabekobeko]

37 で数式が議論され、PR #89 にてその結果を実装しました。これは VFM 1.0.0-alpha.19 にて反映されます。

よって本件は close します。バグや更なる要望がある場合は、別途 issue 登録をお願いします。