genetics-mcp 2.9.1 → 2.9.2

package/skills/genetics-report/references/font-embedding.md

@@ -1,161 +1,185 @@
 # 폰트 임베드
 
-## 왜 심는가
-
-산출물은 **외부 리소스 0인 단일 HTML** 이다. 웹폰트 CDN 을 쓸 수 없다.
-그렇다고 시스템 폰트 스택에 맡기면 고객 PC 환경에 따라 문서가 이렇게 갈린다.
+## 결론 먼저 — 고를 자리가 없다
 
-| 환경 | 폴백 결과 |
-|---|---|
-| macOS | Apple SD Gothic Neo |
-| Windows | 맑은 고딕 |
-| Pretendard 설치된 PC | Pretendard |
+**서식이 폰트를 정한다.**
+`report.json` 에 `font` 를 적어도 두 경로 모두에서 버려진다.
 
-세 폰트는 자족폭·굵기 인상·숫자 모양이 전부 다르다. 실측하면 같은 문장의 폭이
-Pretendard 879.88px vs Apple SD Gothic Neo 846.08px 로 4% 벌어진다. 줄바꿈 위치가
-달라지고, 표지 제목의 인상이 통째로 바뀐다. **보고서를 인쇄하거나 PDF 로 만들면 더 벌어진다.**
+| 경로 | 무슨 일이 일어나는가 | 근거 |
+|---|---|---|
+| 로컬 렌더 | `cfg.update(t['lim-report'])` 가 `font` 키를 통째로 교체 | `assets/render.py:157-158` |
+| 포털 발행 | `font` 가 `REPORT_CLIENT_KEYS` 에 없어 `report_client_fields()` 가 깎아 냄 | `report_publish.php:31-` |
 
-그래서 base64 로 문서 안에 심는다. 용량이 곧 파일 크기이므로 무엇을 넣을지가 설계 문제가 된다.
+그래서 `font.embed: false` 도 안 먹는다 — 교체된 블록에 `embed` 키가 없어 기본값 `True` 로 돌아간다.
+(`SKILL.md:311` 의 「`font.embed: false` 로 끌 수 있다」는 死文 — 그 파일은 이 문서의 담당이 아니라 적어만 둔다.)
 
-## 지금 들어 있는 것
+폰트를 바꿀 이유가 생기면 그것은 **서버 등록부를 고치는 일**이다.
+문서 데이터에서 할 일이 아니다.
 
-`assets/fonts/pretendard-report.woff2` — **300,544B**
+## 지금 실리는 것
 
-| 항목 | 값 | 근거 |
+| 항목 | 값 | 확인 |
 |---|---|---|
-| 폰트 | Pretendard v1.3.9 Variable | SIL OFL 1.1 · 상업 사용·임베드 자유 |
-| 축 | `wght 400–700` 으로 제한 | CSS 가 쓰는 굵기는 400/500/600/650/700 뿐 |
-| 커버리지 | KS X 1001 완성형 2,350자 + 라틴·기호 (총 2,481자 / 2,550 글리프) | 아래 표 참고 |
-| 레이아웃 피처 | `ccmp locl kern mark mkmk calt clig liga rlig tnum case` | **`tnum` 이 핵심** |
-| 힌팅 | 제거 | 화면·PDF 모두 힌팅 없이 충분 |
+| 파일 | `private/builder/fonts/pretendard-gazette.woff2` | `report_publish.php:872` |
+| 크기 | **409,044B** · 1면 | `ls` · 렌더 로그 |
+| 패밀리 | **Pretendard GOV** | `report_publish.php:869` |
+| 축 | **wght 300–700 가변** | `'weight' => '300 700'` |
+| 라이선스 | Pretendard · SIL OFL 1.1 | CSS 첫 줄 주석으로 실림 |
+
+예시 문서를 실제로 구운 결과다.
+
+```
+폰트 임베드 1면 409,044B → base64 545,392B
+생성 · 예시-보고서.html  659,164 B
+```
+
+문서의 **83%가 폰트**다.
+대신 외부 요청이 0이다 — 산출물에서 `http(s)` 로 나가는 `src`·`href` 0건을 실측했다.
+
+## 왜 심는가
+
+시스템 폰트에 맡기면 같은 문장의 폭이 환경마다 갈린다.
+같은 문자열을 64px 로 재면 이렇다.
+
+| 폰트 | 폭 |
+|---|---|
+| Pretendard GOV (임베드본) | 879.88 |
+| Apple SD Gothic Neo (macOS) | 846.08 |
+| Noto Sans KR | 883.58 |
+| `sans-serif` | 869.94 |
+
+4% 차이는 줄바꿈 위치를 바꾼다.
+관보 본문은 `--measure: 37em ≈ 43자`로 글줄을 잰다 — 자폭이 달라지면 그 계산이 통째로 어긋난다.
+인쇄·PDF 에서는 더 벌어진다.
 
