CTAN과 문서

LaTeX을 설치하는 순간 도서관 하나가 함께 설치됩니다. TeX Live 2024의 texmf-dist/doc 아래 문서——모두 CTAN(Comprehensive TeX Archive Network)에서 온 것들입니다——를 세어 보면 PDF만 10,099편이고 트리 전체는 3.7 GB이며, 그 대부분은 한 번도 열리지 않습니다. 내 디스크에 있는 사본을 여는 열쇠는 texdoc이라는 한 단어짜리 명령입니다. 이 페이지에서는 이 아카이브가 어떻게 돌아가는지, 그리고 그보다 더 쓸모 있는 것——이미 가지고 있는 문서를 읽는 법(texdoc, kpsewhich, tlmgr info, 그리고 .dtx에서 설명서를 직접 조판하는 법)을 다룹니다.

texdoc 패키지이름——내 컴퓨터의 설명서를 1초 만에 열기

texdoc booktabs라고 치면 지금 설치되어 있는 booktabs의 설명서 PDF가 그대로 열립니다. 웹 검색이 아니라 디스크 위의 파일입니다. 이것이 중요한 이유는 열리는 것이 설치된 버전에 대응하는 문서이기 때문입니다. 웹에서 찾은 글이 두 세대 전 방식일 수 있지만, texdoc이 건네주는 PDF는 바로 내 환경을 설명합니다. 기본값은 view 모드로, 도구가 가장 좋다고 판단한 결과 하나를 엽니다. 옵션을 붙이면 동작이 달라집니다. -l은 후보를 나열해 번호로 고르게 하고, -m은 좋은 결과가 하나뿐이면 바로 열고 여럿이면 목록을 보여 주며, -s는 평소 숨겨지는 낮은 점수의 결과까지 보여 줍니다.

texdoc booktabs        # open the manual for the version you have installed
texdoc -l siunitx      # list every candidate, then pick one by number
texdoc -I -l booktabs  # plain list, no interactive prompt
texdoc -M -l lshort    # machine-readable: name, score, path, language
texdoc bootabs         # a typo still finds booktabs (fuzzy search)

texdoc이 똑똑한 이유는 파일 이름만 맞춰 보지 않기 때문입니다. 문서 트리(TEXDOCS 경로)를 훑는 것에 더해 TeX Live 데이터베이스 texlive.tlpdb를 조회하여 이름.sty나 이름.cls를 담고 있는 패키지까지 따라갑니다. 그래서 texdoc shortvrb는 shortvrb.sty를 품고 있는 latex 패키지 안의 doc.pdf를 정확히 엽니다. 기본 설정 파일에 alias shortvrb = base/doc라는 줄이 들어 있기 때문입니다. 후보에는 숫자 점수가 붙어서 이름.pdf는 높은 점수를, Makefile은 -1000만큼 낮은 점수를 받습니다. 철자가 틀려 아무것도 맞지 않으면 가장 가까운 패키지 이름을 다시 찾으므로 texdoc bootabs도 booktabs 설명서에 도착합니다. 그래도 실패하면 Unfortunately, there are no good matches for "..."라는 메시지와 함께 texdoc.org의 같은 문서로 가는 안내가 나옵니다.

여러 언어로 읽는 사람에게 특히 중요한 장치가 하나 더 있습니다. texdoc은 시스템 로캘에서 읽는 이의 언어를 추측하고 이름-언어코드.pdf에 가산점을 줍니다. texdoc -l booktabs을 실행하면 영어 booktabs.pdf 옆에 booktabs-de와 booktabs-fr 디렉터리가 함께 나옵니다. 번역된 설명서가 TeX Live에 함께 들어 있기 때문입니다. 같은 이유로 texdoc -l lshort은 60건이 넘는 결과를 돌려주며, 각 언어판이 [fr], [zh], [ko] 같은 표시를 달고 앞쪽에 놓입니다. 자동 판별이 어긋나는 환경이라면 개인 설정 파일에 lang = ko 한 줄을 넣어 고정할 수 있습니다. 파일 위치는 texdoc --files가 알려 주며 macOS에서는 ~/Library/texmf/texdoc/texdoc.cnf입니다. 같은 파일에 mode = list라고 적으면 이후 모든 호출이 -l을 붙인 것과 같이 동작합니다.

그 .sty는 어디에 있는가——kpsewhich와 tlmgr info

