Modify math description for GitHub markdown update

[200km]

Overview

Modify math description for GitHub markdown update

Issue

NA

Details

GitHub has started to support math description in the Markdown. (link)

To follow the update, we need to update followings

• change style of inline equations
• discuss about the management of GitHub pages
• fix small bugs

Validation results

NA

Scope of influence

NA

Supplement

NA

Note

NA

[200km]

@sksat mdBookを使ったGitHub pagesの公開どうしましょうか？軽く試してみたのですが、次の点がめんどそうだなと感じました。

• GitHubがサポートしているinline数式は$ x=y $で、今のものから変える必要がある。これを変えるのは全置換で簡単にできて、いまcommitしているのがそれ。
• こうすると、mdBookのほうでinline数式の表示ができなくなる
• prepro.shを修正して$ x=y $を/( x=y /)に変更しようとしたが難しそうだった

という感じです。そして、mdBookを使うのはまだ必要なのか？と思ってきたのでご意見いただきたいです。
（sedを使いこなせる人は解決できるのかもしれません）

[200km]

For multiple line equations, we cannot use \\. Maybe this issue of MathJax is related.

The following doesn't work

$$\bar{P}_{n,m}=\frac{1}{N_{n,m}}P_{n,m}\\\ \bar{V}_{n,m}=\frac{1}{N_{n,m}}V_{n,m}\\\ \bar{W}_{n,m}=\frac{1}{N_{n,m}}W_{n,m}\\$$

The followings work well

$$\displaylines{ \bar{P}_{n,m}=\frac{1}{N_{n,m}}P_{n,m}\\\ \bar{V}_{n,m}=\frac{1}{N_{n,m}}V_{n,m}\\\ \bar{W}_{n,m}=\frac{1}{N_{n,m}}W_{n,m}\\\ }$$ $$\begin{align} \bar{P}_{n,m}=\frac{1}{N_{n,m}}P_{n,m}\\\ \bar{V}_{n,m}=\frac{1}{N_{n,m}}V_{n,m}\\\ \bar{W}_{n,m}=\frac{1}{N_{n,m}}W_{n,m}\\\ \end{align}$$

[sksat]

元々mdbookを使い始めた理由が，

• GitLabでMarkdownのMathJaxサポートを使って数式を表示していた(ユーザが見るのはGitLabのWeb UIだった)
• GitHubには(当時)MarkdownのMathJaxサポートが無かった
• ユーザが見る場所をGitHub Pagesにして，Markdown -> HTMLの変換をかけることにした

という経緯であり，かつ，mdbookの数式の記法が一般的なものでなかったためにsedで無理矢理置換していたので，必ずしもmdbookに拘る必要は無いというのは同意見です．それはそれとして，sedを頑張ってmdbookでも表示できるようにする，というのは可能ではあると思います．

[200km]

考えは僕と同じだと思いますが、このPRの中で次のどちらですすめるか決める必要があるかなと思います。

1. とりあえずmdbookのことは考えずにGitHub上でいい感じに見えるようにだけ考えて修正する
2. mdbookでも上手く表示できるようにsedを頑張る

1だけで良いなら私の方ですぐできそうだなという感じです。2もやるならお手伝いしてもらえると嬉しいです。

[sksat]

そうですね．一旦1だけでいいんじゃないかなと思っています．mdbookがそんなに便利というわけでもないので．

[200km]

I cannot fix following bug for inline equations.
This works well $a_x$ and $b_y$.

This works well $\bar{a}_x$ and $\bar{b}_y$.

This doesn't work $\bar{a}{x}$ and $\bar{b}{x}$.

I think this is the problem of Github or MathJax and we cannot fix them.

[200km]

@sksat @seki-hiro 文中の一部の特殊なケースのみ表示がおかしくなっていますが、他はきれいに見えるように修正しましたので、レビューをおお願いします。

[seki-hiro]

[Q] 各ファイルをgithub上でView fileから確認する方法だと，"``` math ```"で囲まれた部分が数式に変換されないままなのですが，表示はどのように確認していますか？

[200km]

具体的にはどのファイルで見えていないですか？大体の場所はきちんと表示されているのは確認したのですが、漏れている場所はあるかもしれないです。

[seki-hiro]

DocumentFormat.md, Spec_RWJitter.md, Spec_STT.mdと上から順に見てどれも上手く表示されていないので，ファイルの表示方法に問題があるかと思い質問しました．例えば，DocumentFormat.mdはこのように見えています．

[200km]

うーん？昨日までは正しく表示されていたはずの場所の多くがは表示がおかしくなっていますね。。。GitHub側で表示方法に更新とか入ったのか？

[200km]

これはちゃんと表示される

$$x=y$$

[seki-hiro]

Spec_RWJitter.mdの80行目の数式はきちんと表示されていて，必ずしも"``` math```"が使えないわけではないというのがよくわからないですね．
公式でサポートされている$$ $$を使う方がいいのでしょうか？

[200km]

フォーマットをそのままコピーしたが、これは逆に $$$$で囲んだ部分が表示されない

• Math description
  　　　　- please use equations as
  　　$$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$
  　　　　　　　　or $$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$

　　　　- you can also use inline equation as $x=y$

[200km]

公式でサポートされている$$ $$を使う方がいいのでしょうか？

こういうわけでもないらしい

[200km]

少し修正しただけで次はmathで囲んだ部分が表示されなくなる

• Math description
  　　　　- please use equations as $$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$
  　　　　　　　　or

  \dot{\boldsymbol{x}}=f(\boldsymbol{x},t)
  

　　　　- you can also use inline equation as $x=y$

[200km]

まだ安定しておらずバグが多いという感じなんですかね。。。

[200km]

こういうふうにインデントを付けなければ表示できる

• Math description
  　　　　- please use equations as $$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$
  　　　　- or

$$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$

　　　　- you can also use inline equation as $x=y$

[200km]

インデントがずれるの嫌だし、一昨日まではきれいに表示されていて、そのうちバグも修正される気がするので、このままでも良いのでは？と思ってしまいますね。

[seki-hiro]

1つコメントしていますが，inline表示はほとんど上手く表示されるようになっているのでapproveします．表示がうまくいっていない他の部分はgithub側の対応を待つという認識です．

[seki-hiro]

[Q] かっこの直後の数式は変換できておらず，スペースを入れると変換できるようですが，本来スペースはいらないので対応しないということで良いでしょうか？

[200km]

これは、対応していっていましたが、いくつか漏れているという感じですね。対応しておきます。

[200km]

修正しました。その他も都度気づいたときに対応していきます。

[seki-hiro]

わかりました．お願いします．