-## 세 가지 설계 결정
+## 왜 300 인가 — 「400–700」은 死文이다
 
-### 1. 정적 4종이 아니라 가변 1종
+`gazette.css` 의 굵기는 3종이다: `--w-light: 300` · `--w-body: 400` · `--w-bold: 700`.
+300 이 서는 자리는 셋뿐이고, 전부 문서의 얼굴이다.
 
-| 방식 | 크기 | 굵기 표현 |
+| 선택자 | 크기 | 무엇 |
 |---|---|---|
-| 정적 4종 (400/500/600/700) | 651,196B | 정확 |
-| **가변 1종 (wght 400–700)** | **300,544B** | 정확 + 중간값도 가능 |
-| 가변 1종 (축 제한 없음, 45–930) | 420,916B | 정확 |
-| 정적 2종 (400/700) | 325,576B | `font-weight:650` 이 700 으로 튄다 |
+| `.cover__t2` | 42px | 표지 대제목 **둘째 행**(`title_sub`) |
+| `.pt__no` | 61px | PART 간지 번호 |
+| `.toc__pn` | 20px | 차례의 PART 번호 |
 
-축을 400–700 으로 자르면 variation delta 가 줄어 **30% 작아진다**.
-그리고 CSS 의 `font-weight:650`(소제목)이 실제로 650 굵기로 나온다 — 정적 2종이면 700 으로 스냅된다.
+축을 400–700 으로 자르면 이 셋이 **400 으로 눌린다**.
+육안으로는 「좀 굵네」로만 보여서 안 잡힌다.
 
-브라우저에서 실측한 굵기별 문자열 폭(단조 증가 = 가변 축이 살아 있다는 증거):
+축이 살아 있는지는 폭이 단조 증가하는지로 안다(실측).
 
 ```
-wght 400 → 879.88    wght 600 → 890.34    wght 700 → 895.50
-wght 500 → 885.03    wght 650 → 892.94
+300 → 870.72    400 → 879.88    500 → 885.03    650 → 892.94    700 → 895.50
 ```
 
-### 2. 커버리지는 KS X 1001
+렌더된 문서에서 실제로 쓰인 굵기도 300·400·700 셋뿐이다(실측).
 
-| 커버리지 | 글자 수 | 크기 | 판단 |
-|---|---|---|---|
-| 문서에 실제 쓰인 글자만 | 623 | ~60KB | ❌ **편집기로 새 글자를 타이핑하면 다른 폰트로 떨어진다** |
-| **KS X 1001 완성형** | 2,350 | **300KB** | ✅ 일반 한국어 산문을 사실상 전부 덮는다 |
-| 현대 한글 전체 | 11,172 | 1,195KB | ❌ 4배인데 실익은 의성어·외래어 표기뿐 |
+## 커버리지 — 재는 법
 
