【随時更新】SATySFi ベストプラクティスまとめ
はじめに
ということで、この文書が役に立つかもしれません。
注意事項
- 本プラクティスは2022年4月時点で最新の SATySFi v0.0.7 をベースに記述しています。
- この記事はまだ作りかけです。事情が変わり次第更新していく予定です。
- 抜け漏れがあれば指摘してください。
- 自作パッケージはどうしても贔屓されてしまいます。ご了承ください。
SATySFi を学びたいときのベストプラクティス
-
本を読んで SATySFi をじっくり理解したい、そんなときは The SATySFibook 以上に最適なものはありません。SATySFi 開発者の gfngfn さん自身が執筆されており、SATySFi の理念・構文を理解するのに最適です。
-
公式リポジトリの doc/ 以下に置かれている文書は、より細かい機能（全てのプリミティヴなど）を知るのに役立ちます。
ただし、読むためには satysfi の環境構築を済ませてコンパイルする必要があります。 -
SATySFi に関する記事をたくさん読みたければ、SATySFi Advent Calendar の記事を読んでみましょう。
SATySFi で詰まっているときのベストプラクティス
誰かに質問をしましょう。SATySFi のコミュニティ上で質問するのがおすすめです。
-
- SATySFi に関する話題全般を取り扱う Slack コミュニティです。
- いくつかのチャンネルに分かれており、初心者が質問しやすい
#beginnerチャンネルもあります。 - Twitter では（字数制限などで）行えない具体的なコードに関する質問も、 Slack 上なら行いやすいといえます。
-
- 誰でも閲覧・参加できます。Twitter アカウントをお持ちの方はお気軽にご参加ください。
- SATySFi について気軽に質問・相談できるほか、パッケージの宣伝等にも使われています。
開発・執筆環境を整えるときのベストプラクティス
環境構築
環境構築なんて面倒なことはしたくない！という人
「環境構築」の見出しの下に「環境構築を行わない」という見出しが入るのも変ですが、
実はローカルでの環境構築を一切せずに SATySFi を使う方法が2つほど存在しています。
SATySFi Playground (https://www.satysfi-playground.tech)
- アカウントも何も作ることなく SATySFi を試せる環境です。上記の URL にアクセスするだけで使えます。最もお手軽。
- PDF を生成するタイミングで表示される URL を使えば、組版結果を他の人と共有することもできます。
- 現時点では、標準パッケージ以外のパッケージは使えません。
SATySFi Gitpod Template
- Gitpod というサービスを利用することで、VSCode ライクなオンライン環境で SATySFi が使えます。
- SATySFi Workshop がデフォルトで入っており、コマンド補完やエラー箇所の診断などが効きます。
- Satyrographos を用いて外部パッケージのインストールができます。
- Gitpod を無料で使える範囲には制限がありますが、試しに使う程度であれば問題にはならないでしょう。
ちゃんとローカルに SATySFi を入れてじっくり書きたい！という人
以下の記事を読んで設定しましょう。
SATySFi のインストール・パッケージ管理
殆どのユースケースで、パッケージは Satyrographos で管理するのが最良といえます。
使い方は以下の記事を読みましょう。
エディタによる執筆支援
テキストエディタによっては、SATySFi の構文に対応した拡張機能（プラグイン）が用意されていることがあります。
- VSCode: SATySFi Workshop
- Vim: qnighy/satysfi.vim: Vim syntax plugin for SATySFi typesetting system
- Emacs: gfngfn/satysfi.el: An Emacs major mode for SATySFi など
SATySFi language server を用いることで賢いコマンド補完や定義ジャンプ等が使えるようになります。
SATySFi Workshop には標準で入っている他、Vim や Emacs でも language client の設定を行うことで使用することができます。
詳しい手順は以下の記事を参照。
文書を作成するときのベストプラクティス
クラスファイル
SATySFi におけるクラスファイルは、
文書を作成するときの骨組み全体を規定するパッケージファイルを指します [1]。
たとえば stdja というクラスファイルを使用する場合は文書ファイルの冒頭に以下のように記述します。
@require: stdja
クラスファイルには大きく分けて3種類存在します。
- 標準で用意されているもの
stdjastdjabookstdjareportstandalone
- 標準で用意されておらず、Satyrographos に登録されているもの
exdesign-
jlreqetc.
- 標準で用意されておらず、Satyrographos にも登録されていないもの
「標準で用意されているもの」または「Satyrographos で登録されているもの」を用いるのが楽です。
Satyrographos から使用することのできるクラスファイルの一覧は Satyrographos Package Index から確認するのがよいでしょう。
パッケージを選ぶと、基本情報、インストール方法、ドキュメントといった様々な情報が閲覧できます。
レポート・書籍
レポート・書籍などを記述する際には、選択肢がいくつか考えられます。
stdjabook
一般的な文書を記述するクラスファイルです。
コード例
@require: stdjabook
document (|
title = {タイトル};
author = {monaqa};
show-toc = true;
show-title = true;
|) '<
+section{てきとうな節}<
+subsection{てきとうな小節}<
+pn{
段落1。
}
+p{
段落2。
}
>
>
>
-
標準に含まれており、追加で何かをインストールする必要がありません。
-
以下のコマンドが定義されています。
-
+section,+subsection: 節・小節。 -
\ref,\ref-page: 相互参照。 -
\figure: 浮動する図の挿入。 -
+p,+pn: 段落（+pnのほうは冒頭にインデントが付かない）。 -
\emph: テキストの強調。 -
\footnote: 脚注。
-
-
類似のクラスファイルとして
stdjaがありますが、章節のレイアウトが異なる、stdjaのほうには脚注を付ける\footnoteが無いなど、微妙な違いがあります。
stdjareport
stdjabook と比較すると、より学術的な文書を記述するのに向いたクラスファイルです。
コード例
@require: stdjareport
document (|
title = {タイトル};
author = {monaqa};
|) '<
+chapter{てきとうな章}<
+section{てきとうな節}<
+subsection{てきとうな小節}<
+p{
段落1。
}
+theorem?:({適当な定理})?:(`foo`){適当な主張。}
+proof{読者への練習問題とする。}
+corollary{適当な主張。}
+proof{ Theorem \ref(`theorem:foo`); より明らか。 }
>
>
>
>
- 標準に含まれており、追加で何かをインストールする必要がありません。
-
stdjabookに用意されているコマンドに加え、以下のコマンドが定義されています。-
+chapter章。 -
+definition,+theorem,+example,+lemma,+corollary: 定義、定理、例、補題、系 -
+proof: 証明 -
\dfn: 新出の単語などに用いられる強調
-
-
stdjabookと異なり、目次機能は付いていません。
exdesign
体裁のカスタマイズが可能なクラスファイルです。組版例は公式ドキュメントを参照。
document 関数の引数に多くの項目を渡すことで、体裁を柔軟に指定できます。
jlreq
LuaTeX-ja/pLaTeX/upLaTex における jlreq の作者でもある abenori さんが開発されたクラスファイルです。
（私自身は日本語組版の素人のため正しく判断できませんが）おそらく日本語組版処理の要件を満たすべく開発されているものと考えられます。
stdjabook と同等のコマンドが提供されており、文書のタイトルや目次の体裁を変更する機能も充実しています。使用方法は以下を参照。
スライド
SLyDIFi
プレゼンテーション用のスライドを作成するために開発されたクラスファイルです。他の多くのドキュメントとは異なり、複数のテーマから選択することができます。
また、document 関数の引数ではなく +set-config などのコマンドを用いることでドキュメントの体裁を変更することができます。
組版例やテーマの例は以下を参照。
また、 SLyDIFi を用いてスライドを作成する解説記事も以下で公開されています。
履歴書
SATySFi で履歴書を作成するときに使うことができるパッケージです。実際の組版例はリポジトリの README にあります。
図の挿入
LaTeX の figure 環境では図を浮動させて挿入することができます。SATySFi でもクラスファイルによっては浮動図を扱うことができますが、現状は LaTeX ほど柔軟に指定することはできません。これは SATySFi 本体の制約によるところが大きく、今後の改善が期待されるところです。
-
図をテキスト本文中の指定位置に挿入させることは、クラスファイルを問わず可能です。
- LaTeX の
figure環境の指定位置でいう here (h) に相当。
- LaTeX の
-
一部のクラスファイルでは、図をページの上部に固定して表示することができます。
- LaTeX の
figure環境の指定位置でいう top (t) に相当。 -
\figureという名前のコマンドがそれに対応していることが多いようです。 - 対応クラスファイルは
stdjabookやjlreqなど。
- LaTeX の
-
LaTeX の
figure環境の指定位置でいう bottom (b) や page (p) に相当する機能を提供するクラスファイルは現在存在しないと思われます。- bottom は原理的には可能と思われます。探したらあるかもしれません。
- 現在の SATySFi 本体の制約上、page 相当の機能の実現は本体のアップデートが入らない限り難しいでしょう。
-
図を「ページに対する絶対位置」で指定して挿入することは、クラスファイルを問わず可能です。
- LaTeX でいう
textposパッケージ の機能に相当。
- LaTeX でいう
図をテキスト本文中の指定位置またはページに対する絶対位置で挿入したい場合は、 satysfi-figbox パッケージが便利です。
提供機能・使い方の詳細はマニュアル参照。
表の挿入
satysfi-easytable を使いましょう。
テキストの装飾・書体変更
書体の変更
見出し等の書体設定はクラスファイルに依存するところが大きいのが現状です。
公式の API が提供されているものもあれば、クラスファイル本体をいじらなければ書体が変更できないものもあります。このあたりの事情は上記のクラスファイルの選択時に考慮しておくとよいでしょう。
本文の書体を変更する際は、自分で変更用のコマンドを定義することもできる他、satysfi-fss パッケージを用いることもできます。
簡素な API でフォントセットやウェイト、サイズなどを変更することができます。
ルビ
satysfi-ruby が便利です。侵入の調節や突出禁止など、様々な機能に対応しています。
参考文献の挿入
BiByFi を使うことができます。
SATySFi パッケージを作成するときのベストプラクティス
リポジトリ構成
インターフェースの設計
実装
-
satysfi-baseパッケージにはふとした処理に役立つ関数がいっぱい入っています。積極的に使いましょう。- とりあえず標準の
listパッケージをbase/list-extに置き換えるだけでも、使える関数がぐっと広がります。
- とりあえず標準の
Satyrographos への登録
Satyrographos に登録しておくと、パッケージがぐっと使いやすくなります。自作パッケージを Satyrographos で配布する手順は以下の記事に記されています。
SATySFi に貢献したいときのベストプラクティス
新しい技術である SATySFi に貢献したい！でも何から手を付ければいいか分からない！しかし実は、様々な方法で SATySFi に貢献することができるのです。
SATySFi を使う
SATySFi を使い、 SATySFi を使ったことをアピールするだけでも一種の貢献です。そのソースコードを公開すれば、さらに貢献です。
コミュニティに参加する
SATySFi のコミュニティに参加し、議論してみましょう。初心者の質問に解答するのもよいかもしれません。
SATySFi のドキュメントを充実させる
SATySFi はまだ新しいツールであり、ドキュメントが多くありません。
ドキュメントを充実させるだけでも非常に大きな貢献となるでしょう。
-
有志の方が learn-satysfi という文書の執筆が行われているものの、人手不足でなかなか中身が埋まらないのが現状です。自分が分かる範囲だけでも埋めてもらえると大変助かります。
-
SATySFi の入門記事や解説記事などを書くのも良いでしょう。アドベントカレンダーに登録しておけば、多くの読者が見込めます。
SATySFi のパッケージを作成する・既存パッケージに Issue/PR を送る
TeX/LaTeX と比較すると、SATySFi にはまだまだパッケージが足りません。様々なライブラリを追加することで、 SATySFi が採用される機会も増えていくでしょう。
また、既存のパッケージに対して機能追加の PR を送ったり、 Issue で問題を報告したりするのも貢献といえます。
SATySFi 本体への機能追加・バグ修正を行う
SATySFi は OSS であり、誰でも機能追加・バグ修正の PR を出すことができます。パッケージの追加や修正だけでは実現できない機能は、本体へのコントリビュートで実現してみましょう。
SATySFi の周辺ツールを充実させる
SATySFi を成り立たせるのは、SATySFi 本体やパッケージだけではありません。
- Satyrographos: パッケージマネージャ
- Satyrographos Package Index: パッケージマネージャの Web UI
- docker-satysfi: SATySFi の docker image
- SATySFi playground: オンライン上で簡単に試せる playground
- SATySFi に関連するテキストエディタの拡張・language server（上述）
これらはほとんど全て、SATySFi 本体の開発者とは別の有志によって開発されています。これらに対する貢献も、SATySFi に対する貢献に他なりません。
投げ銭をして、開発者の夕食のグレードを上げる
何か貢献したいけど技術的なことは分からないよ、という方に。
The SATySFibook は無料でダウンロードできますが、投げ銭版を購入することもできます（300円）。さらに金額を上乗せすることもできます。
投げ銭版も無償版と同一のPDFですが，購入頂けると作者が励みになったり夕食のグレードが上がったりして喜びます．宜しければ是非お願い致します
ということで、よければぜひ開発者である gfngfn さんの夕食のグレードを上げてみてください。
-
一般には、メタ情報やブロックテキストといった情報を受け取って document 型の値を返すような関数がクラスファイルの「根幹」にあたります。それらが定義されているパッケージファイルはクラスファイルと呼ぶことができるでしょう。 ↩︎
Discussion