6  마크다운

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

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

6.1 메타데이터(Metadata)

마크다운 문서에서 ‘저자’, ‘문서제목’ 등은 야믈(YAML) 헤더를 사용하여 메타데이터를 표현할 수 있다. YAML 은 “Yet Another Markup Language”를 축약한 두문어지만 중요하지는 않다. YAML 헤더는 다음과 같다. 

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

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

6.2 기본 구문

6.2.1 제목

마크다운에서는 # 기호를 사용하여 문서 제목 수준을 결정한다. # 기호를 한 개부터 여섯 개까지 사용하며, # 기호 개수가 많아질수록 제목 수준은 낮아지고, 텍스트 크기도 작아진다. 예를 들어, 어떤 문서가 첫 번째 큰 제목으로 들어가며와 방법론을 갖고 있고, 방법론 아래에는 두 번째 수준 제목인 동적 인구 모형이 있다면, 다음과 같이 작성한다. 

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

6.2.2 텍스트 서식

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

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


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

6.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"

훌륭해 보입니다!

6.2.4 링크

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

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

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


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

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

6.3 컴파일

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

6.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을 시도해보고 산출결과가 어떻게 달라지는지도 살펴보자.

6.3.2 견본 템플릿

팬독은 최종 문서의 내용을 어디에 배치할지 결정하기 위해 다양한 견본 템플릿을 활용한다. 팬독 견본 템플릿은 문서 변환 과정에서 사용되는 일종의 구조적 지침서다. 견본 템플릿에는 팬독이 문서의 각 요소를 어떻게 배열할지에 대한 지침이 포함되어 있다. 예를 들어, 마크다운 파일을 PDF, HTML, LaTeX 등으로 변환할 때, 견본 템플릿에는 문서의 제목, 저자, 날짜, 텍스트 블록, 이미지 등이 최종 문서에서 어떻게 출력될지 정의되어 있다. 팬독 웹사이트에 견본 템플릿을 찾아 복사하고 수정할 수 있는 정보가 제공되고 있고, 구글 검색을 통해 쉽게 찾을 수 있는 재사용 가능한 다양한 견본 템플릿도 많이 존재한다.

6.3.3 선택옵션 플래그

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

6.4 고급 마크다운

학술 논문 작성 시, 단순 텍스트 이상의 다양한 요소들이 포함된다. 특히, 참고문헌, 표, 그림, 수식은 학술 논문에서 매우 중요한 문서구성 요소다. 이러한 요소들을 추가하는 방법을 살펴볼 때, 특히 유의해야 할 점은 팬독을 사용할 때 \LaTeX 명령어가 다른 형식으로 변환되는 과정에서도 그대로 적용된다는 것입니다. 이런 점이 수식 사용을 상당히 단순화시킨다.

6.4.1 수식

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

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

그리고 다음도 마크다운과 \(\LaTeX\) 코드가 섞여 있지만 적법한 구문이다.

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

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

6.4.2 표

마크다운의 한 가지 단점은 표 생성에 대한 지원이 제한적이라는 점이다. 비록 \(\LaTeX\) 구문을 사용하는 것이 가능하지만, 상대적으로 간단히 표를 표를 작성하는 방법은 있다. 

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

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

교과목 담당자 선수 교과목
마크다운 홍길동 쉘, Git, Makefiles
표 6.1: 고급 마크다운 표작성 사례

표를 구성하는 요소가 몇개 있다. 첫번째 줄은 헤더 로 표제목, 두번째 줄은 정렬, 그 다음 줄이 표에 기술되는 내용물 이 된다. 칼럼은 파이프(|) 기호로 구분한다. 파이프를 수직방향으로 정렬할 필요는 없다. (하지만, 원문서코드를 읽을 때 가독성을 상당히 높힌다 – 대부분의 편집기에서 이런 기능을 플러그인으로 지원한다)

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

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

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

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

6.4.3 그림

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

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

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

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

![소프트웨어 카펜트리 로고\label{f:swc}][swc]
[swc]: http://swcarpentry.github.io/modern-scientific-authoring/assets/img/swc-logo-blue.svg

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

6.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 참조)와 같이 나타난다. 참고문헌은 문서 끝에 자동으로 삽입되며, 저널 요건에 맞춰 서식을 변경하는 수천 가지 방법이 있다.

연습문제

객관식

  1. 마크다운에서 # 기호의 사용 목적은 무엇인가요?
    1. 텍스트 색상 변경
    2. 문서 제목 수준 결정
    3. 텍스트 강조
    4. 링크 생성
  1. 마크다운에서 코드를 표시하는 방법은 무엇인가요?
    1. * 기호 사용
    2. 백틱(`) 사용
    3. _ 기호 사용
    4. # 기호 사용
  1. 마크다운에서 하이퍼링크를 생성하는 방법은 무엇인가요?
    1. # 기호 사용
    2. * 기호 사용
    3. [텍스트](링크) 구문 사용
    4. _ 기호 사용

서술형

  1. 마크다운에서 표를 생성하는 방법에 대해 설명해보세요.
  1. 마크다운에서 참고문헌을 어떻게 관리하고 참조하는지 설명해보세요.