---
name: Ebook style guide (voice, terminology, notation)
description: >
  The prose style rules for the Korean metabolic-modeling textbook: sentence
  voice (formal 서술체 in body, polite 습니다체 in labs), Korean-term-first
  bilingual notation like 플럭스(flux; 대사 통량), consistent symbols within a
  chapter, bolding of key terms, and the book's defining discipline of separating
  model predictions from experimental observation. Use whenever writing or editing
  any prose in this book so the tone matches. Pairs with ebook-section (structure)
  and ebook-glossary (term definitions).
---

# 문체 가이드 — 목소리·용어·표기

이 교재의 문장이 어디서 읽어도 한 사람이 쓴 것처럼 들리게 하는 규칙이다. 구조는 `ebook-section`이, 용어집 등록은 `ebook-glossary`가 담당한다.

## 1. 문장 어투 (voice)

- **본문(장 README·절·마무리 서술)**: 격식 있는 **서술체** — `~이다`, `~한다`, `~된다`. 예: "FBA는 목적함수를 추가해 최적해를 구하는 선형 계획법이다."
- **실습(`lab.md`)**: 독자에게 지시하는 **정중체** — `~합니다`, `~하십시오`, `~해 보십시오`. 예: "먼저 모델을 불러옵니다. 새 세션을 시작했다면 단계 1부터 다시 실행하십시오."
- **스스로 점검 문제·연습**: 명령형 지시 — "…를 구하라", "…를 한 문장으로 설명하라".
- 과장·마케팅 어투를 쓰지 않는다. "혁신적", "압도적" 같은 표현 대신 사실과 조건을 쓴다.

## 2. 용어 이중 표기 (가장 자주 쓰는 규칙)

**한국어 용어를 먼저 쓰고, 그 용어가 처음 등장할 때만 영어 원어(필요하면 약어·짧은 뜻풀이)를 괄호로 병기한다. 이후 같은 장 안에서는 한 표기를 일관되게 쓴다.**

- 기본형: **한글**(English) — `**플럭스**(flux)`, `**목적함수**(objective function)`
- 뜻풀이 추가: **한글**(English; 짧은 뜻) — `**플럭스**(flux; 대사 통량)`
- 약어 도입: **한글**(English, 약어) — `**플럭스 균형 분석**(Flux Balance Analysis, FBA)`
- 이후 재등장: 약어 또는 한글 중 하나로 일관되게 — 이후에는 그냥 `FBA`.
- 핵심 용어는 **볼드(`**…**`)**로 강조하고, 처음 정의될 때 용어집 링크를 건다: `**[화학량론 행렬](../glossary.md)**(Stoichiometric Matrix)`.

각 절 첫머리나 장 README의 "표기와 읽기 원칙"에서 이 규칙을 독자에게 한 번 명시한다.

## 3. 표기 일관성 (notation)

- 수학 기호는 장 전체에서 한 번 정하면 끝까지 같게 쓴다: 화학량론 행렬 $$\mathbf{S}$$, 플럭스 벡터 $$\mathbf{v}$$, 목적계수 $$\mathbf{c}$$, 목적값 $$Z$$, 성장률 $$\mu$$.
- 단위는 코드 폰트로: `mmol gDW⁻¹ h⁻¹`, `h⁻¹`. 성장률은 $$\mu$$(단위 `h⁻¹`).
- 반응·대사물·모델 ID는 코드 폰트로: `e_coli_core`, `EX_glc__D_e`, `Biomass_Ecoli_core`. ID 대소문자를 정확히(예: `EX_o2_e`는 소문자 o).
- **계산 조건과 생물학적 사실을 어휘로 구분한다.** 경계조건(bounds)·목적함수·solver는 "우리가 모델에 부여한 계산 설정"이라고 부르고, 대사·반응·플럭스는 생물학적 대상으로 부른다.

## 4. "예측 vs 관찰"의 규율 (이 책의 핵심 태도)

교재 전체를 관통하는 원칙이며, 문장 단위에서 지켜야 한다.

- 모델 결과는 **"명시된 모델·배지·경계조건·목적함수·solver 아래의 계산 결과"**다. "예측한다", "최적이다"라고 쓸 때 그 조건을 근처에서 밝힌다.
- solver의 `optimal`은 "수치 허용오차 안에서 최적해를 찾았다"는 상태일 뿐, "생물학적 가설이 검증됐다"는 뜻이 아니라고 반복해 상기시킨다.
- 하나의 최적 플럭스를 유일한 세포 상태로 단정하지 않는다. 대안 최적해·FVA·sampling·민감도·외부 검증을 함께 언급한다.
- 값을 인용할 때 의존성을 붙인다: "이 값은 모델·배지·유지에너지·solver 허용오차에 의존한다."

이런 주의는 본문에 녹이거나 아래 상자로 분리한다(문법은 `ebook-section` 참고):

```
{% hint style="warning" %}
본문의 "예측"은 명시된 모델·배지·경계조건·목적함수 아래의 계산 결과다.
실험 관찰이나 인과적 효과와 혼용하지 않는다.
{% endhint %}
```

## 5. 문단 조직 습관

- **정의 → 가정 → 수식 → 해석** 순서로 전개한다. 수식을 던지기 전에 말로 직관을 먼저 준다.
- 어려운 수식은 바로 뒤에 **"용어 하나씩 뜯어보기:"** 문단으로 기호를 풀어 설명한다.
- 조건·가정·절차는 번호 목록으로, 결과의 범위·예외·주의는 hint 상자나 "해석상의 주의"로 분리한다.
- 앞 절에서 손으로 푼 숫자를 뒤 절·실습에서 **같은 숫자로** 재확인하는 "관통 예제"를 즐겨 쓴다("작은 장난감 예제 → 95차원 `e_coli_core` → genome-scale, 차원만 커질 뿐 이론은 같다").
- 교차참조를 적극적으로: `[6.3절](06.md)`, `[Chapter 8](../chapter-8/README.md)`, 용어집·대표 논문 링크.

## 6. 빠른 체크리스트 (문장을 넘기기 전에)

- [ ] 새 용어를 한글 먼저, 영어 병기로 최초 1회 도입했는가?
- [ ] 장 안에서 기호·표기가 일관되는가?
- [ ] "예측/최적"에 조건(모델·배지·목적함수·solver)을 붙였는가?
- [ ] 계산 결과를 실험 사실처럼 단정하지 않았는가?
- [ ] 본문은 서술체, 실습은 정중체인가?
- [ ] 값에 단위와 의존성을 붙였는가?