HWPX creation, reading, and conversion

Converting Legacy .hwp to .hwpx

Legacy .hwp files (OLE2 binary) cannot be directly edited as XML:

# Text extraction only (no formatting)
pip install pyhwp
hwp5txt document.hwp > output.txt

# Via LibreOffice (limited equation support)
libreoffice --headless --convert-to docx document.hwp

Best quality path: Open in 한글 program → Save As HWPX → use reader.py

Reading Content

# Markdown extraction with equations preserved as LaTeX
python scripts/reader.py document.hwpx output.md

# Raw XML access
unzip document.hwpx -d unpacked/
cat unpacked/Contents/section0.xml

Validation

python scripts/validate.py document.hwpx

Creating New Documents

Generate .hwpx files with Python using scripts/generator.py.

Basic Usage

python scripts/generator.py output.hwpx "문서 제목" "본문 내용" [A4|B4] [1|2]

• Paper sizes: A4 (default), B4 (Korean exam paper standard)
• Columns: 1 (default), 2 (newspaper-style, for exam papers)

Programmatic Usage

from generator import generate_hwpx, build_text_para, build_equation_para, build_table, build_empty_para

# Simple document
generate_hwpx("output.hwpx", "제목", "본문 텍스트\n두 번째 줄")

# With inline equations (use $...$ in text)
generate_hwpx("output.hwpx", "수학 문제", "이차방정식 $x^2 + 3x + 2 = 0$을 풀어라.")

# B4 2-column exam paper
generate_hwpx("exam.hwpx", "2024학년도 수학 시험", body_text, "B4", 2)

Custom Section Assembly

For complex documents, build sections manually:

from generator import make_section, build_text_para, build_equation_para, build_table, build_empty_para
import zipfile

paras = []
paras.append(build_text_para("1. 다음 방정식을 풀어라."))
paras.append(build_empty_para())
paras.append(build_equation_para(r"\frac{x+1}{x-1} = 3"))
paras.append(build_empty_para())
paras.append(build_table([["x", "y"], ["1", "2"], ["3", "4"]]))

body = "\n".join(paras)
# Then use make_section() and assemble the ZIP

Page Size

<!-- A4 (default) -->
<hp:pagePr landscape="WIDELY" width="59528" height="84188">
  <hp:margin header="4252" footer="4252" gutter="0"
             left="8504" right="8504" top="5668" bottom="4252"/>
</hp:pagePr>

<!-- B4 JIS (Korean exam paper standard) -->
<hp:pagePr landscape="WIDELY" width="72851" height="103181">
  <hp:margin header="4252" footer="4252" gutter="0"
             left="8504" right="8504" top="7086" bottom="5668"/>
</hp:pagePr>

Units: 1 HWP unit = 1/7200 inch. 8504 units ≈ 30mm.

Multi-Column Layout

<!-- 2-column newspaper style -->
<hp:colPr id="" type="NEWSPAPER" layout="LEFT" colCount="2" sameSz="1" sameGap="2268"/>

Fonts & Styles

<!-- Font declaration in header.xml -->
<hh:fontface lang="HANGUL" fontCnt="2">
  <hh:font id="0" face="신명중명조" type="TTF" isEmbedded="0"/>
  <hh:font id="1" face="나눔고딕" type="TTF" isEmbedded="0"/>
</hh:fontface>

<!-- Character property: 10pt body text -->
<hh:charPr id="0" height="1000" textColor="#000000">
  <hh:fontRef hangul="0" latin="0"/>
</hh:charPr>

<!-- Character property: 11pt bold -->
<hh:charPr id="2" height="1100" textColor="#000000">
  <hh:fontRef hangul="0" latin="0"/>
  <hh:bold/>
</hh:charPr>

height units: 100 = 1pt. 1000 = 10pt, 1100 = 11pt.

HWP Equation Script

CRITICAL: HWP equations are NOT LaTeX. They use a completely different syntax.

LaTeX → HWP Conversion Table

MathON Rules (Korean Math Standard)

These rules are mandatory for Korean education documents (시험지, 교과서).

HWP equations render letters in italic by default. Use rm (roman/upright) explicitly where required.

rm (Roman/Upright) — Use for:

