docs: HWPX/OWPML 내부 실전 가이드 + 영문 README

[airmang]

무엇을

• docs/internals/ — "코드만으로는 알 수 없는, 실제 한/글 동작에서 확인된 HWPX/OWPML 실전 지식"을 정리한 신규 가이드. 색인 1개 + 주제 6개:
  • units.md — HWPUNIT 좌표계(1 inch = 7,200), pt/mm/% 내부 변환
  • lineseg.md — hp:linesegarray 조판 캐시, 편집 후 stale 방치 시 글자 겹침, 문단 단위 스코프 무효화
  • toc-dirty.md — TABLEOFCONTENTS 필드 dirty="1"의 여는 시점 재계산 트리거와 그 한계
  • opc-packaging.md — mimetype 첫 엔트리·STORED, version.xml/manifest, 2016→2011 네임스페이스 정규화
  • memo-structure.md — 메모 본체·MEMO 필드·MemoShapeIDRef 참조 삼박자
  • oracle-limits.md — 텍스트 추출이 침묵 실패할 수 있는 경우와 픽셀 검증이 필요한 이유
• README_EN.md — 현재 main README.md의 충실한 영문 번역(구조·뱃지·링크·코드 블록 동일).
• README.md / README_EN.md — 상단 언어 토글(한국어 | English), "더 보기"에 내부 가이드 링크 추가.

왜

이 프로젝트의 차별점은 산출물을 실제 한컴오피스로 검증한다는 점이고, 그 과정에서 표준 문서·한컴 공식 문서·KS X 6101 어디에도 적혀 있지 않은 내부 동작 지식이 축적되었습니다. 이를 공개해 저장소를 기여자를 위한 권위 있는 학습 자료로 만드는 것이 목적입니다. 영문 README는 비한국어권 기여자의 진입 장벽을 낮춥니다.

검증 방법

• 코드 앵커링: 모든 주장은 이 저장소의 코드·테스트(src/hwpx/..., tests/...) 또는 공개 표준으로 검증했습니다. 실측으로 관찰한 한/글 동작은 내부 참조 없이 "실제 한/글에서 확인된 동작"으로 명시했습니다.
• Sphinx 빌드: sphinx-build -b html docs docs/_build/html(gh-pages 워크플로와 동일) 로컬 실행 → exit 0, build succeeded. 신규 7개 문서 모두 정상 렌더·toctree 배선 완료, 끊긴 링크 경고 없음. 남은 5개 경고는 기존 문서의 pre-existing toc.not_included로 이 PR과 무관.
• 정직성: 시드 지식 중 코드로 검증되지 않은 부분은 검증 가능한 범위로 완화했습니다(예: 메모 본문은 subList가 아니라 메모 요소의 paraList에 위치하며, 여백에 표시되는 텍스트는 MEMO 필드의 subList에서 온다는 실제 구조를 반영).

🤖 Generated with Claude Code