/ coursework

Pandoc, Markdown, KaTeX, Visual Studio Code로 똑똑하게 논문쓰기

대학생, 대학원생이라면 한 번쯤은 논문을 쓰게 된다. 그러나 정작 글쓰기보다 글 자간, 글자 크기 등을 한 줄씩 수동으로 입력하느라, 일일이 이미지를 이동시키느라 애를 먹었던 경험이 있을 것이다. 아무리 마이크로소프트 워드나 한글을 쓴다고 해도 문서 템플릿 및 글자 스타일 정의는 내맘대로 되지 않는다. 좀 더 똑똑하고 쉽고 편리하게 논문을 작성할 수 없을까? 여기에 그 방법이 있다!

이 글에서는 마이크로소프트 사의 비주얼 코드에서 마크다운 문법과 KaTeX 수학 수식기 입력 라이브러리로 글을 작성한 후, 문서 출판 도구인 pandoc으로 pdf 문서를 생성하는 과정을 소개한다. 마지막으로 pandoc 학위 논문 템플릿을 사용해 논문을 작성하고 pdf, docx, html, 전자책 등 다양한 포맷으로 문서 출판하는 방법을 알아본다.

우리는 pandoc, LaTeX, Markdown, KaTeX, 비주얼코드 에디터를 사용할 것이다. 시작하기 앞서 각 도구들에 간단히 알아보자.

  • pandoc : 존 팩프랜드(John Macfarlane)가 하스켈 언어로 제작한 오픈 소스로 하나의 문서를 여러 다른 형태의 문서로 변환하는 유틸리티다. pandoc으로 마크다운(Markdown), HTML, LaTeX, Word docx, epub 등 다양한 형식으로 문서를 변환할 수 있다.

  • LaTeX : LaTeX(레이텍)는 오픈소스 조판시스템(Typesetting System)으로 글, 수식, 그래프 작성이 필요한 문서 작업에 많이 사용한다. 수학 수식은 LaTeX 문법을 이용해서 이미지로 렌더링 후 문서에 첨부된다.

  • Markdown : 마크다운 문법은 특수문자를 활용해 각 행과 텍스트를 스타일링한다. 2004년 존 그루버(John Gruber)가 창안한 것으로 쉽게 쓰고 읽을 수 있고 특수기호와 문자를 이용한 매우 간단한 구조의 문법을 사용하여 웹에서도 보다 빠르게 컨텐츠를 작성하고 보다 직관적으로 인식할 수 있다. 깃허브와 스택오브플로우 등 내 텍스트 에디터는 모두 마크다운 문법을 사용하고 있다. 마크다운 문법은 30분 내면 배울 수 있을 정도로 어렵지 않다. 아직 문법에 익숙하지 않다면 마크다운 가이드를 참고하자.

  • KaTeX : 칸 아카데미에서 만든 오픈 소스 수학 입력 수식기 라이브러리이다. 기존 LaTeX는 이미지 형식으로 변환되어 웹에 적합하지 않은 문제가 있었다. KaTeX는 수학 수식을 SVG로 그려 모든 웹 브라우저에서 사용 가능하다. 깔끔한 타이포와 빠른 성능, 서버 사이드 렌더링이 장점이다. MathJax보다 렌더링 속도가 더 빠르고 기존 LaTeX 문법과 거의 유사하다.

  • Visual Studio Code : 마이크로소프트 사의 오픈 소스 에디터이며 무료이다. 간결한 디자인, 깃허브와 연동, 빠른 실행 속도, 플러그인 제공 등으로 최근 많은 주목을 받고 있는 코드 에디터이다.

왜 마크다운인가?

LaTeX(또는 TeX, '텍'이라고 읽는다.)는 가장 널리 알려진 논문 작성 도구로 수학 수식이 필요한 이공학 논문 작성에 널리 쓰이고 있다. 그러나 LaTeX가 아닌 마크다운을 선택한 이유는 마크다운 문법이 좀더 간결하고 직관적이며 깔끔하기 때문이다.

LaTeX와 마크다운을 서로 비교해보자. 둘 중 어떤 것이 가독성이 높은가?

comparision

1. 설치하기

vscode 플러그인 설치

비주얼 코드에는 기본적으로 마크다운 미리보기 기능이 있어 마크다운 문법을 작성하면서 실시간으로 렌더링된 문서를 확인할 수 있다.

그러나 KaTeX 문법을 읽지 못하므로 Markdown+Math
플러그인을 설치가 필요하다. [install] - [reload] 버튼을 클릭하면 간단히 플러그인 설치가 끝난다.

이제 아래와 같이 수학 수식이 잘 보일 것이다.

example

Pandoc 설치

