docx

DOCX の作成、編集、分析

概要

ユーザーから .docx ファイルの内容の作成、編集、または分析を依頼されることがあります。.docx ファイルは、基本的に読み取りや編集が可能な XML ファイルやその他のリソースを含む ZIP アーカイブです。タスクに応じて、さまざまなツールとワークフローを利用できます。

ワークフローの判断ツリー

コンテンツの読み取り/分析

以下の「テキスト抽出」または「生の XML アクセス」セクションを使用してください

新規ドキュメントの作成

「新しい Word ドキュメントの作成」ワークフローを使用してください

既存ドキュメントの編集

• 自分のドキュメント + 簡単な変更 「基本的な OOXML 編集」ワークフローを使用してください

• 他人のドキュメント 「赤字化（リダクショントラッキング）ワークフロー」（推奨されるデフォルト）を使用してください

• 法律、学術、ビジネス、または政府関連のドキュメント 「赤字化（リダクショントラッキング）ワークフロー」（必須）を使用してください

コンテンツの読み取りと分析

テキスト抽出

ドキュメントのテキスト内容を読むだけであれば、pandoc を使用してドキュメントを Markdown に変換してください。Pandoc はドキュメント構造の保持に優れており、変更履歴の追跡も表示できます:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

生の XML アクセス

コメント、複雑な書式、ドキュメント構造、埋め込みメディア、メタデータを扱う場合は、生の XML アクセスが必要です。これらの機能を扱うには、ドキュメントを展開し、生の XML の内容を読み取る必要があります。

ファイルの展開

python ooxml/scripts/unpack.py <office_file> <output_directory>

主要なファイル構造

• word/document.xml - ドキュメントの main 内容
• word/comments.xml - document.xml で参照されるコメント
• word/media/ - 埋め込み画像およびメディアファイル
• 変更履歴は <w:ins>（挿入）と <w:del>（削除）タグを使用します

新しい Word ドキュメントの作成

Word ドキュメントをゼロから作成する場合は、JavaScript/TypeScript で Word ドキュメントを作成できる docx-js を使用してください。

ワークフロー

1. 必須 - ファイル全体を読む: docx-js.md（約 500 行）を最初から最後まで完全に読んでください。このファイルの読み取りに範囲制限を設定しないでください。 ドキュメント作成に進む前に、詳細な構文、重要な書式設定ルール、ベストプラクティスについてファイルの全内容を読んでください。
2. Document、Paragraph、TextRun コンポーネントを使用して JavaScript/TypeScript ファイルを作成してください（依存関係はすべてインストール済みと想定して構いませんが、インストールされていない場合は下記の依存関係セクションを参照してください）
3. Packer.toBuffer() を使用して .docx としてエクスポートしてください

既存の Word ドキュメントの編集

既存の Word ドキュメントを編集する場合は、Document ライブラリ（OOXML 操作用の Python ライブラリ）を使用してください。このライブラリはインフラのセットアップを自動的に処理し、ドキュメント操作のためのメソッドを提供します。複雑なケースでは、ライブラリを通じて基盤の DOM に直接アクセスできます。

ワークフロー

1. 必須 - ファイル全体を読む: ooxml.md（約 600 行）を最初から最後まで完全に読んでください。このファイルの読み取りに範囲制限を設定しないでください。 Document ライブラリの API と、ドキュメントファイルを直接編集するための XML パターンについてファイルの全内容を読んでください。
2. ドキュメントを展開してください: python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Document ライブラリを使用する Python スクリプトを作成して実行してください（ooxml.md の「Document Library」セクションを参照）
4. 最終的なドキュメントをパックしてください: python ooxml/scripts/pack.py <input_directory> <office_file>

Document ライブラリは、一般的な操作向けの高レベルメソッドと、複雑なケース向けの DOM への直接アクセスの両方を提供します。

ドキュメントレビューのための赤字編集ワークフロー

このワークフローでは、OOXML に実装する前に、Markdown を使って変更履歴の付いた包括的な変更を計画できます。重要: 変更履歴を完全なものにするには、すべての変更を体系的に実装する必要があります。

バッチ処理の戦略: 関連する変更を 3〜10 件のバッチにまとめます。こうすることで、効率を保ちつつデバッグを管理しやすくなります。次のバッチに進む前に、各バッチをテストしてください。

原則: 最小限かつ正確な編集 変更履歴を実装する際は、実際に変更されるテキストのみをマークしてください。変更のないテキストを繰り返すと、編集内容のレビューが難しくなり、不適切に見えます。置換は [変更のないテキスト] + [削除] + [挿入] + [変更のないテキスト] に分割してください。変更のないテキストについては、元の <w:r> 要素を抽出して再利用することで、元の run の RSID を維持してください。

例 - 文中の「30 days」を「60 days」に変更する場合:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

変更履歴のワークフロー