-이 문서는 **위지윅으로 편집된다.** 그래서 "지금 쓰인 글자만" 은 틀린 답이다.
-KS X 1001 밖 음절(`뷁`, `똠` 같은)은 시스템 폰트로 떨어지지만 두부(□)가 되지는 않는다 — 우아한 폴백이다.
+이 기계에는 `fontTools`·`brotli` 가 없다.
+그래서 폰트 파일을 열어 글리프를 세는 대신 **브라우저에서 잰다**.
+없는 글자는 폴백으로 떨어지므로 폭이 다르게 나온다.
 
-KS X 1001 2,350자를 정확히 뽑는 방법(표를 들고 다닐 필요가 없다):
-
-```python
-# EUC-KR 로 2바이트 인코딩되고 선행 바이트가 0xB0–0xC8 인 음절이 정확히 2,350자
-c.encode('euc-kr')  # len == 2 and 0xB0 <= b[0] <= 0xC8
+```js
+const c = document.createElement('canvas').getContext('2d');
+c.font = '400 64px "Pretendard GOV"';
+const d = new Map();                               // 현대 한글 11,172 음절의 폭 분포
+for (let cp = 0xAC00; cp <= 0xD7A3; cp++) {
+  const v = c.measureText(String.fromCodePoint(cp)).width.toFixed(2);
+  d.set(v, (d.get(v) || 0) + 1);
+}
+console.log([...d].sort((a, b) => b[1] - a[1]));   // 두 무리로 갈린다
 ```
 
-### 3. `tnum` 을 반드시 남긴다
+실측 결과 — 55.31px 이 **2,350자**, 55.36px 이 8,822자.
+2,350 = KS X 1001 완성형이고, 55.36 은 폴백 폭이다.
+즉 지금 실린 것은 **KS X 1001 완성형**이다.
 
-구조 CSS 는 11곳에서 `font-variant-numeric: tabular-nums` 를 쓴다 — 지표 밴드의 큰 숫자,
-판정표의 절 번호, 표지 메타의 날짜. 여기서 자릿수 폭이 어긋나면 표가 흔들린다.
+폰트 파일 전체 글리프 수(라틴·기호 포함)는 **확인 못 함** — 세려면 `fontTools` 가 필요하다.
 
-`pyftsubset --layout-features=''` 로 레이아웃 피처를 통째로 버리면 `tnum` 이 사라지고,
-**CSS 는 그대로인데 정렬만 조용히 죽는다.** 화면으로는 "표가 좀 어긋나 보이네" 정도로만 보인다.
+KS X 1001 밖 음절(`뷁` 같은)은 시스템 폰트로 떨어진다.
+두부(□)가 되지는 않는다 — 우아한 폴백이다.
+포털 편집기(`/edit`)에서 사람이 새로 타이핑한 글자가 여기 걸린다.
 
-피처를 남기는 비용은 6KB 다 (294KB → 300KB). 남긴다.
+## `tnum` 은 반드시 남긴다
 
-## 다시 만들기
+`gazette.css` 가 `font-variant-numeric: tabular-nums` 를 **20곳**에서 쓴다.
+차례의 절 번호, 머리띠 배지, 표의 수치가 전부 여기 걸린다.
 
-```bash
-python3 -m venv .fontenv && .fontenv/bin/pip install fonttools brotli
+`pyftsubset --layout-features=''` 로 피처를 통째로 버리면 `tnum` 이 사라진다.
+**CSS 는 그대로인데 자릿수 정렬만 조용히 죽는다** — 화면으로는 「표가 좀 어긋나 보이네」로만 보인다.
 
-curl -sLO https://raw.githubusercontent.com/orioncactus/pretendard/v1.3.9/\
-packages/pretendard/dist/public/variable/PretendardVariable.ttf
+남길 목록은 `assets/subset_font.py` 의 `LAYOUT` 상수다.
+`ccmp locl kern mark mkmk calt clig liga rlig tnum case`.
 
