baip/skills

필기 및 타자 원본에서 접근성 있는 강의 노트 만들기

결과물은 문서당 하나의 마크다운 파일과 문서당 하나의 그림 그리기 스크립트입니다. 여기에 번들로 제공되는 도구 키트를 사용하여 태그된 PDF와 웹사이트가 생성됩니다. 마크다운이 유일한 소스이며, 수정은 .md 파일에만 적용되고 생성된 .tex나 HTML에는 절대 적용하지 않습니다.

                     ┌─ mkweb.py   → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
                     └─ md2tex.py  → <class>.cls → lualatex  → PDF beside the .md

프로젝트 구조는 다음과 같습니다:

md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py   build scripts, run from the root
<class>.cls  contents.yaml  CONVENTIONS.md  BUILD.md
src/                 lectures: NN_Name.md, with NN_Name.tex and .pdf beside each
2026/                one offering's homework and exams, same arrangement
figures/             fig_<doc>_<NN>_<name>.svg, and the PDFs made from them
scripts/figures_audit.py
scripts/figures/     figlib.py, make_figures_<doc>.py, data helpers
originals/  work/    the originals and page images, untracked

번들 항목

경로	용도
scripts/init_project.py	새 프로젝트 스캐폴딩, 또는 기존 프로젝트에서 --update-toolkit 실행
scripts/render_pages.py	원본 페이지(및 확대된 부분)를 읽을 수 있도록 렌더링
scripts/contact_sheet.py	변경된 SVG 그림을 하나의 PNG로 렌더링하여 검사 및 전송
scripts/notation_lint.py	표기법 타협 플래그: 단어로 된 극한, 설명된 주석, 평평해진 아래 첨자, 수학 외부의 문자, 잘못된 대체 텍스트 블록, PDF 글꼴에 없는 글리프
assets/toolkit/	빌드 스크립트 및 notes.cls, init_project.py로 프로젝트에 배치됨
assets/templates/	contents.yaml, 예제 강의 및 그리기 스크립트, .gitignore, package.json
references/transcribing.md	원본 읽기, OneNote 특이 사항, 강의 및 과제, 인계 전 검사
references/figures.md	리뷰를 통과하는 그림 그리기 방법
references/notation-pass.md	기존 문서를 실제 표기법으로 개정, 단독 또는 병렬 도우미와 함께
references/review-and-delivery.md	리뷰 라운드, git, 파일 브리지를 통한 작업, 게시
references/conventions.md, references/building.md	프로젝트의 CONVENTIONS.md 및 BUILD.md가 됨

0. 프로젝트 설정 또는 찾기

1. 기존 프로젝트를 찾으세요: contents.yaml, md2tex.py, *.cls, CONVENTIONS.md, BUILD.md. 있다면 먼저 CONVENTIONS.md와 BUILD.md를 읽고 이 스킬과 다른 부분은 따르세요. 작성자가 내린 결정을 기록하고 있기 때문입니다. 프로젝트의 최근 커밋도 확인하세요. 작성자가 종종 문서를 수동으로 개정하며, 해당 개정이 현재 하우스 스타일(앞표지 표현, 마무리 노트 유지)입니다.

2. 그렇지 않으면 새로 스캐폴드하세요:

   python3 <skill>/scripts/init_project.py <folder> \
       --title "CHEM 101 — General Chemistry" --short "CHEM 101" \
       --class chem101 --author "…" --copyright "…"
   

   예제 강의를 한 번 빌드하여 시스템이 설정되었는지 확인하고(BUILD.md에 설치 목록이 있습니다), 그런 다음 contents.yaml, src/, scripts/figures/ 및 figures/에서 제거하세요.

3. 추론할 수 없는 것은 한 라운드에 물어보세요: 과정명 및 약어, 어떤 문서를 먼저 처리할지, 원본과 프로젝트가 어디에 있는지(업로드, 작성자 컴퓨터의 폴더, git 저장소), 각 라운드에서 PDF와 웹사이트를 빌드할지 여부, 누가 푸시할지. 다른 지시가 없으면 로컬에서 커밋하고 절대 푸시하지 마세요.

4. 고정 지침은 이후 모든 라운드에 적용됩니다 ("빌드하지 마세요", "제가 직접 푸시할게요").

1. 원본 읽기

