리눅스 환경에서 판독(pandoc)은 40가지 이상의 다양한 파일 형식 간의 변환을 가능하게 하는 강력한 도구입니다. 마크다운 형식으로 작성된 문서를 깃(git) 저장소에 보관하고, 이를 다양한 형식으로 간편하게 배포하여 효율적인 문서 관리 시스템을 구축할 수 있습니다.
문서 변환과 코드 기반 문서 시스템
판독은 다양한 파일 형식을 지원하여 문서 변환 작업을 매우 간단하게 만들어줍니다. 이는 문서 작업을 할 때 매우 유용한 도구입니다.
하지만 판독의 진정한 가치는 단순한 ‘코드로서의 문서(docs-as-code)’ 시스템의 토대로 활용될 때 더욱 빛을 발합니다. ‘코드로서의 문서’는 소프트웨어 개발에서 사용하는 기술과 원칙을 문서 작성, 특히 소프트웨어 개발 프로젝트 문서에 적용하는 개념입니다. 물론 이는 다양한 종류의 문서 개발에도 적용 가능합니다.
소프트웨어 개발자들은 주로 선호하는 편집기나 통합 개발 환경(IDE)을 사용하여 코드를 작성합니다. 작성된 코드는 텍스트 파일 형태로 저장되며, 여기에는 프로그램의 소스 코드가 포함됩니다.
소스 코드의 개발 및 개선 과정을 추적하기 위해 개발자들은 버전 관리 시스템(VCS), 특히 Git을 가장 많이 활용합니다. 이를 통해 개발자들은 소스 코드 파일의 모든 변경 이력을 완벽하게 관리하고, 파일의 이전 버전에도 빠르게 접근할 수 있습니다. Git은 파일들을 저장소에 저장하며, 각 개발자의 컴퓨터에는 로컬 저장소가 있고, 클라우드에 호스팅된 중앙 원격 저장소를 통해 공유합니다.
프로그램 실행 버전을 만들 준비가 되면, 컴파일러를 사용하여 소스 코드를 읽고 실행 가능한 바이너리 파일을 생성합니다.
간결한 텍스트 기반 마크업 언어로 문서를 작성하면, VCS를 이용하여 문서의 버전 관리를 효율적으로 할 수 있습니다. 문서 배포나 게시 준비가 완료되면, 판독을 사용하여 웹 기반(HTML), 워드 프로세서 또는 조판(LibreOffice, Microsoft Word, TeX), PDF, 전자책(ePub) 등 다양한 형식으로 변환할 수 있습니다.
이 모든 작업이 버전 관리되는 간결한 텍스트 파일 세트를 통해 가능하다는 점이 핵심입니다.
판독 설치
Ubuntu 환경에 판독을 설치하려면 다음 명령어를 사용하세요.
sudo apt-get install pandoc
Fedora에서는 아래 명령어를 실행해야 합니다.
sudo dnf install pandoc
Manjaro에서는 다음 명령어를 입력하세요.
sudo pacman -Syu pandoc
설치된 판독의 버전은 ‘–version’ 옵션을 통해 확인할 수 있습니다.
pandoc --version
파일 없이 판독 사용하기
명령줄 옵션 없이 판독을 실행하면, 표준 입력을 통해 입력된 내용을 받을 수 있습니다. Ctrl+D 키를 누르면 입력이 종료됩니다. 판독은 입력된 내용을 마크다운 형식으로 간주하고, HTML 형식으로 출력합니다.
다음 예시를 살펴보겠습니다.
pandoc
몇 줄의 마크다운 텍스트를 입력한 후 Ctrl+D를 누르면
판독은 이에 해당하는 HTML 출력을 즉시 생성합니다.
하지만 판독을 효과적으로 사용하려면 파일을 이용해야 합니다.
마크다운 기본
마크다운은 간결한 마크업 언어이며, 특정 문자들에 특별한 의미를 부여합니다. 일반 텍스트 편집기를 이용하여 마크다운 파일을 작성할 수 있습니다.
마크다운은 텍스트를 방해하는 시각적으로 복잡한 태그 없이 가독성이 뛰어납니다. 마크다운 문서의 서식은 해당 문서가 나타내는 서식과 유사합니다. 다음은 몇 가지 기본적인 마크다운 문법입니다.
텍스트를 기울임꼴로 강조하려면 별표로 감쌉니다. *강조합니다*
텍스트를 굵게 표시하려면 별표 두 개를 사용합니다. **굵게 표시됩니다**
제목은 숫자 기호/해시(#)로 표시하며, 텍스트는 공백으로 해시와 분리합니다. 최상위 제목에는 해시 하나, 두 번째 수준에는 두 개를 사용합니다.
글머리 기호 목록을 만들려면 각 줄을 별표로 시작하고 텍스트 앞에 공백을 추가합니다.
번호 매기기 목록을 만들려면 각 줄을 숫자로 시작하고 마침표를 입력한 다음, 텍스트 앞에 공백을 추가합니다.
하이퍼링크를 생성하려면 사이트 이름을 대괄호([])로 감싸고, 괄호 안에 URL을 넣습니다. [How to Geek 링크](https://www.wdzwdz.com/)
이미지를 삽입하려면 대괄호와 괄호 앞에 느낌표(![])를 사용합니다. 대괄호 안에 이미지의 대체 텍스트를 입력하고, 괄호 안에 이미지 경로를 넣습니다. 예시: .
다음 섹션에서는 위에서 소개된 마크다운 문법에 대한 더 많은 예시를 다룰 것입니다.
파일 변환
파일 변환은 매우 간단합니다. 판독은 일반적으로 파일 이름으로부터 작업 중인 파일 형식을 자동으로 파악합니다. 여기서는 마크다운 파일에서 HTML 파일을 생성해 보겠습니다. ‘-o'(출력) 옵션을 사용하여 생성할 파일의 이름을 판독에 알려줍니다.
pandoc -o sample.html sample.md
마크다운 예시 파일인 ‘sample.md’에는 아래 이미지에 표시된 간단한 마크다운 코드가 포함되어 있습니다.
‘sample.html’ 파일이 생성됩니다. 이 파일을 더블클릭하면 기본 브라우저에서 열립니다.
이번에는 Open Document Format 형식의 텍스트 문서를 생성해 보겠습니다. 이 파일은 LibreOffice Writer에서 열 수 있습니다.
pandoc -o sample.odt sample.md
ODT 파일은 HTML 파일과 동일한 내용을 담고 있습니다.
흥미로운 점은, 그림의 대체 텍스트가 자동으로 그림에 대한 캡션으로 사용된다는 것입니다.
파일 형식 지정
‘-f’ (from) 및 ‘-t’ (to) 옵션을 사용하면 판독에게 변환하려는 파일 형식을 명확히 지정할 수 있습니다. 이는 파일 확장자가 유사한 여러 파일 형식을 처리할 때 특히 유용합니다. 예를 들어, TeX와 LaTeX는 모두 “.tex” 확장자를 사용합니다.
또한 ‘-s’ (독립 실행형) 옵션을 사용하면 판독은 완전하고 독립적인 LaTeX 문서에 필요한 모든 LaTeX 프리앰블을 자동으로 생성합니다. ‘-s’ 옵션을 생략하면 생성되는 출력은 다른 LaTeX 문서에 삽입 가능한 올바른 형식의 LaTeX 코드일 뿐이며, 독립적인 LaTeX 문서로 제대로 구문 분석되지 않습니다.
다음 명령어를 입력해 봅시다.
pandoc -f markdown -t latex -s -o sample.tex sample.md
텍스트 편집기에서 ‘sample.tex’ 파일을 열면 생성된 LaTeX 코드를 확인할 수 있습니다. LaTeX 편집기가 있다면 TEX 파일을 열어 LaTeX 조판 명령이 어떻게 해석되는지 미리 볼 수 있습니다. 아래 이미지에서는 창을 축소하여 보여주기 때문에 디스플레이가 좁아 보이지만, 실제로는 제대로 표시됩니다.
위 예시에서는 Texmaker라는 LaTeX 편집기를 사용했습니다. Ubuntu에 Texmaker를 설치하려면 다음 명령어를 사용하세요.
sudo apt-get install texmaker
Fedora 환경에서는 다음 명령어를 실행합니다.
sudo dnf install texmaker
Manjaro에서는 다음 명령어를 사용하세요.
sudo pacman -Syu texmaker
템플릿을 이용한 파일 변환
판독이 제공하는 뛰어난 유연성에 대한 감을 잡으셨을 것입니다. 한 번만 작성하면 거의 모든 형식으로 문서를 게시할 수 있습니다. 매우 강력한 기능이지만, 문서가 다소 평범하게 보일 수 있습니다.
템플릿을 사용하면 판독이 문서를 생성할 때 사용하는 스타일을 지정할 수 있습니다. 예를 들어, 판독에게 CSS(Cascading Style Sheets) 파일에 정의된 스타일을 사용하도록 지시할 수 있습니다. 이는 ‘–css’ 옵션을 통해 가능합니다.
다음은 레벨 헤더 위아래의 간격을 스타일링하고, 텍스트 색상을 흰색으로, 배경색을 파란색 계열로 변경하는 간단한 CSS 파일입니다.
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
전체 명령어는 다음과 같습니다. 독립 실행형 옵션(‘-s’)도 함께 사용했습니다.
pandoc -o sample.html -s --css sample.css sample.md
판독은 이 최소한의 CSS 파일에 정의된 스타일을 사용하여 1레벨 헤더에 적용합니다.
HTML 파일을 다룰 때 사용할 수 있는 또 다른 미세 조정 옵션은 마크다운 파일에 HTML 마크업을 포함하는 것입니다. 이렇게 추가된 HTML 마크업은 생성된 HTML 파일에 그대로 전달됩니다.
하지만 이 기술은 HTML 출력만 생성할 때 사용하는 것이 좋습니다. 여러 파일 형식을 다루는 경우, 판독은 HTML 형식이 아닌 파일에 대한 HTML 마크업을 무시하고 해당 마크업을 텍스트 형태로 파일에 전달합니다.
ODT 파일이 생성될 때 사용되는 스타일도 지정할 수 있습니다. 비어 있는 LibreOffice Writer 문서를 열고 필요에 맞게 제목 및 글꼴 스타일을 조정합니다. 여기서는 머리글과 바닥글도 추가했습니다. 이 문서를 “odt-template.odt”로 저장합니다.
이제 이 파일을 ‘–reference-doc’ 옵션을 사용하여 템플릿으로 사용할 수 있습니다.
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
이전의 ODT 예시와 비교해 보세요. 이 문서는 다른 글꼴을 사용하며 색상이 적용된 머리글과 바닥글을 포함합니다. 하지만, 정확히 동일한 ‘sample.md’ 마크다운 파일에서 생성되었습니다.
참조 문서 템플릿은 문서 제작의 다양한 단계를 나타내는 데 사용할 수 있습니다. 예를 들어 ‘초안’ 또는 ‘검토용’ 워터마크가 있는 템플릿을 만들어 최종 문서에 워터마크가 없는 템플릿을 사용할 수 있습니다.
PDF 생성
기본적으로 판독은 LaTeX PDF 엔진을 사용하여 PDF 파일을 생성합니다. 적절한 LaTeX 종속성을 충족하는 가장 쉬운 방법은 Texmaker와 같은 LaTeX 편집기를 설치하는 것입니다.
하지만 LaTeX는 상당히 규모가 큰 설치입니다. 하드 드라이브 공간이 제한되어 있거나 TeX 또는 LaTeX를 사용할 필요가 없다고 판단되면, ODT 파일을 생성한 다음 LibreOffice Writer에서 열어 PDF로 저장하는 것이 좋습니다.
코드로서의 문서
마크다운을 문서 작성 언어로 사용할 때 얻을 수 있는 이점은 다음과 같습니다.
- 일반 텍스트 파일 작업은 빠릅니다. 비슷한 크기의 워드 프로세서 파일보다 로드 속도가 빠르며 문서 전체를 더 빠르게 탐색할 수 있습니다. gedit, Vim, Emacs를 비롯한 많은 편집기가 마크다운 텍스트에 대한 구문 강조를 지원합니다.
- 문서의 모든 버전에 대한 타임라인을 확인할 수 있습니다. Git과 같은 VCS에 문서를 저장하면 동일한 파일의 두 버전 간의 차이점을 쉽게 파악할 수 있습니다. 이는 파일이 일반 텍스트일 때만 가능합니다. VCS가 작동하는 방식 때문입니다.
- VCS는 누가 언제 변경했는지 기록할 수 있습니다. 이는 대규모 프로젝트에서 다른 사람과 자주 협업하는 경우에 특히 유용합니다. 또한 문서 자체에 대한 중앙 저장소를 제공합니다. GitHub, GitLab, Bitbucket과 같은 많은 클라우드 호스팅 Git 서비스는 무료 티어 플랜을 제공합니다.
- 여러 형식으로 문서를 생성할 수 있습니다. 몇 가지 간단한 셸 스크립트를 사용하여 CSS 및 참조 문서에서 스타일을 가져올 수 있습니다. 문서를 VCS 저장소에 저장하고, 해당 저장소를 지속적 통합 및 지속적 배포(CI/CD) 플랫폼과 통합하면 소프트웨어 빌드 시마다 문서를 자동으로 생성할 수 있습니다.
마지막 생각들
판독은 여기에서 다룬 것보다 훨씬 더 많은 옵션과 기능을 제공합니다. 대부분의 파일 형식에 대한 변환 프로세스를 조정하고 미세 조정할 수 있습니다. 자세한 내용은 판독 공식 웹페이지의 상세한 예시를 참고하십시오.