11  마크다운

마크다운은 마크다운(markdown) 형식으로, 아래 한글, MS 워드, 리눅스 오픈 오피스, 맥 페이퍼즈 와 달리 화면에 보이는 것이 글자 그대로 텍스트다. 서식은 나중에 부가되는 소프트웨어로 입혀지게 된다.

핵심적인 마크다운 언어 구문을 살펴보자. 시작하기 전에, 몇가지 마크다운 방언(?)이 인터넷에 존재하고 있다는 점을 상기한다. CommonMark은 표준에 기초해서 생성되었고, GFM은 GitHub 에서 개발되어 너무나도 널리 사용되어 이미 표준이 되었다. 이번 학습은 두 마크다운에 공통으로 존재하는 구문을 소개한다. 또다른 흥미롭지만 아직 미완성인 Scholarly Markdown도 있는데, 학계 저작을 목표로 개발되고 있다.

11.1 메타데이터(Metadata)

마크다운으로 문서 메타데이터를 저자가 야믈(YAML) 헤더에 나타낼 수 있다. YAML 은 “Yet Another Markup Language”를 축약한 두문어지만 중요하지는 않다. YAML 헤더는 다음과 같다.

---
title: "마크다운과 팬독(`pandoc`)을 활용한 과학기술문서 저작"
shorttitle: "현대적인 과학기술 문서 저작"
author: 이광춘
date: "2015년 7월 7일"
---

상기 야믈(YAML) 헤더 요소는 견본(템플릿) 으로 사용되고 해당 문서에 대한 메타데이터가 정의된다.

11.2 기본 구문

11.2.1 제목

