hwpx-editing

HWPX Editing

HWPX is a zip of XML (HWPML). The traps that corrupt a file aren't obvious from the outside, so read the relevant section of references/hwpx-guide.md before editing, and run the scripts in scripts/ to repack and verify — don't hand-roll the zip or eyeball correctness.

HWPX only. This handles .hwpx (zip + XML) exclusively. A legacy .hwp (OLE binary, signature D0CF11E0) must be converted first. The scripts detect .hwp and say so. For one file, 한글의 다른 이름으로 저장 → HWPX; for a folder, scripts/hwp_to_hwpx.py FOLDER converts in batch (needs Windows + 한글 + pywin32), including password-protected files — see "Legacy .hwp" below. Read-only text/image extraction from .hwp doesn't need conversion at all: use the hwp5-reading skill.

The one rule that matters most

Never re-zip an HWPX with a normal zip writer. 한글 rejects a file whose unchanged entries were re-deflated. Use the raw-preserving repacker (scripts/hwpxlib.py:repack_preserve): it byte-copies every entry you didn't touch and re-deflates only what you changed, so a no-op repack is byte-identical to the source — meaning "if the original opens in 한글, your edit opens too."

Workflow

1. Inspect first. python scripts/inspect_hwpx.py FILE.hwpx --breaks — see per-section counts (paragraphs, tables, pic, equation, fields) and, crucially, which paragraphs carry a hidden pageBreak/columnBreak. If a heading is split from its content or a page/column is blank, hunt those breaks first (§6-A) — don't reach for keepWithNext. Body-paragraph breaks are usually leftover cruft. ⛔ Breaks live in two places: the paragraph's pageBreak attribute and its paraPr's <hh:breakSetting pageBreakBefore="1"> in header.xml — --breaks lists both. A paraPr that a docx→hwpx conversion created can carry pageBreakBefore; if your build clones that paraPr for a new style, every paragraph using the clone starts a new page. When cloning a paraPr, set pageBreakBefore="0" and put page breaks on paragraphs only. (2026-10-12 T4: an upstream docx builder began writing pageBreakBefore; the cloned caption style made each table its own page and pushed every figure caption off its figure, 20→23 pages. Four blind fixes — line spacing, keepWithNext, per-figure breaks, a docx-side skip — were tried before header.xml was read. Layout regressed after an upstream change → diff that change and read the actual paraPr/breakSetting first; don't trial-fix.)
2. Read the matching guide section in references/hwpx-guide.md (map below). The XML ids/refs (charPrIDRef, paraPrIDRef, borderFillIDRef, …) differ per file — always read them from the actual file, never assume.
3. Edit the XML with lxml, following the invariants:
   • After editing or creating any paragraph, remove its <hp:linesegarray> (cached line layout goes stale → broken spacing). After structural edits, strip linesegarray from the whole section so 한글 fully re-lays-out. Use hwpxlib.strip_linesegarray.
   • When you clone a node (endnote, table, equation, image), it inherits the original's id/instId → duplicates → instability. Reassign fresh ids with hwpxlib.make_uid, including nested subList>p / tbl/tc/p ids.
   • Reuse existing charPr/paraPr definitions instead of adding new ones; if you must add, update the itemCnt or 한글 rejects the file.
4. Repack with hwpxlib.repack_preserve(src, changed, out, added): changed = edited entries (keep the XML declaration on top), added = new entries like BinData/imageN.png or a new sectionN.xml (also register these in content.hpf).
5. Verify every build: python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx. All hard checks must pass (byte-identity self-check, well-formed XML incl. content.hpf, zero duplicate ids, IDRef/itemCnt integrity, table cell widths, no 각주/미주 nested inside another 주석, zip integrity + mimetype first/STORED). It also prints a minimal-change diff so you can confirm only intended changes are present.
6. Render, then look — python scripts/audit_layout.py FILE.hwpx. Steps 1–5 all pass on defects that only a render shows: a number broken across two lines because its column got one character wider, a table footnote stranded alone on the next page, a table-of-contents number that no longer matches. Any change to a table's values, widths, or footnote length needs this step — the earlier checks cannot see layout.
7. Round-trip in 한글. LibreOffice can't render HWPX, so render-dependent judgments (which heading orphans, whether spacing looks right) need the user to open the file in 한글 and, for equations/TOC, run 도구→차례 새로 고침 or double-click→close to finalize. Say so.