HWPX에서 글상자(TextBox)는 Control 요소가 아닙니다. <hp:rect> 도형 안에 <hp:drawText>를 내포한 구조입니다.

#![allow(unused)]
fn main() {
// ❌ WRONG (HWPX는 control 요소가 아님)
Control::TextBox(...)

// ✅ CORRECT (HWPX 실제 구조)
// <hp:rect ...><hp:drawText>...</hp:drawText></hp:rect>
}

수식은 일반 도형(선/타원/다각형)과 달리 offset, orgSz, curSz, flip, rotation, lineShape, fillBrush, shadow 요소가 없습니다.

<!-- ❌ WRONG — equation은 shape common이 없음 -->
<hp:equation><hp:offset .../><hp:orgSz .../></hp:equation>

<!-- ✅ CORRECT — sz + pos + outMargin + script만 -->
<hp:equation>
  <hp:sz .../>
  <hp:pos .../>
  <hp:outMargin .../>
  <hp:script>...</hp:script>
</hp:equation>

flowWithText="1" (도형은 0), outMargin left/right=56 (도형은 0 또는 283).

글상자를 인코딩할 때 지켜야 할 6가지 규칙입니다.

1. 모서리 좌표는 hc: 네임스페이스: <hc:pt0> ~ <hc:pt3> (hp:pt0 아님)
2. 요소 순서: shape-common → drawText → caption → hc:pt0-3 → sz → pos → outMargin → shapeComment
3. lastWidth = 전체 width: margin을 차감하지 않음
4. Shadow alpha = 178: 기본값 0이 아님
5. shapeComment 필수: <hp:shapeComment>사각형입니다.</hp:shapeComment>
6. Shape run 후 <hp:t/> marker 필수: 모든 shape 포함 run에 빈 <hp:t/> 추가

한글은 path를 자동으로 닫지 않습니다. 첫 꼭짓점을 마지막에 반복하지 않으면 삼각형이 2변만 표시됩니다.

<!-- ❌ WRONG — 삼각형이 2변만 표시됨 -->
<hc:pt x="0" y="100"/>
<hc:pt x="50" y="0"/>
<hc:pt x="100" y="100"/>

<!-- ✅ CORRECT — 첫 꼭짓점을 마지막에 반복 -->
<hc:pt x="0" y="100"/>
<hc:pt x="50" y="0"/>
<hc:pt x="100" y="100"/>
<hc:pt x="0" y="100"/>

barChart와 stockChart가 catAx를 공유하는 3축 레이아웃을 사용하면 한글 렌더링이 깨집니다. 각 차트 타입은 자체 축 쌍(catAx+valAx)을 가져야 합니다.

<!-- ❌ WRONG — 3축 layout (catAx 공유) → 한글 렌더링 깨짐 -->
<c:barChart>...<c:axId val="1"/><c:axId val="3"/></c:barChart>
<c:stockChart>...<c:axId val="1"/><c:axId val="2"/></c:stockChart>
<c:catAx><c:axId val="1"/>...</c:catAx>

<!-- ✅ CORRECT — OOXML 표준 4축 combo layout -->
<c:barChart>...<c:axId val="3"/><c:axId val="4"/></c:barChart>
<c:stockChart>...<c:axId val="1"/><c:axId val="2"/></c:stockChart>
<c:catAx><c:axId val="1"/><c:crossAx val="2"/>...</c:catAx>
<c:valAx><c:axId val="2"/><c:crossAx val="1"/>...</c:valAx>
<c:catAx><c:axId val="3"/><c:crossAx val="4"/><c:delete val="1"/>...</c:catAx>
<c:valAx><c:axId val="4"/><c:crossAx val="3"/><c:crosses val="max"/>...</c:valAx>

secondary catAx는 delete="1"로 숨깁니다.

build_col_pr_xml은 self-closing <hp:colPr ... />를 생성합니다. </hp:colPr>를 검색하면 매칭에 실패합니다.

#![allow(unused)]
fn main() {
// ❌ WRONG — self-closing 태그를 놓침
xml.find("</hp:colPr>")

// ✅ CORRECT — 양쪽 형태 모두 매칭
xml.find("<hp:colPr")
}

secPr 내 ctrl 요소 순서: secPr → colPr → header → footer → pageNum

Modern(22) 스타일셋에서 개요 8/9/10의 paraPr 인덱스는 순차적이지 않습니다. 순차적이라고 가정하면 잘못된 스타일이 적용됩니다.

Modern 스타일셋에서 사용자 paraShape는 인덱스 20부터 시작합니다.

실제 한글 파일에서는 <hh:paraPr> 당 2개 이상의 <hp:switch>가 있습니다 (예: 제목용 하나, 여백/줄간격용 하나). 스키마는 Option<HxSwitch>가 아닌 Vec<HxSwitch>를 사용해야 합니다.

#![allow(unused)]
fn main() {
// ❌ WRONG
switches: Option<HxSwitch>

// ✅ CORRECT
switches: Vec<HxSwitch>
}

<hp:hyperlink> 요소는 HWPX에 존재하지 않습니다. KS X 6101의 field pair 패턴을 사용해야 합니다.

<!-- ❌ WRONG — 이런 요소 없음 -->
<hp:hyperlink href="...">...</hp:hyperlink>

