mdbook-satysfiを作成しました

Transcript

1. mdbook-satysfi を作成しました 金子尚樹 (@puripuri2100) 2021/6/26 1/34
2. 自己紹介 所属： 開成学園開成高等学校 学年： 高校三年生 GitHub： github.com/puripuri2100 e-mail： puripuri2100@gmail.com twitter： @puripuri2100 使っている言語： SATYSFI, Rust, OCaml など。 Haskell や Ruby も少し書くだ けならできます。 趣味： ペンシルパズル・ジャグリング・写真撮影・読書など。 2/34
3. 自己紹介（SATYSFI 関係のこと） SATySFi Advent Calendar (2018 | 2019 | 2020) の主催 satysfi-image・ satysfi-ruby などの便利パッケージの作成、 satysfi-json など のライブラリの作成、 satysfi-class-exdesign などのクラスファイル作成、 xml2saty などの変換ツール等、 色々作っています。 satysfi-base のお手伝 いもしています。 learn-satysfi という SATYSFI の解説サイトも作っています。 お手伝いし てくださる方、絶賛お待ちしております。 SATySFi Slack の管理をしています。 まだ入っていない方はぜひ入って みてください！気軽に質問できたり、逆に質問している人に回答したり できます。また、 SATYSFI 関連の情報が多く回ってきます。 3/34
4. SATYSFI Slack への入り方 4/34
5. mdbook-satysfi とは 5/34
6. mdbook-satysfi の概要 mdbook という 「markdown ファイル群からドキュメントを生成するツー ル」 のプラグインで、 「markdown ファイル群から SATYSFI ファイルを生 成する」役割を果たします。 メリット： 設定ファイルに一行書くだけで自動で走る ほとんどの文書の変換に対応できている markdown ファイル内に書いた HTML タグにも対応できる デメリット：特に無し 6/34
7. mdbook とは 文書構成が書かれた SUMMARY.md ファイルと原稿が書かれた markdown ファイルからドキュメントを生成してくれるソフトウェアです。 book.toml という TOML ファイルで細かな設定を行うことが可能であった り、プラグインを簡単に入れることができたりと、使い勝手が良いです。 Rust で実装されており、 rust-lang 公式が作成・管理をしています。 「早くて使いやすく拡張のしやすい GitBook」 という評価だと思われま す。 前述の learn-satysfi も mdbook を使っています。 7/34
8. mdbook とは rust-lang 公式が整備していることもあって Rust 関係のドキュメントで使 われています。 8/34
9. mdbook のプラグイン機能 mdbook-<name> というソフトウェアを用意して book.toml に [preprocessor.<name>] や [output.<name>] と書いておくと、 mdbook を起動したときに自動で実行されます。 中身のチェックや文字数カウントなどをするプリプロセッサの拡張機能 と、 中身を基に変換をしたりしてファイルを出力できる 「代替バックエ ンド」の 2 種類があります。 mdbook-satysfi は「代替バックエンド」です。 9/34
10. 先行事例（mdbook-latex） Rust などで XƎL ATEX を再実装した Tectonic をバックエンドとして使う。 機能がまだ弱いらしいので、 SATYSFI で置き換えてみたら便利になりそう な気がした。 10/34
11. リポジトリ https://github.com/puripuri2100/mdbook-satysfi にリポジトリがあります。 スターお願いします！ 11/34
12. mdbook-satysfi の使い方 12/34
13. mdbook のインストール Rust のコンパイラとパッケージマネージャの cargo をインストールし、そ れを使ってインストールする方法が一番楽です。 cargo をインストールす れば Rust のコンパイラも自動で入るのであまり考えなくて良い。 詳しくは https://www.rust-lang.org/tools/install を参照のこと。 cargo をインストールしたら cargo install mdbook を実行するだけで良い。 13/34
14. mdbook-satysfi のインストール mdbook-satysfi は crates.io に登録済みなので cargo を使ってインストール することが出来る。 cargo install mdbook-satysfi でインストールが終了する。 14/34
15. mdbook-satysfi の呼び出し book.toml という設定ファイルに [output.satysfi] という一行を入れるだけで良い。 SATYSFI は jpeg ファイルしか対応していない為、 埋め込まれている SVG ファイルや png ファイルなどは全て変換してリンクを貼りなおす必要が ある。 自動で変換され、特に設定が無ければ book/satysfi/main.saty というファイ ルに出力される。 15/34
16. PDF の自動ビルド [output.satysfi] pdf = true というように、 pdf = true という一行を入れると裏で SATYSFI が回って自 動で PDF ファイルが出力される。 その他詳しい設定は https://puripuri2100.github.io/mdbook-satysfi/ja/ を読 んでください。 16/34
17. mdbook-satysfi の拡張機能 以下の項目について自由に設定できる HTML タグを変換する際のコマンド名と引数の設定 パッケージの追加読み込み クラスファイルの変更 詳しくはドキュメント（https://puripuri2100.github.io/mdbook-satysfi/ja/） を読んでください。 必要な関数とコマンドを定義すれば自分の好みのデザインのクラスファイ ルを使うことができるため、多くのデザインが出てくると嬉しいです。 17/34
18. mdbook-satysfi の 作成方法について 18/34
19. データの取得 stdin から JSON 形式の文字列で設定や本文のデータが与えられ、 それを mdbook ライブラリが提供している RenderContext::from_json という関数で 処理するとデータ構造を得ることができます。 得られるデータの例： SUMMARY.md の中の文章構造とそれに対応するファイルの中身 タイトルや著者名などのデータ ファイルのあるパス 19/34
20. テキストを出力したい形式にする markdown テキストを与えられるので、それを解析します。 解析には pulldown_cmark というライブラリを使用しました。 mdbook 本体も使用しており、高速なのでこれ以外選択肢は無いと言って も良いです。 markdown を解析した結果を「開始タグ」・「テキスト」・「終了タグ」 に分けて順に渡してくれます。木構造のような再帰構造ではないので好み はわかれるかもしれません。 20/34
21. pulldown_cmark の罠 markdown に埋め込まれた HTML コードの解析がとてつもなく大変になり ます。 <!-- <p> hoge --> <span style="background-color: #0099FF" class="foo">fuga</span> HTML コードかどうかを「1 行単位」でしか教えてくれないため、コメン トへの対応や途中で改行されている HTML タグへの対応が大変 （場合分 けが複雑） 21/34
22. pulldown_cmark の罠を避ける方法 markdown に埋め込まれた HTML コードを含めて全てのテキストを HTML コードに変換し、変換後の HTML テキストを解析する！ コメントの対処や変なタグへの対処が楽になります。 pulldown_cmark ライブラリは標準で HTML への変換関数を提供してくれ ており、 変換方法に手を入れることも出来るため、 高速に簡単に変換で きます。 HTML コードの解析には html_parser ライブラリを使用。 PEG を使用した パーサーで、 HTML コードを木構造に変換してくれるので、再帰関数を使 用して HTML タグを SATYSFI コードに変換します。 22/34
23. mdbook 独自拡張への対応 ソースコードなどの外部ファイルの中身の挿入に関して mdbook 独自の markdown 拡張があるため、それに対応する必要がある。 {{#include file.rs}} のようにすると file.rs を読み込めるような拡張です。 行数指定ができたりします。 正規表現や手書きパーサーを駆使して解析するしかないので、 公式で関 数の提供が欲しいところですね。 23/34
24. class-mdbook-satysfi について 24/34
25. class-mdbook-satysfi とは mdbook-satysfi で出力されたファイルで標準で読み込むクラスファイルで す。 satyrographos-repo に登録してあるので、 opam update opam install satysfi-class-mdbook-satysfi satyrographos install をすることでインストールされます。 デモファイルは https://satyrographos-packages.netlify.app/docs/class-mdbook- satysfi-doc/class-mdbook-satysfi-demo.pdf をご覧ください。 25/34
26. 定義したコマンド 目次用の +Chapter・ +Separator・ +PartTitle といったコマンド、 強調用 の \strong・ \emph コマンド、 表用の +table・ +thead・ +tr・ \th コマン ドなど、 HTML タグに対応するコマンドを定義しています。 markdown 表記法内では書くことができない ruby タグや sup タグなどに対 応する \ruby コマンドや \sup コマンドもいくつか提供しています。 1000 行程度で実装できるほか、ドキュメントにも「定義しなければいけな いコマンド」の一覧を載せていますので、デザインの違うクラスファイル を作ってくださる方をお待ちしております！ 26/34
27. 出力された PDF の見た目 目次からリンクを貼り、 PDF しおりも自動で付くようになっています。 27/34
28. 出力された PDF の見た目 28/34
29. 出力された PDF の見た目 29/34
30. 出力された PDF の見た目 30/34
31. 出力された PDF の見た目 31/34
32. 依存したライブラリ satysfi-base 表や箇条書きの実装に使いました satysfi-easytable 表の実装に使いました satysfi-uline \stroke コマンドの実装に使いました satysfi-ruby \ruby コマンドの実装に使いました satysfi-quotation +block-quote コマンドの実装に使いました satysfi-fonts-noto-* 本文のフォントに使いました satysfi-fonts-inconsolata コード部分のフォントに使いました 作者の方々ありがとうございます。 32/34
33. まとめ 33/34
34. まとめ mdbook-satysfi という mdbook の拡張機能を作りました。 HTML コードを一旦経由することで HTML タグへの対応を行いました。 mdbook の独自拡張への対応が大変でした。 class-mdbook-satysfi という専用のクラスファイルも用意しました。 将来は learn-satysfi などにも使いたいですね。 34/34