SATySFiに関すること

この記事は2018年に投稿されたのち、2023年2月に更新を行いました。

はじめに

SATySFiとは

SATySFiとは、型による静的検証能力の高い組版システムです。

従来の組版システムであるLaTeXにはない特徴である可読性の高さと詳細なエラー報告機能を持つことを目指して作られています。

The SATySFibook（SATySFiのマニュアル）が無料で見ることができるようになりました。URLはここです。わからないところがあったらその箇所を読みましょう。
投げ銭もできます。紙とインクでできた方も欲しい方はここから買いましょう！

SATySFiの特徴

• マークアップ言語
• 裏でTeXを使っていたりせずに自前でPDFファイルを出力してくれる
• PDFファイルだけではなく、HTMLファイルやTeXファイルを出力する機能もある
• 数式を表現することが非常に得意
• エラーが表示されるタイミングが早く、わかりやすい
• 機能の拡張が便利
• 非常に若いソフトであり、オワコン化が囁かれているLaTeXに代わりになることが可能かもしれない
• LGPLv3の元GitHubで公開されているOSSである（つまり、タダで使用できる）

（今更だけど）この記事の目的

SATySFiを始めようと思った人のため、そして自分のためにSATySFi関係の情報を集めておくことが目的です。

「SATySFi完全に理解した」という人のためではないのでご了承くださいませ。

間違っていることが書いてありましたら教えてください。直していきたいと思います（根本から間違っているという場合でも見捨てずに教えていただけると嬉しいです）。

注意事項

書く内容に関しては正確なものになるように気をつけていますが、間違っていることを書いているかもしれません。この記事に頼り切らず、他の情報と合わせて使用してください。

この記事を使用したことで受けた被害等の責任は取りかねます。

SATySFiはまだバージョンが0.0.8であり、また近々後方互換性のない変更が入る0.1.0がリリースされる予定があります。このように、どんどん機能が追加されていったり、今まであった機能が廃止されたりと言った変化が起きることは充分ありえるため、注意をしてください（v1.0.0までに互換性のない変更があることは十分にありえるので、パッケージ作成者は情報を追うべきです）。

この記事に情報は2023年2月時点での最新版のSATySFiについて述べていきます（大きな変更がSATySFiに加わったらなるべく対応していくつもりです）。
ですので古いSATySFiにはない機能について述べたりしていきますが、ご了承ください。

筆者のスペック

これを書いている人のスペックです。参考までに

• 使用OSはUbuntuやWindows11
• よく使う言語はRust・OCamlなど
• Ubuntu on WSLにSATySFiの最新版を入れている。

SATySFiのインストール方法

SATySFi インストール手引き 2021年5月版を読むと良いと思います。ここではSATySFiのパッケージマネージャであるsatyrographos（サティログラポス）を使ってインストールする方法を主に紹介しています。

他にはソースコードから手動でビルドする方法があり、これは公式READMEを参照すると良いでしょう。

いずれにせよ、WindowsではWindows Subsystem for Linux(WSL)を使用する必要があります。最新のWindowsであればMicrosoft Storeからボタンを推すだけでインストールすることができるため、手軽に行えます。

opamとsatyrographosを使ったインストール

一番標準です

まずはopamのインストールを行います。正確な情報はopamのドキュメントを参照してください。概ね

bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"

を実行すればよいと思います。

インストール時に必要とするソフトウェアとしては

• bubblewrap
• build-essential
• curl
• git
• m4
• unzip

あたりがあります

次にOCamlのコンパイラをインストールします。必要なバージョンは2023年2月時点では4.12.0以上です。各自で確認したい場合はsatysfi.opamファイルの制約を確認してください。

opam init --comp 4.14.0
eval $(opam env)

のようなコードになります。

もしWSLなどでインストールに失敗した場合にはsandboxが使えないからかもしれません。その場合には無効化するオプションでインストールをしてください。

opam init --comp 4.14.0 --disable-sandboxing
eval $(opam env)

.bashrcファイルなどの設定ファイルにeval $(opam env)を書いておくと、シェル起動時に常にopam環境を呼び出すことができます。

次にopamの外部リポジトリを登録します。

opam repository add satysfi-external https://github.com/gfngfn/satysfi-external-repo.git
opam repository add satyrographos https://github.com/na4zagin3/satyrographos-repo.git
opam update

最後にsatysfiとその標準ライブラリ、そしてsatyrographosをインストールし、パッケージのインストールを行います。

opam install satysfi-dist satysfi satyrographos
satyrographos install

これで最新版のSATySFi及びパッケージマネージャを使用することができます。

ソースコードからのインストール

ソースコードからのインストールではSATySFiの最新版を使用することができます。また、satyrographosのみをインストールすることでパッケージマネージャの恩恵も得ることができます。

手順としては、opamとOCamlのインストールと外部リポジトリの登録までは一緒です。

その後SATySFiのリポジトリを手元にcloneします。

git clone https://github.com/gfngfn/SATySFi.git

その後、フォルダに移動しビルド及びインストールをします。

cd SATySFi
opam pin add satysfi .
opam install satysfi