<!-- ✅ CORRECT — KS X 6101 field pair -->
<hp:run charPrIDRef="0">
  <hp:ctrl>
    <hp:fieldBegin type="HYPERLINK" fieldid="0">
      <hp:parameters cnt="4">
        <hp:stringParam name="Path">https://url.com</hp:stringParam>
        <hp:stringParam name="Category">HWPHYPERLINK_TYPE_URL</hp:stringParam>
        <hp:stringParam name="TargetType">HWPHYPERLINK_TARGET_DOCUMENT_DONTCARE</hp:stringParam>
        <hp:stringParam name="DocOpenType">HWPHYPERLINK_JUMP_NEWTAB</hp:stringParam>
      </hp:parameters>
    </hp:fieldBegin>
  </hp:ctrl>
  <hp:t>링크 텍스트</hp:t>
  <hp:ctrl><hp:fieldEnd beginIDRef="0" fieldid="0"/></hp:ctrl>
</hp:run>

각주/미주를 별도 문단으로 만들면 각주 번호가 단독 줄에 표시됩니다. 반드시 같은 문단의 Run에 포함해야 합니다.

#![allow(unused)]
fn main() {
// ❌ WRONG — 별도 문단으로 만들면 "1)"이 단독 줄에 표시됨
paras.push(p("본문 텍스트."));
paras.push(ctrl_para(Control::footnote(notes), CS_NORMAL, PS_JUSTIFY));

// ✅ CORRECT — 같은 문단의 Run에 포함
paras.push(Paragraph::with_runs(
    vec![
        Run::text("본문 텍스트.", CharShapeIndex::new(0)),
        Run::control(Control::footnote(notes), CharShapeIndex::new(0)),
    ],
    ParaShapeIndex::new(0),
));
}

type="PAGE_NUM"은 유효한 fieldBegin 타입이 아닙니다. 본문에 쪽번호를 삽입할 때는 autoNum 메커니즘을 사용해야 합니다.

<!-- ❌ WRONG — PAGE_NUM은 존재하지 않는 타입 -->
<hp:fieldBegin type="PAGE_NUM" ...>

<!-- ✅ CORRECT — autoNum 메커니즘 사용 -->
<hp:ctrl>
  <hp:autoNum num="1" numType="PAGE">
    <hp:autoNumFormat type="DIGIT" userChar="" prefixChar="" suffixChar="" supscript="0"/>
  </hp:autoNum>
</hp:ctrl>

3가지 쪽번호 메커니즘 혼동 주의:

• <hp:pageNum>: secPr 내 ctrl (머리글/바닥글 자동 배치)
• <hp:autoNum numType="PAGE">: 본문 텍스트 인라인 삽입
• type="PAGE_NUM" fieldBegin: 존재하지 않음

pageBreak 속성을 하드코딩된 0으로 설정하면 페이지 나누기가 동작하지 않습니다.

#![allow(unused)]
fn main() {
// ❌ WRONG (하드코딩)
page_break: 0,

// ✅ CORRECT — para.page_break 필드에서 읽기
page_break: u32::from(para.page_break),
}

encoder/section.rs의 build_paragraph()에서 pageBreak 속성을 para.page_break 필드로부터 읽어야 합니다.

BREAK_WORD를 사용하면 양쪽 정렬(justify) 텍스트에서 글자 사이 공간이 균등 분배되어 글자가 비정상적으로 퍼집니다. 한글 기본값인 KEEP_WORD를 사용해야 합니다.

#![allow(unused)]
fn main() {
// ❌ WRONG — 양쪽 정렬 시 글자 사이 공간 균등 분배 → 퍼짐 현상
break_non_latin_word: "BREAK_WORD"

// ✅ CORRECT — 한글 기본값, 단어 단위 공간 분배 → 자연스러운 정렬
break_non_latin_word: "KEEP_WORD"
}

위치: crates/hwpforge-smithy-hwpx/src/encoder/header.rs build_para_pr()

KS X 6101 스키마에는 FILLED_DIAMOND, FILLED_CIRCLE, FILLED_BOX가 유효한 값으로 정의되어 있지만, 실제 한글은 이를 인식하지 못합니다. EMPTY_* 형태와 headfill/tailfill 속성(0 또는 1)으로 채움 여부를 제어해야 합니다.

<!-- ❌ WRONG — 한글이 인식하지 않음 (화살촉 안 보임) -->
<hp:lineShape headStyle="FILLED_DIAMOND" headfill="1" .../>

<!-- ✅ CORRECT — EMPTY_* + headfill="1" = 채워진 다이아몬드 -->
<hp:lineShape headStyle="EMPTY_DIAMOND" headfill="1" .../>

<!-- ✅ CORRECT — EMPTY_* + headfill="0" = 빈 다이아몬드 -->
<hp:lineShape headStyle="EMPTY_DIAMOND" headfill="0" .../>

적용 대상: EMPTY_DIAMOND, EMPTY_CIRCLE, EMPTY_BOX 비기하 도형은 그대로: NORMAL, ARROW, SPEAR, CONCAVE_ARROW (fill 속성 무관)

DropCapStyle은 문단 속성이 아니라 도형(AbstractShapeObjectType)의 속성입니다. 값은 SCREAMING_SNAKE_CASE가 아닌 PascalCase를 사용해야 합니다.

<!-- ❌ WRONG — SCREAMING_SNAKE_CASE -->
dropcapstyle="DOUBLE_LINE"

<!-- ✅ CORRECT — PascalCase (KS X 6101 XSD 준수) -->
dropcapstyle="DoubleLine"

유효한 값: None, DoubleLine, TripleLine, Margin