Edición HWPX
HWPX es un zip de XML (HWPML). Las trampas que corrompen un archivo no son obvias
desde fuera, por lo que lea la sección correspondiente de references/hwpx-guide.md
antes de editar y ejecute los scripts en scripts/ para reempaquetar y verificar —
no haga el zip manualmente ni confíe en la corrección visual.
Solo HWPX. Esto maneja exclusivamente
.hwpx(zip + XML). Un.hwpheredado (binario OLE, firmaD0CF11E0) debe convertirse primero en 한글 mediante 다른 이름으로 저장 → HWPX(.hwpx). Los scripts detectan.hwpy lo indican.
La regla más importante
Nunca vuelva a comprimir un HWPX con un escritor zip normal. 한글 rechaza un archivo
cuyas entradas no modificadas fueron re-deflactadas. Use el reempaquetador preservador de
bytes (scripts/hwpxlib.py:repack_preserve): copia byte a byte cada entrada que no tocó
y re-deflacta solo lo que cambió, de modo que un reempaquetado sin cambios es byte-idéntico
al origen — lo que significa "si el original se abre en 한글, su edición también se abre".
Flujo de trabajo
- Inspeccione primero.
python scripts/inspect_hwpx.py ARCHIVO.hwpx --breaks— vea conteos por sección (párrafos, tablas,pic, ecuación, campos) y, crucialmente, qué párrafos llevan unpageBreak/columnBreakoculto. Si un encabezado está separado de su contenido o una página/columna está en blanco, cace esos saltos primero (§6-A) — no recurra akeepWithNext. Los saltos de párrafo del cuerpo suelen ser residuos. - Lea la sección correspondiente de la guía en
references/hwpx-guide.md(mapa abajo). Los ids/referencias XML (charPrIDRef,paraPrIDRef,borderFillIDRef, …) difieren por archivo — léalos siempre del archivo real, nunca asuma. - Edite el XML con lxml, siguiendo las invariantes:
- Después de editar o crear cualquier párrafo, elimine su
<hp:linesegarray>(el diseño de línea en caché se vuelve obsoleto → espaciado roto). Después de ediciones estructurales, elimine linesegarray de toda la sección para que 한글 vuelva a diseñarlo completamente. Usehwpxlib.strip_linesegarray. - Cuando clone un nodo (nota al final, tabla, ecuación, imagen), hereda el
id/instIddel original → duplicados → inestabilidad. Reasigne ids frescos conhwpxlib.make_uid, incluyendo ids anidados desubList>p/tbl/tc/p. - Reutilice definiciones
charPr/paraPrexistentes en lugar de agregar nuevas; si debe agregar, actualice elitemCnto 한글 rechaza el archivo.
- Después de editar o crear cualquier párrafo, elimine su
- Reempaquete con
hwpxlib.repack_preserve(origen, cambiados, salida, agregados):cambiados= entradas editadas (mantenga la declaración XML al inicio),agregados= nuevas entradas comoBinData/imagenN.pngo un nuevoseccionN.xml(también regístrelas encontent.hpf). - Verifique cada compilación:
python scripts/verify.py EDITADO.hwpx --orig ORIG.hwpx. Todas las comprobaciones estrictas deben pasar (autocomprobación de identidad de bytes, XML bien formado incl.content.hpf, cero ids duplicados, integridad zip + mimetype primero/ALMACENADO). También imprime un diff de cambio mínimo para que pueda confirmar que solo están presentes los cambios previstos. - Pruebe en 한글. LibreOffice no puede renderizar HWPX, por lo que los juicios dependientes de renderizado (qué huérfanos de encabezado, si el espaciado se ve bien) necesitan que el usuario abra el archivo en 한글 y, para ecuaciones/TDC, ejecute 도구→차례 새로 고침 o haga doble clic→cerrar para finalizar. Dígalo.
Scripts (scripts/) — ejecute estos, no reinvente
| Script | Propósito |
|---|---|
hwpxlib.py | Biblioteca: repack_preserve, own (texto del cuerpo real, excluye 각주·미주·메모 / nota al pie·nota al final·memo), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, más ayudantes de verificación §7. Impórtelo. |
inspect_hwpx.py ARCHIVO [--text] [--breaks] | Volcado de estructura; encuentre saltos de página/columna ocultos. |
verify.py EDITADO [--orig ORIG] | Ejecute la lista de verificación completa §7; salida distinta de cero en fallo (comprobable en CI). |
selftest.py | Demuestre que el reempaquetador es sin pérdidas sin un archivo real. |
tables_to_xlsx.py ARCHIVO [SALIDA] | Exporte tablas a Excel (.xlsx), celdas combinadas preservadas (necesita openpyxl). Celdas con solo imagen/ecuación → [그림]/[수식]; .hwp heredado es rechazado con orientación. |
Los scripts necesitan lxml (pip install lxml); la exportación tabla→Excel también necesita openpyxl. Python 3.10+.
Dónde leer en la guía (references/hwpx-guide.md)
Cargue solo la sección que necesite — la guía abre con un "흔한 실패 TOP" (modos de fallo principales); hojee eso primero, luego salte a:
- §1 Estructura y análisis — espacios de nombres,
own(), "verificar todas las secciones", texto de tabla por celda (noitertextmasivo). - §2 Reempaquetado (preservador de bytes) — el reempaquetador joya de la corona. Espejo de
hwpxlib. - §3 Reglas comunes — eliminación de
linesegarray, deduplicación de ids después de clonar. - §4 Edición de contenido — párrafos, tablas (la suma de anchos de celda debe igualar el ancho
de la tabla o 한글 lo rechaza; combinaciones), imágenes (
orgSz=px×75, cálculo de tamaño, verificar por contenido no orden de extracción, legibilidad de matplotlib "figura pequeña, texto grande"), formato, notas al final/notas al pie (requerido envoltorio<hp:ctrl>), memos y alcance de auditoría de erratas (sin regex general). - §5 Columnas · TDC · ecuaciones —
colPr,TABLEOFCONTENTSdesde párrafos de nivel de esquema, script de ecuación 한컴 (no LaTeX; tabla de formas). - §6 Gestión de página/columna — saltos ocultos primero, prevención de encabezado huérfano
(
keepWithNext, sin párrafo vacío después de un encabezado,columnBreakcondicional), limpieza de páginas en blanco, tablas anchas → región de 1 columna + mover un bloquesecPra través de límites de sección. - §7 Lista de verificación — qué automatiza
verify.py, más la advertencia de prueba en 한글.
Barreras de protección
- Esto edita documentos solamente; nunca necesita las credenciales del usuario, y no obtiene ni ejecuta contenido remoto. Trabaje sobre una copia y conserve el original.
- Preserve el contenido del autor: solo cambie lo que el usuario pidió; el
diff de cambio mínimo en
verify.pyes su prueba.