以下はPythonプログラム `pandoc.py` の解析結果です。

---

## 1) プログラムの動作

`pandoc.py` は、ドキュメント変換ツールであるPandocの機能をPythonスクリプトから簡単に利用するためのユーティリティです。主に以下の2つの機能を提供します。

1.  **Pandocテンプレートの生成**: Word (docx) または PowerPoint (pptx) 形式のPandocリファレンスドキュメント（テンプレート）を生成します。これにより、ユーザーは生成されたファイルを編集して、変換後のWordやPowerPointドキュメントのスタイル、フォント、レイアウトなどをカスタマイズできます。
2.  **Markdownから他の形式への変換**: MarkdownファイルをWord (docx), PowerPoint (pptx), または HTML 形式に変換します。変換時には、以下のオプションをサポートします。
    *   カスタムテンプレートの適用 (`docx`/`pptx` 変換時)
    *   数式表示のためのMathMLの有効化 (`html` 変換時)
    *   カスタムCSSの適用 (`html` 変換時)
    *   出力ファイル名の指定
    *   目次の自動生成 (`docx` 変換時)
    *   Markdownファイルの先頭にあるYAMLメタデータブロックの扱いを制御

**詳細な動作**:

*   **`find_pandoc()`**: `pandoc` 実行ファイルのパスを検索します。以下の優先順位で探索します。
    1.  環境変数 `pandoc_path` で指定されたパス。
    2.  環境変数 `tkProg_path` に基づく特定のパス（Windowsなら `tkApp_Win/pandoc/pandoc.exe`、Linuxなら `tkApp_Linux/pandoc/pandoc`）。
    3.  システム環境変数 `PATH` から検索。
    いずれの場所でも見つからない場合でも、最終的には `"pandoc"` という文字列を返し、システム `PATH` にある `pandoc` コマンドが実行可能であることを期待して `subprocess` に渡します。
*   **`find_template()`**: `--template` オプションで指定されたテンプレートファイルを以下の順に探します。
    1.  スクリプトを実行したカレントディレクトリ。
    2.  `pandoc.py` スクリプトが存在するディレクトリ。
    どちらでも見つからない場合、ユーザーが指定した元のパスをそのまま返します（Pandocがそのパスでファイルを見つけることを期待します）。
*   **`parse_args()`**: コマンドライン引数を解析し、ユーザーが指定したオプションを取得します。
*   **`make_pandoc_template()`**: `--make_template` オプションが指定された場合、Pandocの `--print-default-data-file` オプションを使用して、デフォルトのdocxまたはpptx参照ドキュメントを生成します。
*   **`convert_with_pandoc()`**: `--convert` オプションが指定された場合、入力Markdownファイルを指定された形式に変換します。
    *   `docx`, `pptx` 変換では `--reference-doc` オプションでテンプレートファイルを適用できます。
    *   `html` 変換では `--mathml` オプションでMathMLを有効にしたり、`--css` オプションでカスタムCSSを適用できます。また、生成されたHTMLファイルは、MathJaxライブラリをCDN経由で読み込むためのスクリプトとHTMLの基本構造でラップされ、数式表示を強化します。
*   **`run_command()`**: 実際の `subprocess.run` を使ってPandocコマンドを実行し、ファイルが見つからない場合やPandocがエラーを返した場合に適切なエラーメッセージを表示します。

## 2) 必要な非標準ライブラリとインストールコマンドとインストール方法

このPythonスクリプト自体は、`os`, `sys`, `argparse`, `pathlib`, `shutil`, `platform`, `subprocess` といった**Pythonの標準ライブラリのみ**を使用しており、追加のPythonライブラリを `pip install` でインストールする必要はありません。

ただし、このスクリプトが機能するためには、**外部ツールである `Pandoc` 本体**がシステムにインストールされている必要があります。

**Pandocのインストール方法**:

Pandocはクロスプラットフォームなツールであり、オペレーティングシステムによってインストール方法が異なります。以下のいずれかの方法でインストールしてください。