kpsewhich booktabs.sty는 LaTeX이 실제로 읽을 파일의 절대 경로를 한 줄로 돌려줍니다. 문서가 설명서와 어긋나게 동작할 때 가장 먼저 의심할 것은 버전이 아니라 “읽고 있는 파일이 내가 생각하는 그 파일이 아닐 가능성”이고, 이 명령이 그것을 한 번에 확인해 줍니다. --all을 붙이면 검색 순서대로 모든 후보가 나옵니다. kpsewhich --all article.cls를 실행하면 두 줄이 돌아옵니다. texmf-dist/tex/latex/base/article.cls와 texmf-dist/tex/latex-dev/base/article.cls입니다. 같은 이름의 파일이 뒤쪽 것을 가리고 있는 상태가 눈에 보이는 것입니다. 직접 만든 .sty를 홈에 둔 기억이 있다면 kpsewhich -var-value=TEXMFHOME이 알려 주는 디렉터리(macOS에서는 ~/Library/texmf)를 의심하세요. 파일을 못 찾으면 아무것도 출력하지 않고 종료 코드 1을 돌려주므로 스크립트의 조건문에도 그대로 쓸 수 있습니다.

kpsewhich booktabs.sty          # which file will TeX actually read?
kpsewhich --all article.cls     # every copy, in search order
kpsewhich -var-value=TEXMFHOME  # your personal tree

tlmgr info booktabs             # version, licence, collection, sizes
tlmgr info --list booktabs      # run / source / doc files, one by one

tlmgr info booktabs은 다른 질문에 답합니다. 어디에 있느냐가 아니라 카탈로그가 뭐라고 적고 있느냐입니다. 한 줄 설명, 긴 설명, 소속 컬렉션, 라이선스(lppl1.3c), src・doc・run 각 부분의 용량, 그리고 버전이 나옵니다. cat-contact-bugs나 cat-contact-repository 항목이 함께 나오기도 하는데, 그것이 그 패키지의 이슈 트래커 주소입니다. tlmgr info --list booktabs을 실행하면 파일들이 세 묶음으로 나열되고, 이 세 묶음이 곧 TeX Live의 디렉터리 구조입니다. tex/latex/booktabs/booktabs.sty(실행 시 읽히는 본체), doc/latex/booktabs/booktabs.pdf(texdoc이 여는 설명서), 그리고 source/latex/booktabs/booktabs.dtx와 .ins(앞의 둘이 만들어지는 원본)입니다.

.dtx와 .ins——소스가 그대로 설명서가 되는 구조

.dtx는 코드와 해설을 한 파일에 함께 담은 형식이며, 같은 파일을 두 가지 방식으로 처리할 수 있습니다. tex 패키지이름.ins를 실행하면 docstrip이 해설 행을 버리고 .sty를 써 내고, pdflatex 패키지이름.dtx를 실행하면 이번에는 코드가 한 줄씩 주석이 붙은 채로 조판되어 설명서 PDF가 됩니다. 실제로 multirow로 시험해 보니 tex multirow.ins가 multirow.sty・bigstrut.sty・bigdelim.sty 세 파일을 만들었고, pdflatex multirow.dtx가 30쪽짜리 주석 소스를 뽑아 주었습니다. 이 형식이 고마운 이유는 texdoc 설명서에 없는 동작까지 추적할 수 있기 때문입니다. 구현이 그대로 거기에 있으니 “왜 이 옵션은 이렇게 되는가”를 끝까지 읽어 낼 수 있습니다.

# copy the two source files out of the tree first, then:
tex multirow.ins        # docstrip: writes multirow.sty, bigstrut.sty, bigdelim.sty
pdflatex multirow.dtx   # the same .dtx typeset as an annotated source PDF
pdflatex multirow.dtx   # run twice so the cross-references settle

이 구조가 극단까지 간 예가 LaTeX 본체입니다. texdoc source2e를 실행하면 『The LaTeX 2ε Sources』가 열립니다. Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach 등의 이름이 적힌 1,308쪽짜리 주석 커널 전문입니다. 그리고 문서를 읽는 습관이 붙으면 재미있는 것들이 눈에 들어옵니다. tlmgr info booktabs이 알려 주는 버전은 1.61803398——황금비 φ = 1.618033988…의 자릿수를 배포할 때마다 하나씩 늘린 것이고, booktabs.dtx 안에도 “(converging to phi, the golden ratio)”라고 적혀 있습니다. 버전 번호가 실은 수열이라는 것은 농담이지만, 농담임을 확인할 수 있는 곳은 .dtx뿐입니다.

