markdown.qmd

# 마크다운

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

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

[cm]: http://commonmark.org/
[gfm]: https://help.github.com/articles/github-flavored-markdown/
[scm]: http://scholarlymarkdown.com/

## 메타데이터(Metadata)

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

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

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

## 기본 구문

### 제목

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


::::: {.columns}

::: {.column width=47.5%}
````yaml
# 들어가며
# 방법론
## 동적 인구 모형
````
:::

::: {.column width=5%}
:::

::: {.column width=47.5%}
``` bash
# 들어가며 {.unnumbered}
# 방법론 {.unnumbered}
## 동적 인구 모형 {.unnumbered}
```
:::

:::::


### 텍스트 서식

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

::::: {.columns}

::: {.column width=47.5%}
````yaml
*이탤릭* 그리고 _이탤릭_
**굵게** 그리고 __굵게__
***이탤릭 굵게.*** 그리고 ___이탤릭 굵게.___
````
:::

::: {.column width=5%}
:::


::: {.column width=47.5%}
*이탤릭* 그리고 _이탤릭_ <br>
**굵게** 그리고 __굵게__ <br>
***이탤릭 굵게.*** 그리고 ___이탤릭 굵게.___
:::

:::::

### 코드

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

::::: {.columns}

::: {.column width=47.5%}
````yaml
프로그램 실행은 `python helloworld.py`으로 프롬프트를 작성한다.
````
:::

::: {.column width=5%}
:::


::: {.column width=47.5%}
프로그램 실행은 `python helloworld.py`으로 프롬프트를 작성한다.
:::

:::::



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

::::: {.columns}

::: {.column width=47.5%}
````yaml
```
이것이
R, 파이썬
코드블록 입니다.
```
````
:::

::: {.column width=5%}
:::


::: {.column width=47.5%}
```yaml
이것이
R, 파이썬
코드블록 입니다.
```
:::

:::::




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

::::: {.columns}

::: {.column width=47.5%}
````yaml
`python` 으로 언어를 명세한다:

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

훌륭해 보입니다!
````
:::

::: {.column width=5%}
:::

::: {.column width=47.5%}
`python` 으로 언어를 명세한다:

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

훌륭해 보입니다!
:::

:::::


### 링크

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

::::: {.columns}

::: {.column width=47.5%}
````yaml
이것은 [첫번째 링크], 다음은 또다른 [두번째 링크][link2] 혹은 [세번째 링크](http://link.1)

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

::: {.column width=5%}
:::

::: {.column width=47.5%}
이것은 [첫번째 링크], 다음은 또다른 [두번째 링크][link2] 혹은 [세번째 링크](http://link.1)

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

:::::


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

## 컴파일

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

### 팬독(`pandoc`) 으로 컴파일

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

````yaml
pandoc input.ext -o output.ext
````


#### 기본 구문

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

````yaml
pandoc manuscript.md -o manuscript.pdf
````

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

````yaml
pandoc manuscript.md -o manuscript.doc
````

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

### 견본 템플릿

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

### 선택옵션 플래그

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


## 고급 마크다운

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


### 수식

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

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

그리고 다음도 적법하다:

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

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

### 표

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

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

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

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

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

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

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


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

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

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


### 그림

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

예를 들어, 

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

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

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

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

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

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

### 참고문헌

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

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

````yaml
@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 참조)`와 같이 나타난다.

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