Pandoc 다운로드 페이지에서 최신 버전을 설치한다. MAC의 경우 homebrew로 pandoc를 설치하는 것이 빠르다. brew install pandoc로 설치하면 된다.

TeX 폰트 지원 엔진 설치

먼저 pdf로 변환 시, LaTeX 엔진인 XeTeX을 설치해야 한다. XeTeX는 TTF 및 OTF와 같은 많은 시스템 폰트를 TeX 폰트로 쓸 수 있게 해주는 TeX 조판 시스템 엔진(TeX typesetting engine)이다.

윈도우에서는 Tex Live, MiKTeX 둘 중 하나를, MAC에서는 Tex Live의 MAC버전인 MacTeX를 사용하는 것이 좋다. MacTeX는 용량이 크기 때문에 저용량 버전인 BasicTex을 설치하는 것이 좋다.

이후 기본 TeX 기본 폰트를 설치한다.

tlmgr install collection-fontsrecommended

2. 문서 작성하기

pdf 문서 생성

이제 pandoc 명령어로 pdf 문서를 생성해보자. papersize를 입력하지 않으면 US Letter 사이즈가 나온다. -VKey=Val 쌍으로 입력하는 것을 말한다.

pandoc doc.md -o doc.pdf --pdf-engine=xelatex -V papersize:a4 

그러나 생성된 pdf 문서를 열어보면 영어는 보이지만 한국어는 보이지 않을 것이다.

empty-korean-in-latex

그리고 아래와 같은 오류 메시지가 출력된 것을 확인할 수 있다. XeTeX에 내장된 한국어 폰트가 없기 때문이다.

[WARNING] Missing character: There is no 용 in font [lmroman10-regular]:mapping=tex-text;!
[WARNING] Missing character: There is no 한 in font [lmroman10-regular]:mapping=tex-text;!
[WARNING] Missing character: There is no 다 in font [lmroman10-regular]:mapping=tex-text;!
[WARNING] Missing character: There is no 식 in font [lmroman10-regular]:mapping=tex-text;!

따라서 유효한 한국어 폰트를 지정해야 한다.

한국어 폰트 설정

터미널에서 fc-list :lang=ko 명령어로 한국어 폰트 리스트를 확인할 수 있다. 영어일 경우 ko대신 en을 입력한다. 아쉽게도 한국어 폰트와 영어 폰트를 각각 다르게 처리할 수 있는 방법이 없기 때문에 NanumBarunGothicOTF(나눔바른고딕) 등과 같이 영어 및 한국어 폰트 모두를 지원하는 폰트를 선택해야 한다.

[~]$ fc-list :lang=ko
/Library/Fonts/NanumBarunGothicUltraLight.otf: NanumBarunGothicOTF,나눔바른고딕OTF,NanumBarunGothicOTF UltraLight,나눔바른고딕OTF UltraLight:style=UltraLight
/System/Library/Fonts/AppleSDGothicNeo.ttc: Apple SD Gothic Neo,Apple SD 산돌고딕 Neo:style=Heavy,무거운
/System/Library/Fonts/AppleSDGothicNeo.ttc: .Apple SD Gothic NeoI,Apple SD 산돌고딕 Neo:style=SemiBold,세미볼드체
/Library/Fonts/NanumGothicExtraBold.otf: NanumGothicOTF,나눔고딕OTF,NanumGothicOTFExtraBold,나눔고딕OTF ExtraBold:style=ExtraBold,Regular,Bold
/Library/Fonts/NanumMyeongjoExtraBold.otf: NanumMyeongjoOTF,나눔명조OTF,NanumMyeongjoOTF ExtraBold,나눔명조OTF ExtraBold:style=ExtraBold,Regular
/Library/Fonts/NanumMyeongjoBold.otf: NanumMyeongjoOTF,나눔명조OTF:style=Bold
/System/Library/Fonts/AppleSDGothicNeo.ttc: .Apple SD Gothic NeoI,Apple SD 산돌고딕 Neo:style=UltraLight,아주옅은체
....

이 중 나눔명조 NanumMyeongjoOTF를 메인폰트로 지정해보자.-V mainfont='NanumMyeongjoOTF'를 추가하면 된다.

다시 pdf 문서를 만들어보자.

pandoc doc.md -o doc.pdf --pdf-engine=xelatex -V mainfont='NanumMyeongjoOTF' -V papersize=a4

이제 한글 문자도 보인다.

empty-korean-in-latex

문서 스타일링

문서 자간, 여백, 폰트, 색상, 들여쓰기 등 커스터마이징이 필요하다. 하지만 이전과 같이 명령어를 길게 늘여트려 쓰는 것은 매우 불편하다. 대신해 마크다운 파일의 첫 부분에 스타일을 정의할 수 있다. 공식 문서 내 Variables for LaTeX 파트에 자세하게 나와있다.

