Make, read, edit and check HWPX (OWPML) and HWP (HWP 5.0) documents for Hancom Office Hangul

version
0.4.0
GitHub stars
34

Install

/plugin install hwpx-docs@blackbuddle

Run it inside Claude Code after adding the marketplace with /plugin marketplace add BlackBuddle/hwpx-docs.

Contents

Discovered from source

Skills 11

gongmun-style — the text of Korean official documents

This skill writes the TEXT of a 공문: tone, words, sentences, and notation inside the text. Layout (page, fonts, boxes, block positions) belongs to the HWPX skill; it reads references/structure.md and references/levels.json from here. Sources: 행정안전부 「2025 행정업무운영 편람」 (S01) and 2011 edition (S10), 「행정업무의 운영 및 혁신에 관한 규정」 and 시행규칙, 한글 맞춤법 (고시), 행정절차법·행정심판법 (appeal notice), 국가기록원 순화어 목록 (S11), 문체부 보도자료 (공공누리 제1유형). Only sources that are free to reuse are cited; every rule in references/ cites a source id or says "convention" (this skill's own judgment).

Procedure

  1. Reader and type. The reader is the 수신처. Several 수신처: write for the least expert one. To citizens, or 공개 구분 공개: write for the general public. Never assume the 수신처 knows your office's own abbreviations. Also fix the type (기안문/시행문, 회신, 내부결재, 보고서, 보도 자료, 안내문/공고문). Reader and type set the ending style (references/phrases.md §0, references/wording.md EN1-EN11) and which words stay (step 4).
  2. Facts. Collect who, when, where, what, how, why, numbers with units, the basis (law, related document). If a fact is missing, ask the user or leave ○○; never invent a number, date, name, document number, recipient department or purpose.
  3. Draft with patterns. Take the title, opening and request sentences from references/phrases.md for that type and purpose. One or two facts per sentence.
  4. Words and grammar. Core rule: keep a word (loanword, Chinese-character word, field term) when this reader understands it and no plain word says the same; if the reader may not understand it, use a plain word of the same meaning, or keep it with a gloss at first use when none exists. Pick the word for the sense in the sentence. Not being native Korean is never a reason by itself; Roman letters only in parentheses after Hangul (통합 인증(SSO)). The tables in references/wording.md list candidates; its §7 explains the rule; fix grammar and spacing (references/grammar.md); write dates, times and amounts by references/notation.md. If a Korean writing-style skill (for example ko-writing) is installed, apply it too, except its rules that conflict with 공문 form (fixed endings, item symbols, short sentences).
  5. Check. Go through references/checklist.md item by item. If Python is available, also run python scripts/check_gongmun.py <file> from this skill's folder (--internal for an internal report; --register general for a non-공문 file) and judge each finding by its meaning.

Most-used rules

  • Endings by reader. Other offices, companies, citizens: ~합니다, ~바랍니다, ~하시기 바랍니다, ~해 주시기 바랍니다, ~해 주십시오, ~알려 드립니다. Never ~바람, ~요망, ~할 것, 있음, 불가함, -하라, 엄금 to them. One ending style per body. Internal 보고서/결재: 개조식 lines (~함., ~임., noun phrase) with full particles. 보도 자료: plain ~다. [EN1-EN14, PH50]
  • Opening. Basis first: 관련: ○○부 ○○과-123(2026. 11. 3.) or 「○○법」 제○조에 따라 …. Then the purpose: ○○을 다음과 같이 알려 드립니다. / ○○에 협조하여 주시기 바랍니다. No basis: start with the act (○○ 교육생을 다음과 같이 모집합니다.). [PH01-PH19, PH102-PH106]
  • Title. Content + kind: ○○ 행사 참석 협조 요청, 2026년 ○○ 교육 계획 알림, ○○ 결과 보고; not ○○ 관련 건. [PH35, PH36, PH113, PH114]
  • Stock phrases. 만전을 기할 -> 최선을 다할, 철저를 기하여 -> 철저히 하여, 확행 바랍니다 -> 꼭 하시기 바랍니다, 적의 조치 -> 적절한 조치, ~에 의거하여 -> ~에 따라, 시행코자 -> 시행하고자, 통보 바람 -> 알려 주시기 바랍니다, 엄수할 것 -> 꼭 지켜 주시기 바랍니다, ~하지 않을 수 없습니다 -> ~해야 합니다. [PH71-PH101, PH126-PH136]
  • Words. 금일 -> 오늘, 금번 -> 이번, 상기 -> 위의, 익일 -> 다음 날, 송부 -> 보냄, 감안 -> 고려, 제고 -> 높임, 용이 -> 쉬움, 제반 -> 여러, 향후 -> 앞으로, 통보 -> 알림, 가이드라인 -> 지침, 우천 시 -> 비가 오면, 매뉴얼 -> 설명서 / 업무 지침 (by context), 테스트 베드 -> 시험대. Replace them in titles, headings and item labels too (향후 계획 -> 추진 계획), and also when the user's own request uses them. Kept with a gloss for citizens: 송달; kept: 스타트업, 로그인, 홈페이지, 세미나. [wording.md §3-§3d, §7, G41]
  • Sentences. Split at ~인바, ~하며,; link with 이에. No comma right after a connective ending: 개최하며, 축제를 -> 개최하며 축제를, 모집하오니, 재학생이 -> 모집하오니 재학생이. Active voice, no ~에 의해, ~에 있어서, ~되어지다, 보여지다, 개선시키다, 회의를 가졌다. The reader 제출s, the office 접수s. [G30-G45, PH20, PH107-PH110, wording.md §4]
  • Notation. 2026. 11. 14.(토), 14:00, 14:00~16:00, 일시: …, 금113,560원(금일십일만삼천오백육십원) for a formal amount, 2,134만 5천 원 for the public, 10만 톤, 50여 명, 총 28건. Event and project names in ‘ ’ or no marks; 「 」 only for laws. Labels 수신, 제목, 붙임 take two spaces, no colon (수신 내부결재). [N02-N13, G19, G22, G46, structure.md §5]
  • Spacing. Spaced: 계약 시, 승인 후, 기한 내, 추진 중, 기관 간, 연체 여부, 15세 이상, 및, 등. Attached: 2개월간, 20일경, 제4장, 재교육, 것뿐, 그동안. [G20-G29]

Tone only (chat replies, notices without layout)

When only the 공문 tone is wanted (for example in chat replies), apply the endings, words and sentence rules above. Do not add 수신, 제목, item symbols, 붙임 or 끝.. Keep everyday notation (오전 11시 40분 is fine). Example: 오늘 점심 메뉴를 다음과 같이 알려 드립니다. 메뉴는 김치찌개로 정하였습니다. 11시 40분까지 식당 앞에 모여 주시기 바랍니다.

References (stable file names)

  • references/phrases.md — sentence patterns by document type and purpose, titles, address words, stock phrases (PH01-PH136).
  • references/wording.md — ending rules (EN), word tables P (2025 편람 list, 1993 list S11, pairs selected by this skill), T (translation style, stock forms), A (overbearing), X (discriminatory).
  • references/grammar.md — content rules, spelling, spacing, sentence grammar, plain Korean, reader's side (G01-G53).
  • references/notation.md — date, time, money, numbers, units, punctuation (N01-N19).
  • references/checklist.md — the final check, in order.
  • references/structure.md, references/levels.json — block ids, item levels L1-L8, 끝./붙임 cases (shared with the HWPX skill; do not rename ids).
  • references/sources.md — every source with URL, date and the rules from it.
  • scripts/check_gongmun.py — optional checker; --selftest must say ok after any table change.
  • MAINTAINING.md — how to update this skill.

Limits

  • Statutes were read from mirrors while law.go.kr was down (2026-11-14); check exact wording there before you quote an article.
  • No official source fixes a list of 개조식 endings or a sentence-length number; those rules are marked "convention".

HWPX and HWP core

hd below = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py" (Python 3.10+, standard library only).

Every document is made from the same primitives (page, paragraphs, runs, tables, shapes, pictures), written by one builder from a JSON spec. There are no per-form templates in code. The XML forms come from files saved by Hangul 2024 and are checked by round trips. Spec format: ${CLAUDE_PLUGIN_ROOT}/docs/spec.md.

HWPX and HWP

Both formats take the same commands. Name the output .hwp instead of .hwpx (hd build spec.json out.hwp, hd md, hd html) and the document is written as HWP 5.0 with no Hangul; a received .hwp goes to slots, edit, guard, text, read, preview, pagefit, readability the same way as a .hwpx. The table of every command and how it reaches a .hwp is ${CLAUDE_PLUGIN_ROOT}/docs/hwp-parity.md. A .hwp write that meets an object or value it does not know (none of the tested files shows it) stops with UNSUPPORTED <element> and writes nothing: then make the HWPX and hd convert it with Hangul. Never name a ZIP .hwp.

Which skill

input or taskskill
fonts, paragraph spacing, links, notes, Markdown or HTML input, readabilityhwpx-text
tables (merges, lines, fills, sizes)hwpx-table
boxes, lines, text boxes, pictures, chartshwpx-objects
page size, margins, columns, header/footer, page numbershwpx-page
an image of a form, "make it the same as this"hwpx-from-image
fill or change a received HWPX (keep its look), HWPX to text or Markdownhwpx-edit
공문 (기안문, 시행문), 개조식 보고서hwpx-gongmun (text rules: gongmun-style)
Hangul's file-access prompt, passwordshwpx-security
"읽기 좋게", 쪽 넘김 줄이기, 표 안 끊기게, 쪽 꽉 차게 (only when asked)hwpx-readability

Build and check (every time)

  1. Write spec.json (docs/spec.md). Use measured values (mm, pt), not guesses. Repeated looks: styles + class.
  2. hd build spec.json out.hwpx — it also prints the readability findings (RDnn ..., READABILITY ...).
  3. A new document: apply the safe fixes (hd readability spec.json --fix spec.json, then build again) and tell the user the advice items. A reproduction: report the findings, change nothing (skill hwpx-text).
  4. Windows + Hangul only, and only when you ask for it: hd render hwpx out.hwpx pages/ --backend hangul (Hangul opens a safe copy: no macros, no links to outside) -> OPEN OK <file> pages <n> and pages/out_p<N>.png. Before it, tell the user in one line: how many files, and that Hangul may ask once for file access ("모두 허용").
  5. Compare with the target (hd render side, hd img overlay), fix, repeat. Give the user the HWPX and a PNG.

Read an existing file: hd read in.hwpx spec.json (unknown elements come out as raw {"xml": ...} and are written back as given). Change the JSON, then hd build. To change only the text of a received file, use skill hwpx-edit instead: it keeps every other byte.

Facts that matter most (${CLAUDE_PLUGIN_ROOT}/docs/rules.md)

  • Table cols/heights are outer cell sizes. A block table starts 1 mm right of the text area (outer margin): "margin": 0 aligns it with the text.
  • Body text starts at top margin + header length. Default page: A4, margins 20/20/20/15, header/footer 15 mm.
  • Paragraph spacing is in pt; line spacing 160 % = 1.6 x font size per line.
  • ○ □ ☐ ※ · are SYMBOL characters: font sets all 7 language fonts, so they follow it.
  • Never answer Hangul's file-access prompt by code and never change Hangul security settings (skill hwpx-security).

Files

  • docs/spec.md (spec), docs/rules.md (XML rules + evidence), docs/coverage.md (every Hangul feature C1-C14; its builder column names the spec key of each feature), docs/interfaces.md (functions of each module). The keys of the feature packages (master_pages, text_direction, dropcap, named_styles, toc, form, object ...) are in docs/spec.md section "More keys of the feature packages"; each skill lists the keys of its area.
  • lib/hwpx_docs/ modules core, text, table, objects, page, edit, extract, render, check (a feature package registers its own commands and self-test: docs/interfaces.md); hd selftest runs every self-test and the 271 fixture round trips (tests/fixtures).

Edit an existing HWPX or HWP

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". A received form keeps its look only if nothing but the text changes. These commands change text only; every table, style, picture and ZIP entry stays as it is.

  1. hd slots form.hwpx -> one line per slot: p3 (body paragraph), t1.r2c4 (table 1, row 2, column 4), o2 (header/footer/note/text box), with [label] when a short cell names that slot (the empty cell to its right, or below).
  2. Write values.json with slot keys or labels: {"성명": "가람", "t1.r3c2": "000-0000-0000", "p5": "새 문단"}. \n = next line.
  3. hd edit form.hwpx filled.hwpx --values values.json [--set KEY=TEXT] [--replace OLD=NEW] [--check 동의함]. An unknown key or label stops with UNMATCHED (nothing written) unless --allow-missing. It prints the guard.
  4. Guard (also alone): hd guard form.hwpx filled.hwpx [--forbid 옛기관명] [--require 새기관명] [--max-unchanged 0.35]
    • STRUCTURE: same paragraphs, tables, cell grid, objects, styles.
    • BUDGET: a changed paragraph or cell that needs more lines -> its row or the body grows (pages can move). Shorten the text, or tell the user.
    • RESIDUE: forbidden words, missing required words, placeholders (○○, {{..}}, XXX, ___), unchanged sentences.
  5. Render (skill hwpx-core; tell the user first that Hangul may ask once for file access) and compare with the original page.

Rules: never rebuild a received form from scratch to change its text (the look changes); never edit inside text boxes or charts with --set unless the user asks (they are o slots); the edited paragraphs lose their line layout cache, which Hangul rebuilds; the preview picture is replaced with a blank one so no old text stays in the file.

A received .hwp (HWP 5.0, not HWPX): the same commands and steps with the file name changed, no Hangul unless you ask for --backend hangul — hd slots form.hwp, hd edit form.hwp filled.hwp --values values.json, hd guard form.hwp filled.hwp --render pages/. hd edit changes text only and keeps every other byte of the file. In a paragraph with a 누름틀 the value goes inside the field. The guard also draws both files (COMPARE PAGE n TEXT = only text changed, FORM = lines or boxes moved: the form changed; pages/<name>_compare.html shows where). Password, 배포용, DRM and 한글 97 files are refused. To add rows or paragraphs (hd edit never does): hd hwp tohwpx f.hwp f.hwpx, hd read f.hwpx s.json, change the JSON, hd build s.json out.hwp (no Hangul; stops with UNSUPPORTED <element> only for an object or value the .hwp writer does not know). hd preview f.hwp out/ draws a .hwp with no Hangul, and so do hd hwp compare and hd guard --render unless you give --backend hangul (Windows; Hangul then opens a safe copy with the scripts blanked and the linked pictures removed, and may ask once for file access). A macro (script) of the received .hwp stays in the edited file; hd edit f.hwp out.hwp ... --drop-scripts blanks it (for a file you do not trust). Form objects of a .hwp (check boxes, radio buttons, lists): hd form list f.hwp works; hd form fill f.hwp out.hwp writes through the same route (UNSUPPORTED <element> only for an object or value that is not known).

Other tools:

  • hd text in.hwpx [--md] [-o out.md] — text or Markdown (tables as Markdown tables, footnotes as [^n]).
  • A whole new document in the same look: read it as a spec (hd read) or make a preset (skill hwpx-text).
  • Form objects (check boxes, radio buttons, lists, edit boxes made with Hangul's 양식 개체): hd form list in.hwpx, then hd form fill in.hwpx out.hwpx --set name=value [...] (hd edit does not change them). Spec key form: docs/spec.md "Fields and references".
  • Hide personal data in a received file before it goes out: hd secure in.hwpx out.hwpx --mask-private (skill hwpx-security).

Form from an image

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Full procedure, checklist template and lessons: ${CLAUDE_SKILL_DIR}/references/image-to-hwpx.md. Read it before you start.

Short form:

  1. Save the target as PNG (hd render topng target.jpg target.png); find the paper size (default A4 portrait).
  2. hd measure target.png --page-mm 210 -> H/V lines, GRID, COLS/ROWS (table widths, heights), INK (margins), text bands. Font size from a line of N Korean characters L mm long: size_pt = L / N / 0.3528.
  3. Copy the text exactly; new text by skill ko-writing (공문: gongmun-style).
  4. Write the checklist (one row per visible element) BEFORE the spec; hd check out.hwpx checklist.md reads it.
  5. hd build form.json form.hwpx, hd check, hd render hwpx form.hwpx out/, then hd render side side.png target.png out/form_p1.png and hd img overlay ov.png target.png out/form_p1.png. Fix the spec where red/blue pairs show an offset; repeat.
  6. hd readability form.hwpx: report the findings to the user; do not change the target's look.
  7. Give the user the HWPX and the side-by-side PNG.

Rules from tests: match glyph height first (font size), then line width with 자간/장평, never by smaller cell margins; copy every visible line break; never add a fill that you cannot see; a gradient bar = its mean colour. No per-form templates: every form uses the same spec primitives (docs/spec.md); an element with no spec key -> closest primitives, or hd read an HWPX that has it (raw XML passes through), and note the gap.

공문 and 개조식 보고서

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Layout only: the wording, item symbols, dates, 붙임 and 끝. follow skill gongmun-style (${CLAUDE_PLUGIN_ROOT}/skills/gongmun-style/). Check the text with python "${CLAUDE_PLUGIN_ROOT}/skills/gongmun-style/scripts/check_gongmun.py" <text file>.

공문 (기안문, 시행문, 내부결재)

  1. Copy ${CLAUDE_PLUGIN_ROOT}/templates/gongmun.json (A4, top 30, bottom 15, left 20, right 15 mm; named styles; a skeleton body). Replace every ○○ and delete the blocks that you do not need: the 수신자 line only stays with 수신자 참조, the 협조자 line only with a 협조자. Official: the A4 size, the fields and their order, the label words. Convention (the 편람 states no margin, font, size or line value for a 기안문): margins, 휴먼명조 12 pt, the sizes and lines. The table is ${CLAUDE_PLUGIN_ROOT}/docs/gongmun-defaults.md.
  2. Items: one block per item with "class": "l1" ... "l8" and the symbol written in the text: L1 1. L2 가. L3 1) L4 가) L5 (1) L6 (가) L7 ① L8 ㉮ (levels.json). Each level starts 2타 further right; wrapped lines align to the first letter of the item text. The classes carry hang (the level): the builder measures the widest mark of each level in the list (10. is wider than 1.), writes one TAB after the mark and sets the hanging width, so no indent is measured by hand for any font or size. Write the mark and one space in the text ("p": "10. 안건"); do not write a tab or two spaces. A level with one item has no symbol. 가나다... continues with 거너더... after 하.
  3. 붙임 and 끝. (levels.json A1-A2, E1-E6): several 붙임 use attach (붙임 1. ...) and attach_next (2. ...), one 붙임 without a number uses attach_one (붙임 ○○○계획서 1부.); the classes keep the wrapped lines and the next items on one text column. 끝. goes 2 spaces after the last text; with 붙임 after the last 붙임 line; after a table whose last cell is filled, on its own line below the table; a table that ends early gets 이하 빈칸 in the next cell and no 끝..
  4. 결문 (closing block), official order and words: 발신명의 (centred; 관인생략 or 서명생략 may stand right of it), 수신자 line, then 직위 이름 for each signer WITHOUT the words 기안자, 검토자, 결재권자 (협조자 직위 이름 keeps its word; 전결 or 대결 go in the signer's cell), 시행 처리과명-연도별 일련번호(시행일) 접수 ...(접수일), 우 우편번호 도로명주소 / 홈페이지, 전화번호 (지역번호)... 팩스번호 (지역번호)... / 전자우편주소 / 공개 (공개, 부분공개( ) or 비공개( ) with the 정보공개법 제9조제1항 clause number). Not in the template and optional: the agency logo (2 cm x 2 cm, left end of the 행정기관명 line) and a slogan right above it.
  5. hd gongmun-check spec.json (official fields and wording, GM01-GM05), hd build, hd readability, render (skill hwpx-core), check the text with check_gongmun.py.

Hangul-made 공문 samples to read as a start (hd read <file> spec.json): ${CLAUDE_PLUGIN_ROOT}/tests/fixtures/ gongmun.hwpx (기안문), gongmun_sihaeng.hwpx (시행문, several 수신), gongmun_gyeoljae.hwpx (결재란), gongmun_gongo.hwpx (공고문), gongmun_bodo.hwpx (보도자료), gongmun_tongji.hwpx (통지서).

개조식 보고서

Markdown -> hd md report.md report.hwpx (preset report-gongmun: title box, chapter bars, □ ○ - · items, grid tables). Markdown subset and presets: skill hwpx-text (references/presets.md).

HWPX objects

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Spec: ${CLAUDE_PLUGIN_ROOT}/docs/spec.md sections "Shape", "Chart" and the pic block; rules S25, G01-G02 in ${CLAUDE_PLUGIN_ROOT}/docs/rules.md; status in ${CLAUDE_PLUGIN_ROOT}/docs/coverage.md C6.

  • Shapes: a block {"shapes": [...], "p": "optional text"} anchors floating objects to that paragraph. x, y are mm from the paper (or rel: page|para) top-left corner. Types: rect (with text = text box, round, fill, line), ellipse, line (x2, y2, arrow). Use shapes for anything that is not text or a table grid: free boxes, rules, circles, stamps, check marks.
  • Pictures: {"pic": {"src": "a.png", "w": 40, "h": 30, "inline": true}}, path relative to the spec file; PNG, JPEG, GIF or BMP; the file is embedded (BinData).
  • Charts: {"chart": {"native": true, "type": "bar|hbar|line|pie|combo", "w": 140, "h": 80, "categories": [...], "series": [{"name": ..., "values": [...], "color": "#4472C4"}], "title": ..., "x_title": ..., "y_title": ..., "legend": "right|bottom|false", "labels": true}} makes a real Hangul chart object: the user edits the data ("차트 데이터 편집"), type and style in Hangul (rules 5b CH01-CH11). Without "native": true the builder draws the chart with shapes (bar or line only; grid, axes, labels, legend): vector and editable, but not a chart object; it is also the automatic fallback (FALLBACK chart: <reason>). Example (shapes): ${CLAUDE_PLUGIN_ROOT}/examples/chart-report/.
  • Equations are runs ({"equation": "a over b"}, skill hwpx-text).
  • More chart kinds: type: "area" (stacked), type: "scatter" (categories = x numbers, lines, x_min, x_max), a second value axis with axis: "secondary" on a series (y2_title, y2_min, y2_max); keys in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/chart/spec.md.
  • More object keys (docs/spec.md "More keys of the feature packages" > "Objects"; rules OB01- in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/objects2/rules.md): picture bright, contrast, effect, crop, border; caption on pictures, shapes, objects; position hrel, halign, vpos, flow, overlap, wrap side side, same_para; block object with kind polygon, curve (펜), connector, textart (글맵시), group; block ole (embedded file); run item proof (교정 부호).

Check: hd build, then render (skill hwpx-core) — floating objects can only be checked on the page image.

HWPX page

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Spec: ${CLAUDE_PLUGIN_ROOT}/docs/spec.md section "Document"; rules S01-S08, S12, S15-S18 in ${CLAUDE_PLUGIN_ROOT}/docs/rules.md; status in docs/coverage.md C4, C10.

{"page": {"size": "A4", "landscape": false,
          "margin": {"left": 20, "right": 20, "top": 20, "bottom": 15, "header": 15, "footer": 15, "gutter": 0}},
 "columns": {"count": 2, "gap": 8, "line": "0.12mm solid", "type": "newspaper|balanced|parallel"},
 "header": ["머리말"], "footer": {"blocks": ["꼬리말"], "apply": "both|even|odd"},
 "page_number": {"pos": "bottom_center", "format": "digit", "side": "-"},
 "page_border": {"border": "0.4mm solid", "offset": 5, "text_border": "paper|content"},
 "body": [...]}
  • size: A4 (Hangul's own 59528 x 84186 hu), A3, A5, B4, B5, LETTER, LEGAL or [width, height] mm.
  • The body starts at top margin + header length (S05): to put the first line at 30 mm with a 10 mm header, set top 20.
  • Several setups (portrait then landscape): {"sections": [{"page": ..., "body": [...]}, ...]}.
  • Page break: block {"page_break": true} or "page_break": true on a paragraph or table block; column break: "column_break": true. Keep headings with their text: "keep_next": true.
  • 공문 margins (시행규칙 서식): top 30, bottom 15, left 20, right 15 mm (skill hwpx-gongmun).

More page keys (docs/spec.md "More keys of the feature packages" > "Page"; rules PX01- in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/pagex/rules.md):

  • odd / even pages: header_odd, header_even, footer_odd, footer_even;
  • 바탕쪽: master_pages ([{"type": "both|even|odd|last|optional", "body": [...]}]);
  • vertical writing: text_direction (vertical, vertical_all), vertical_head;
  • line numbers line_numbers; 원고지 manuscript, char_grid, line_grid; 주석 모양 note_shape;
  • hide on the first page hide_first; blocks hide_page (hide header, page number ... on one page) and columns_here (change the columns inside a page); a label sheet is a table block with page.margin.
  • After a fix of the page flow, skill hwpx-readability (hd pagefit) checks where the pages break (only on request).

HWPX and HWP readability (pagefit)

hd pagefit check|fix and hd readability take a .hwp as well as a .hwpx; pagefit fix in.hwp out.hwp writes a new .hwp through HWPX.

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Use it only when the user asks for it ("읽기 좋게", "쪽 넘김 줄이기", "표 안 끊기게", "가독성", "쪽 꽉 차게"). Never run it after a normal build (md2hwpx, hd build) on your own: this is the user's reading style.

Profile = the style

profilewhat it does
readableuse this for the requests above: reading units (heading + first content, item + sub items, table or figure with caption / introduction / notes, summary box, 붙임, last paragraph + 끝. + 결문) stay on one page; a long table is cut between rows with the header repeated and 3 rows at least in each part; pointers ("표 3 참조", page numbers) and footnotes that go on are reported; free space goes into paragraph and table spacing; a page break always goes before the heading and introduction that keep with a table (Hangul does not carry a heading over a break); a table of a third of a page or more that would leave 40 mm or more empty above it is cut between rows (header repeated) instead of moved whole; fixed row heights stay (freeing them made text lines overlap in Hangul)
minimalthe least change (heading keeps with the next paragraph, no single lines, forced breaks after a mostly empty page, short last page); what hd pagefit does with no --profile
own file--profile my.json: copy lib/hwpx_docs/pagefit/profiles/readable.json, keep "extends": "readable" and write only the keys that change (format: lib/hwpx_docs/pagefit/profile.py); hd pagefit profiles [name] prints a profile in full

Ask the user once whether they have their own profile file; if not, use readable.

Steps

  1. Check: hd pagefit check <file.hwpx|spec.json> --profile readable. Show the findings (page numbers, what makes the reader turn the page, how empty a page is) in the user's language.
  2. Fix into a NEW file, never over the original: hd pagefit fix <in> <out.hwpx> --profile readable (prints before, the changes, after). Text, text size and the order of the content never change; only keep flags, page breaks and paragraph / table spacing do.
  3. Check in Hangul when it is installed: hd render hwpx <out.hwpx> <dir> --backend hangul (hidden Hangul, one batch, on a safe copy) and compare the page count with the one fix printed. The page layout of pagefit follows Hangul within 1 mm on the documents measured; footnote pages are less exact.
  4. Report what is left: a page that stays empty (a unit that does not fit the free space), a sentence that points at a table on another page, a pointer to a page number ("3쪽", "다음 쪽": the numbers may have moved), a footnote that goes on, a table without header rows. These need the user's decision, not a bigger change.

Limits: vertical-writing sections are skipped; the preview, not Hangul, computes the pages (steps 1-2), so step 3 is the proof.

Hangul security

The file-access prompt

Hangul 2024 asks "한글을 이용하여 위 파일에 접근하려는 시도 ..." (접근 허용 / 모두 허용) when an automation script OPENS an existing file (render, verify, round trip). Making or reading an HWPX with hd build, hd read, hd md, hd html needs no Hangul and shows no prompt.

  • Only the user answers it. Never click it by code, never change Hangul security settings, never install or register a DLL for the user.
  • The scripts open all files of one batch in ONE Hangul and wait up to 300 s for the answer (HANGUL ACCESS PROMPT ...). With no answer they close it (= deny) and stop the batch.
  • Before each render or check batch, tell the user in one line: how many files, and that one "모두 허용" click is expected.

Optional: no prompt (the user does it)

Hancom publishes an official automation security module (developer.hancom.com/hwpautomation, section "보안 승인 모듈"). The user downloads it from that page, puts the DLL in a folder, adds a REG_SZ value under HKEY_CURRENT_USER\Software\HNC\HwpAutomation\Modules (name: any, data: the DLL's full path) and sets the environment variable HWPX_DOCS_SECURITY_MODULE (old name HWPX_DOCS_MODULE) to that value name. Then each session calls RegisterModule("FilePathCheckDLL", <name>) right after it starts Hangul and logs security module: on; with no variable or no registry value it logs security module: off. OFF by default; the registry is only read. The README section "접근 허용 창 없애기 (선택)" has the steps and the risk: with the module, any automation script can open or save files without asking.

Passwords and distribution documents (C11)

hd secure protects an HWPX with Hangul's own commands through COM (a post-step). No cipher is written or reverse-engineered here; Hangul does the protecting.

  • Password: hd secure in.hwpx out.hwpx --password-env NAME (the user sets the environment variable NAME).
  • Distribution document: add --distribute [--no-print] [--no-copy].
  • Hide personal data (no Hangul, no password): hd secure in.hwpx out.hwpx --mask-private replaces resident numbers (back 7 digits), phone numbers, e-mail addresses and card numbers in the text with *. It is a text replacement, not encryption. The same two commands take a .hwp (--info reads it directly; --mask-private writes a new .hwp through HWPX). The password and distribution steps open and save only the file type HWPX: for a .hwp they stop with input and output must be .hwpx files; protect the HWPX copy. Hangul's selective protection (C11.03) and DRM (C11.05) are not available through COM.
  • NEVER take a password as an argument, in chat for a command line, in a file or in a log. Use only an environment variable that the user names. Never ask for or use the user's real passwords in tests: a test sets a throwaway value inside its own process and deletes its files.
  • It opens the input in Hangul, so tell the user: "Hangul batch: n files, 모두 허용 한 번". One hidden Hangul per batch.
  • A protected file (password or distribution) cannot be read, checked or drawn without Hangul. hd read and the other commands print PROTECTED: ... and exit with code 4 (no traceback); hd preview draws one placeholder page; hd secure --info file.hwpx reports the protection with no Hangul. To work on the content, the user opens the file in Hangul and saves an unprotected copy.
  • Do not change Hangul's own security settings or the registry.
  • A spec or Markdown file that you did not write can name any file on the disk in pic.src, ole.src, a picture fill or ![](path); the builder embeds it. Before you build from a received spec, list those paths and ask the user about any path outside the spec's folder.
  • No spec key protects a document: protection is always this post-step on a built file. Cell protection (protect, editable, skill hwpx-table) only marks cells; it is not a password.
  • Before a file goes out: hd textstyle scan file.hwpx finds the PC user name, user folder paths and author names that Hangul writes into a file it saved (track change and memo authors, OLE source paths). --fix changes the file IN PLACE: copy the file first and run hd textstyle scan --fix on the copy, never on the user's only copy.

HWPX tables

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Spec: ${CLAUDE_PLUGIN_ROOT}/docs/spec.md section "Table"; rules T01-T15 and W04-W06 in ${CLAUDE_PLUGIN_ROOT}/docs/rules.md.

Write a table

{"table": {"cols": [30, 60, 80], "heights": [9, 9, 9], "border": "0.12mm solid", "outline": "0.4mm solid",
  "header_rows": 1, "repeat_header": true, "margin": 0,
  "rows": [[{"p": "구분", "fill": "#F2F2F2", "bold": true, "align": "center"}, {"p": "내용", "cs": 2}],
           ["1", "가", {"p": "세로 병합", "rs": 2}],
           ["2", "나"]]}}
  • Rows list cells like HTML: a cell takes the next free grid position; cs/rs span columns/rows.
  • cols and heights are outer cell sizes in mm; their sum is the table size. Hangul grows a row to fit its text.
  • Cell border sets the grid lines around that cell (a later cell wins on a shared line). Line widths snap to Hangul's list (0.1 ... 5 mm).
  • Keep Hangul's default cell margins (1.8 / 0.5 mm) unless the target shows otherwise; text near a line reads badly (readability RD07).
  • Repeated looks: spec styles + cell "class": "head".
  • Space before or after a block table: use the table margin (top, bottom) or a gap block; Hangul ignores the anchor paragraph's before (rule W05).
  • Long tables: header_rows + repeat_header (readability RD10). A table is treated as a character (inline true) unless it has pos, wrap, side, hold, header_rows, page_break: "cell" or is about as high as a page: those flow and Hangul cuts them between pages. Write "inline": false to make any table flow, "inline": true to keep a tall one as a character (rule TB11).

More table features (rules TB01-TB11 in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/table/rules.md)

  • Cell fill: a colour, a gradient {"type": "gradient", "kind": "linear", "angle": 90, "colors": [a, b]} (give 2 colours; Hangul draws 3 black) or a picture {"type": "image", "src": "a.png", "mode": "tile"}.
  • Table caption: {"text": "제목", "side": "bottom"} (auto number "표 1"). Floating table: pos with rel / vrel / hrel, halign, valign, wrap. Cell protect, and formula (=SUM(?1:?3); the shown result goes in p, the builder does not calculate).
  • Line types in border: 18 names, the last six (wave doublewave thick3d thickrev3d 3d rev3d) are drawn solid in the preview.
  • Text beside a square-wrapped floating table: side (both_sides, left_only, right_only, largest_only); a floating table that shares its paragraph with text: same_para (reader rule S26). All table keys: docs/spec.md "Table" and its list "More table keys".
  • A long table on a page: skill hwpx-readability (hd pagefit) cuts it between rows with the header repeated (on request).

Check

hd build, then hd check out.hwpx checklist.md with rows such as table[0].cols, table[0].heights, text("구분").cell.fill (query forms: skill hwpx-from-image), then render (skill hwpx-core).

HWPX text

hd = python "${CLAUDE_PLUGIN_ROOT}/lib/hd.py". Spec keys: ${CLAUDE_PLUGIN_ROOT}/docs/spec.md sections "Runs", "Char props", "Para props".

Markdown and HTML

  • Markdown: hd md in.md out.hwpx [--preset <name|file.json>] [--fallback] [--keep] (default preset report-gongmun). Exit 2 with UNMAPPED line <n>: ... = the preset has no style for that element: add it to the preset MAP, or rerun with --fallback (nearest preset style -> core feature -> plain text; one FALLBACK line each). Presets, extending them, new presets from an HWPX or an image: ${CLAUDE_SKILL_DIR}/references/presets.md.
  • HTML of any design: hd html in.html out.hwpx [--spec out.json]. It computes the CSS like a browser in print mode (cascade, specificity, inheritance, @media print, @page) and lists what it does not use as UNSUPPORTED. Judge the result against the browser print: hd render html in.html out/ (Edge; outside a sandbox).
  • The other way: hd text in.hwpx --md gives Markdown of an HWPX (skill hwpx-edit).

Readability

hd readability <file.hwpx|spec.json> [--fix fixed.json] prints RDnn <where>: <problem> and READABILITY ....

  • A reproduction (image, HTML, an existing form) keeps the target's look: report the findings, change nothing (hd html does this).
  • A new document (Markdown, a description) gets the safe fixes: word break, line spacing, contrast, cell margins, keep-with-next headings, repeated table headers (hd md applies them unless --keep). Tell the user the advice items (gaps in justified lines, small text, long lines, heading spacing).

More text keys (docs/spec.md "More keys of the feature packages": "Text and styles", "Fields and references")

  • Tab stops tabs ([{"pos": mm, "type": "left|right|center|decimal", "leader": "dot"}], \t in the text); Hangul's style list named_styles (document) + style (block, cell, run; next, type: char); drop cap dropcap (block); 덧말 and 한자 병기 dutmal (run); picture bullet bullet_image; latin_break, word_break. Rules TS01- in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/textstyle/rules.md.
  • Fields: cross-reference xref (run), table of contents toc (block), index index_mark (run) + index (block), form objects form (run; hd form list|fill), track changes change (run), 누름틀 field. Rules F01- in ${CLAUDE_PLUGIN_ROOT}/lib/hwpx_docs/fields/rules.md.
  • Equations {"equation": "a over b"} (run, Hangul equation script).

Facts (docs/rules.md H, W)

  • Korean line break names are inverted: word_break: "word" = 어절 (break at spaces), "char" = 글자 (Hangul's default). Text that wraps only between words needs "word".
  • Negative indent = hanging: the first line starts at left, the wrapped lines at left + |indent|.
  • condense (공백 최소값) changes where justified lines break.
  • List items: put "hang": <level> on the block or its class and write "mark text"; the builder puts the text of the first line and of the wrapped lines on one column (a tab after the mark, docs/spec.md, H27). Markdown lists and HTML ul/ol get it from the converter; a sub-level mark starts under the text of its parent (report preset).
  • A space is 0.5 em wide in Hangul unless font_space is set; the 자간 (spacing) is a % of the advance of each character, spaces included (H28).
  • RD14: a wrapped paragraph whose last line is short (under 30 % of the line, or 2 words or fewer under 60 %) is fixed by the 자간 of the paragraph (tighten to -8 %, else loosen to +4 %) in a new document (hd md; --keep and hd html print it as advice). Table cell text: justified by default in the report preset (td JUSTIFY, so a wrapped line reaches the right edge), centred vertically (Markdown) or as CSS says (HTML), by Hangul's own vertical alignment; CSS height on a cell or row is a minimum row height (H30, W12, W13).
  • Write all Korean text that you make (not copied text) by skill ko-writing if it is installed; 공문 text by skill gongmun-style. This skill does layout.

Sponsors

Details

Marketplace
BlackBuddle/hwpx-docs
Category
Community

More from BlackBuddle/hwpx-docs

All 3