줄에 숫자 기호(#)를 한개부터 여섯개까지 작성해서 텍스트에 작성되는 구분 수준이 결정된다. 예를 들어, 다음 문서는 첫번째 큰 제목 두개(들어가면, 방법론)를 갖고, 방법론 제목에 중첩된 두번째 제목을 갖는다: 동적 인구 모형

# 들어가며
# 방법론
## 동적 인구 모형

들어가며

방법론

동적 인구 모형

11.2.2 텍스트 서식

마크다운으로 쉽게 이탤릭, 굵게, 이탤릭 굵게 글씨체를 지정할 수 있다. (하지만, 모든 마크다운이 마지막 서식구문에 동의하지는 않는다). 글꼴에 서식 적용은 * 혹은 _을 사용해서 적용한다. 따라서 다음 명령어는 모두 동등하다:

*이탤릭* 그리고 _이탤릭_
**굵게** 그리고 __굵게__
***이탤릭 굵게.*** 그리고 ___이탤릭 굵게.___

이탤릭 그리고 이탤릭
굵게 그리고 굵게
이탤릭 굵게. 그리고 이탤릭 굵게.

11.2.3 코드

코드는 백틱으로 텍스트를 감싸 인라인(inline) 으로 작성하거나,

프로그램 실행은 `python helloworld.py`으로 프롬프트를 작성한다.

프로그램 실행은 python helloworld.py으로 프롬프트를 작성한다.

혹은 백틱(`) 3개나 틸드(~) 3개를 한줄씩 코드상하에 넣어 코드블록을 구분한다:

```
이것이
R, 파이썬
코드블록 입니다.
```

이것이
R, 파이썬
코드블록 입니다.

코드블록 첫번째 행에, 프로그래밍 언어 를 명세하는 것도 가능하다:

`python` 으로 언어를 명세한다:

```python
for i in xrange(5):
  print "This is line " + str(i) + " of this useless loop.\n"
```

훌륭해 보입니다!

python 으로 언어를 명세한다:

for i in xrange(5):
  print "This is line " + str(i) + " of this useless loop.\n"

훌륭해 보입니다!

11.2.4 링크

하이퍼링크를 작성하는 방식은 두가지가 있다. 첫번째는 인라인 으로 작성하는 것으로 [텍스트](http://link.tld) 방식을 사용한다. 두번째는 명칭을 지정한 표식을 사용하는 방식이다. 예를 들어:

이것은 [첫번째 링크], 다음은 또다른 [두번째 링크][link2] 혹은 [세번째 링크](http://link.1)

[첫번째 링크]: http://link.1
[link2]: http://link.2

이것은 첫번째 링크, 다음은 또다른 두번째 링크 혹은 세번째 링크

명칭을 지정한 표식을 사용하는 방식에 대한 구문은 [텍스트][표식] 이 먼저 나오고 나서, [표식]: http://link 표식링크가 문서 다음에 뒤따라 나온다. [표식]이 없는 경우 [텍스트]: link 방식으로 동작하게 된다.

11.3 컴파일

지금까지 작성원고는 말그대로 마크다운 자체 파일(확장자가 mkd, .markdown, .pandoc)이다. 마크다운을 뭔가 다른 것으로 변환할 필요가 있다. 대체로 PDF, 혹은 텍스트 프로세서에서 볼 수 있는 문서형식이 된다.

11.3.1 팬독(pandoc) 으로 컴파일

팬독(pandoc) 프로그램이 이런 작업을 수행하는 나름 최적의 도구다.(물론, jekyll 처럼 웹에 특화된 도구도 존재한다.) 대부분의 명령-라인 도구와 마찬가지로, pandoc은 입력값으로 파일과 일부 선택옵션 플래그를 순차적으로 받는다. pandoc을 호출하는 기본방식은 다음과 같다:

pandoc input.ext -o output.ext

기본 구문

팬독(pandoc) 아래 숨은 마술 로 입력파일이 출력 파일로 된다. 다음 경우에, 입력파일은 마크다운으로 PDF 파일을 생성하는 마술 명령어는 다음과 같다:

pandoc manuscript.md -o manuscript.pdf

그리고 MS 워드 문서를 생성하려면 다음과 같다.

pandoc manuscript.md -o manuscript.doc

docx, otf는 신규 워드문서와 리브레오피스 확장자다. txt, rtf, html을 시도해보고 산출결과가 어떻게 달라지는지 살펴본다.

11.3.2 견본 템플릿

최종문서에 작성한 것을 어디에 넣을지 팬독(pandoc)은 어떻게 알 수 있을까? 다양한 견본 템플릿 이 존재하는데, 견본 템플릿에는 pandoc이 모든 요소를 어디에 넣을지 정리되어 있다. pandoc 웹사이트에서 견본 템플릿을 복사하고 변경할 수 있는 다양한 정보가 담겨있다. 구글로 바로 찾을 수 있는 재사용가능한 견본 템플릿이 상당히 많다.

11.3.3 선택옵션 플래그

선택옵션 플래그를 통해서 pandoc에 추가적인 인자를 전달한다. pandoc 에서 지원하는 인자가 상당히 많은데, 자세한 정보는 쉘를 열고 man pandoc 도움말을 참조하거나, 인터넷 온라인 문서를 참조한다. 본 학습에서는 참고문헌과 관련된 두가지 선택옵션 플래그에 집중한다.

11.4 고급 마크다운

학술적 논문은 단순 텍스트보다 많은 정보가 담긴다. 이번 학습에서 참고문헌, 표, 그림, 수식을 추가하는 방법을 다룬다. 기억할 한가지 중요한 점은 LaTeX 명령어가 다른 형식으로 변환할 때 (최소한 pandoc을 사용할 때 그런데, pandoc은 가장 일반적인 프로그램이다), 그대로 먹힌다는 사실이다. 이런 점이 수식 사용을 상당히 단순화시킨다.

11.4.1 수식

수식을 LaTeX 구문으로 작성할 수 있다. 예를 들어, 아래 코드 덩어리는 적법한 마크다운 구문이다:

The equation for a polynomial function is $y(x) = ax^2 + bx +c$.

그리고 다음도 적법하다:

The sum of a vector of numbers ($\mathbf{v}$) is noted

\begin{equation}
\sum_{x=1}^n\mathbf{v}_i
\end{equation}

11.4.2 표

마크다운이 갖는 이슈중 하나는 표에 대한 지원이 미약하다는 점이다. (하지만, LaTeX 구문을 사용하는 것은 가능) 그럼에도 불구하고, 상대적으로 간단한 표를 작성하는 방법은 있다.

|  교과목  |    담당자 |     선수 교과목 |
|:---------|:-----------|------------------:|
| 마크다운 | xwMOOC        | 쉘, Git, Makefiles |

상기 구문을 적용하면 다음에 나온 표가 작성된다.

교과목	담당자	선수 교과목
마크다운	xwMOOC	쉘, Git, Makefiles

표를 구성하는 요소가 몇개 있다. 첫번째 줄은 헤더 로 표제목, 두번째 줄은 정렬, 그 다음 줄이 표에 기술되는 내용물 이 된다.

칼럼은 파이프(|) 기호로 구분한다. 파이프를 수직방향으로 정렬할 필요는 없다. (하지만, 원문서를 읽을 때 가독성을 상당히 높힌다 – 편집기 대부분에는 이런 기능을 플러그인으로 지원한다)

기본디폴트 설정으로 칼럼은 좌측 정렬 된다. 정렬을 명세하려면, 두번째 행에 다음과 같이 : 세미콜론을 사용해서 지정한다.

|   좌측정렬  |  중앙정렬  |    우측정렬   | 기본 설정 (좌측) |
|:-------------|:--------:|--------------:|:---------------|
| `:---`       |  `:--:`  |        `---:` | `----`         |

상기 구문을 적용하면 다음에 나온 표가 작성된다.

좌측정렬	중앙정렬	우측정렬	기본 설정 (좌측)
:---	:--:	---:	----

11.4.3 그림

그림은 마크다운에서 잘 지원되고 있다. 표기법은 링크에 사용된 표기법을 따르지만, 느낌표(!)를 앞에 위치시킬 필요가 있다.

예를 들어,

![소프트웨어 카펜트리 로고](images/swc-logo-blue.png)

상기 구문을 적용하면 다음과 같이 그림이 삽입된다.

소프트웨어 카펜트리 로고

다른 방법으로 다음과 같이 그림 삽입 구문을 작성해도 된다.

![소프트웨어 카펜트리 로고][swc]
[swc]: (images/swc-logo-blue.png)

LaTeX 명령어, \label{f:swc} 라벨을 넣은 것에 주목한다. \autoref{f:swc}를 사용해서 텍스트에 그림을 참조하게 한다. LaTeX에 autoref 팩키지는 놀랍도록 유용한데, 참조하는 객체 유형을 식별해서, 사람이 관여하지 않고도 Fig. 1, Tab. 2, Eqn. 3, 혹은 기타 필요한 것을 자동으로 완성시킨다.

11.4.4 참고문헌

학술논문에 있는 최종 요건은 참고문헌이다. pandoc과 pandoc-citeproc 확장기능을 통해 마크다운이 참고문헌 기능을 매우 우아하게 처리한다. pandoc 서지관리 모듈은 다양한 형식으로부터 인용을 불러올 수 있다. 최초 CSL JSON 와 CSL YAML로 설계되어, bibtex과 RIS를 수용할 수 있다.

참고문헌을 참조하는 방식은 인용키, @CitationKey를 이용한다. 예를 들어, (bibtex) 라이브러리에 다음 참고문헌이 담겨 있다면:

@ARTICLE{thom99,
    title = {The raw material for coevolution},
    journal = {Oikos},
    author = {Thompson, John N},
    number = {1},
    volume = {84},
    year = {1999},
    pages = {5--16},
}

텍스트에 @thom99 을 넣어 참조한다. 모든 참고문헌 관리 소프트웨어를 사용해서 pandoc에서 지원되는 형식 중 하나로 내보내기 한다. 인용키가 보여주는 방식을 사용자 정의에 맞추면 된다.

참고문헌을 ([@John2012; @Jack2014])와 같이 결합할 수 있고, 인라인 으로 “저자-년도” 스타일을 지정해서 사용하고 있다면 @Doe2013 작성하게 되면 Doe (2013)와 같이 표시되고, 괄호를 사용해서 [@Doe2013]와 같이 사용하면 (Doe, 2013) 산출물을 얻게 된다. 또한, 텍스트를 추가하는 것도 가능하다: [검토를 위해 @Billy2015 참조] 와 같이 작성하면, (검토를 위해 Billy et al., 2015 참조)와 같이 나타난다.

참고문헌이 문서 끝에 자동으로 삽입된다. 저널 요건에 맞춰 서식을 바꾼 수천가지 방법이 있다.