# ドキュメントエンジンを選ぶ

LaTeX、Typst、Markdown、Quarto、Calepin の文書がどのように PDF になるかを理解し、プロジェクトに必要なコンパイラを選びます。

エンジンは、ソースを読者が目にする文書に変換します。文書の言語は、プロジェクトを作成するときに選びます。LaTeX プロジェクトでは、ビルドを実行する LaTeX コンパイラも選べます。

## 言語を選ぶ

| 作業内容 | 始めるなら | PDF になる流れ |
|---|---|---|
| 論文誌への投稿、定着した学位論文クラス、既存の `.tex` プロジェクト | LaTeX | Tectonic、または `latexmk` 経由で実行するコンパイラ |
| 簡潔な組版の構文で書く新しい論文、レポート、履歴書 | Typst | 組み込みの Typst 0.15.1、またはプロジェクトが固定した別のバージョンの Typst |
| 文章の草稿、メモ、複数の形式に書き出したい文書 | Markdown | Pandoc がソースを LaTeX に変換し、Tectonic が PDF を生成 |
| R、Python、Julia のコードが結果を生み出す分析レポート、論文、スライド | Quarto | Quarto が `.qmd` または `.Rmd` のファイルを PDF、ウェブページ、スライドにレンダリング |
| コードチャンクを含む Typst の文書 | Calepin | Calepin がコードを実行し、組み込みの Typst が PDF をビルド |

