mdbook-satysfi

mdbook-satysfiはmarkdownファイルからHTMLファイルで構成されたbookを生成するRust製のソフトウェアであるmdbookの拡張機能を提供するソフトウェアです。

mdbook-satysfiをインストールした状態でbook.tomlに[output.satysfi]という記述を追加してmdbook buildを実行すると、bookの内容と同じ内容のSATySFiのドキュメントファイルが生成されます。

実装

実装はRustで行っています。

リポジトリはpuripuri2100/mdbook-satysfiです。

依存するもの

インストールにはRustとCargoを必要とします。

また、生成されたドキュメントファイルを処理するためにはclass-mdbook-satysfiというSATySFi用のライブラリのv0.2.0が必要であり、これのインストールにはsatyrographosが必要です。 当然のことながらSATySFiも必要です。

インストール方法

RustとCargoをインストールした状態で

cargo install mdbook-satysfi

と行うことで最新版が手に入ります。

License

mdbook-satysfiはMITライセンスのもと公開されています。

出力するファイルの名前を変更する

book.tomlに以下のような内容を加えることで出力されるSATySFiの文書ファイルの名前を変更することができます。

[output.satysfi]
output-file-name = "name.saty";

読み込むパッケージを指定する

book.tomlに以下のような内容を加えることで読み込むパッケージを追加することができます。

divタグやspanタグで独自のタグを作るときに、それに対応するコマンドを用意したいときに便利です。

[output.satysfi]
require-packages = ["base/int"]
import-packages = ["local"]

require-packagesではstring arrayを与えます。指定したパッケージが@require:で読み込まれます。

import-packagesでは、指定したパッケージが@imports:で読み込まれます。

HTMLタグを変換する

markdownファイル内にはHTMLタグを直接書くことができます。

ここではそのHTMLタグを処理するための方法を説明します。

ただし、mdbook-satysfiはmarkdownファイルを一旦HTMLに変換した後に処理をする方法を取っているため、意図しないタグの衝突が起こる可能性があることに充分注意して下さい。

book.toml内に以下のようなコードを書いてください。

[output.satysfi]
  [output.satysfi.html]
    [output.satysfi.html.hoge]
      command_name="fuga"
      children_type="inline"
      [[output.satysfi.html.hoge.attribute]]
        name = "src"
        type = "link option"
      [[output.satysfi.html.hoge.attribute]]
        name = "title"
        type = "inline"

[output.satysfi.html.<tag-name>]とすることで、そのタグが実際に書かれていた場合にその下に書いた設定が適用されます。

divタグとspanタグの場合はclassで指定した名前が使われます。

command_nameはコマンドを出力する際にどうするかを設定します。デフォルトはタグ名です。

children_typeは子要素がどうなるかを表しています。書かないと子要素は無視されます。 与えられるのは

• inline
• block
• inline list
• block list
• inline code
• block code

だけです。

[[output.satysfi.html.<tag-name>.attribute]]とすることで属性をSATySFiコマンドの引数に変換することができます。

属性はこのテーブルに追加した順に渡されます。

nameは属性の名前です。

typeは属性の値がどうなるかを表しています。* optionのとき、その属性がなかった場合はNoneになります。optionが付いていないでその属性がなかった場合はその部分は無視されます。

与えられるのは

• string
• link
• int
• bool
• inline
• block

とそれぞれのoptionです。

linkとは相対パスのことで、画像タグの処理などに使うことを想定しています。与えられた相対パスをその原稿の書かれたmdファイルのパスと結合してSATySFiファイルに書き出します。

クラスファイルを自作する

mdbook-satysfiによって出力されたファイルを処理するためのクラスファイルを自作することができます。

必要なコマンドなど

(|
  title : inline-text;
  authors : inline-text list;
  description : inline-text option;
  language : string option;
|)

というレコード型を一つ目の引数に、block-textを二つ目の引数に持ち、document型を返す、documentという名前の関数を提供する必要があります。

languageフィールドに入力される値はSome(`ja`)やSome(`en`)といったものです。

実装する必要があるコマンドは以下の通りです。