it (Italic) — Default for:

Mixed rm/it Patterns (Probability/Statistics)

Spacing Rules

HWPX File Structure

document.hwpx (ZIP)
├── META-INF/
│   └── container.xml          # OPF container (root file path)
├── Contents/
│   ├── content.hpf            # OPF package manifest (file list)
│   ├── header.xml             # Document settings (fonts, styles, paragraph properties)
│   ├── section0.xml           # Main content (paragraphs, equations, images, tables)
│   └── section1.xml           # Additional sections (optional)
├── BinData/                   # Image file storage
│   ├── image1.png
│   └── image2.png
├── Preview/
│   └── PrvText.txt            # Preview text
├── settings.xml               # Application settings
└── mimetype                   # "application/hwp+zip"

XML Reference

Namespaces

hp = http://www.hancom.co.kr/hwpml/2011/paragraph  (body content)
hh = http://www.hancom.co.kr/hwpml/2011/head       (header/styles)
hs = http://www.hancom.co.kr/hwpml/2011/section     (sections)
hc = http://www.hancom.co.kr/hwpml/2011/core        (core)
ha = http://www.hancom.co.kr/hwpml/2011/app          (application)

Text Paragraph

<hp:p id="0" paraPrIDRef="0" styleIDRef="0"
     pageBreak="0" columnBreak="0" merged="0">
  <hp:run charPrIDRef="1">
    <hp:t>문제 텍스트입니다.</hp:t>
  </hp:run>
</hp:p>

Inline Equation in Text

CRITICAL: An empty <hp:t/> MUST follow every equation element.

<hp:p id="0" paraPrIDRef="0" styleIDRef="0"
     pageBreak="0" columnBreak="0" merged="0">
  <hp:run charPrIDRef="1">
    <hp:t>이차방정식 </hp:t>
  </hp:run>
  <hp:run charPrIDRef="1">
    <hp:equation id="0" zOrder="0" numberingType="EQUATION"
        textWrap="TOP_AND_BOTTOM" textFlow="BOTH_SIDES" lock="0"
        dropcapstyle="None" version="Equation Version 60" baseLine="61"
        textColor="#000000" baseUnit="1100" lineMode="CHAR" font="HYhwpEQ">
        <hp:sz width="14000" widthRelTo="ABSOLUTE"
               height="3000" heightRelTo="ABSOLUTE" protect="0"/>
        <hp:pos treatAsChar="1" affectLSpacing="0" flowWithText="1"
                allowOverlap="0" holdAnchorAndSO="0"
                vertRelTo="PARA" horzRelTo="PARA"
                vertAlign="TOP" horzAlign="LEFT"
                vertOffset="0" horzOffset="0"/>
        <hp:outMargin left="56" right="56" top="0" bottom="0"/>
        <hp:shapeComment>수식입니다.</hp:shapeComment>
        <hp:script>x^rm{2}+rm{3}x+rm{2}=rm{0}</hp:script>
    </hp:equation>
    <hp:t/>
  </hp:run>
  <hp:run charPrIDRef="1">
    <hp:t>을 풀어라.</hp:t>
  </hp:run>
</hp:p>

Key equation attributes:

• version="Equation Version 60": CRITICAL — 수식 렌더러 버전. 빈 문자열이면 복잡한 수식이 표시되지 않음
• baseLine="61": Baseline offset (한글 프로그램 기본값)
• vertRelTo="PARA", horzRelTo="PARA": CRITICAL — 문단 기준 위치. PAPER/COLUMN 사용 시 수식 렌더링 실패
• vertAlign="TOP", vertOffset="0": 문단 상단 정렬, 오프셋 0
• outMargin top="0" bottom="0": 상하 여백 0 (한글 기본값)
• <hp:shapeComment>수식입니다.</hp:shapeComment>: 한글 프로그램 호환성용 주석
• width: Equation width (HWP units, ~600 per character)
• height: Equation height (default 3000)
• treatAsChar="1": Inline equation
• font="HYhwpEQ": HWP equation font (required)

Tables

CRITICAL: Table cells use borderFillIDRef="3" for standard solid-line borders.

