# 帳票設計書 2-help

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `help` コマンドが出力するCLIヘルプ情報の設計書です。

### 本帳票の処理概要

`help` コマンドは、Ghosttyの使用方法と利用可能なアクション一覧を標準出力に表示するCLIレポートです。

**業務上の目的・背景**：ユーザーがGhosttyの使い方を理解し、利用可能なコマンドやオプションを確認できるようにするために必要です。初めてGhosttyを使用するユーザーや、コマンドを忘れたユーザーがすぐに情報を得られるようにします。

**帳票の利用シーン**：
- 初めてGhosttyをインストールした際の使い方確認
- 利用可能なアクション（+コマンド）の一覧確認
- コマンドライン引数の形式確認
- macOSでのCLI起動の注意事項確認

**主要な出力内容**：
1. 使用方法（Usage）の説明
2. ターミナルエミュレータの起動方法
3. 設定オプションの指定方法
4. `-e`オプションによるコマンド実行方法
5. macOSでの起動に関する注意事項
6. 利用可能なアクション一覧
7. アクション別ヘルプの参照方法

**帳票の出力タイミング**：`ghostty +help`、`ghostty --help`、または `ghostty -h` コマンド実行時

**帳票の利用者**：エンドユーザー、初心者ユーザー、システム管理者

## 帳票種別

CLIレポート（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +help` | コマンド実行 |
| - | CLI | `ghostty --help` | コマンド実行 |
| - | CLI | `ghostty -h` | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

ヘルプ情報は固定テキストとアクション一覧の2部構成です。

```
┌─────────────────────────────────────┐
│      Usage説明                       │
├─────────────────────────────────────┤
│      詳細説明（固定テキスト）          │
├─────────────────────────────────────┤
│      Available actions一覧           │
├─────────────────────────────────────┤
│      追加ヘルプ案内                   │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Usage | 使用方法 | 固定テキスト | "Usage: ghostty [+action] [options]" |

### 明細部（固定テキスト）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 概要説明 | ターミナルエミュレータまたはアクション実行 | 固定テキスト | テキストブロック |
| 2 | 設定オプション説明 | --key=value形式の説明 | 固定テキスト | テキストブロック |
| 3 | -eオプション説明 | コマンド実行オプション | 固定テキスト | テキストブロック |
| 4 | macOS注意事項 | macOSでのCLI制限 | 固定テキスト | テキストブロック |

### 明細部（アクション一覧）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | アクション名 | 各アクションの名前 | Action enum | "  +{action_name}" |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 追加ヘルプ案内 | アクション別ヘルプの参照方法 | 固定テキスト | テキストブロック |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | 全アクションを無条件で出力 | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | Action enum定義順 | 定義順 |

### 改ページ条件

改ページなし（単一ページ出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| Action enum | アクション一覧 | コンパイル時型情報 |
| 固定テキスト | ヘルプ本文 | ソースコード埋め込み |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | 計算処理なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C[stdoutバッファ初期化]
    C --> D[固定ヘルプテキスト出力]
    D --> E[Action enumをループ]
    E --> F[各アクション名を出力]
    F --> G{全アクション処理完了?}
    G -->|No| F
    G -->|Yes| H[追加ヘルプ案内出力]
    H --> I[バッファフラッシュ]
    I --> J[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（単一レポート） |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

## セキュリティ考慮事項

- 機密情報は含まれない
- 固定テキストとenum定義のみを使用

## 備考

- `--help`は他のアクションと組み合わせ可能（`+list-themes --help`等）
- アクション固有のヘルプはhelp_stringsモジュールから取得

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

アクション一覧の元となるenum定義を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ghostty.zig | `src/cli/ghostty.zig` | Action enumの定義（26-71行目）と全アクション一覧 |

**読解のコツ**: Action enumの各フィールドがそのまま `+action` コマンドになります。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty.zig | `src/cli/ghostty.zig` | detectSpecialCase関数（72-93行目）での--help/-h検出 |
| 2-2 | help.zig | `src/cli/help.zig` | run関数がエントリーポイント（23行目） |

**主要処理フロー**:
1. **23行目**: `pub fn run(alloc: Allocator) !u8` - メイン処理開始
2. **27-31行目**: argsIteratorでオプション解析
3. **33-35行目**: stdoutバッファとwriter初期化
4. **36-63行目**: 固定ヘルプテキストをwriteAll
5. **65-67行目**: Action enumをinlineループしてアクション名出力
6. **69-74行目**: 追加ヘルプ案内出力
7. **75行目**: バッファフラッシュ

#### Step 3: アクション固有ヘルプを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ghostty.zig | `src/cli/ghostty.zig` | help_error処理（100-131行目）でアクション固有ヘルプを出力 |

### プログラム呼び出し階層図

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ help.run (help.zig:23)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  ├─ stdout.writeAll (固定テキスト出力)
                  │
                  ├─ @typeInfo(Action).enum.fields (アクション一覧取得)
                  │      └─ stdout.print (各アクション出力)
                  │
                  └─ stdout.flush (バッファフラッシュ)
```

### データフロー図

```
[入力]               [処理]                    [出力]

コマンド引数 ───▶ help.run()
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
固定テキスト    Action enum      Options解析
(ソース埋め込み)  (コンパイル時)    (引数処理)
    │                 │                 │
    └─────────────────┼─────────────────┘
                      │
                      ▼
                  stdout出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| help.zig | `src/cli/help.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Action enum定義、ディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| help_strings | ビルド時生成 | 生成ファイル | アクション固有ヘルプ文字列 |
