docs: document hp tab support

airmang · airmang · commit 3ba1f908faf7 · 2026-04-01T14:50:46.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 모든 중요한 변경 사항은 이 문서에 기록됩니다. 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)과 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## [Unreleased] - 2026-04-01
+### 변경
+- `hp:tab` 및 `ctrl id="tab"` 지원을 README와 usage 문서에 반영했습니다.
+- `Paragraph.text`, `TextExtractor`, 텍스트/HTML/Markdown exporter가 탭 의미를 `\t`로 보존한다는 점을 문서화했습니다.
+- `preserve_breaks` 옵션이 탭/줄바꿈 평탄화 여부를 제어한다는 설명을 보강했습니다.
+
 ## [2.8.2] - 2026-03-08
 ### 변경
 - README를 현재 공개 API와 CLI 범위에 맞춰 정리했습니다. Quick start, 텍스트 추출, 객체 검색 예시를 실제 호출 방식 기준으로 수정했습니다.
diff --git a/README.md b/README.md
@@ -144,6 +144,8 @@ for obj in ObjectFinder("문서.hwpx").find_all(tag="tbl"):
     print(obj.tag, obj.path)
 ```
 
+`hp:tab`과 `ctrl id="tab"`은 탭 문자(`\t`)로 보존됩니다. 따라서 `Paragraph.text`, `TextExtractor`, `export_text()`/`export_html()`/`export_markdown()` 경로에서 같은 탭 의미를 유지한 채 roundtrip 할 수 있습니다. 필요하면 `preserve_breaks=False`로 줄바꿈/탭을 공백 기반으로 평탄화할 수 있습니다.
+
 ### 🎨 스타일 기반 텍스트 치환
 
 서식(색상, 밑줄, charPrIDRef)으로 런을 필터링해 선택적으로 교체합니다.
diff --git a/docs/usage.md b/docs/usage.md
@@ -1028,11 +1028,13 @@ with TextExtractor("sample.hwpx") as extractor:
             print(text)
 ```
 
+`hp:tab` 또는 `ctrl id="tab"`이 들어 있는 문단도 같은 방식으로 처리됩니다. 예를 들어 `left<tab>right` 형태의 런은 `paragraph.text()`에서 `"left\tright"`로 보이며, `HwpxDocument`로 다시 저장한 뒤 다시 열어도 탭 의미가 유지됩니다.
+
 문단 객체(`ParagraphInfo`)의 `text()` 메서드에는 추가로 다음과 같은 인자를 전달할 수 있습니다.
 
 - `object_behavior`: 표, 도형 등 인라인 개체를 `"skip"`, `"placeholder"`, `"nested"` 중 하나로 처리합니다.
 - `object_placeholder`: 자리표시자 모드를 사용할 때 형식을 지정합니다.
-- `preserve_breaks`: 줄바꿈과 탭을 유지할지 여부를 결정합니다.
+- `preserve_breaks`: 줄바꿈과 탭을 유지할지 여부를 결정합니다. 기본값은 `True`이며, `hp:tab`과 `ctrl id="tab"`은 `\t`로 렌더링됩니다. `False`로 주면 탭/줄바꿈을 공백 기반으로 평탄화할 수 있습니다.
 
 `iter_sections()`와 `iter_paragraphs()` 메서드를 사용하면 원하는 구역에만 접근하거나 중첩 문단을 제외하는 등 탐색 범위를 세밀하게 조정할 수 있습니다.
 