1. Markdown 表現を取得する: 変更履歴を保持したまま、ドキュメントを Markdown に変換します:

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. 変更を特定してグループ化する: ドキュメントを確認し、必要なすべての変更を特定して、論理的なバッチにまとめます:

   位置の特定方法（XML 内で変更箇所を見つけるため）:

   • セクションや見出しの番号（例: 「セクション 3.2」「第 IV 条」）
   • 番号が付いている場合は段落の識別子
   • 前後の一意なテキストを使った grep パターン
   • ドキュメントの構造（例: 「最初の段落」「署名欄」）
   • Markdown の行番号は使用しないでください。XML の構造には対応していません

   バッチの構成（関連する変更を 1 バッチあたり 3〜10 件にまとめます）:

   • セクションごと: 「バッチ 1: セクション 2 の改訂」「バッチ 2: セクション 5 の更新」
   • 種類ごと: 「バッチ 1: 日付の修正」「バッチ 2: 当事者名の変更」
   • 複雑さごと: 単純なテキスト置換から始め、その後で複雑な構造の変更に取り組みます
   • 順番どおり: 「バッチ 1: 1〜3 ページ」「バッチ 2: 4〜6 ページ」

3. ドキュメントを読み、展開する:

   • 必須 - ファイル全体を読むこと: ooxml.md（約 600 行）を先頭から最後まで完全に読んでください。このファイルを読む際、範囲の制限は一切設けないでください。特に「Document Library」と「Tracked Change Patterns」のセクションに注意してください。
   • ドキュメントを展開する: python ooxml/scripts/unpack.py <file.docx> <dir>
   • 推奨 RSID を控える: 展開スクリプトは、変更履歴に使用する RSID を提案します。この RSID をコピーして、手順 4b で使用してください。

4. バッチ単位で変更を実装する: 関連する変更を論理的にグループ化し（セクション、種類、または位置の近さによる）、1 つのスクリプトにまとめて実装します。この方法には次の利点があります:

   • デバッグが容易になります（バッチが小さいほど、エラーの切り分けがしやすくなります）
   • 段階的に進められます
   • 効率を保てます（バッチサイズ 3〜10 件が適しています）

   バッチのグループ化の例:

   • ドキュメントのセクションごと（例: 「セクション 3 の変更」「定義」「解約条項」）
   • 変更の種類ごと（例: 「日付の変更」「当事者名の更新」「法律用語の置換」）
   • 位置の近さごと（例: 「1〜3 ページの変更」「ドキュメント前半の変更」）

   関連する変更の各バッチについて、次の作業を行います:

   a. テキストを XML に対応づける: word/document.xml を grep して、テキストが <w:r> 要素にどのように分割されているかを確認します。

   b. スクリプトを作成して実行する: get_node でノードを検索し、変更を実装してから doc.save() を呼び出します。パターンについては ooxml.md の 「Document Library」 セクションを参照してください。

   注意: スクリプトを書く直前には必ず word/document.xml を grep し、現在の行番号を取得してテキスト内容を確認してください。スクリプトを実行するたびに行番号は変わります。

5. ドキュメントをパックする: すべてのバッチが完了したら、展開したディレクトリを .docx に戻します:

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. 最終確認: ドキュメント全体を包括的に確認します:

   • 最終ドキュメントを Markdown に変換します:

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • すべての変更が正しく適用されたことを確認します:

     grep "original phrase" verification.md  # 見つからないはず
     grep "replacement phrase" verification.md  # 見つかるはず
     

   • 意図しない変更が入り込んでいないことを確認します

ドキュメントを画像に変換する

Word ドキュメントを視覚的に分析するため、次の 2 段階の手順で画像に変換します:

1. DOCX を PDF に変換する:

   soffice --headless --convert-to pdf document.docx
   

2. PDF のページを JPEG 画像に変換する:

   pdftoppm -jpeg -r 150 document.pdf page
   

   これにより page-1.jpg、page-2.jpg などのファイルが作成されます。

オプション:

• -r 150: 解像度を 150 DPI に設定します（画質とサイズのバランスに応じて調整してください）
• -jpeg: JPEG 形式で出力します（PNG を希望する場合は -png を使用してください）
• -f N: 変換を開始するページ（例: -f 2 は 2 ページ目から開始します）
• -l N: 変換を終了するページ（例: -l 5 は 5 ページ目で停止します）
• page: 出力ファイルの接頭辞

特定の範囲を指定する例:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

コードスタイルガイドライン

重要: DOCX 操作のコードを生成する場合:

• コードは簡潔に書いてください
• 冗長な変数名や無駄な処理は避けてください
• 不要な print 文は避けてください

依存関係

必要な依存関係（利用できない場合はインストールしてください）:

• pandoc: sudo apt-get install pandoc（テキスト抽出用）
• docx: npm install -g docx（新規ドキュメント作成用）
• LibreOffice: sudo apt-get install libreoffice（PDF 変換用）
• Poppler: sudo apt-get install poppler-utils（PDF を画像に変換する pdftoppm 用）
• defusedxml: pip install defusedxml（安全な XML パース用）