touying-author

Touying Author

Touying を使用した Typst プレゼンテーションの作成ガイドです。明快な構成、再現可能な設定、スライドで安全に使えるパターンを重視します。

クイックスタート

• Touying とテーマをインポートし、#show: <theme>.with(...) でテーマを適用します。
• 設定を一元管理し、スライドのコンテンツは別ファイルから読み込みます。
• 見出しを使ってスライドを作成します。カスタムレイアウトやアニメーションには #slide を使用します。
• 最小限のスライド資料には examples/simple.typ を、テーマの基本形には examples/default.typ を使用します。

examples/simple.typ のスニペット：

#import "@preview/touying:0.6.1": *
#import themes.simple: *

#show: simple-theme.with(
  aspect-ratio: "16-9",
  footer: [Simple slides],
)

ベストプラクティスとコード構成

• #show とすべての config-* 呼び出しを適用する単一のエントリーファイル（例：main.typ）を使用します。
• 複数ファイルで構成するスライド資料では、globals.typ + main.typ + content.typ のパターンに従います。循環参照を避けるため、コンテンツには #include を、グローバル設定には #import を使用します。
• ドキュメントでは、共有設定ファイルに config.typ（docs/start.md を参照）と globals.typ（docs/multi-file.md を参照）の両方が使用されています。名前を1つ選び、プロジェクト内で一貫して使用してください。
• 大規模なスライド資料では、content.typ を sections/ に移動し、main.typ から sections/content.typ（および必要に応じて sections/another-section.typ）を読み込みます。
• set page や場当たり的なグローバル show を直接使用するのではなく、config-page、config-common、config-info、config-colors、config-methods、config-store を優先します。
• ほとんどのスライドには見出しを使用します。どの見出しレベルでスライドを作成するかは、config-common(slide-level: n) で選択します。
• カスタムレイアウトまたはアニメーションに限り #slide を使用し、スライド関数は必ず touying-slide-wrapper でラップします。
• コールバック形式のアニメーション（#slide(repeat: n, self => [...])）では、repeat を明示的に設定し、utils.methods(self) を使って uncover、only、alternatives にアクセスします。

単一ファイル構成

.
├── globals.typ
├── main.typ
└── content.typ

複数ファイル構成

.
├── globals.typ
├── main.typ
└── sections/
    ├── content.typ
    └── another-section.typ

コア API マップ（エクスポート）

• スライド：touying-slides、slide、touying-slide、touying-slide-wrapper、empty-slide
• ダイナミクス：pause、meanwhile、uncover、only、effect、alternatives、alternatives-match、alternatives-fn、alternatives-cases
• 設定：config-common、config-page、config-info、config-colors、config-methods、config-store、default-config、touying-set-config、appendix
• ユーティリティ：utils.*（高さに合わせる、幅に合わせる、カバー用ヘルパー、進捗、見出し用ヘルパー）
• コンポーネント：components.side-by-side、components.adaptive-columns、components.progressive-outline、components.custom-progressive-outline
• インテグレーション：touying-reducer、touying-equation、touying-mitex、speaker-note、pdfpc.*
• リコール：touying-recall、touying-fn-wrapper

スライド構成と見出し

• 見出しラベルを使って、番号付け、アウトライン、ブックマークを制御します。<touying:hidden> を使用し（docs/code-styles.md を参照）、<touying:unnumbered>、<touying:unoutlined>、<touying:unbookmarked>、<touying:skip> については docs/changelog.md を参照してください。
• 目次スライドには components.adaptive-columns(outline(...)) を使用し、進捗に応じたアウトラインには components.progressive-outline を使用します。
• == <touying:hidden> を使うと、空のタイトルスライドを挿入して、直前の見出しコンテキストをクリアできます。
• 見出しを変更せずにスライドを分割するには、#pagebreak() または --- を使用します。
• ヘッダーやフッターのないスライドには #empty-slide[...] を使用します。
• ハンドアウト出力で各スライドの最後のサブスライドだけを残すには、config-common(handout: true) を使用します。
• メインのスライド資料の後に最後のスライド数を固定するには、#show: appendix を使用します。

examples/default.typ のスニペット：

= Outline <touying:hidden>

#components.adaptive-columns(outline(title: none, indent: 1em))

アニメーションと動的コンテンツ

• シンプルな表示には #pause と #meanwhile を使用します。マークがサポートされていない context 内での使用は避けてください。
• レイアウトのスペースを確保するには #uncover を使用し、非表示のときにレイアウトのスペースをなくすには #only を使用します。
• マークによって警告が表示される場合は、repeat と utils.methods(self) を使ったコールバック形式のスライドを使用します。
• 数式のアニメーションでは、$ ... $ 内で pause／meanwhile を使用します。インライン数式テキストにヘルパーが必要な場合は、touying-equation を使用します（#pause または #pause; も使用できます）。
• シンプルなアニメーション、複雑なアニメーション、コールバックアニメーション、数式アニメーションについては、examples/example.typ を参照してください。