텍스트 추출은 타자된 텍스트만 반환합니다. 필기와 스케치는 잉크이므로 페이지를 렌더링하여 이미지로 읽고, 작은 부분은 확대하세요:

python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5

첫 번째 문서 전에 references/transcribing.md를 읽으세요.

2. 전사하기

프로젝트의 CONVENTIONS.md를 따르세요. 가장 중요한 규칙:

• 어디에 넣을지. 강의는 src/NN_Name.md; 과제와 시험은 연도 폴더(예: 2026/homework03_solution.md)에 넣습니다. 각 항목을 checked: false로 contents.yaml에 추가합니다. 작성자만 true로 설정하여 웹사이트에 게시합니다.
• 앞표지. title, docheading(유일한 h1), lang, runningfoot, description (" lecture notes: ."), subtitle ("."). 본문 제목은 ##로 시작하며 레벨을 건너뛰지 않습니다. "About this transcription" 노트나 페이지 경계 표시는 없습니다: 작성자가 제거하므로 추가하지 마세요.
• 과제 솔루션. 솔루션만 전사하며, ## Problem N 및 ### Part (a): <what it finds> 아래에 둡니다. 작성자가 문제 세트(.tex 또는 .pdf)를 제공하면 솔루션 이해와 표기법 참조에만 사용하고 텍스트 변환에는 사용하지 마세요.
• 수학: 원본의 표기법, 올바르게 조판. LaTeX는 $…$, $$…$$는 ::: eq 내부에 사용합니다. 합, 곱, 적분은 극한을 포함합니다; 행렬과 행렬식은 조판합니다; 스크립트 문자는 \mathcal{}; 인덱스는 이탤릭, 레이블은 직립; 실제 중첩 아래 첨자(x_{j}, x\, j 아님); \text{} 안의 단어; 분수를 감싸는 \left(\right)는 그려진 경우에만; 아래 첨자 목록의 쉼표 뒤, 인접 분수 사이, 미분 기호 앞에만 \,; \underbrace 뒤에 연산자가 오면 {}; 분수가 포함된 지수는 \exp(…).
• 손으로 쓴 주석은 표기법이 됩니다 (\cancel, \underbrace{…}_{0}, 레이블이 있는 중괄호, \overset{…}{=}, \boxed, 평가 막대). 이러한 방정식은 음성 형태를 가집니다: ::: {.eq alt="…"} 정확히 하나의 디스플레이 방정식을 포함하며, 마크(LaTeX 없음, 큰따옴표 없음)를 명명하는 일반 문장이 있어야 합니다. 일반 방정식은 대체 텍스트가 필요 없습니다: MathJax의 MathML을 통해 리더가 탐색할 수 있습니다.
• PDF 텍스트 글꼴에 일부 기호가 없습니다 (⋮, ①, π, ′, ≪, ≫). 수학으로 작성하세요($\vdots$). 동그라미 숫자는 "state 1"과 같이 쓰세요. 누락된 문자가 있으면 빌드가 실패합니다.
• 표: 파이프 테이블만 사용하며, 헤더 행이 있어야 하고 규칙은 없습니다. 긴 테이블 앞에는 그림을 배치하고, 바로 뒤에는 배치하지 마세요. 테이블을 페이지에 맞게 충분히 좁게 유지하세요(너무 넓으면 빌드가 경고합니다).
• 블록: ::: eq, ::: problem, ::: keep, ::: flush, ::: quote, ::: note. [H]는 없습니다.
• 원본의 오류는 작성된 대로 전사하고 마무리 노트에 증거와 함께 플래그를 지정하며, 절대 조용히 수정하지 마세요. 작성자가 수정하라고 하면 수정하세요.
• 마무리 노트 (## Notes on changes made for accessibility)에는 작성자가 확인하거나 결정해야 할 사항만 포함합니다: 가능한 오류, 불확실한 판독, 추가 사항. 상용구는 없습니다.

빌드 전에 python3 <skill>/scripts/notation_lint.py <doc>.md를 실행하세요: 오류는 수정해야 하고, 경고는 원본과 대조하여 확인해야 합니다.

3. 모든 그림 다시 그리기

모든 스케치는 figlib.py를 기반으로 한 scripts/figures/make_figures_<doc>.py로 그려진 SVG가 되며, 이름은 fig_<doc>_<NN>_<name>.svg입니다. 마크다운에서 상대 경로로 다음과 같이 참조됩니다: ![**Title.** Long description.](../figures/fig_….svg){#fig-<doc>-<NN> width=NNN alt="…"} 그리고 [](#fig-<doc>-<NN>)로 인용됩니다. 그리기 전에 references/figures.md를 읽으세요. 간단히 말해: 방정식에서 곡선을 계산하고 플롯 중앙에 배치하며, 객체에서 시작하고 끝나는 화살표를 그리고, 레이블을 선 가까이에 명확하게 유지하고(place_label은 밀집 플롯에서 사용), 악센트와 동그라미 숫자는 입력하지 말고 그리고, viewBox를 그림에 맞게 조정하고, 그림이 변경될 때마다 캡션을 업데이트하세요.

4. 빌드 및 확인

python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <name>                  # e.g. 09_Mixtures or homework03_solution
python3 buildtex.py <name>                # 12 checks, plus a too-wide warning
python3 mkweb.py && python3 checkweb.py   # 9 checks per page, MathJax errors included
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<doc>_*.svg

• 출력을 확인하세요. 변경된 모든 그림의 콘택트 시트를 보고 변경된 방정식, 표, 그림이 포함된 PDF 페이지를 렌더링하세요. 시트를 작성자에게 보내세요.
• checked: false로 보류된 문서는 웹사이트에 게시되지 않습니다. 페이지를 테스트하려면 true로 설정한 복사본에서 사이트를 빌드하세요.
• 검사 11("수식 대체 텍스트가 원시 LaTeX가 아님")은 tagpdf 1.0보다 오래된 TeX Live에서 실패합니다. 게시된 PDF를 만드는 시스템에서 실패하면 숨기지 말고 알리세요.
• 작성자가 빌드하지 말라고 한 경우, 해당 폴더에 빌드 출력을 쓰지 마세요. 위험한 변경을 확인하기 위해 별도 복사본을 사용하는 것은 괜찮습니다.
• 검사는 필요 조건일 뿐 충분 조건이 아닙니다. 게시 전에 PDF에는 PAC 2024를, 사이트에는 WCAG 감사를 권장합니다.

5. 리뷰 라운드 및 일괄 개정

references/review-and-delivery.md를 읽으세요. 간단히: 먼저 작성자의 현재 파일과 동기화하고, 항목당 하나의 작업과 확인 작업을 만든 다음 각 항목을 원본과 교차 확인하고, 질문은 편집과 별도로 답변하며(질문에 대해 작성자가 결정할 때까지 아무것도 변경하지 않음), 프로젝트 전반의 규칙은 툴킷과 CONVENTIONS.md에서 수정하고, 항목당 한 줄로 보고합니다.

작성자가 여러 문서에 걸쳐 동일한 개정을 요청하면(예: "05–10을 01–04에 적용한 것과 일치시키세요"), references/notation-pass.md를 읽으세요: 작성자의 자체 개정을 모델로 연구하고, 스크립트로 기계적인 부분을 수행한 후 방정식별 작업을 병렬 도우미(각각 두세 문서)에게 서면 브리핑과 함께 넘기세요.

6. 전달

• 프로젝트가 작성자의 컴퓨터에 있는 경우 해당 시스템에서 편집하세요. SVG는 복사하지 말고 그리기 스크립트를 직접 실행하여 재생성하세요. 파일 브리지가 이미지를 전송 중에 변환할 수 있기 때문입니다. 복사할 때 체크섬으로 확인하세요.
• 작성자의 신원으로 커밋하고 항목을 나열하는 메시지를 작성하세요. 요청받지 않는 한 절대 푸시하지 말고, 요청하는 훅은 거절하세요.
• 작성자 컴퓨터에 대한 연결이 끊어지면 자신의 클론에 커밋하고 git 번들(git bundle create x.bundle <their-head>..main)을 전달하여 당기거나 연결이 복원될 때 적용하세요.
• python3 package.py는 contents.yaml에서 전체 프로젝트의 아카이브를 빌드하며, scripts/figures_audit.py가 실패하면 거부합니다.
• 프로젝트에 최신 툴킷을 제공하려면: python3 <skill>/scripts/init_project.py <folder> --update-toolkit.