ドキュメント変換 CLI リファレンス

コマンド一覧

まずこの表からタスクに合ったコマンドを選びます。すべてのコマンドは機械可読な出力のための --json に対応しています。

インストールとコマンドの形式

gordon-doc コマンドはパッケージと一緒にインストールされます。gordon-doc --help または gordon-doc <command> --help で、インストール済みバージョンが受け付けるオプション値を確認できます。既定では人間向けの簡潔な結果を表示します。出力を他のプログラムが処理する場合は --json を付けてください。

python -m pip install gordon-doc-converter
gordon-doc version
gordon-doc convert --help

診断とバージョン

本番実行の前に doctor を使ってください。検出したプラットフォーム、対話的セッションかどうか、各 renderer の利用可否を報告します。engines は renderer の機能だけを一覧し、全体の健全性は判定しません。version はインストール済みパッケージのバージョンを返します。利用可能なエンジンがない場合、doctor は exit code 3 で終了します。

gordon-doc doctor
gordon-doc engines --json
gordon-doc version --json

単一ドキュメントの変換

convert は DOCX、ODT、PDF、HTML、Markdown の入力を受け付けます。--to を指定しない場合、DOCX、ODT、HTML、Markdown は PDF を生成します。PDF 入力では常に --to が必要です。ODT と HTML はセマンティック抽出により Markdown、HTML、YAML、JSON へも変換でき、エンジンは不要です。ODT のページ画像は先に LibreOffice で組版します。--to を繰り返すと複数の artifact を要求できます。--output は単一ファイルの artifact に適しています。省略した場合、サービスはソースと同じ場所に安全な出力名を導出し、--overwrite がない限り既存ファイルを置き換えません。DOCX から HTML では、--engine word-com が Windows 上の Word COM で組版します。省略するか --mode server を使うとセマンティック抽出になります。

gordon-doc convert report.docx --output report.pdf
gordon-doc convert report.docx --to markdown --to html --to yaml --to json
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.pdf --to yaml --to json
gordon-doc convert report.html --to markdown --to yaml --to json
gordon-doc convert report.odt --to docx --engine libreoffice
gordon-doc convert report.odt --to markdown --to yaml --to json
gordon-doc convert report.pdf --to images --dpi 144

変換ポリシーと出力オプション

--engine word-com、libreoffice、gotenberg は、その DOCX から PDF エンジンの使用を要求します。明示指定した場合はフォールバックしません。DOCX から HTML では、--engine word-com が Word COM で組版し、省略または --mode server ではセマンティック抽出になります。--mode は自動ポリシーを選びます：desktop、server、container、strict-word、strict-libreoffice。変更履歴は --revisions final、original、markup、コメントは --comments omit、appendix、markup で指定しますが、いずれもエンジンの対応状況に依存します。--timeout の単位は秒です。HTML と Markdown では --orientation portrait または landscape で A4 レイアウトを選べます。--gotenberg-url はこの呼び出しで使う Gotenberg の base URL を指定します。

gordon-doc convert contract.docx --engine word-com --revisions final --comments appendix
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.html --to pdf --orientation landscape
gordon-doc convert report.docx --mode server --gotenberg-url http://renderer:3000

構造化 YAML および JSON Artifact

--to yaml と --to json は、同じバージョン付きセマンティックドキュメントをシリアライズします。DOCX、PDF、HTML のいずれのソースからも生成できます。Schema 1.3 は Markdown に近い見出し、段落、リスト、表のテキストを保ちながら、意味のあるリンク、画像、変更履歴、注釈、ソース順序、metadata、逆引き locator を保持します。--to を繰り返せば、抽出は 1 回で両方の形式を書き出せます。--metadata は none、basic、layout を受け付けます。データのない任意の値は null ではなく省略されます。--json-lines は JSON artifact を <stem>.json ではなく <stem>.jsonl へ改行区切りのレコードとして書き出します。最初に document レコード、続いてソース順のすべての block、最後に asset、annotation、warning のレコードが並び、各 block は section_path を持つため行ストリームでも見出し階層を復元できます。DOCX、PDF、HTML のソースに適用され、Markdown、HTML、YAML の出力は変わりません。--to json はドキュメント artifact を書き出し、これとは別の --json フラグは CLI の結果契約を stdout に書き出します。

