latex-pdf — 전문 LaTeX PDF 조판 가이드
목표는 "컴파일 가능"이 아니라, 독자가 PDF를 보자마자 프로페셔널하다고 느끼게 하는 것입니다. 인도물은 내용과 실제 페이지를 기준으로 합니다. 컴파일 성공은 컴파일이 완료되었음을 증명할 뿐, 시각적 검수를 대체할 수 없습니다.
목차
핵심 원칙
조판은 두 가지 검사 목표를 따르며, 다른 스킬에 의존하지 않습니다.
① 조판은 독서를 위한 것 — 모든 조판 결정은 "이것이 독자의 이해를 돕는가?"에 답해야 합니다. 설정을 제거해도 독서 경험이 동일하다면, 그 설정은 존재할 필요가 없습니다.
② 절제가 곧 프로페셔널리즘 — 정보를 전달하지 않는 모든 시각적 요소를 제거하십시오. 장식용 선, 배경, 컬러 박스 — 대부분 제거해야 합니다. 전문적인 조판은 "노력하지 않은 것처럼 보이지만" 아마추어 조판은 "많이 노력했지만 지저분해 보입니다."
자세한 가독성 원칙 매핑은 가독성-원칙을 참조하세요.
엔진 선택
엔진을 잘못 선택하는 것이 가장 흔한 실수이며, 특히 중국어 콘텐츠에 pdflatex을 사용하는 경우입니다.
중국어/일본어/한국어가 있습니까?
├─ 예 → xelatex(+ ctex 패키지)
│ (lualatex도 가능하지만 컴파일이 더 느림)
└─ 아니오 → 시스템 폰트가 필요합니까?
├─ 예 → xelatex 또는 lualatex(+ fontspec)
└─ 아니오 → pdflatex(가장 빠르고 호환성 좋음)
새 CJK 문서는 XeLaTeX 또는 LuaLaTeX를 우선 사용하고, 실제 폰트 지원을 확인하십시오. 기존에 사용 가능한 pdfLaTeX/CJK 템플릿은 이유 없이 교체해서는 안 됩니다. fandol은 일반 pdfLaTeX 경로에 적합하지 않습니다.
| 엔진 | 장점 | 단점 | 적용 시나리오 |
|---|---|---|---|
pdflatex | 가장 빠르고 안정적이며 생태계가 가장 넓음 | 유니코드 기본 지원 안 함, 시스템 폰트 사용 불가 | 순수 영어 문서 |
xelatex | 기본 유니코드, 시스템 폰트, CJK 친화적 | 느림 | 중국어 문서 기본 선택 |
lualatex | 가장 강력한 폰트 처리, Lua 내장 가능 | 가장 느림 | 고급 조판 기능 필요 시 |
컴파일 전략
먼저 출처와 실행 경계 확인
컴파일 전에 .tex 파일, 포함된 .sty/.cls 파일, 빌드 구성 및 첨부 파일 경로를 정적으로 검사하고, 파일 읽기/쓰기, 외부 명령, Lua 등의 실행 기능을 주의하십시오. 정적 검사는 안전 증명이 아닙니다. 신뢰할 수 없는 프로젝트의 경우, 개인 파일이 없고 네트워크가 차단되며 쓰기, 실행 시간 및 리소스가 제한된 격리 환경을 사용하십시오. 적절한 격리가 없으면 컴파일을 중단하고 보고하며, 개인 환경에서 시험 실행하지 마십시오.
셸 이스케이프(shell-escape)는 기본적으로 비활성화하며, minted나 그래픽 외부화를 위해 자동으로 활성화하지 않습니다. latexmk를 실행할 때는 -norc를 사용하여 시스템, 사용자 또는 프로젝트 rc 파일이 자동으로 로드되지 않도록 하십시오. 다른 빌드 스크립트 및 외부 보조 프로그램은 별도로 검토하십시오. 패키지 설치, 네트워크 접속, 패키지 다운로드 또는 환경 변경은 이미 승인된 범위 내에서만 수행하고, 승인되지 않은 경우 먼저 승인을 받으십시오.
적절한 컴파일 체인 재사용
기존 프로젝트는 적합한 빌드 방식을 그대로 사용하십시오. 다중 패스 컴파일과 참고문헌을 자동으로 처리해야 할 때 latexmk를 사용할 수 있습니다. 다음 예제는 검사된 입력에 대해서만, 허용된 작업 디렉토리에서 실행됩니다.
# xelatex 문서 (중국어 기본)
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
# pdflatex 문서
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
# 보조 파일 정리
latexmk -norc -c
매개변수 설명:
-interaction=nonstopmode: 오류 발생 시 일시 중지하지 않음 (스크립트 환경에 필수)-halt-on-error: 첫 번째 오류에서 중지하여 문제 위치 파악 용이
biber (참고문헌)
참고문헌이 필요할 때는 latexmk가 호출할 biber/BibTeX와 입력을 확인한 후 승인된 경우에만 실행하십시오. 자동 감지를 추가 실행 권한으로 간주하지 마십시오.
가독성 조판 원칙
다음은 핵심 원칙 요약입니다. 자세한 매핑과 코드 예제는 가독성-원칙을 참조하세요.
페이지 지오메트리
한 줄당 50-75자를 목표로 합니다(66이 이상적이며, TeX 기본값과 일치).
\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% 중국어 문자 1자는 영문자 약 2배 폭이므로, 줄당 35중문자 ≈ 70영문자
표
일반 데이터 표는 booktabs의 세로선 없는 스타일을 우선 사용합니다. 사용자, 학술지 또는 기관 템플릿에 별도 요구사항이 있는 경우 해당 규칙을 유지합니다.
\usepackage{booktabs}
\begin{tabular}{lrr}
\toprule
지표 & 2024 & 2025 \\
\midrule
매출 & 120 & 150 \\
\bottomrule
\end{tabular}
booktabs 디자인의 전제는 세로선이 없다는 것입니다. 세로선이 있으면 가로선 간격이 끊어집니다. 이것은 버그가 아니라 기능입니다.
간격 시스템
단락 구분은 다음 두 가지 중 하나를 선택하고 혼용하지 마십시오:
% 방법 A: 첫 줄 들여쓰기 (학술 문서, ctex 기본)
\setlength{\parindent}{2em}
% 방법 B: 단락 간격 (기술 문서, 보고서)
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}
폰트
본문은 세리프(가독성 좋음), 코드는 고정폭을 사용합니다. xelatex/lualatex에서는 fontspec으로 시스템 폰트를 설정합니다.
\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}
microtype
거의 공짜로 얻을 수 있는 품질 향상 — 자간 미세 조정으로 본문이 더 정돈됩니다.
\usepackage{microtype}
% 참고: xelatex에서는 protrusion만 지원(폰트 확장 없음)하지만 여전히 로드할 가치가 있습니다.
미망인/고아 행 방지
단락의 첫 줄이나 마지막 줄이 페이지 경계에 단독으로 나타나는 것을 방지합니다.
\widowpenalty=10000
\clubpenalty=10000
코드 하이라이트
기본적으로 listings를 사용합니다(외부 종속성 없음). minted는 품질이 더 높지만 Python + Pygments/latexminted가 필요합니다.
\usepackage{listings}
\usepackage{xcolor}
\lstset{
basicstyle=\ttfamily\small,
keywordstyle=\color{blue!70!black},
commentstyle=\color{gray},
stringstyle=\color{green!50!black},
numbers=left,
numberstyle=\tiny\color{gray},
frame=none,
breaklines=true,
showstringspaces=false,
}
워크플로우
이 워크플로우를 처음 사용하는 사람을 위한 것입니다.
Step 0: 환경 감지
로컬 컴파일이 필요하고 기존 도구 정보가 불충분한 경우에만 감지합니다. 먼저 감지 스크립트를 읽어 신뢰할 수 있는 PATH 프로그램을 호출하고 현재 권한에 부합하는지 확인합니다. 이 스크립트는 보고만 하며 설치나 설정을 수정하지 않습니다.
이번에 실제로 읽은 SKILL.md의 절대 상위 디렉토리에서 skill_root를 해석합니다. 현재 작업 디렉토리가 스킬 디렉토리라고 가정하지 말고, 다음을 실행하십시오.
bash "$skill_root/scripts/check_latex_env.sh"
누락된 구성 요소와 감지 실패는 별도로 보고합니다. 작업에 실제로 필요하고 이미 승인된 종속성만 설치하고, 승인되지 않은 경우에는 갭 또는 기존 대안을 제시합니다. 자세한 단계는 필요에 따라 환경 감지 가이드를 읽으십시오.
Step 1: 요구사항 이해
확인:
- 문서 유형: 논문 / 보고서 / 이력서 / 슬라이드 / 일반
- 언어: 중국어 / 영어 / 혼합
- 독자: 학술 / 비즈니스 / 기술 / 일반
- 특수 요구사항: 참고문헌 / 코드 블록 / 수학 공식 / 데이터 차트
Step 2: 엔진 선택
위의 엔진 선택 결정 트리에 따라 결정합니다. 중국어 → xelatex가 가장 일반적인 선택입니다.
Step 3: .tex 생성
가독성 조판 원칙을 적용하고, 패키지 가이드의 표준 로드 순서 템플릿을 따릅니다.
Step 4: 컴파일
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
Step 5: 로그 확인
main.log를 열고 Warning과 Overfull/Underfull을 검색합니다.
- Overfull hbox → 넘치는 텍스트, 수식 또는 열 너비를 찾아 실제 페이지를 확인하고 부분적으로 수정합니다. 전역
\sloppy로 문제를 은폐하지 마십시오. - Underfull hbox → 줄이 너무 느슨함, 일반적으로 무해함.
- Font shape warning → 폰트 모양을 사용할 수 없음, fontspec 설정 확인.
- Undefined references → 다시 컴파일해야 함 (latexmk가 자동으로 처리했을 것입니다).
인도물에 영향을 주는 경고(예: 글자 누락, 확인되지 않은 참조, 눈에 띄는 오버플로)는 수정하십시오. 무해하거나 템플릿 제약으로 인한 경고는 이유를 설명하고, 모든 경고를 0으로 만들지 않아도 됩니다.
Step 6: 실제 페이지 확인 및 인도
실제 PDF를 렌더링하거나 열어서 페이지 수, 글자 누락, 잘림, 표/수식/코드, 링크, 책갈피 및 관련 접근성 요구사항을 확인하고, 필요에 따라 폰트 포함 여부와 텍스트 복사 가능 여부를 확인합니다. 수정 후 다시 컴파일하고 영향을 받은 페이지를 재확인합니다. 렌더링할 수 없는 경우 "시각적 검증되지 않음"이라고 명확히 표시하고, 컴파일 성공을 페이지 승인 통과로 간주하지 마십시오.
실제로 생성되고 확인된 파일을 출력합니다.
- PDF — 최종 인도물
- .tex 소스 파일 및 필요한 로컬 리소스 — 재현 가능한 진입점, 실제 명령, 컴파일 결과 및 검증되지 않은 항목을 유지합니다.
evals/evals.json은 평가용 데이터이며 실행 명령이 아닙니다. 이 스킬을 테스트할 때만 읽으십시오.
함정 빠른 참조
문제가 발생하면 유형별로 참조하십시오.
| 문제 유형 | 참조 파일 | 일반적인 증상 |
|---|---|---|
| 컴파일 오류 | common-pitfalls §컴파일 오류 Top 10 | Undefined control sequence, Missing $, 중단됨 |
| 인코딩/문자 | common-pitfalls §인코딩 및 문자 | 비 ASCII 오류, 스마트 따옴표, 중국어 문장 부호 간격 |
| 플로트 | common-pitfalls §플로트 | 그림/표가 문서 끝으로 이동 |
| 표 | common-pitfalls §표 | 열 너비 오버플로, 페이지 넘김 |
| 폰트 | common-pitfalls §폰트 | 시스템 폰트를 찾을 수 없음, CJK 미적용 |
| 패키지 충돌 | package-guide §패키지 충돌 매트릭스 | Option clash, 기능 이상 |
| 로드 순서 | package-guide §로드 순서 규칙 | 책갈피 오류, 링크 끊김 |
| 조판 품질 | readability-principles | 문서가 "아마추어"처럼 보임 |
| 환경 문제 | environment-check | 명령을 찾을 수 없음, 권한 오류 |
| ctex 폰트 | environment-check §일반적인 환경 문제 §6 | fontset 'fandol' is unavailable |
빠른 진단 체크리스트
컴파일 실패 시 다음 순서로 확인하십시오.
- ✅ 올바른 엔진을 사용했습니까? (중국어 → xelatex)
- ✅
latexmk를 사용했습니까? (다중 패스 컴파일 및 biber 자동 처리) - ✅
-interaction=nonstopmode를 사용했습니까? (대화형 모드에서 멈추지 않음) - ✅ 패키지 로드 순서가 현재 문서 클래스 및 패키지의 실제 제약 조건을 따릅니까? (일반적으로 hyperref는 나중에, cleverref는 그 다음에)
- ✅ 모든
\begin{...}에 해당하는\end{...}가 있습니까? - ✅ 모든
{에 해당하는}가 있습니까? - ✅ 이미지 경로가 올바릅니까? (
\graphicspath로 검색 경로 설정) - ✅ 패키지가 모두 설치되었습니까? (
kpsewhich <pkg>.sty로 확인) - ✅ 중국어 문서가 ctex를 사용하고 올바른
fontset을 지정했습니까? - ✅ 로그 끝을 확인하십시오 — LaTeX의 오류 메시지는 일반적으로 실제 문제가 있는 줄을 가리킵니다.