この選択で、エディタのツールバー、ソースの構文、使える書き出し形式が決まります。LaTeX コンパイラを変えても、文書が Typst や Markdown に変換されるわけではありません。LaTeX プロジェクトを Typst に移すには、[新しい Typst プロジェクトに変換](/docs/typst/#convert-a-latex-project-to-typst)します。

## Tectonic

手軽な LaTeX 環境には **Tectonic** を使います。Oleafly に同梱されており、ビルドに必要な TeX パッケージをダウンロードして、次回以降のビルド用にキャッシュします。テンプレートが特定のコンパイラを求めていないなら、まずはこれで始めてください。

出張の前などに、オンラインのうちに一度コンパイルしておきます。キャッシュ済みのプロジェクトはオフラインでもコンパイルできますが、新しいパッケージはダウンロードが必要になる場合があります。 **設定 → 一般 → オフラインモード** を有効にすると、Tectonic はキャッシュを使うようになります。

## pdfLaTeX

出版社や既存のプロジェクトが指定している場合は **pdfLaTeX** を選びます。従来の LaTeX のワークフローに沿っており、古いクラスやパッケージの組み合わせによく合います。`latexmk` が入った TeX ディストリビューションが必要です。

## XeLaTeX

**XeLaTeX** を求めるプロジェクト、特に `fontspec`、OpenType フォント、多言語の文章を使うプロジェクトで選びます。ソースで指定したフォントが、インストールされているか、プロジェクトに含まれていることを確認してください。こちらも `latexmk` 経由で実行されます。

## LuaLaTeX

それを求めるテンプレート、Lua ベースの組版、または Oleafly のタグ付き PDF のワークフローには **LuaLaTeX** を選びます。タグ付き PDF は、支援技術が利用できる文書構造を持っています。結果は[プリフライトのチェック](/docs/preflight/)で確認してください。コンパイラを選んだだけで、タグの品質が保証されるわけではありません。

## Typst

Oleafly には Typst 0.15.1 が同梱されています。Typst プロジェクトを作成し、`.typ` ファイルに書いて **再コンパイル** をクリックします。TeX のインストールは要りません。

**設定 → エンジン → Typst** では、Typst 0.11 から 0.15 までのインストールや、コンピュータにすでにある Typst の利用もできます。各プロジェクトが自分のバージョンを固定するため、Oleafly が新しい Typst に移っても、論文のレイアウトは変わりません。Typst は、文書が初めてパッケージをインポートしたときに Typst Universe からダウンロードします。 **オフラインモード** では、キャッシュ済みのパッケージか、プロジェクトに入っているパッケージだけに限られます。

Typst には独自の構文、パッケージ、フォントの扱いがあります。バージョン、パッケージ、フォント、ビルドのバリアントは [Typst プロジェクト](/docs/typst/)で説明しています。[Typst の執筆ガイド](/docs/writing/typst/)には、出発点になる完全な文書とツールバーの操作があります。

## Markdown

Markdown では **Pandoc** が組版用の文書を準備し、Tectonic が PDF をビルドします。Pandoc がない場合は **設定 → エンジン → Markdown** を開いてインストールします。そのあと Markdown プロジェクトを開いてコンパイルします。

見出し、リスト、数式、ビジュアルエディタについては、[Markdown の執筆](/docs/writing/markdown/)を参照してください。プロジェクトで使える出力形式は、[書き出しガイド](/docs/export/)で説明しています。

## Quarto

Quarto は、`.qmd` と `.Rmd` の文書を PDF、ウェブページ、スライドに変換します。お使いのコンピュータに Quarto があれば、Oleafly はそれを使います。ない場合は **設定 → エンジン → Quarto** を開き、 **Quarto 1.10.19 をダウンロード** を選びます。ボタンにはダウンロードのサイズも表示されます。Oleafly は、ダウンロードしたものを展開する前に確認し、そのコピーを自分のアプリのフォルダに保存します。Quarto がない状態でコンパイルすると、プレビューに、その場でインストールするか **エンジンの設定を開く** かの選択肢が表示されます。

文書が最初に宣言している形式で、何ができるかが決まります。

- `pdf`、`typst`、`beamer` は PDF をビルドします。`format: typst` には TeX のインストールは要りません。`pdf` と `beamer` は LaTeX を通るので、まだ TeX がない場合は **設定 → エンジン → LaTeX** から TinyTeX をインストールしてください。
- `html`、`revealjs`、`dashboard` はウェブページをビルドします。見るには、プレビューで **ブラウザで開く** を選びます。

文書が形式を宣言していない場合、Oleafly は、文書のフォルダと、そこからプロジェクトのルートまでの上位のフォルダにある `_quarto.yml` または `_metadata.yml` から形式を探します。どこにも形式がなければ、Quarto はウェブページをビルドします。`pdf_document` など、R Markdown の `output:` を指定している `.Rmd` ファイルには、対応する Quarto の形式が使われます。

コードは、お使いのコンピュータにすでにある R、Python、Julia で実行されます。Oleafly がそれらをインストールすることはなく、同じ設定タブの **言語** に、見つかったものが表示されます。Python のコードには、その Python に Jupyter も必要です。書き出しでは DOCX と HTML を選べ、どちらも Quarto がレンダリングします。 **新規プロジェクト** ダイアログには Quarto のテンプレートが 2 つあります。Typst を通して PDF をビルドする **Quarto article** と、reveal.js のスライドである **Quarto slides** です。

## Calepin

Calepin は、Typst の文書内のコードを実行し、その結果を PDF に入れます。Calepin の文書は、`/.calepin/calepin.typ` をインポートする `.typ` ファイルです。 **Calepin report** テンプレートから始めるか、Typst プロジェクトで **再コンパイル** の横の矢印を開き、 **エンジン（このプロジェクト）** の下で **Calepin** を選びます。

インストールは Quarto と同じく、 **設定 → エンジン → Calepin** から **Calepin 0.0.61 をダウンロード** で行います。Calepin は、Oleafly に付属する Typst でビルドします。言語がインストールされていないチャンクには短い注記が表示され、文書の残りの部分はそのままビルドされます。書き出しでは HTML を選べ、Calepin がレンダリングします。

## プロジェクトでコードを許可する

Quarto や Calepin の文書内のコードはあなたの権限で実行されるため、許可するまでは、プロジェクトごとにオフになっています。コードが必要なコンパイルのあと、エディタの上のバナーに、コードがオフであることが表示され、 **このプロジェクトでコードを許可** が提示されます。 **再コンパイル** の横の矢印を開き、 **コード（このコンピュータ）** の下で **このコンピュータでコードを実行** を選ぶこともできます。 **オフ** を選ぶと、再びオフになります。コードを許可するのは、プロジェクト内のすべてのファイルを信頼できる場合だけにしてください。

この選択は、このコンピュータにだけ適用されます。プロジェクトには保存されず、プロジェクトのエンジンを変更すると、コードは再びオフになります。[共有プロジェクト](/docs/collaboration/)では、プロジェクトを編集できる人なら誰でもそのコードを変更できるため、Oleafly はもう一度確認します。

コードがオフの間は、次のようになります。

- Quarto は、各チャンクのコードを実行せずに表示します。フィルター、ショートコード、`_extensions`、プリレンダーとポストレンダーのスクリプト、インラインの R コードは、それでもコードを実行するため、それらを使う文書は、コードを許可するまでコンパイルされません。
- Calepin はコードを省略できません。Oleafly は、Calepin が前回の実行時に保存した結果から、通常の Typst で PDF をビルドします。結果がない場合、コンパイルは止まり、コードを許可するよう求めます。

[元の場所で開いた](/docs/library/#folders-opened-in-place)フォルダも、Quarto や Calepin でコンパイルするには、先に信頼する必要があります。どちらのエンジンでも、ソースと PDF の同期は使えません。

## 新規プロジェクトの既定を設定する

**設定 → エンジン → LaTeX** を開いて **既定のコンパイルエンジン** を **Tectonic（組み込み）** か **latexmk（システム TeX）** から選びます。以降に作成する LaTeX プロジェクトは、すべてそのエンジンで始まります。

- **新規プロジェクト** ダイアログから作る白紙のプロジェクトやテンプレート、および研究プロジェクト。
- 読み込んだ ZIP、フォルダ、arXiv の論文、GitHub リポジトリ。
- Word ファイルや PDF など、LaTeX プロジェクトに変換した文書。

エンジンはプロジェクトの `project.json` に書き込まれるため、プロジェクトを開いた共著者も同じ方法でコンパイルします。pdfLaTeX、XeLaTeX、LuaLaTeX を指定している読み込み済みのプロジェクトは、`latexmk` で動くとき、そのコンパイラを保ちます。既存のプロジェクトに保存されたコンパイラは、そのプロジェクト自身の選択のままです。

独自のエンジンを持たない、[元の場所で開いた](/docs/library/#folders-opened-in-place)フォルダは、信頼すると既定に従います。それまでは Tectonic で表示とコンパイルを行います。どちらの場合も、Oleafly がそのフォルダに何かを書き込むことはありません。

Typst の場合は **設定 → エンジン → Typst** を開いて既定のバージョンを選びます。新しい Typst プロジェクトは、作成時点で既定になっているバージョンを固定します。あとから既定を変えても、既存のプロジェクトのバージョンは変わりません。

## 現在のプロジェクトのコンパイラを変える

[プロジェクトツールバー](/docs/project-toolbar/)で **再コンパイル** の横の矢印を開きます。LaTeX プロジェクトでは **コンパイラ（このプロジェクト）** の下から Tectonic、自動、pdfLaTeX、XeLaTeX、LuaLaTeX のいずれかを選び、コンパイルします。選んだインストールにテンプレートが必要とするパッケージやフォントがない場合は、ログを確認してください。

Typst プロジェクトでは、同じメニューに代わりに **Typst のバージョン（このプロジェクト）** があります。インストール済みのバージョンを選ぶか **既定** を選んで設定に従います。このメニューの **エンジン（このプロジェクト）** グループで、文書を **Typst** と **Calepin** の間で切り替えられます。

## 既存の TeX ディストリビューションを検出する

**設定 → エンジン → LaTeX** を開いて、検出されたツールチェーンを確認します。Oleafly は、`latexmk` と補助ツールを含む、完全なコンパイラ環境があるかどうかを調べます。一部だけのシステムインストールが、動作している管理下のインストールより優先されることはありません。

## 管理下の TinyTeX をインストールする

従来型のコンパイラが必要なのに持っていない場合は、LaTeX エンジンの設定にあるインストール用のボタンを使います。Oleafly は専用の TinyTeX を `~/.oleafly/tinytex` 以下にダウンロードします。管理者権限は不要です。最初のダウンロードに約 250 MB、パッケージ用にさらに空き容量を見込んでください。

## パッケージを管理する

LaTeX エンジンの設定にあるパッケージの一覧では、パッケージの絞り込み、説明の確認、追加と削除ができます。タグ付けのバッジは、タグ付き PDF を作るときに注意が必要なパッケージを示します。これらの操作が管理するのは `latexmk` が使う TeX ディストリビューションで、Tectonic のキャッシュは別になっています。

[LaTeX のパッケージとタグ付き PDF のガイドを読む →](/docs/latex-engines/)