Hello SATySFi!

一般的なプログラミング言語と同じように、Hello SATySFi!というテキストがあるPDFファイルを作り、SATySFiの世界に慣れてみましょう。

フォルダを作る

このPDFファイルを作成するためのフォルダをmkdirなどを使って作りましょう。

WSLを利用している場合は、Windows側にフォルダを作り、/mnt/c/Users/hogehoge/DocumentsのようにWSL側からアクセスするのが良いでしょう。

そのフォルダの場所に移動してwslコマンドを使ってWSLを起動すれば自動で上記のパスになっていると思います。

ファイルを作る

hello_satysfi.satyというファイルを作ります。SATySFiでの文書ファイルは.saty拡張子です。

文書を書いて実行する

作成したhello_satysfi.satyを開き、以下のコードを入力してください。

@require: stdja

document(|
  title = {Hello \SATySFi;};
  author = {私};
  show-title = true;
  show-toc = false;
|) '<
  +p{
    Hello \SATySFi;!
    はじめまして！
  }
>

VSCode, Vim, Emacs, AtomではそれぞれSATySFi用のシンタックスハイライトをする拡張が存在しています。 各自インストールしてみると良いでしょう。

satysfi hello_satysfi.saty

とすることでPDFファイルが出力されます。

ブラウザやDockerを使っている人は、それぞれの利用方法を確認してください。 これ以降はsatysfiコマンドを使う方法を説明しますが、特に変わらないと思っていてください。

また、このようにPDFファイルを生成することを便宜的に「コンパイル」と呼んでいきます。

出力されたPDFファイルを開いてみてください。「Hello SATySFi! はじめまして！」と書かれているはずです。

ToDo: スクリーンショットを貼る

文書の解剖

書かれた文書を詳しく確認していきましょう。

まず、ファイル冒頭の

@require: stdja

です。

ここでSATySFiの標準ライブラリに含まれているクラスファイルの一つである、stdja.satyhを読み込んでいます。

出力されるPDFファイルの体裁を決定する特殊なパッケージファイルの一つです。LaTeXのそれとは細かいところは違いますが、果たす役割は同じと思って良いと思います。

次に、document (| ~ |) '< ~ >の部分です。

ここでは「documentという関数に(| ~ |)という値と'< ~ >という値を与える」ということをしています。

documentという関数はstdjaクラスファイルによって提供されるもので、二つの引数を取って文書となる値を返す関数です。

全てのクラスファイルがdocumentという関数を提供するとも限りませんし、引数が二つに限定されるとも限りません。不安であれば各クラスファイルのドキュメントを確認しましょう。

document関数に渡す引数を確認しましょう。

(|
  title = {Hello \SATySFi;};
  author = {私};
  show-title = true;
  show-toc = false;
|)

は「レコード」というデータ構造を表します。レコードは「ラベルに値を結び付けている」ものをまとめているもので、並べる順番は関係ありません。ですので、上のコードと

(|
  show-title = true;
  show-toc = false;
  title = {Hello \SATySFi;};
  author = {私};
|)

は同一のものです。

document関数が要求しているレコードでは、

  • title
  • author
  • show-title
  • show-toc

という4つのラベルを要求しています。

titleでは文書のタイトルを{}で囲まれた中に書き、authorでは文書のタイトルを{}で囲まれた中に書きます。 show-titleでは「タイトルをPDFに表示するかしないか」をtrueかfalseのどちらかで指定します。 show-tocでは「目次をPDFに表示するかしないか」をtrueかfalseのどちらかで指定します。

'<
  +p{
    Hello \SATySFi;!
    はじめまして！
  }
>

は文書の本体です。'<>という記法は、「文章のブロック」を示します。縦方向に連なる“箱”をイメージしてみてください。厳密には、箱になる前の“生の箱”です。 この“生の箱”をdocument関数の中で“箱”に組み上げ、さらにPDF文書に変換しています。 以降、この“生の箱”のことを「ブロックテキスト」と呼びます（ちなみに、“箱”の方は「ブロックボックス」と呼びます）。

+p{}は「文字からなる段落を箱にする機能」を持つ特殊な関数です。ブロックテキスト内では+から始まる特殊な関数しか使えません。この特殊な関数を「ブロックコマンド」と呼んでいきます。 通常の関数は小文字から始まりますが、ブロックコマンドは+の後は任意のアルファベットから始まり、アルファベット・数字・-の3種類の文字が任意の組み合わせで使うことができます。

ブロックコマンドはブロックテキスト内で何個も連ねることができます。 例えば、

'<
  +p{
    1個目の段落
  }
  +p{
    2個目の段落
  }
>

という風にです。

+pブロックコマンドに与える値を見てみましょう。{}という記法は「一文字ごとに箱になったものが横にたくさん連なっている枠」のイメージです。これもまた厳密にはそうなる前の“生の枠”です。“生の枠”の方を「インラインテキスト」と呼び、“枠”の方を「インラインブロック」と呼んでいます。

インラインテキスト内では行頭行末の空白と改行は（ほとんど）意味を持ちません。 見やすいように改行し、インデントを付けましょう。

インラインテキスト内ではほとんどの文字がそのまま使えます。 ただし、

  • `
  • %
  • \
  • ;
  • $
  • *
  • @
  • #
  • {
  • }
  • <
  • >
  • |

の文字は\を使ってエスケープする必要があります。

さて、このインラインテキスト内で関数を使いたくなる時は\から始まる「インラインコマンド」を使います。 \SATySFiというコマンドは「SATYSFIという文字列の内、YとIを少し下げて表示する」という関数です。 ブロックコマンドと同じように、インラインコマンドには引数として値を受け取り、様々な機能を実現することができます。

ブロックコマンドやインラインコマンドがインラインテキストやブロックテキストの引数を取らないときは;を使うことで「コマンドの終了」を宣言します。 厳密な使い分けについては後の章を読んでください。