• +Chapter: [(int list) option; int; inline-text; block-text]：章を表すコマンドです。引数はそれぞれ「何番目の章の子や孫になっているのか」・「深さ」・「タイトル」・「中身」です。
• +PartTitle: [inline-text]：目次に出力する部の分け目です。引数はタイトルです。
• +Separator: []：目次に出力するラインを表します。引数はありません。
• \strong: [inline-text]：強調を表します。
• \emph: [inline-text]：強調を表します。
• \strike: [inline-text]：打ち消し線を表します。
• +block-quote: [block-text]：引用を表します。
• \block-quote: [block-text]：引用を表します。
• +heading: [int; inline-text]：節のタイトルを表します。一つ目の引数は深さです。
• +p: [inline-text]：段落を表します。
• \p: [inline-text]：段落を表します。
• +code: [string]：インラインコードを表します。
• \code: [string]：インラインコードを表します。
• +code-block: [string option; string option; string]：ブロックコードを表します。一つ目の引数は指定された言語を表し、二つ目の引数はカラーテーマを表します。ここに与えられる値はbook.tomlにcolor-theme = "theme name"と表記されると変更可能です。
• \code-block: [string option; string option; string]：同上
• \href: [string; inline-text]：リンクを表します。
• +img: [string; inline-text]：画像挿入を表します。二つ目の引数はキャプションです。
• \img: [string; inline-text]：画像挿入を表します。二つ目の引数はキャプションです。
• \footnote: [string]：脚注を出力します。引数はkeyです。
• +add-footnote: [string; inline-text]：脚注の中身を登録します。一つ目の引数はkeyで、二つ目の引数が中身です。
• +rule: []：線を出力します。
• \task-list-marker: [bool]：trueのときはチェック印付きの四角を出力し、falseのときは空の四角を出力します。\itemコマンドの引数内に書かれます。
• \item: [inline-text]：箇条書きの際に使用します。
• \lisgint: [inline-text list]：箇条書きです。
• +lisgint: [inline-text list]：箇条書きです。
• \enumerate: [int; inline-text list]：数字付きの箇条書きです。一つ目の引数は「数字がどこから始まるか」を表します。
• +enumerate: [int; inline-text list]：数字付きの箇条書きです。一つ目の引数は「数字がどこから始まるか」を表します。
• +table: [block-text]：表を出力します。
• +thead: [block-text]：表のヘッダーです。
• +tbody: [block-text]：表の本体です。
• +tr: [inline-text list]：表の横方向を指定します。
• \th: [string option; inline-text]：ヘッダーの中で表の一セルを表すコマンドです。一つ目の引数は位置を表します。中央ぞろえの時はSome(`center`)・左揃えの時はSome(`left`)・右揃えの時はSome(`right`)が与えられます。
• \td: [string option; inline-text]：\thのボディ版です。

その他のコマンドについて

mdbook-satysfiはマークダウンをHTMLに変換してからSATySFiコードに変換をする形を取っています。そのため、原理的にはHTMLタグ全てに対応するコマンドが必要です。ですが、それらに対応するかどうかはクラスファイル作成者に任されます。

また、divタグとspanタグではclassで指定した名前がコマンド名として使われる仕様なため、それらが使用されているマークダウンファイルを処理したい場合はそれに対応するコマンドを実装する必要があるかもしれません。

クラスファイルの変更の仕方

[output.satysfi]以下に

class-file-name = "class-file-folder/class-file-name"
is-class-file-require = true

のように記述します。

class-file-nameにはクラスファイルの名前を文字列型で入力します。class-file-nameフィールドが無い、もしくは文字列型ではない場合はclass-mdbook-satysfi/mdbook-satysfiが使用されます。

is-class-file-requireには「クラスファイルの読み込みが@requireかどうか」を真偽値で入力します。trueの場合は@requireで読み込まれ、falseの場合は@importで読み込まれます。 デフォルト値はtrueです。

SATySFiを呼び出す

[output.satysfi]テーブルの中にpdf = trueというコードを入れると、自動でSATySFiが呼び出され、出力したsatyファイルがコンパイルされてPDFファイルが生成されます。

デフォルトではpdf = falseで、SATySFiは呼び出されません。

高度な設定

[output.satysfi]
  [output.satysfi.pdf]
    # 各種設定

とすることで高度な設定を行うことができます。

SATySFiの起動コマンドを変更する

以下のようにcommandsというkeyに対してSATySFiを起動するためのコマンドを文字列か文字列のリストで与えることでSATySFiの起動コマンドを変更することができます。デフォルトはsatysfiです。

[output.satysfi]
  [output.satysfi.pdf]
    commands = ["wsl", "satysfi"]

上のように、["wsl", "satysfi"]と与えると、SATySFiを起動するために

wsl satysfi main.saty

というコマンドが実行されます。

このままではLinuxでもwslコマンドが呼ばれてしまうため、OSごとに切り替えることができるようになっています。

[output.satysfi]
  [output.satysfi.pdf]
    commands = {
      windows = ["wsl", "satysfi"],
      macos = ["satysfi"],
      linux = "satysfi",
      others = "satysfi"
    }

のようにすることでOSごとに呼び出しコマンドを切り替えることができます（この場合も、コマンド名として文字列または文字列のリストを与えます）。

現在、選択できるのは

• Windows
• MacOS
• Linux

の3種類のみで、それ以外のOSはothersでひとまとめにされています。

省略した場合はデフォルトのsatysfiが起動コマンドとして選択されますので、

[output.satysfi]
  [output.satysfi.pdf]
    commands = {windows = ["wsl", "satysfi"]}

と書けば「Windowsのときにはwsl satysfi <file name>で起動させ、それ以外のOSではsatysfi <file name>で起動させると設定できます。

SATySFiに与えるオプションの変更

SATySFiに与えるオプションを変更することができます。

• 変更するためにTOMLに与える時に使うキーの名前
• 対応して変更されるSATySFiのオプション
• キーに対応して与える値の種類
• デフォルトの値

の一覧のリストは以下のようになっています。

なお、text-mode-configsで文字列を与える場合は、

[output.satysfi]
  [output.satysfi.pdf]
    text-mode-cofings = "tex,latex"

のようにカンマ区切りで文字列を与えてください。

文字列のリストで与える場合はそのまま

[output.satysfi]
  [output.satysfi.pdf]
    text-mode-cofings = ["tex", "latex"]

のように与えてください。

また、config-pathに与えるパスは「“{build-dir}/satysfi”フォルダ」からの相対パスにしてください。

output-file-nameに与えるファイルのパスはconfig-path同様に、「“{build-dir}/satysfi”フォルダ」からの相対パスにしてください。