# 문체와 코드 규약

79회 전체가 이 규약을 공유한다. 설계안의 Part 0에 있는 내용을 한곳에 모은 것이다.

## 문체

| 층위 | 형태 |
|---|---|
| 종결어미 | 한다체 — "~이다", "~한다", "~된다" |
| 권유 | 해라체 청유형 — "~해 보자", "~알아보도록 하자" |
| 성격 | 무표적 서술체. 비유와 수사를 쓰지 않는다 |

- 인칭은 "우리는/우리가"까지만 쓴다. "여러분", "당신"은 쓰지 않는다
- 비유·의인화·과장을 쓰지 않는다
- 절 제목은 개념 이름 그대로 쓴다. 마지막 절은 "마치며"이다
- 독자의 수준이나 심리를 단정하지 않는다
- 아직 다루지 않은 뒤 회차를 근거로 삼지 않는다. 예고는 마지막 한 문장만 한다
- 용어는 한국어(English)로 병기한다

## 수식 전개

1. 회차 안에서 (1.1), (1.2)처럼 번호를 매긴다
2. 줄 사이마다 무엇을 했는지 한국어 한 문장을 넣는다
3. "쉽게 알 수 있듯이", "자명하게"를 쓰지 않는다. 세 줄이면 세 줄을 적는다
4. 인용할 때 "앞에서 본 것처럼"이 아니라 "5회 정리 5.2에 의하여"라고 지목한다
5. $\varepsilon$과 $\delta$ 중 무엇이 먼저 주어지는지를 문장으로 확인한다
6. 부등식을 뒤집는 조작(음수 곱하기, 역수)에는 그 사실을 표시한다

### 수식 번호와 기호

- 번호는 `\tag{1.3}`으로 직접 붙인다. 앞자리가 회차 번호이므로 1회의 셋째 식이 (1.3)이다
- **수식 안에는 한국어를 넣지 않는다.** MathJax의 수학 글꼴에는 한글 자형이 없어 `S_{\text{안}}` 같은 표기가 깨진다. 라틴 문자로 기호를 정하고 그 뜻을 본문에서 한국어로 밝힌다. 1회에서 안쪽 넓이를 $s_n$, 바깥쪽 넓이를 $S_n$이라 둔 것이 그 예이다
- **줄바꿈(`\\`)이 든 수식에는 `$$ ... $$` 안에서 `\tag`를 쓸 수 없다.** Sphinx가 `\\`를 발견하면 수식을 `split` 환경으로 감싸는데, `split` 안에서는 `\tag`가 오류가 된다. `cases`·`matrix`·`aligned`가 모두 여기에 걸린다. 이럴 때는 `{math}` directive에 `:nowrap:`을 주고 `\begin{equation}`을 직접 쓴다.

````text
```{math}
:nowrap:
\begin{equation}
|a| = \begin{cases} a & (a \ge 0) \\ -a & (a < 0) \end{cases} \tag{4.12}
\end{equation}
```
````

- 자주 쓰는 약칭은 `_config.yml`의 `mathjax3_config`에 매크로로 등록되어 있다. `\R` `\N` `\Z` `\Q` `\eps` `\dd` `\abs{}` `\norm{}` `\set{}` `\inner{}{}` `\grad` `\curl` `\divg` `\vv{}` `\bd`

### 정리 상자

정의·정리·보조정리·증명·예제는 `sphinx-proof`의 directive로 적는다. **번호는 책 전체에 걸쳐 이어서 자동으로 매겨진다.** 회차 안에서 1부터 다시 시작하지 않는다.

번호가 자동이므로 앞 회차의 정리를 손으로 "정리 6"이라 적으면 안 된다. 앞에 회차를 새로 끼워 넣으면 번호가 밀리기 때문이다. **언제나 라벨로 지목한다.** 라벨은 회차와 내용을 담아 `thm-3-inequality`처럼 짓는다.

````text
```{prf:theorem} 제목
:label: thm-1-archimedes

내용
```

```{prf:proof}
증명
```
````

본문에서는 ``{prf:ref}`thm-1-archimedes` `` 와 같이 라벨로 지목한다. 다른 회차의 것도 같은 방법으로 지목하며, 링크가 자동으로 걸린다.

