## 닥북 모음집용 docbookto 명령에 대해

### 류광

docbookto 명령은 DocBook XML 파일을 다른 형식의 파일로 변환하는 명령입니다. 닥북 한국의 류광이 작성했으며 Lua 5.0+ 라이선스를 따릅니다. 소스 코드는 %DOCBOOK_HOME%\software\luascript\docbookto\ 디렉터리에 있습니다.

## 사용법:

### 명령 구문

     docbookto html [옵션] <입력파일.xml>

여러 개의 HTML 파일들을 생성합니다.

     docbookto onehtml [옵션] <입력파일.xml> [출력파일.html]

하나의 HTML 파일을 출력합니다. [출력파일]에 출력 HTML 파일 이름을 지정하면 그 파일에 저장됩니다. 지정하지 않으면 표준 출력(콘솔)으로 출력됩니다.

     docbookto pdf [옵션] <입력파일.xml 또는 입력파일.fo> [출력파일.pdf]

PDF 파일을 생성합니다. [출력파일.pdf]을 생략하며 <입력파일.pdf>가 쓰입니다.

     docbookto fo [옵션] <입력파일.xml> [출력파일.fo]

XSL-FO 파일을 생성합니다. [출력파일.fo]로 출력 FO 파일 이름을 지정하면 그 파일에 저장됩니다. 지정하지 않으면 표준 출력(콘솔)으로 출력됩니다.

### 옵션

     -c <설정 파일>

지정된 파일에 담긴 XSLT 매개변수 설정들이 XSLT 처리기에 적용됩니다. 설정 파일의 구조에 대해서는 다음 절에서 좀 더 설명합니다.

     -p <XSLT 매개변수> <값>

추가적인 XSLT 매개변수와 값을 지정하는 옵션으로, 설정 파일을 수정하지 않고도 매개변수들을 시험해 보고자 할 때 유용합니다. -c 옵션으로 지정한 설정 파일에 같은 이름의 매개변수가 있는 경우 설정 파일의 것이 무시됩니다. 여러 개의 매개변수들을 지정하는 경우 매번 -p를 지정해야 합니다.

     -s <XSL 스타일시트 파일>

기본 XSL 스타일시트 파일 대신 지정된 파일을 사용합니다. {XSL파일.xsl} 형태로 지정하면 %DOCBOO_HOME%\stylesheet\XSL파일.xsl 로 간주됩니다.

     --xalan

XSLT 처리기로 기본 xsltproc 대신 Xalan을 사용합니다.

     --saxon

XSLT 처리기로 기본 xsltproc 대신 Saxon을 사용합니다.

     --debug

변환 명령을 실제로 실행하지는 않고 명령문만 출력합니다.

## 설정 파일에 대해

-c 옵션으로 지정하는 설정 파일은

     매개변수이름 = 값

형태의 항목들이 한 줄에 하나씩 존재하는 파일이어야 합니다. 각 매개변수는 유효한 닥북 XSL 매개변수이어야 합니다.[1]

다음은 설정 파일의 예입니다.

    # 목차 관련
    generate.toc=book toc,title article toc,title
    toc.section.depth=2

    # 이미지 관련
    admon.graphics = 1
    admon.graphics.path = {DBK_BASE_URL}/stylesheet/docbook-xsl/images/
    callout.graphics.path = {DBK_BASE_URL}/stylesheet/docbook-xsl/images/callouts/

    # callout (xalan)
    use.extensions=1
    callouts.extension=1
    textinsert.extension=1

설정 파일에서 #로 시작하는 줄은 주석입니다. 그리고 값 부분의 {DBK_BASE_URL}은 docbookto 명령 실행 시 환경 변수 DBK_BASE_URL의 값(dbkshell.bat에 정의된)로 치환됩니다.

docbookto가 인식하는 설정 파일은 runlua xslt 명령에도 사용할 수 있습니다.

-c 옵션으로 지정된 파일은 절대 경로일 수도 있고 상대 경로일 수도 있습니다. 상대 경로인 경우 현재 docbookto를 실행한 디렉터리를 기준으로 합니다. 또한 {설정 파일} 형태로 지정하면 %DOCBOOK_HOME%\conf에서 해당 파일을 찾습니다. 예를 들어 닥북 모음집을 e:\docbook에 설치했다고 할 때,

     > docbookto html -c {custom-html.conf} test.xml

은 e:\docbook\conf\custom-html.conf 를 사용합니다.

-c 옵션을 지정하지 않은 경우 다음과 같은 기본 설정 파일들이 쓰입니다.

- docbookto pdf나 docbookto fo: %DOCBOOK_HOME%\conf\dbk-pdf.conf

- docbookto html : %DOCBOOK_HOME%\conf\dbk-html.conf

- docbookto onehtml : %DOCBOOK_HOME%\conf\dbk-onehtml.conf

## Xalan 관련

닥북 모음집 1.0(dbkpack-1.0)에는 Xalan 2.7.1이 포함되어 있습니다. docbookto 실행 시 --xalan 옵션을 지정하면 xsltproc 대신 Xalan이 XSL 변환을 수행합니다.

Xalan은 xsltproc보다 느리지만 (현재의)xsltproc으로는 처리할 수 없는 기능 몇 가지를 제공합니다. 대표적인 것이 callout 입니다. http://docbook.or.kr/phpBB2/viewtopic.php?t=471 를 참고하세요.

     > docbookto pdf programlisting.xml

로 생성한 PDF와

     > docbookto pdf --xalan programlisting.xml

로 생성한 PDF를 비교해 보시면 차이를 알 수 있을 것입니다.

## Saxon 관련

닥북 모음집 1.0(dbkpack-1.0)에는 Saxon 6.5.5가 포함되어 있습니다. docbookto 실행 시 --saxon 옵션을 지정하면 xsltproc 대신 Saxon이 XSL 변환을 수행합니다.

Saxon은 xsltproc보다 느리지만 (현재의)xsltproc으로는 처리할 수 없는 기능 몇 가지를 제공합니다. 대표적인 것이 한글 색인입니다. 이에 대해서는 http://docbook.or.kr/phpBB2/viewtopic.php?topic=733을 참고하세요.

<index />와 <indexterm>들이 적절히 존재하는 XML 파일로부터 가, 나, 다 순의 한글 색인이 포함된 PDF를 생성하는 방법은 다음과 같습니다.

     > docbook pdf --saxon -s {dbk-fo-autoidx.xsl} test.xml

또한 Saxon은 앞 절에서 말한 callout 기능도 제공합니다.

[1] 닥북 변환의 여러 특성들을 제어하는 XSL 매개변수들에 대해서는 DocBook XSL: The Complete Guide의 Part II. Stylesheet options 또는 DocBook XSL Stylesheets Reference Documentation을 참고하세요.