---
papersize: a4
mainfont: NanumMyeongjoOTF
margin-left: 0.5in
margin-right: 0.5in
margin-bottom: 0.5in
margin-top: 0.5in
---

별도로 .tex 파일에 LaTeX 문법으로 스타일 템플릿을 만들어 문서 스타일을 정의하고 관리할 수 있다. 마크다운 파일 내 LaTeX 문법을 혼용하여 자신만의 문서 양식을 만들 수 있다.

3. 논문 쓰기

지금까지 간단한 마크다운 문서를 작성하고 판독으로 pdf 파일을 생성하는 방법을 알아보았다. 그러나 전형적인 논문 양식과 구조는 매우 복잡하다. 학교나 학회마다 요구사항과 양식도 상이하다. 따라서 판독을 이용한 논문 템플릿을 보일러플레이트 삼아 뼈대로 활용하고 스타일링을 고쳐 사용할 것을 추천한다. pandoc을 사용한 가장 유명한 논문 작성 라이브러리인 phd 논문 마크다운(phd thesis markdown)를 사용하면 쉽게 논문을 작성하고 출판할 수 있다.

톰 폴라드(Tom Pollard)는 마크다운, LaTeX, Pandoc으로 실제 본인의 학위 논문을 썼다. 그리고 그가 사용한 문서 양식을 작은 프로그램으로 만들어 깃허브에 공개했다. LaTeX와 마크다운을 혼용한 목차, 제목, 본문, 주석, 참고문헌 등의 문서 템플릿을 만들었고, 별도 스타일링 템플렛도 정의했다. make pdf 또는 make html로 pdf, html 문서를 생성한다. 실제로 많은 대학원생들이 그의 프로젝트를 가져가 자기 대학의 문서 양식을 만들고 이를 자신의 학위 논문에 사용하고 있다.

그 예로 호주 UNSW 대학 박사과정 학생인 튜 립슨(Mathew Lipson)은 폴라드 코드 고쳐 몇 가지 기능을 추가하고 자신의 대학 논문 양식으로 수정했다. 그는 깃북(gitbook)으로 퍼블리싱 및 docx 문서 변환 기능을 추가한 버전을 내놨다. 생성된 pdf, html, docx 문서 모습은 아래와 같다.

.pdf
latex example
.html
html example
.docx
docx example

한국어 폰트는 물론 문서 스타일링도 가능하다. style > preamble.tex 파일에서 % 주석을 풀고 \setmainfont에 한영 폰트를 모두 지원하는 폰트이름을 설정하면 된다.

% % Fonts and typesetting
% \setmainfont[Scale=1.1]{Helvetica}
% \setsansfont[Scale=1.1]{Verdana}

% FONTS
\usepackage{xunicode}
\usepackage{xltxtra}
\defaultfontfeatures{Mapping=tex-text} % converts LaTeX specials (``quotes'' --- dashes etc.) to unicode
% \setromanfont[Scale=1.01,Ligatures={Common},Numbers={OldStyle}]{Palatino}
% \setromanfont[Scale=1.01,Ligatures={Common},Numbers={OldStyle}]{Adobe Caslon Pro}
%Following line controls size of code chunks
% \setmonofont[Scale=0.9]{Monaco}
%Following line controls size of figure legends
% \setsansfont[Scale=1.2]{Optima Regular}

개인적으로 매튜 립슨의 버전이 좀더 우리에게 친숙한 논문 양식이며 대제목, 소제목, 본문 모두 마크다운 문법으로 작성할 수 있어 더 좋은 버전이라고 판단된다. pandoc에서는 .epub, .mobi도 지원하기에 전자책 출판도 가능하다.

이외에도 pandoc 위키에 다양한 해외 학회 저널, 강의 노트, 전자책 출판, HTML 등 다양한 pandoc 템플릿이 있다. 꼭 논문 작성이 아니더라도 용도에 맞는 템플릿을 골라 편집해 쓸 수 있고 다른 사람들과 공유할 수 있다. 내가 다니는 대학의 논문 템플릿을 만들고 깃허브에 올려 친구들과 학우들에게 쓸 수 있게 해보면 어떨까? 누군가의 수고를 덜어주고 도와주는 일은 정말 멋진 일이니까 말이다.

물론 논문, 전자책 작성 과정을 깃허브에서도 진행할 수 있다. 매일 조금씩 작성하고 커밋할 수도 있을 것이다. 이로써 글쓰기의 본질인 '내용'에만 오롯이 집중할 수 있게 됐다. 간단한 명령어로 현존하는 거의 모든 문서 형식을 만들 수 있다. 훌륭한 도구들이 모여 강력한 문서 작성 시스템을 만들어냈다. 이 것이 바로 오픈 소스의 힘이 아닐까.