導入の経緯

概要

mathjaxとmark downの周辺状況から,なぜmathjax-yardが必要になったかをまとめておきます.

状況

数値計算や物理シミュレーションにおいては,解説に数式が不可欠です. 記法としては$LaTeX$形式がありますが,これをhtmlで表示するには工夫が必要です. gemなどを作るとき,yardでdocumentationを自動化することが可能です. しかし,そこに数式を組み込んでも,うまく表示されません.

MathML or mathjax

MathML mathjax
firefoxのみ なんでも

mark down with mathjax extension

  • Githubのwikiはmark down 記法を取っているが,math拡張が切られた.
  • Qiitaなどは独自拡張しているが,ない.
  • yard
    • mathjaxの拡張ができる
    • optionsに,組み込まれてはいない.
  • atom
    • mathjax-wrapper とmarkdown_preview_plusでlive変換・表示できる.
    • htmlへの変換はあるが,あまりきれいでない.
  • pandoc
    • mathjaxを組み込んでhtmlに変換できる
    • cssなどに汎用性がなく,体裁をいじるのは難しい.

つまり

個別にmathjaxの入ったmd文書をhtmlに変換することができたとしても, yardで自動生成される体裁の整った文書としては得ることが難しいというのが現状です.

解決法

そこで,yardのpre, postコマンドとして動作するmathjax-yardを開発しました.

  • yardで変換される,/.md中の数式をMATHJAXタグに付け替え.
  • yardでmd->html変換
  • できたdoc/file.*.htmlのMATHJAXタグを数式に戻す という操作をしています.

やり残し

  • default動作以外のyard変換への対応
    • 特に*.rbへの対応
  • hikiへの対応
  • yardへのpull request
  • $を記述しようとしてもだめ.
    • \$で逃げている(16/6/23対応断念).
  • 最小一致を使った記述の単純化(16/6/23対応).
  • Rakefileでのコマンド一発での変換
    • 一つ所に書くと,systemコマンドなどがmultitaskで走ってしまう.
    • taskを分割してそれぞれを終了させた(16/6/23対応).