Edição de HWPX
HWPX é um ZIP de XML (HWPML). As armadilhas que corrompem um arquivo não são óbvias
de fora, então leia a seção relevante de references/hwpx-guide.md
antes de editar, e execute os scripts em scripts/ para recompactar e verificar —
não tente fazer o zip manualmente ou verificar a correção visualmente.
Apenas HWPX. Isso lida exclusivamente com
.hwpx(ZIP + XML). Um.hwplegado (binário OLE, assinaturaD0CF11E0) deve primeiro ser convertido no 한글 via 다른 이름으로 저장 → HWPX(.hwpx). Os scripts detectam.hwpe informam.
A regra mais importante
Nunca recrie um HWPX com um gravador ZIP normal. O 한글 rejeita um arquivo cujas
entradas inalteradas foram re-deflacionadas. Use o recompactador que preserva os bytes originais
(scripts/hwpxlib.py:repack_preserve): ele copia byte a byte cada entrada que você não
tocou e re-deflaciona apenas o que você alterou, de modo que uma recompactação sem alterações é
byte-idêntica à fonte — significando "se o original abre no 한글, sua edição também abre".
Fluxo de trabalho
- Inspecione primeiro.
python scripts/inspect_hwpx.py ARQUIVO.hwpx --breaks— veja contagens por seção (parágrafos, tabelas,pic,equation, campos) e, crucialmente, quais parágrafos carregam umapageBreak/columnBreakoculta. Se um título estiver separado de seu conteúdo ou uma página/coluna estiver em branco, descubra essas quebras primeiro (§6-A) — não alcancekeepWithNext. Quebras de parágrafo de corpo geralmente são resquícios. - Leia a seção correspondente do guia em
references/hwpx-guide.md(mapeamento abaixo). Os IDs/refs XML (charPrIDRef,paraPrIDRef,borderFillIDRef, …) diferem por arquivo — sempre leia-os do arquivo real, nunca suponha. - Edite o XML com lxml, seguindo as invariantes:
- Depois de editar ou criar qualquer parágrafo, remova seu
<hp:linesegarray>(layout de linha em cache fica obsoleto → espaçamento quebrado). Após edições estruturais, remova linesegarray da seção inteira para que o 한글 refaça o layout completamente. Usehwpxlib.strip_linesegarray. - Quando você clona um nó (nota de fim, tabela, equação, imagem), ele herda o
id/instIdoriginal → duplicatas → instabilidade. Atribua novos IDs comhwpxlib.make_uid, incluindo IDs aninhados desubList>p/tbl/tc/p. - Reutilize definições existentes de
charPr/paraPrem vez de adicionar novas; se precisar adicionar, atualize oitemCntou o 한글 rejeita o arquivo.
- Depois de editar ou criar qualquer parágrafo, remova seu
- Recompacte com
hwpxlib.repack_preserve(src, changed, out, added):changed= entradas editadas (mantenha a declaração XML no topo),added= novas entradas comoBinData/imagemN.pngou um novosectionN.xml(também registre-as emcontent.hpf). - Verifique cada construção:
python scripts/verify.py EDITADO.hwpx --orig ORIG.hwpx. Todas as verificações rigorosas devem passar (autoverificação de identidade de byte, XML bem formado incluindocontent.hpf, zero IDs duplicados, integridade do ZIP + mimetype primeiro/ARMAZENADO). Ele também imprime uma diff de alteração mínima para que você confirme que apenas as alterações pretendidas estão presentes. - Teste no 한글. O LibreOffice não pode renderizar HWPX, portanto julgamentos dependentes de renderização (se cabeçalhos órfãos, se o espaçamento parece correto) precisam que o usuário abra o arquivo no 한글 e, para equações/SUMÁRIO, execute 도구 → 차례 새로 고침 ou clique duas vezes → feche para finalizar. Avise isso.
Scripts (scripts/) — execute estes, não recrie
| Script | Propósito |
|---|---|
hwpxlib.py | Biblioteca: repack_preserve, own (texto real do corpo, exclui 각주·미주·메모 / nota de rodapé·nota de fim·memorando), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, além de auxiliares de verificação §7. Importe-a. |
inspect_hwpx.py ARQUIVO [--text] [--breaks] | Despejo da estrutura; encontre quebras ocultas de página/coluna. |
verify.py EDITADO [--orig ORIG] | Execute a lista de verificação completa §7; saída com código diferente de zero em falha (integrável a CI). |
selftest.py | Prove que o recompactador é sem perdas sem um arquivo real. |
tables_to_xlsx.py ARQUIVO [SAÍDA] | Exporte tabelas para Excel (.xlsx), células mescladas preservadas (precisa de openpyxl). Células com apenas imagem/equação → [그림]/[수식]; .hwp legado é recusado com orientação. |
Os scripts precisam de lxml (pip install lxml); a exportação de tabelas para Excel também precisa de openpyxl. Python 3.10+.
Onde ler no guia (references/hwpx-guide.md)
Carregue apenas a seção que você precisa — o guia abre com um "흔한 실패 TOP" (principais modos de falha); folheie isso primeiro, depois vá para:
- §1 Estrutura e análise — namespaces,
own(), "verifique todas as seções", texto de tabela por célula (nãoitertextem massa). - §2 Recompactação (preservação de bytes) — o recompactador principal. Espelha
hwpxlib. - §3 Regras comuns — remoção de
linesegarray, dedup de ID após clonagem. - §4 Edição de conteúdo — parágrafos, tabelas (soma das larguras das células deve igualar a largura
da tabela ou 한글 rejeita; mesclagens), imagens (
orgSz=px×75, cálculo de tamanho, verifique por conteúdo não ordem de extração, legibilidade matplotlib "figura pequena, texto grande"), formatação, notas de fim/rodapé (encapsulamento<hp:ctrl>obrigatório), memorandos, e escopo de auditoria de erros de digitação (sem regex genérico). - §5 Colunas · SUMÁRIO · equações —
colPr,TABLEOFCONTENTSa partir de parágrafos de nível de estrutura, script de equação 한컴 (não LaTeX; tabela de formulários). - §6 Gerenciamento de página/coluna — quebras ocultas primeiro, prevenção de
cabeçalhos órfãos (
keepWithNext, sem parágrafo vazio após um cabeçalho,columnBreakcondicional), limpeza de páginas em branco, tabelas largas → região de 1 coluna + mover um blocosecPrentre seções. - §7 Lista de verificação de verificação — o que
verify.pyautomatiza, além da ressalva do teste no 한글.
Proteções
- Isso edita apenas documentos; nunca precisa das credenciais do usuário e não busca nem executa conteúdo remoto. Trabalhe em uma cópia e mantenha o original.
- Preserve o conteúdo do autor: altere apenas o que o usuário pediu; a
diff de alteração mínima em
verify.pyé sua prova.