*   **Windows**:
    1.  Pandocの公式サイト ([https://pandoc.org/installing.html](https://pandoc.org/installing.html)) から `.msi` インストーラーをダウンロードし、実行します。
    2.  または、[Chocolatey](https://chocolatey.org/) (Windowsパッケージマネージャー) を使用している場合:
        ```bash
        choco install pandoc
        ```
*   **macOS**:
    1.  [Homebrew](https://brew.sh/) (macOSパッケージマネージャー) を使用している場合:
        ```bash
        brew install pandoc
        ```
    2.  または、Pandocの公式サイトから `.pkg` インストーラーをダウンロードし、実行します。
*   **Linux (Debian/Ubuntu)**:
    ```bash
    sudo apt update
    sudo apt install pandoc
    ```
*   **Linux (Fedora/RHEL)**:
    ```bash
    sudo dnf install pandoc
    ```
*   **その他のOS / 公式ガイド**:
    Pandocの公式サイト ([https://pandoc.org/installing.html](https://pandoc.org/installing.html)) に詳細なインストール手順が記載されています。

インストール後、ターミナルやコマンドプロンプトで `pandoc --version` と入力し、バージョン情報が表示されれば正しくインストールされています。

## 3) 必要な入力ファイル

プログラムの動作モードによって、必要な入力ファイルが異なります。

*   **テンプレート生成モード (`--make_template`)**:
    *   特別な入力ファイルは**不要**です。Pandoc自体がデフォルトの参照ドキュメントを生成します。
*   **変換モード (`--convert`)**:
    *   **必須**:
        *   **Markdownファイル**: 変換元のMarkdown形式のファイル。`--infile` オプションでパスを指定します（例: `lecture_textbook.md`, `my_presentation.md`）。
    *   **任意**:
        *   **参照ドキュメント（テンプレート）**: `docx` または `pptx` に変換する場合、スタイリングのために使用するWordまたはPowerPointファイル。`--template` オプションでパスを指定します（例: `template_textbook.docx`, `template_slide.pptx`）。これは通常、事前に `--make_template` で生成し、カスタマイズしたものです。
        *   **カスタムCSSファイル**: `html` に変換する場合、スタイルを適用するためのCSSファイル。`--css` オプションでパスを指定します（例: `custom_style.css`）。

## 4) 実行後に生成される出力ファイル

プログラムの動作モードによって、生成される出力ファイルが異なります。

*   **テンプレート生成モード (`--make_template`)**:
    *   `--template` オプションで指定されたパスに、Pandocのデフォルトの参照ドキュメント（テンプレート）が生成されます。
        *   `docx` テンプレートの場合: `--template my_template.docx` を指定すると `my_template.docx` が生成されます。
        *   `pptx` テンプレートの場合: `--template my_template.pptx` を指定すると `my_template.pptx` が生成されます。
*   **変換モード (`--convert`)**:
    *   `--infile` で指定されたMarkdownファイルが、`--convert` で指定された形式に変換されて出力されます。
    *   **デフォルトの出力ファイル名**: `--infile` のファイル名と同じで、拡張子が変換先の形式になります。
        *   例: `lecture_textbook.md` を `docx` に変換する場合、`lecture_textbook.docx`
        *   例: `my_slide.md` を `pptx` に変換する場合、`my_slide.pptx`
        *   例: `my_document.md` を `html` に変換する場合、`my_document.html`
    *   **カスタム出力ファイル名**: `--outfile` オプションで出力ファイル名を明示的に指定した場合、そのファイル名で出力されます。
        *   例: `--convert docx --infile my_document.md --outfile final_report.docx` を実行すると `final_report.docx` が生成されます。

## 5) コマンドラインでの使用例 (Usage)

### 1. Pandocテンプレートの生成

デフォルトのWordまたはPowerPointの参照ドキュメント（テンプレート）を生成します。
生成されたテンプレートファイルは、`--template` オプションで指定したパスに保存されます。これを編集することで、変換後のWord/PowerPointドキュメントのスタイルをカスタマイズできます。

```bash
# Word (docx) テンプレートの生成
# 'my_custom_template.docx' がカレントディレクトリに生成されます。
python pandoc.py --make_template docx --template my_custom_template.docx

# PowerPoint (pptx) テンプレートの生成
# 'my_custom_template.pptx' がカレントディレクトリに生成されます。
python pandoc.py --make_template pptx --template my_custom_template.pptx
```

### 2. Markdownファイルの変換

MarkdownファイルをWord (docx), PowerPoint (pptx), または HTML 形式に変換します。

```bash
# MarkdownをWord (docx) に変換（カスタムテンプレート使用）
# 'my_document.md' を 'my_document.docx' に変換します。
# 'my_custom_template.docx' を参照ドキュメントとして使用し、スタイルを適用します。
python pandoc.py --convert docx --infile my_document.md --template my_custom_template.docx

# MarkdownをPowerPoint (pptx) に変換（カスタムテンプレート使用）
# 'my_presentation.md' を 'my_presentation.pptx' に変換します。
# 'my_custom_template.pptx' を参照ドキュメントとして使用し、スタイルを適用します。
python pandoc.py --convert pptx --infile my_presentation.md --template my_custom_template.pptx

# MarkdownをHTMLに変換（MathMLで数式表示）
# 'my_document.md' を 'my_document.html' に変換し、数式をMathMLで表示します。
python pandoc.py --convert html --infile my_document.md --mathml

# MarkdownをHTMLに変換（カスタムCSS使用）
# 'my_document.md' を 'my_document.html' に変換し、'custom_style.css' を適用します。
python pandoc.py --convert html --infile my_document.md --css custom_style.css

# MarkdownをHTMLに変換（出力ファイル名を指定）
# 'my_document.md' を 'output.html' に変換します。
python pandoc.py --convert html --infile my_document.md --outfile output.html

# MarkdownをWord (docx) に変換（目次自動生成、YAMLメタデータブロックを通常のコンテンツとして解釈）
# 'my_document.md' を 'my_document.docx' に変換し、目次を生成します。
# '--no-yaml' は、Markdownファイルの先頭にあるYAMLメタデータブロックを、特別なメタデータではなく通常のMarkdownコンテンツとして扱います。
python pandoc.py --convert docx --infile my_document.md --template my_custom_template.docx --toc 1 --no-yaml
```

### 一般的なオプション

*   `--pandoc_path PATH`: Pandoc実行ファイルのパスを明示的に指定します。デフォルトでは自動で検索されます。
*   `--verbose`: Pandocの実行時に詳細な出力を表示します。
*   `--pause 1`: プログラム終了時にEnterキーの入力を求めます（デバッグや確認用）。
*   `--outfile FILENAME`: 出力ファイル名を明示的に指定します。指定しない場合は、入力ファイル名から自動生成されます。