<hp:tbl id="0" zOrder="0" numberingType="TABLE"
    textWrap="TOP_AND_BOTTOM" textFlow="BOTH_SIDES" lock="0"
    dropcapstyle="None" pageBreak="CELL" repeatHeader="1"
    rowCnt="2" colCnt="3" cellSpacing="0" borderFillIDRef="3" noAdjust="0">
  <hp:sz width="42000" widthRelTo="ABSOLUTE"
         height="3600" heightRelTo="ABSOLUTE" protect="0"/>
  <hp:pos treatAsChar="1" .../>
  <hp:outMargin left="0" right="0" top="0" bottom="0"/>
  <hp:inMargin left="0" right="0" top="0" bottom="0"/>
  <hp:tr>
    <hp:tc name="" header="0" hasMargin="0" protect="0" editable="0"
           dirty="0" borderFillIDRef="3">
      <hp:subList id="" textDirection="HORIZONTAL" lineWrap="BREAK"
                  vertAlign="CENTER" ...>
        <hp:p ...><hp:run charPrIDRef="0"><hp:t>Cell</hp:t></hp:run></hp:p>
      </hp:subList>
      <hp:cellAddr colAddr="0" rowAddr="0"/>
      <hp:cellSpan colSpan="1" rowSpan="1"/>
      <hp:cellSz width="14000" height="1800"/>
      <hp:cellMargin left="141" right="141" top="141" bottom="141"/>
    </hp:tc>
  </hp:tr>
</hp:tbl>

Table width calculation: Default total width 42000. Column widths = total_width / n_cols.

Images

1. Add image to BinData/ in ZIP
2. Register in Contents/content.hpf:

<opf:item id="img1" href="BinData/image1.png" media-type="image/png"/>

3. Reference in section XML:

<hp:pic id="0" zOrder="0" numberingType="PICTURE"
    textWrap="TOP_AND_BOTTOM" textFlow="BOTH_SIDES">
  <hp:imgRect>
    <hp:orgSz width="28000" height="28000"/>
    <hp:curSz width="0" height="0"/>
  </hp:imgRect>
  <hp:sz width="28000" widthRelTo="ABSOLUTE"
         height="28000" heightRelTo="ABSOLUTE" protect="0"/>
  <hp:pos treatAsChar="1" .../>
  <hp:img bright="0" contrast="0" effect="REAL_PIC" binaryItemIDRef="1"/>
</hp:pic>

Endnotes (Solutions/Explanations)

Endnotes auto-place at document end — useful for exam solutions:

<hp:run charPrIDRef="1">
  <hp:ctrl>
    <hp:endNote number="1" suffixChar="41" instId="2000000000">
      <hp:subList id="" textDirection="HORIZONTAL" lineWrap="BREAK" vertAlign="TOP">
        <hp:p ...>
          <hp:run charPrIDRef="0">
            <hp:ctrl>
              <hp:autoNum num="1" numType="ENDNOTE">
                <hp:autoNumFormat type="DIGIT"/>
              </hp:autoNum>
            </hp:ctrl>
          </hp:run>
          <hp:run charPrIDRef="2">
            <hp:t>정답: 42</hp:t>
          </hp:run>
        </hp:p>
      </hp:subList>
    </hp:endNote>
  </hp:ctrl>
</hp:run>

Page Breaks & Column Breaks

<!-- Page break -->
<hp:p id="0" paraPrIDRef="0" styleIDRef="0" pageBreak="1" columnBreak="0" merged="0">
  <hp:run charPrIDRef="0"><hp:t/></hp:run>
</hp:p>

<!-- Column break -->
<hp:p id="0" paraPrIDRef="0" styleIDRef="0" pageBreak="0" columnBreak="1" merged="0">
  <hp:run charPrIDRef="0"><hp:t/></hp:run>
</hp:p>

content.hpf (OPF Package Manifest)

Register all files:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<opf:package xmlns:opf="http://www.idpf.org/2007/opf" unique-identifier="bookid" version="1.0">
  <opf:manifest>
    <opf:item id="header" href="Contents/header.xml" media-type="application/xml"/>
    <opf:item id="section0" href="Contents/section0.xml" media-type="application/xml"/>
    <opf:item id="img1" href="BinData/image1.png" media-type="image/png"/>
  </opf:manifest>
  <opf:spine>
    <opf:itemref idref="header"/>
    <opf:itemref idref="section0"/>
  </opf:spine>
