Asciidoctor-pdf 한글 적용하기

 개발 문서를 Asciidoctor를 사용해보고자 알아보던 중 Asciidoctor 문서를 PDF로 생성할 경우 한글 출력에 문제가 있음이 확인되었다.

Asciidoctor 의 Theme 의 font 설정을 통해 해결할 수 있다는 글을 보고 방법을 찾아 보았다.

문서의 독립적인 Theme를 설정하는 것으로 Theme중 font에 대한 내용만 재정의 하여 대응할 수 있었다.

먼저 Theme 를 재정의하고 사용할 Font를 저장하기위해 문서 폴더 하위에 res 폴더을 만들어 두었다. 그리고 그 폴더에서 사용할 맑은 고딕 폰트 "malgun.ttf"와 "D2Coding-Ver1.3.2-20180524.ttf"를 복사해 두었다.

그리고 Theme를 작성하기위해 설치된 기본 Theme인 default-theme.yaml 파일을 my-theme.yaml로 복사하였다.

default-theme.yaml파일을 asciidoctor-pdf 가 설치된 경로의 data\themes 에서 복사하였다.

복사하고 기본값을 반영하기위해 extends: default를 추가하고 필요한 부분만 아래와 같이 작성하였다.

extends: default
font:
  catalog:
    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
    Noto Sans:
      normal: malgun.ttf
      bold: malgun.ttf
      italic: malgun.ttf
      bold_italic: malgun.ttf
    # M+ 1mn supports ASCII and the circled numbers used for conums
    M+ 1mn:
      normal: D2Coding-Ver1.3.2-20180524.ttf
      bold: D2Coding-Ver1.3.2-20180524.ttf
      italic: D2Coding-Ver1.3.2-20180524.ttf
      bold_italic: D2Coding-Ver1.3.2-20180524.ttf
page:
  background_color: FFFFFF
  layout: portrait
  initial_zoom: FitH
  margin: [0.4in, 0.4in, 0.4in, 0.4in]
  # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress
  margin_inner: 0.0in
  margin_outer: 0.0in
  size: A4
base:
  font_family: Noto Sans

이렇게 정의한 theme 파일과 폰트를 적용하기위해 아래 명령을 수행하였다.

asciidoctor-pdf --theme my-theme.yml -a pdf-themesdir=res -a pdf-fontsdir="res;GEM_FONTS_DIR" test.adoc --out-file test_my2.pdf

그 결과 한글은 정상적으로 출력 되는 것을 확인하였다.

하지만 kbd 매크로의 일부가 정상적으로 출력 되지 않는 현상이 나타났다.

그래서 추가 정보(https://docs.asciidoctor.org/pdf-converter/latest/theme/cjk/)를 찾아 수정하였다.

extends: default
font:
  catalog:
    merge: true
    Noto Sans KR: malgun.ttf
    Noto Sans Mono KR: D2Coding-Ver1.3.2-20180524.ttf
  fallbacks:
  - Noto Serif
page:
  background_color: FFFFFF
  layout: portrait
  initial_zoom: FitH
  margin: [0.4in, 0.4in, 0.4in, 0.4in]
  # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress
  margin_inner: 0.0in
  margin_outer: 0.0in
  size: A4
base:
  font_family: Noto Sans KR
codespan:
  font-family: Noto Sans Mono KR
kbd:
  font-family: $codespan-font-family
code:
  font-family: $codespan-font-family

위 Theme 로 얻은 결과이다.

한글과 키보드 단축키 매트로가 모두 정상적으로 출력되는 결과를 얻었다.