+## 다시 만들 때 — 함정 하나
+
+거의 실행할 일이 없다.
+실행한다면 `--wght` 는 **기본값이 `300:700`** 이라 적지 않아도 된다(2026-08-24 고침).
+관보가 `--w-light: 300` 을 쓰기 때문이고, 400 부터 자르면 표지 둘째 행과 간지 숫자가 눌린다.
+
+```bash
+python3 -m venv .fontenv && .fontenv/bin/pip install fonttools brotli
 .fontenv/bin/python assets/subset_font.py PretendardVariable.ttf \
-    assets/fonts/pretendard-report.woff2
+    ~/project/FCG/report-portal/private/builder/fonts/pretendard-gazette.woff2 \
+    --wght=300:700
 ```
 
-옵션:
-
-| 플래그 | 용도 |
-|---|---|
-| `--coverage=full` | 현대 한글 11,172자 (1.19MB) |
-| `--coverage=used --used-from=out.html` | 그 문서에 쓰인 글자만 (편집 안 할 때만) |
-| `--wght=400:900` | 더 굵은 표제가 필요할 때 |
-| `--wght=400` | 단일 굵기 (가변 축 제거) |
+기본값대로 구우면 파일 이름만 `gazette` 이고 내용은 300 이 없는 폰트가 된다.
+그러면 표지 둘째 행과 간지 번호가 400 으로 눌린 문서가 나간다.
 
-## CSS 쪽 함정 두 가지
+## CSS 쪽 함정 셋
 
-### `format("woff2-variations")` 를 쓰지 말 것
+**① `format("woff2-variations")` 를 쓰지 않는다.**
+폐기된 표기다 — 인식 못 하는 브라우저가 그 `src` 를 통째로 건너뛰고 조용히 대체 폰트로 떨어진다.
+`build.py:328-331` 이 `"woff2"` 만 쓴다. 산출물에서 `woff2-variations` 0건 확인.
 
-폐기된 표기다. 인식하지 못하는 브라우저는 **그 `src` 를 통째로 건너뛰고** 조용히 대체 폰트로 떨어진다.
-가변 woff2 도 `format("woff2")` 로 충분하다.
+**② 패밀리 이름은 `Pretendard` 가 아니라 `Pretendard GOV` 다.**
+고객 PC 에 Pretendard 가 설치돼 있어도 부딪히지 않는다 — 이름이 다르기 때문이다.
+스택 첫 후보가 `"Pretendard GOV"`, 둘째가 `"Pretendard"` 인 것이 그 설계다.
 
-```css
-src: url(data:font/woff2;base64,…) format("woff2");   /* ✅ */
-src: url(data:font/woff2;base64,…) format("woff2-variations");  /* ❌ 조용히 무시될 수 있음 */
-```
+**③ 이름을 바꿀 때는 따옴표를 조심한다.**
+`build.py:330` 이 `font-family:{fam}` 을 **따옴표 없이** 박는다.
+숫자로 시작하는 낱말이나 특수문자가 든 이름을 넣으면 그 선언이 깨진다.
 
-### 폰트 스택 맨 앞을 `Pretendard` 로 둘 것
+## `build.py` 를 직접 부르면 폰트가 갈린다
 
-`@font-face` 로 선언한 패밀리는 같은 이름의 **시스템 설치본보다 우선**한다. 그래서 스택은
-`Pretendard, -apple-system, …` 로 시작한다.
+`cfg` 에 `font` 가 없으면 `build.py:313-315` 가 `fonts/pretendard-report.woff2` + `'400 700'` 으로 떨어진다.
+그 옛 파일(**300,544B**)이 아직 레포에 남아 있어서 **조용히 실린다**.
+결과는 300 이 죽은 문서인데, 렌더는 성공으로 끝난다.
 
-`"Pretendard Variable"` 을 앞에 두면 안 된다 — 임베드본의 패밀리명은 `Pretendard` 이므로
-고객 PC 에 Pretendard Variable 이 설치돼 있으면 **그쪽이 먼저 잡혀** 환경마다 렌더가 갈린다.
-임베드한 의미가 사라진다.
+로컬 렌더는 `python3 assets/render.py <report.json>` 하나로 한다.
 
-## 임베드가 실제로 먹었는지 확인하는 법
+## 임베드가 먹었는지 확인하는 법
 