gordon-doc convert report.docx --to yaml --to json --metadata basic
gordon-doc convert report.pdf --to yaml --to json --metadata layout
gordon-doc convert report.html --to yaml --to json --metadata basic
gordon-doc convert report.docx --to json --json-lines
gordon-doc convert report.docx --to json --json

逆引き位置指定とソース検証

構造化 artifact は source.sha256 で入力ファイルを厳密に特定し、正規化された各 block や表セルを source_anchor.content_sha256 で検証します。DOCX の anchor は OOXML の part と element path を使い、Word が提供する場合はネイティブの段落 ID も含みます。表セルでは path に行と列のインデックスが追加されます。PDF の anchor は 1 起点の物理ページを使います。PDF のページ内座標は現時点では提供されておらず、将来の layout provider で追加できます。ファイルオフセットは安定した locator ではありません。DOCX の再圧縮や PDF の最適化・増分保存は、表示される内容を変えずにオフセットを変えてしまいます。

変換の進捗表示

convert と batch は、対話的なターミナルで自動的に段階別の進捗を表示します。進捗は stderr にのみ出力されるため、リダイレクトした stdout や機械可読な結果は汚れません。--json は自動進捗を無効にします。--progress で強制表示、--no-progress で抑制できます。バッチの進捗は、根拠のない時間の百分率ではなく、完了ファイル数と総ファイル数を報告します。

gordon-doc convert report.docx --to yaml --progress
gordon-doc convert report.docx --to json --no-progress
gordon-doc batch one.docx two.docx --output-dir converted --progress

ページ画像と HTML テンプレート

--to images は PDF ソース、または DOCX から生成した PDF をラスタライズします。--dpi は 1 から 600、--image-format は png または jpeg、--quality は JPEG に適用されます。--page を 1 起点のページ番号で繰り返すとページを選択でき、--background は画像の背景色を設定します。画像出力は <stem>.pages という名前のディレクトリで、連番のファイルを含みます。template は編集可能な A4 HTML の出発点を書き出し、--overwrite がない限り既存ファイルを保護します。

gordon-doc convert report.pdf --to images --image-format jpeg --quality 85 --page 1 --page 3
gordon-doc template report.html --orientation landscape

PDF の比較とバッチ変換

compare は PDF の構造、フォント、サイズ、レンダリング後のピクセルを調べます。--diff-dir を設定すると差異のあるページを PNG で保存でき、--dpi で比較時のラスター解像度を制御します。batch は 1 つ以上の DOCX を順番に変換し、各ファイルの失敗を隔離します。出力は常に PDF です。--output-dir は生成した各 PDF を指定ディレクトリに保存します。いずれかの項目が失敗すると batch の exit code は非ゼロになり、--json は CI レポート用にすべての項目の結果を保持します。

gordon-doc compare expected.pdf actual.pdf --diff-dir differences --json
gordon-doc batch one.docx two.docx --output-dir converted --mode server --json

JSON 結果と Exit Code

すべてのコマンドが --json を受け付けます。変換成功時の payload には、選択されたエンジンと試行したエンジン、artifact のパスと metadata、所要時間、実際に適用された注釈モード、warning、フォールバック情報が含まれます。失敗時には安定した error code、安全なメッセージ、判明していればエンジン名、retryable フラグが含まれます。exit code 0 は成功、2 は入力が無効または出力が既に存在、3 はエンジンや機能が利用不可、4 は変換の失敗・タイムアウト・出力なし、5 は PDF 検証の失敗を表します。

gordon-doc convert report.docx --json
# PowerShell: stop a script if conversion fails
gordon-doc convert report.docx --output report.pdf
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }