markdown_02_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%}
# 들어가며 {.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` 도움말을 참조하거나,
인터넷 온라인 문서를 참조한다.
본 학습에서는 참고문헌과 관련된 두가지 선택옵션 플래그에 집중한다.