</opf:package>

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

mkdir unpacked
unzip document.hwpx -d unpacked/

Step 2: Edit XML

Edit files in unpacked/Contents/. Key files:

• section0.xml — main body content
• header.xml — fonts, styles, paragraph properties

Use the Edit tool directly for string replacement. Do not write Python scripts.

Step 3: Repack

cd unpacked
zip -r ../output.hwpx . -x ".*"

CRITICAL: The mimetype file must be the first entry and stored uncompressed:

cd unpacked
zip -0 ../output.hwpx mimetype
zip -r ../output.hwpx . -x mimetype ".*"

Converting Between Formats

HWPX → Markdown

python scripts/reader.py document.hwpx output.md

Extracts text, equations (as LaTeX $...$), and images.

Markdown → HWPX

python scripts/generator.py output.hwpx "Title" "Body text with $equations$"

Supports inline $...$ equations auto-converted to HWP equation script.

Conversion Quality Comparison

Best quality path: HWP → 한글에서 HWPX 저장 → reader.py (equations preserved as LaTeX)

Critical Rules

• version="Equation Version 60" — 수식 렌더러 버전 필수. 빈 문자열이면 수식이 본문에 표시되지 않음
• vertRelTo="PARA", horzRelTo="PARA" — 수식 위치는 문단 기준. PAPER/COLUMN 사용 시 렌더링 실패
• Empty <hp:t/> after equations — Without it, equations won't display
• \sqrt, \text, \mathrm 변환 시 end_pos +1 — _match_brace 후 닫는 }를 건너뛰어야 중괄호 불일치 방지
• ^/_ 뒤 공백 금지 — v^ rm{2}는 파싱 오류. v^rm{2} 또는 v^{rm{2}}로 붙여 써야 함
• UTF-8 encoding — Use html.escape() for XML content
• binaryItemIDRef matching — Image refs must match content.hpf IDs
• <hp:colPr> inside <hp:secPr> — Multi-column fails otherwise
• Equation width — ~600 HWP units per character, minimum 3000, max ~18000 for 2-column
• borderFillIDRef="3" — Required for table cell borders to render
• rm vs it — Variables: italic (default). Geometry vertices, units, probability symbols: roman (rm)
• cdot not bullet — Always use cdot for dot product
• Unit spacing — Backtick (`) between number and unit is mandatory
• HWP equations are NOT LaTeX — Completely different syntax; never mix them

Common Mistakes & Debugging

1. Equation blank in body but visible in editor: version="" (빈 문자열) → version="Equation Version 60" 필수
2. Equation blank in body (position): vertRelTo="PAPER" → vertRelTo="PARA", horzRelTo="COLUMN" → horzRelTo="PARA" 변경
3. Equation not displaying: Missing <hp:t/> after <hp:equation> element
4. Superscript/subscript broken: ^ 또는 _ 뒤에 공백이 있으면 안 됨. v^rm{2} (O), v^ rm{2} (X)
5. Brace mismatch in equation script: \sqrt, \text 변환 시 end_pos = m.end() + len(content) + 1 (닫는 } 건너뛰기)
6. Korean text garbled: XML encoding not UTF-8, or missing html.escape()
7. Image not showing: binaryItemIDRef doesn't match content.hpf id
8. 2-column layout broken: <hp:colPr> not inside <hp:secPr>
9. Page break not working: Use pageBreak="1" attribute on <hp:p>
10. Column break not working: Use columnBreak="1" attribute on <hp:p>
11. Table borders missing: borderFillIDRef not set to "3" (solid line)
12. Equation too wide: Max ~18000 for 2-column, ~40000 for single column
13. rm/it confusion: Variables are italic, geometry vertices/units/probability are roman
14. Bullet instead of cdot: Use cdot for dot product, never bullet

Dependencies

• Python 3.8+: Required for scripts
• pyhwp: pip install pyhwp (HWP5 binary reading only)
• LibreOffice: Optional, for .hwp → .docx conversion
• pandoc: Optional, for HTML → Markdown conversion