HWPX 편집
HWPX는 XML(HWPML)의 ZIP 압축 파일입니다. 파일이 손상되는 함정은 외부에서 명확히 드러나지 않으므로, 편집 전에 반드시 references/hwpx-guide.md의 해당 섹션을 읽고, scripts/의 스크립트를 실행하여 재압축 및 검증하세요 — 직접 ZIP을 만들거나 눈으로 확인하지 마세요.
HWPX 전용입니다. 이 스킬은
.hwpx(ZIP + XML)만 다룹니다. 레거시.hwp(OLE 바이너리, 시그니처D0CF11E0)는 먼저 한글에서 다른 이름으로 저장 → HWPX(.hwpx) 로 변환해야 합니다. 스크립트가.hwp를 감지하면 안내 메시지를 출력합니다.
가장 중요한 규칙 하나
절대 일반 ZIP 작성기로 HWPX를 다시 압축하지 마세요. 한글은 변경되지 않은 항목이 재압축된 파일을 거부합니다. 원시 보존 리패커(scripts/hwpxlib.py:repack_preserve)를 사용하세요: 이 함수는 건드리지 않은 모든 항목을 바이트 단위로 복사하고 변경한 항목만 다시 압축하므로, 아무것도 변경하지 않은 리패킹 결과는 원본과 바이트 단위로 동일합니다. 즉, "원본이 한글에서 열리면, 당신의 편집본도 열립니다."
작업 흐름
- 먼저 검사하세요.
python scripts/inspect_hwpx.py FILE.hwpx --breaks— 섹션별 개수(문단, 표,pic, 수식, 필드)와, 중요한 것은 어떤 문단에 숨은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/pID도 포함합니다. - 기존
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. 모든 하드 검사가 통과해야 합니다 (바이트 정체성 자체 검사,content.hpf포함 well-formed XML, 중복 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 전체 체크리스트 실행; 실패 시 0이 아닌 종료 코드 반환 (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 리패킹 (원시 보존) — 핵심 리패커.
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가 증거입니다.