CTAN이란 무엇인가——1992년에 만들어진 하나의 주소

CTAN(Comprehensive TeX Archive Network, ctan.org)은 TeX 관련 자료를 두는 곳을 하나로 정하기 위해 만들어졌습니다. 1992년 독일의 Rainer Schöpf와 Joachim Schrod, 영국의 Sebastian Rahtz, 그리고 미국의 George Greenwade——‘CTAN’이라는 이름을 낸 사람이 그입니다——가 구축했고, 1993년 영국 Aston에서 열린 EuroTeX 학회에서 공식 발표되었습니다. 착상 자체는 1991년의 토론으로 거슬러 올라갑니다. 그전까지 매크로와 글꼴은 여기저기 FTP 사이트에 흩어져 있었고, 서로 다른 사람들이 같은 자료를 따로따로 다시 모으고 있었습니다. 그러니 CTAN이 푼 문제는 “둘 곳이 없다”가 아니라 “둘 곳이 너무 많다”였습니다.

오늘날 CTAN의 입구는 패키지 페이지 ctan.org/pkg/<이름>입니다. 여기에는 Sources(원본), Documentation(PDF), Version, Licenses, Copyright, Maintainer, Contained in(TeX Live / MiKTeX에 들어 있는지), Topics(주제 분류)가 나열됩니다. 실무에서 효과를 보는 것은 뒤의 두 가지입니다. Contained in을 보면 tlmgr install로 설치되는지 손으로 넣어야 하는지 한눈에 알 수 있습니다. Topics는 “이름은 모르지만 기능은 안다”일 때의 입구로, 표 조판을 찾는다면 table 주제를 따라가면 됩니다. 라이선스 항목은 거의 언제나 LPPL(LaTeX Project Public License)이며, 이는 배포와 개변의 조건을 정한 TeX 세계의 표준 라이선스입니다.

‘Network’이라는 말은 장식이 아닙니다. CTAN은 중심 사이트와 전 세계의 공식 미러로 이루어져 있고, 미러는 자동으로 동기화됩니다(현재 하나를 운영하려면 디스크 50 GB 남짓이 필요합니다). 그래서 내려받기 주소에 mirror.ctan.org를 쓰면 가까운 미러로 자동 분배됩니다. TeX Live 공식 안내서도 기본 패키지 저장소는 https://mirror.ctan.org를 통해 자동으로 선택된 CTAN 미러라고 명시합니다. 특정 미러로 고정하고 싶다면 목록이 ctan.org/mirrors에 있습니다. 반대 방향의 흐름도 있습니다. 저자는 새 패키지나 갱신본을 중심 사이트의 접수 영역에 업로드하고, CTAN 팀의 처리를 거쳐 미러로 퍼집니다. 이 투고를 돕는 도구까지 TeX Live에 들어 있어서 ctanify는 CTAN이 선호하는 구조의 압축본을 만들고, ctan-o-mat은 보내기 전에 유효성을 검사합니다. 그리고 TeX Live 자체가 ‘CTAN의 스냅숏’입니다. 내 디스크에 있는 3.7 GB의 문서가 곧 이 아카이브의 사본인 것입니다.

로컬 문서와 온라인 문서, 무엇을 믿을 것인가

내 문서가 컴파일되는지를 결정하는 것은 내 디스크에 있는 문서입니다. 그러니 “왜 안 되는가”를 조사할 때는 texdoc을 먼저 여세요. 반대로 “이 기능이 추가되었는가”를 알아볼 때는 CTAN 패키지 페이지나 texdoc.org를 봅니다. 그쪽은 언제나 최신입니다. 둘이 어긋나는 상황은 실제로 있습니다. TeX Live의 각 릴리스는 언젠가 동결되고 그 뒤의 갱신은 다음 릴리스에 실리므로, tlmgr info가 알려 주는 버전이나 주제 분류가 CTAN 표시보다 오래된 일은 흔합니다. 차이를 발견하면 안전한 순서는 이렇습니다. 먼저 tlmgr info <패키지이름>으로 내 판본을 확인하고, 그다음 CTAN 쪽 기술과 견주어 읽습니다. 웹에서 주운 코드가 돌아가지 않는 원인은 상당수 글이 낡아서가 아니라 내 환경과 글쓴이의 환경이 다르기 때문입니다.