HWPX 編集
HWPX は XML(HWPML)のZIP です。ファイルを破損させる罠は外からはわかりにくいため、編集前に references/hwpx-guide.md の該当セクションを読み、scripts/ 内のスクリプトを実行して再パッケージ・検証してください — 手作業でZIPを作ったり、目視で正しさを確認したりしないでください。
HWPX 限定。 このスキルは
.hwpx(ZIP + XML)のみ扱います。レガシーな.hwp(OLE バイナリ、シグネチャD0CF11E0)は、まず 한글 で 他の名前で保存 → HWPX(.hwpx) により変換する必要があります。スクリプトは.hwpを検出するとその旨を表示します。
最も重要な唯一のルール
通常のZIPライターでHWPXを再圧縮してはいけません。 한글 は、変更していないエントリが再deflateされたファイルを拒否します。raw-preserving repacker(scripts/hwpxlib.py:repack_preserve)を使用してください:これは変更していない各エントリをバイトコピーし、変更したエントリだけを再deflateするため、何も変更しない再パッケージは元のファイルとバイト単位で同一になります。つまり、「元のファイルが한글で開ければ、あなたの編集後ファイルも開ける」ということです。
ワークフロー
- まず調査する。
python scripts/inspect_hwpx.py FILE.hwpx --breaks— セクションごとのカウント(段落、表、pic、equation、フィールド)と、特にどの段落に隠れたpageBreak/columnBreakがあるかが表示されます。見出しが本文から分離されている場合や、ページ/カラムが空白の場合は、まずそれらの改行を探し(§6-A)、keepWithNextに頼らないでください。本文段落の改行は通常、残存するクルク(ごみ)です。 - 対応するガイドのセクションを
references/hwpx-guide.mdで読む(対応表は下記)。XMLのID/参照(charPrIDRef、paraPrIDRef、borderFillIDRef、…)はファイルごとに異なります — 常に実際のファイルから読み取り、推測しないでください。 - lxml でXMLを編集し、以下の不変条件に従う:
- 段落の編集または作成後、その
<hp:linesegarray>を削除する(キャッシュされた行レイアウトは古くなり、ゆがんだ字間の原因になります)。構造編集後は、セクション全体の linesegarray を削除し、한글 が完全に再レイアウトするようにします。hwpxlib.strip_linesegarrayを使用。 - ノード(脚注・文末脚注・表・数式・画像)をクローンする場合、元の
id/instIdを継承するため → 重複 → 不安定性が発生します。hwpxlib.make_uidで新しいIDを割り当て(subList>p/tbl/tc/pのIDも含む)。 - 新しい
charPr/paraPr定義を追加する代わりに既存のものを再利用します。どうしても追加する必要がある場合はitemCntを更新しないと、한글 がファイルを拒否します。
- 段落の編集または作成後、その
hwpxlib.repack_preserve(src, changed, out, added)で再パッケージ:changed= 編集したエントリ(XML宣言は先頭に保持)、added= 新しいエントリ(BinData/imageN.pngや新しいsectionN.xmlなど。これらはcontent.hpfにも登録する)。- ビルドごとに検証:
python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx。すべてのハードチェックが成功すること(バイト同一性自己チェック、整形式XML(content.hpfを含む)、重複IDゼロ、ZIP整合性 + mimetype が先頭/STORED)。また 最小変更diff を表示するので、意図した変更のみが行われたことを確認できます。 - 한글 で往復確認。LibreOffice は HWPX をレンダリングできないため、レンダリングに依存する判断(見出しの孤立、字間の見た目など)は、ユーザーが 한글 でファイルを開き、数式や目次の場合は 도구 → 차례 새로 고침 を実行するか、ダブルクリック→閉じる、で確定する必要があります。その旨を伝えてください。
スクリプト(scripts/)— これらを実行し、再発明しないでください
| スクリプト | 目的 |
|---|---|
hwpxlib.py | ライブラリ: repack_preserve、own(実体本文のみ、脚注・文末脚注・メモを除外)、make_uid、strip_linesegarray、find_duplicate_ids、structural_counts、および§7検証ヘルパー。import して使用。 |
inspect_hwpx.py FILE [--text] [--breaks] | 構造ダンプ;隠れたページ/カラム改行を発見。 |
verify.py EDITED [--orig ORIG] | 完全な§7チェックリストを実行;失敗時は非ゼロ終了コード(CIゲート可能)。 |
selftest.py | 実際のファイルを使わずにリパッカーがロスレスであることを証明。 |
tables_to_xlsx.py FILE [OUT] | 表をExcel(.xlsx)にエクスポート、結合セルを保持(openpyxl が必要)。画像/数式のみのセルは [그림]/[수식] に;レガシー .hwp はガイダンスとともに拒否。 |
スクリプトには lxml(pip install lxml)が必要;表→Excelエクスポートには openpyxl も必要。Python 3.10+。
ガイドで読む場所(references/hwpx-guide.md)
必要なセクションのみを読み込んでください — ガイドは 「흔한 실패 TOP」(よくある失敗トップ) から始まります;まずそれをざっと読み、その後以下にジャンプ:
- §1 構造とパース — 名前空間、
own()、「全セクションをチェック」、セル単位の表テキスト(一括itertextではない)。 - §2 リパック(raw-preserving) — 王冠の宝石のリパッカー。
hwpxlibと対応。 - §3 共通ルール —
linesegarray削除、クローン後のID重複除去。 - §4 コンテンツ編集 — 段落、表(セル幅の合計が表幅と一致しないと 한글 が拒否;結合)、画像(
orgSz=px×75、サイズ計算、コンテンツで検証(抽出順序ではない)、matplotlibの可読性「小さい図、大きい文字」)、書式、文末脚注・脚注(<hp:ctrl>ラッピング必須)、メモ、および誤植監査の範囲(総当たり正規表現は禁止)。 - §5 カラム・目次・数式 —
colPr、TABLEOFCONTENTS(アウトラインレベル段落から)、한컴 数式スクリプト(LaTeX ではなく;フォーム一覧付き)。 - §6 ページ/カラム管理 — まず隠れた改行、孤立見出し防止(
keepWithNext、見出し後の空段落禁止、条件付きcolumnBreak)、白紙ページ削除、幅広の表 → 1カラム領域、secPrブロックのセクション境界を越えた移動。 - §7 検証チェックリスト —
verify.pyが自動化する内容と、往復確認の注意点。
ガードレール
- このスキルはドキュメントの編集のみを行います。ユーザーの認証情報を必要とせず、リモートコンテンツを取得・実行しません。コピーで作業し、オリジナルは保持してください。
- 作成者のコンテンツを保護:ユーザーが依頼したものだけを変更すること。
verify.pyの最小変更diffがその証明です。