標準ライブラリのインストールには2種類の方法があります。一つはsatyrographosを使ったインストールで、もう一つはSATySFiのリポジトリの中にあるインストーラを使う方法です。

satyrographosを使う場合にはsatyrographosと標準ライブラリをインストールします。

opam install satyrographos stysfi-dist
satyrographos install

インストーラを使う場合には、SATySFiフォルダでインストーラを起動します。

# 必要であればフォルダに移動
# cd SATySFi
./download-fonts.sh
sudo ./install-libs.sh

Docker Imageを使う

SATySFi単体のイメージの他にもSATySFi本体以外にもsatyrographosが入ったイメージなどがあり、便利です。

詳しくは"docker imageを使う"を読んでください。

satysfi-unofficial

matsud224氏が「SATySFiをちょっと試してみたい人がOCamlのビルドからやらないといけないのはハードルが高い」と思ったらしく、少し簡単にSATySFiを入れられるようなものを整えてくださいました。

satysfi-unofficialのREADMEを読んでそれに従えばインストールできます。

SATySFi Playground

正確にはインストールするものではありませんが、インターネット上でコンパイルすることができるものです。

demoファイルのコンパイル

とりあえずdemoファイルをコンパイルしてみましょう。
SATySFiのリポジトリをcloneもしくはダウンロードするか、SATySFiのリリースをダウンロードするかしましょう。

準備ができたらターミナルを開きます。ターミナルで、demoフォルダまで移動し、ビルドします。

cd demo
make

するとログが出てPDFファイルが出力されると思います。

ココらへんはLaTeXのコンパイルと似たようなものでしょう。。

コンパイルが終わったら出力されたPDFファイルを見てみましょう。

ヘッダーやフッター、画像の出力、数式の出力等ができていることがわかるでしょう。

これの中身はdemo.satyに書いてあります。見てみると面白いでしょう。

SATySFi関係の拡張子

まずは通常の文を書くのが.satyファイルです。LaTeXで言うところの.texファイルでしょう。

機能を拡張、追加するコマンドを書くのが.satyhファイルです。LaTeXで言うところの.styファイルでしょう。

ページ数などの一時情報が記録されているのがsatysfi-auxファイルです。LaTeXで言うところの.auxファイルでしょう。これは自動で作成されるので触る必要はありません。

これ以外にもSATySFiによって提供される拡張子はいくつかありますが、表に出てくるのはこれくらいです。

コンパイルオプション

satysfi demo.saty -o output.pdf
satysfi --help

などのようにしてオプションを付けてコンパイルしたりすることができます。
--helpで全てのオプションを確認することができます。

主なパッケージ

標準ライブラリ

SATySFiで提供されるパッケージです。
これらはlib/dist/packages内にあります。

これらはSATySFiが見つけることが出来る場所に置いてあるので、文書の冒頭で@require: stdjabookの様に書いて読み込むことができます。

.satyhファイルと同じフォルダ内にある.satyhファイルを読み込むときは@import: localの様に書いて読み込みます。（参考ツイート1,参考ツイート2,参考ツイート3）

satyrographosでインストールできるパッケージ

satyrographosでインストールできるパッケージの一覧はSatyrographos Package Indexというサイトで見ることができます。概要のほかにドキュメントも見ることができるので非常に便利です。

ここではここからいくつか紹介してみます（ここにあるのが全てではありません）。

クラスファイル

• class-jlreq：日本語組版の要件になるべく沿うような組版をしてくれる
• class-slydifi：スライド作成ができる
• class-stjarticle：標準ライブラリを少し改造してみたもの

数学関係

• azmath：様々な便利関数の追加
• derive：証明木を描画する
• ncsq：ダイアグラムを描画する
• karnaugh：カルノー図を描画する
• siunitx：単位記号の提供
• chemfml：化学式の記述

ソースコード描画

• code-printer：シンタックスハイライトとカラーテーマを提供する
• algorithm：疑似コード生成

図表

• easytable：表組
• figgox：自由度の高い図表の配置
• image：画像の貼り付け
• enumitem：箇条書きのカスタマイズ
• colorbox：綺麗な枠機能の提供
• arrows：矢印描画
• parallel：minipage機能の提供

その他便利機能

• latexcmds：LaTeX標準のよくあるコマンドの提供
• uline：下線・打消し線の提供
• ruby：ルビ機能

フォント

• fss：フォントの切り替えをサポートします

フォントファイルのダウンロード及び設定を行ってくれるライブラリ達です。
沢山あるので色々とみて自分の手で選んでください！

• [fonts-noto-*]：Notoフォント系列（sans・sans cjk jp・serif・serif cjk jp・emoji）
• han sans jp
• han serif jp
• dejavu
• asana math
• computer modern unicode
• theano

プログラミング関係

• base：事実上の標準ライブラリです。多数の便利な関数が提供されています。
• zrbase：便利な関数が多数提供されています
• num-conversion：様々な数字表記法との相互変換
• railway：パスの記述の際に補助情報を表示する
• json：JSONパーサ
• csv：CSVパーサ

エディタ拡張

ファイルを編集する際、なにも補助がないとなかなか厳しいです。そこでSATySFiを書く時に補助してくれる拡張機能を紹介します。