**directive 제목에 백틱을 쓰지 않는다.** CommonMark 는 백틱 펜스의 여는 줄에 백틱이 다시 나오면 그 줄을 펜스 시작으로 인정하지 않는다. 그러면 블록 경계가 어긋나 **뒤따르는 코드 셀이 본문 글자로 흡수되어 조용히 사라진다.** 셀이 변수를 정의하고 있었다면 `NameError` 로 드러나지만, 그렇지 않으면 아무 경고 없이 내용만 빠진다.

```text
나쁨 :  ```{admonition} `quad` 는 되고 `integrate` 는 안 되는 이유
좋음 :  ```{admonition} quad 는 되고 integrate 는 안 되는 이유
```

`.\build.ps1 scaffold --check` 가 이 경우를 찾아 준다.

**펜스 안에 펜스를 넣을 때는 바깥쪽 백틱을 하나 더 쓴다.** 정리 상자 안에 `{math}`나 코드 블록을 넣으면, 안쪽의 백틱 세 개가 바깥 상자를 먼저 닫아 버린다. 바깥을 백틱 네 개로 열면 해결된다. 증상은 그 뒤의 directive가 통째로 본문 글자로 나오고 `label ... not found` 경고가 뜨는 것이다.

## 설명 장치 다섯 가지

비유를 쓰지 않으므로 그 자리를 다음 다섯 가지가 대신한다.

| 장치 | 예 |
|---|---|
| 구체적 수치 | $\varepsilon=0.01$일 때 $\delta$를 실제로 계산한다 |
| 특수한 경우 | 계단함수가 상수함수일 때의 적분 |
| 반례 | 열린구간에서 최대최소 정리 |
| 기하적 그림 | 상합과 하합의 직사각형 |
| 역사적 사실 | 아르키메데스의 포물선 구적 |

## 색 규약

`calc_style.색` 사전이 이 표를 담고 있다. 그림에서 색의 뜻은 79회 내내 같다.

| 요소 | 색 | 용도 |
|---|---|---|
| 함수 그래프 | `#000000` 검정 | 대상 |
| 하합·안쪽 근사 | `#1f77b4` 파랑 | 아래에서 접근 |
| 상합·바깥쪽 근사 | `#ff7f0e` 주황 | 위에서 접근 |
| 차이·오차 | `#d62728` 빨강 | $U_n-L_n$, $\abs{f(x)-A}$ |
| 허용 범위 | 회색 반투명 | $\varepsilon$ 띠, $\delta$ 구간 |
| 반례 | `#9467bd` 보라 | 조건이 깨지는 예 |
| 기호 결과 | `#2ca02c` 초록 | sympy가 준 정확한 값 |

## 코드

모든 코드 조각의 첫 네 줄은 다음 형식이다.

```python
# [7회] 상합과 하합
# 목적 : 분할 수를 늘렸을 때 두 값의 차이가 어떻게 변하는지 확인한다
# 층  : 1층(정의) → 2층(scipy 대조) → 3층(sympy 정확식)
# 주의 : 속도가 아니라 정의를 그대로 옮기는 데 목적이 있다
```

- 변수명은 한국어로 쓴다. 수학 기호에 대응하는 것만 영문을 유지한다($n$, $f$, $\varepsilon$)
- 출력문도 한국어로 쓴다
- sympy 결과는 `sp.pprint` 또는 `sp.latex`로 낸다
- 모든 실험에는 "확인할 것" 항목을 붙인다

## 공통 모듈

| 모듈 | 담당 | 파트 |
|---|---|---|
| `calc_style` | 색 규약, 한글 글꼴 | 전체 |
| `calc_sym` | 기호 계산 (3층) | 전체 |
| `calc_viz` | 리만합, 계단함수, 오차창 | I |
| `calc_viz2` | 할선과 접선, 누적넓이 | II |
| `calc_series` | 부분합, 수렴 판정 | III |
| `calc_vec` | 곡선, 프레네 틀, 장 | IV |
| `calc_multi` | 선적분, 이중적분 | V |
| `calc_surf` | 곡면, 플럭스, 내부 상쇄 | VI |

모듈은 저장소 루트의 `lib/` 에 있고, `pip install -e .` 로 설치되어 있으므로
어느 회차에서나 `from calc_viz import ...` 로 부를 수 있다.