examples/simple.typ のスニペット：

== Dynamic slide

Did you know that...

#pause

...you can see the current section at the top of the slide?

examples/example.typ のスニペット：

#slide(
  repeat: 3,
  self => [
    #let (uncover, only, alternatives) = utils.methods(self)

    At subslide #self.subslide, we can

    use #uncover("2-")[`#uncover` function] for reserving space,

    use #only("2-")[`#only` function] for not reserving space,

    #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
  ],
)

レイアウトとテーマ設定

• 視覚的な一貫性を保ってください。新しいレイアウト、図、表、描画には、（別途指示がない限り）ドキュメントで使用されているフォント、色、文字の階層を再利用してください。内部での一貫性も維持してください（同じ関数には同じサイズと色を適用します）。
• 列には #slide 内で composer を使用します。(1fr, 2fr) またはカスタムの grid 関数を渡してください。
• 余白、ヘッダー、フッター、背景には config-page を使用し、set page は直接使用しないでください。
• レイアウトの変更が許容される場合に限り、config-methods(cover: utils.semi-transparent-cover.with(alpha: 85%)) を使用します。
• ヘッダー／フッターやナビゲーション要素にテーマ固有の値を保存するには、config-store を使用します。
• 自動セクションスライドを無効にするには config-common(new-section-slide-fn: none) を使用します。または、カスタム関数を指定して置き換えることもできます。
• グローバルスタイルは、#show: <theme>.with(...) の前後に適用するか、テーマ内で config-methods(init: ...) を使って適用します。
• タイトル、著者、日付には config-info(...) を使用し、日付の書式は config-common(datetime-format: ...) で設定します。

examples/default.typ のスニペット：

#import "@preview/touying:0.6.1": *
#import themes.default: *

#import "@preview/numbly:0.1.0": numbly

#show: default-theme.with(
  aspect-ratio: "16-9",
  config-common(
    slide-level: 3,
    zero-margin-header: false,
  ),
  config-colors(primary: blue),
  config-methods(alert: utils.alert-with-primary-color),
  config-page(
    header: text(gray, utils.display-current-short-heading(level: 2)),
  ),
)

発表者ノートとプレゼンター向けツール

• #speaker-note[...] でノートを追加します。
• config-common(show-notes-on-second-screen: right) または bottom を使うと、2 画面目にノートを表示できます。
• enable-pdfpc: true と typst query --field value --onе "<pdfpc-file>" で pdfpc メタデータをエクスポートします。

同梱のドキュメントとサンプルを使用する

• タスクに必要なドキュメントだけを読み、ドキュメントツリー全体を読み込まないようにしてください。
• 基本事項とインポートのパターンについては、docs/start.md と docs/intro.md を読んでください。
• 複数ファイルのレイアウトと include のパターンについては、docs/multi-file.md を読んでください。
• スライド単位の動作と見出しの動作については、docs/layout.md と docs/sections.md を読んでください。
• シンプルスタイルとブロックスタイル、ページ割りのテクニックについては、docs/code-styles.md を読んでください。
• グローバルスタイルと config-info の使い方については、docs/global-settings.md を読んでください。
• pause、meanwhile、カバーの動作、数式アニメーションについては、docs/dynamic/*.md を読んでください。
• テーマ固有の API とデフォルト設定については、docs/themes/*.md を読んでください。
• pdfpc と Pympress の使い方については、docs/external/*.md を読んでください。
• CeTZ／Fletcher／Theorion／MiTeX との連携については、docs/integration/*.md を読んでください。
• 各テーマの実用的なテンプレートとして examples/*.typ を使用してください。

ファイルツリー（ドキュメントとサンプル）

docs/
├── build-your-own-theme.md
├── changelog.md
├── code-styles.md
├── dynamic
│   ├── complex.md
│   ├── cover.md
│   ├── equation.md
│   ├── handout.md
│   ├── other.md
│   └── simple.md
├── external
│   ├── pdfpc.md
│   ├── pympress.md
│   └── typst-preview.md
├── global-settings.md
├── integration
│   ├── cetz.md
│   ├── codly.md
│   ├── fletcher.md
│   ├── mitex.md
│   ├── pinit.md
│   └── theorion.md
├── intro.md
├── layout.md
├── multi-file.md
├── progress
│   ├── counters.md
│   └── sections.md
├── sections.md
├── start.md
├── themes
│   ├── aqua.md
│   ├── custom.md
│   ├── dewdrop.md
│   ├── metropolis.md
│   ├── simple.md
│   ├── stargazer.md
│   └── university.md
└── utilities
    └── fit-to.md

examples/
├── aqua-zh.typ
├── aqua.typ
├── default.typ
├── dewdrop.typ
├── example.typ
├── metropolis.typ
├── simple.typ
├── stargazer.typ
└── university.typ