• satysfi.vim
  VimでSATySFiを使う時に補助してくれる拡張機能です。
• satysfi.el
  EmacsでSATySFiを使う時に補助してくれる拡張機能だと思います。
• satysfi-workshop
  VSCodeでSATySFiを使う時に補助してくれる拡張機能です。

その他便利ツール

• satysfi-formatter：コードフォーマッタ
• satysfi-language-server：SATySFiのLSPです

書き方

※SATySFiに標準で含まれているパッケージであるstdjabookを使用する想定で書きます。

まずは簡単なドキュメントです。

@require: stdjabook
StdJaBook.document(|
    title = {Hello \SATySFi;};
    author = {私};
    show-title = true;
    show-toc = true;
|)'<
    +p{
        はじめてのサティスファイ！
    }
>

これをHello.satyとして保存し、

satysfi Hello.saty

とするとHello.pdfという名前のPDFファイルが出てきます。

次に中身を見ていきましょう。

一番最初の@require: stdjabookですが、これは既に説明したように、パッケージを読み込むためのコマンドです（stdjabookはLaTeXでいうところのクラスファイルに相当するもの）。

二番目のStdJaBook.document(||)'<>ですが、この文書全体に関する指定です。document(||)'<>でも良いのですが、「stdjabookによって提供されたものを使うことを明らかにするためにStdJaBook.を付けるべき」という考えのもとStdJaBookをつけています。これはどちらでも良いです（参考ツイート）。documentの中身ですが、こうなる理由はstdjabook側でdocumentが以下のように定義されているからです。

  val document : 'a -> block-text -> document
    constraint 'a :: (|
      title : inline-text;
      author : inline-text;
      show-toc : bool;
      show-title : bool;
    |)

なので、titleとauthorにはインラインテキスト（普通の文章）を、show-tocとshow-titleにはtureかfalseのどちらかを入れましょう。
これらの役割は名の通りですが、titleはこの文書のタイトルを、authorは著者名を入れるものです。show-tocは目次を出力するかしないかの選択を、show-titleはタイトルを出力するかしないかの選択です。

三番目の+pですが、これは段落を表すコマンドです。
stdjabookでは以下のように定義されています。

この他にも、行頭インデントなしの段落を表す+pnというコマンドもあります。

一応stdjabookが提供するコマンドとその役割を書いておきます。

• title（inline-textを入れてください。最初のdocumentの部分で指定します。名前の通り、文書のタイトルを書きます。）
• author（inline-textを入れてください。最初のdocumentの部分で指定します。名前の通り、文書の作者の名前を書きます。）
• show-title（trueかfalseを指定します。最初のdocumentの部分で指定します。タイトルを表示するか否かを選択します。）
• show-toc（trueかfalseを指定します。最初のdocumentの部分で指定します。目次を表示するか否かを選択します。）
• \ref（相互参照です。本文中で使用します。）
• \ref-page（ページの相互参照です。本文中で使用します。）
• \figure（画像の配置です。）
• +p（行頭インデントのある段落を書くのに使用します。）
• +pn（行頭インデントのない段落を書くのにしようします。）
• +section（節です。）
• +subsectioon（小節です。）
• \emaph（強調です。）
• \footnote（フットノートです。）

この時、+sectionや+subsectionは、

+section{節タイトル}<
    +p{文章}
>

のように<>を後ろにつけます。これは

水平方向（文字が行をなす向き）の入力を { 〜 } で，垂直方向（行が段落をなす向き）の入力を < 〜 > で括って両者を区別する

ということらしいです（参照ツイート）。

数式の書き方についてですが、基本的に${}の中に書けば良いらしいです（あまり数式を書かないのでよくわからない）。

${a^5 \times a^7 \times a^3 = a^{15}}

と書くと

$a^5 \times a^7 \times a^3 = a^{15}$

と出力されます。書き方はLaTeXと“ほぼ一緒”と考えて構わないでしょう（gfncmdが提供する書き方寄りだと思います（作者が同じだからある意味当然かも））。

資料

リポジトリなどでは

• The SATySFibookのPDFファイルでここで公開されている
• 提供されているプリミティブな関数の説明がdoc/doc-primitives.satyに書かれている
• 様々な機能の説明のあるWikiページ
• 日本語で書かれたメモがあります。

が公開されています。

他に、qnighy氏がまとめてくださった「SATySFi構文メモ」および、forestaa氏による更新版があります。

また、設計思想等を知ることが出来るものとして、「【2017年度未踏／No.2】型による静的検証能力の高い組版システムの開発 」という動画と、「スライド」があります。

SATySFi Advent Calendar及びSATySFi Confから多くの資料に当たることができます。

• SATySFi Advent Calendar 2018
• SATySFi Advent Calendar 2019
• SATySFi Advent Calendar 2020
• SATySFi Advent Calendar 2021
• SATySFi Advent Calendar 2022
• SATySFi Conf 2020
• SATySFi Conf 2021
• SATySFi Conf 2022

情報共有場所

SATySFiのSlackチャンネルがあります。

招待リンクから参加してみてください。