-눈으로는 판정할 수 없다. Apple SD Gothic Neo 와 Pretendard 는 본문 크기에서 거의 같아 보인다.
-브라우저 콘솔에서 재는 것이 유일하게 확실하다.
+`fontchk.mjs` 는 이것을 **안 잡는다** — 렌더된 활자 크기·굵기 분포만 본다.
+콘솔에서 두 줄로 확인한다.
 
 ```js
-document.fonts.check('64px Pretendard')            // true 여야 한다
-const w = (f, wt=400) => {
-  const c = document.createElement('canvas').getContext('2d');
-  c.font = `${wt} 64px ${f}`;
-  return c.measureText('읽을 수 있는 보고서 0123456789').width;
-};
-w('Pretendard') !== w('"Apple SD Gothic Neo"')     // true 여야 한다 (폴백이 아님)
-w('Pretendard', 650) !== w('Pretendard', 700)      // true 여야 한다 (가변 축이 살아 있음)
+[...document.fonts].map(f => [f.family, f.weight, f.status]);
+// → [["Pretendard GOV", "300 700", "loaded"]] 여야 한다
 ```
 
-`qa.py` 는 `@font-face` 존재와 `format` 문자열까지만 검사한다. 렌더 여부는 위 세 줄로 확인한다.
+다른 패밀리와 폭을 비교하는 방식은 쓰지 않는다.
+실측에서 **없는 패밀리의 폴백 폭 895.50 이 Pretendard GOV 700 과 같은 값**으로 나왔다.
+같은 패밀리 안에서 300 < 400 < 700 인지를 보는 편이 확실하다.
 
-## 다른 폰트를 쓸 때
+## 다른 폰트로 갈아야 한다면
 
-라이선스를 먼저 확인한다. **임베드는 배포에 해당**하므로 웹폰트 임베드를 허용하는 라이선스여야 한다.
+**임베드는 배포에 해당한다.** 웹폰트 임베드를 허용하는 라이선스여야 한다.
 
 | 폰트 | 라이선스 | 임베드 |
 |---|---|---|
-| Pretendard | SIL OFL 1.1 | ✅ |
-| 나눔 계열 | SIL OFL 1.1 | ✅ |
-| 본고딕 / Noto Sans KR | SIL OFL 1.1 | ✅ |
-| 맑은 고딕 | Microsoft | ❌ 임베드 불가 (시스템 폴백으로만) |
-| 대부분의 유료 한글 폰트 | 개별 계약 | ⚠️ 웹폰트 조항 확인 필수 |
-
-`report.json` 에서 지정한다.
-
-```json
-"font": { "embed": true, "file": "fonts/내폰트.woff2",
-          "family": "내폰트", "weight": "400 700",
-          "license": "폰트명 · 라이선스 · 출처 URL" }
-```
+| Pretendard | SIL OFL 1.1 | 가능 |
+| 나눔 계열 · 본고딕 / Noto Sans KR | SIL OFL 1.1 | 가능 |
+| 맑은 고딕 | Microsoft | 불가 (시스템 폴백으로만) |
+| 유료 한글 폰트 | 개별 계약 | 웹폰트 조항 확인 필수 |
+
+바꾸는 자리는 세 곳이고, 전부 `report.json` 바깥이다.
+`report_publish.php` 의 `REPORT_TEMPLATES` · `gazette.css` 의 `--font` · 레포의 `fonts/`.
+셋 중 하나를 놓치면 문서가 폴백으로 나가는데 육안으로는 잘 안 잡힌다.
+
+## 조판 규칙은 여기 없다
 
-`family` 를 바꾸면 `assets/report.css` 의 `body { font-family: … }` 첫 항목도 같이 바꿔야 한다.
+활자 스케일·괘선·간격 격자·인쇄 페이지 문법은 `gazette-report` 스킬이 원전이다.
+검사기 8종의 실행법도 그쪽에 있다 — 두 벌로 두지 않는다.