DocBook XML 문서로 CHM 도움말 파일 만들기

주의: [DocBook XML 문서로 CHM 도움말 파일 만들기]의 가장 최근 판은 이곳에서 확인할 수 있습니다.

시작하며

닥북 형식으로 문서를 작성할 때의 가장 큰 장점은 다양한 형태의 결과물을 얻을 수 있다는 점입니다.
보통 닥북 형식으로 문서를 작성한 후 HTML 또는 PDF 형식으로 변환하는 것이 일반적인데
이 뿐만 아니라 마이크로소프트 윈도우에서 사용하는 도움말 파일 형식으로도 변환할 수 있습니다.
도움말 파일의 확장자는 .chm 으로 대부분의 윈도우 응용 프로그램들이 제공하는 도움말 형식입니다.
CHM 은 HTML 문서와 그에 연결된 그림 파일 등을 하나의 파일로 묶어서 압축한 것으로
목차 기능과 검색 기능을 제공하며 압축을 하기 때문에 용량 또한 원래의 문서보다 작습니다.
윈도우 뿐만 아니라 리눅스에서도 xchm, gnochm 등의 프로그램을 이용해서 열람할 수 있으므로
HTML 문서와 비교해 범용성에서는 떨어지나 대신 배포는 더 용이합니다.
본문에서는 닥북 문서를 CHM 도움말로 변환하는 방법에 대해서 다룹니다.

준비물

문서에서는 다음 파일을 기준으로 설명합니다:

• DocBook

  -   docbook-5.0
  -   docbook-xsl-1.73.2
  -   docbook-xml-4.5
  -   docbook-xsl-ns-1.74.3
  -   fop-0.94
  

• 마이크로소프트의 HTML Help Workshop

CHM 생성

CHM 파일을 만들기 위해서는 문서의 실제 내용에 해당하는
HTML 파일 및 그림 파일이 필요하며 이외에도 HHP 파일과 HHC 파일이 있어야합니다.
HHC 파일은 CHM 파일의 목차를 구성하는 HTML 파일이며
HHP 파일은 HHC 파일과 HTML 파일의 정보를 가지고 있으며
이외에도 CHM 을 생성할 때 필요한 옵션 및 정보를 가지고 있는 파일입니다.
보통 HHC 파일은 toc.hhc, HHP 파일은 htmlhelp.hhp 를 의미하지만
옵션을 사용해서 이들 이름은 얼마든지 변경할 수 있습니다.
그리고 HTML Help Workshop 의 hhc.exe 컴파일러를 이용해서
상기 HHP 와 HHC 파일을 컴파일하면 CHM 파일이 생성됩니다.

이 HHP 파일과 HHC 파일 및 본문에서 사용할 HTML 파일을 생성하려면
닥북이 제공하는 XSL 파일을 사용합니다.
docbook-xsl 파일을 다운로드 받은 후 압축을 해제하면 htmlhelp 디렉터리가 존재합니다.
htmlhelp 디렉터리 하부에는 다음과 같은 XSL 파일이 있습니다:

  +- docbook-xsl-1.73.2
    +- htmlhelp
      +- htmlhelp-common.xsl
      +- htmlhelp.xsl
      +- profile-htmlhelp-common.xsl
      +- rofile-htmlhelp.xsl

이 XSL 파일을 이용해서 닥북 문서를 CHM 파일을 만들기 직전의 원시 코드를 생성합니다:

  $ xsltproc --nonet --xinclude -o dest-path docbook-xsl-1.73.2/htmlhelp/htmlhelp.xsl cms21-ref-manual.xml

xsltproc 은 리눅스에서 실행하며 그 이후에 생성된
htmlhelp.hhp 와 toc.hhc 파일 그리고 HTML 파일을 윈도우즈에서
HTML Help Workshop 을 이용해서 컴파일하면 htmlhelp.chm 파일을
생성할 수 있습니다:

  > "C:\Program Files\HTML Help Workshop\hhc.exe" htmlhelp.hhp

문제 해결

윈도우에서 닥북 파일을 변환

시그윈 환경을 이용하면 윈도우에서 HHP 및 HHC 파일을 생성할 수 있습니다.
이 경우 영문 닥북 파일은 문제가 없으나 한글 닥북 파일의 경우 인코딩의 문제로 인해
결과물이 제대로 생성되지 않을 수도 있습니다.
이에 대한 해결 방법은 문서에서 다루지 않습니다.
윈도우에서 닥북 파일을 변환하는 방법은
Documention with DocBook on Win32 문서를 참조하세요.

XSL 옵션 추가

기본으로 제공하는 docbook-xsl 의 htmlhelp.xsl 옵션 이외의 옵션을 추가하거나
다른 옵션값으로 변경하려면 xsl 파일을 따로 생성하는 것이 편합니다.
아래와 같은 style-chm.xsl 파일을 생성합니다:

  <?xml version='1.0'?>
  <!--

  * DocBook - The Definitive Guide

http://www.docbook.org/tdg/en/html/docbook.html

  * DocBook XSL Stylesheets: Reference Documentation

http://docbook.sourceforge.net/release/xsl/current/doc/

  * DocBook XSL - The Complete Guide

http://www.sagehill.net/docbookxsl/index.html

  -->
  <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

    <xsl:import href="docbook-xsl-1.73.2/htmlhelp/htmlhelp.xsl"/>

    <!-- 자체 옵션 명시 -->

  </xsl:stylesheet>

생성한 XSL 파일을 이용해서 닥북 문서를 빌드하도록 합니다:

  $ xsltproc --nonet --xinclude -o dest-path style-chm.xsl cms21-ref-manual.xml

사용할 수 있는 자세한 옵션은 공식 홈페이지의
HTML Parameter Reference를 참고합니다.

파일 이름 문제

기본 XSL 옵션을 이용해서 닥북 문서를 빌드하면 HTML 파일 이름이
일괄적으로 ch01 과 같은 형태를 가집니다.
실제 본문의 절(section) 아이디를 파일 이름으로 사용하려면 다음 옵션을 style-chm.xsl 에 추가합니다:

  <!-- 절(section) id를 파일이름으로 사용 -->
  <xsl:param name="use.id.as.filename" select="1"></xsl:param>

스타일 시트 적용

기본으로는 스타일 시트를 적용하지 않는 평범한 HTML 문서를 생성하게 되어 있습니다.
도움말 파일을 화려하거나 가독성 있게 꾸미기 위한 스타일 시트를 적용하려면
다음 옵션을 style-chm.xsl 에 추가합니다:

  <!-- HTML 스타일시트 파일 이름 -->
  <xsl:param name="html.stylesheet">style.css</xsl:param>
  <xsl:param name="html.stylesheet.type">text/css</xsl:param>

  <!-- CSS 사용 -->
  <xsl:param name="css.decoration" select="1"></xsl:param>

인코딩 문제

대부분의 리눅스 시스템은 UTF-8 환경이기 때문에 생성된 HTML 파일 역시 UTF-8 인코딩을 가집니다.
윈도우 도움말 시스템의 경우 본문 HTML 은 UTF-8 인코딩이어도 상관이 없으나 목차 파일은
CP949 인코딩이 아니면 깨진 한글이 보이게 됩니다.
또한 본문이 UTF-8 인코딩일 경우 글자는 깨지지 않으나 검색을 제대로 할 수 없는 문제가 있습니다.
그러므로 가능하면 CP949 인코딩을 가지도록 변환해야 합니다.
이를 위해서는 다음 옵션을 style-chm.xsl 에 추가합니다:

  <!-- EUC-KR 인코딩 사용 -->
  <xsl:output method="html" encoding="EUC-KR" indent="yes"/>
  <xsl:param name="chunker.output.encoding">EUC-KR</xsl:param>
  <xsl:param name="textdata.default.encoding">EUC-KR</xsl:param>
  <xsl:param name="htmlhelp.encoding">EUC-KR</xsl:param>

리눅스에서 CHM 생성

생성한 HHP 와 HHC 파일을 리눅스에서 CHM 파일로 변환하려면 와인(Wine)을 사용합니다.
우분투의 경우 다음 명령으로 와인을 설치할 수 있습니다:

  $ sudo apt-get install wine

와인을 이용해서 CHM 파일을 생성하려면 다음 명령을 수행합니다:

  $ wine ms-html-workshop/hhc.exe htmlhelp.hhp

실행시 itss.dll 과 관련한 다음과 같은 오류가 발생할 수도 있습니다:

  fixme:itss:ITStorageImpl_SetControlData 0x135458
  fixme:itss:ITStorageImpl_SetControlData 0x1360d0
  HHC5010: Error: Cannot open "C:\windows\temp\TFS220e.tmp". Compilation stopped.

이 경우 와인에 기본으로 포함된 itss.dll 을 사용하도록 하면 됩니다.
itss.dll 을 native 로 사용하도록 하는 방법은 여러가지가 있지만
HTML Workshop 을 을 실행할 때만 적용하려면 WINEDLLOVERRIDES 환경 변수를 사용합니다.

  WINEDLLOVERRIDES="itss=n" wine ms-html-workshop/hhc.exe htmlhelp.hhp

자세한 내용은 Basic Wine Commands를 참조하세요.

명령줄에서 도움말 파일의 특정 장 열기

도움말 파일을 실행하면 도움말 창이 나타나면서 도움말의 가장 첫 장이 화면에 출력됩니다.

CHM 파일의 경우 Microsoft HTML Help Executable 형식으로
윈도우 설치시 기본으로 hh.exe 에 연결이 되어있습니다.
윈도우즈에서 연결이 되어 있는 파일은 굳이 프로그램 이름없이
파일 이름만 가지고 ShellEcecute() 등의 함수를 이용해서 자동으로
연결된 프로그램을 이용해서 열립니다.

보통은 가장 첫 장을 화면에 보여주는데 특정 위치를 열려면
hh 명령 다음에 mk:@MSITStore:<chm file path>::<html file path in chm file>
형식으로 넣어주면 됩니다:

  > hh mk:@MSITStore:/path/filename.chm::/path\topicname.htm

실행 예는 다음과 같습니다:

  > hh mk:@MSITStore:htmlhelp.chm::/api.htm
  > hh mk:@MSITStore:c:\windows\help\htmlhelp.chm::/flash\browse.htm

관련 내용은 MSDN 페이지를 참조하세요.

검색 기능이 동작하지 않을 경우

CHM 파일에서 검색 기능이 동작하지 않는 것은 itircl.dll 과 연관이 있습니다.
보통 윈도우에서 이런 증상이 나타나는 경우 hhc.exe 로 컴파일 할 때
다음과 같은 메시지가 발생합니다.

  HHC6003: Error: The file Itircl.dll has not been registered correctly.

윈도우에서 이 문제를 해결하려면 itircl.dll 파일을 다시 등록해주어야 합니다:

  > cd c:\windows\system32
  > regsvr32 itircl.dll

DllRegisterServer 성공 이라는 메시지가 나타나면 등록에 성공한 것입니다.

리눅스에서 와인을 이용해서 HTML Workshop 을 구동하는 경우 역시
HTML Workshop 은 itircl.dll 을 사용하는데 이와 관련해서 와인 버전 1.1.12 에서
다음과 같은 수정사항이 있기 때문에 가능하면 1.1.12 이후 버전의 와인을 사용하도록 합니다:

  Bugs fixed in 1.1.12:
  ...
  16603  DllRegisterServer not implemented in itircl.dll
  ...

리눅스에서 역시 regsvr32 를 이용해서 itircl.dll 을 등록해주고
itss.dll 과 마찬가지로 환경 변수를 이용해서 native 모드로 동작시켜야 하지만
그럼에도 불구하고 생성된 CHM 파일이 검색 기능을 지원하지 않을 수 있습니다.
이것과 관련해서는 아직 해결책을 찾지 못한 상태입니다.

정리하며

지금까지 docbook-xsl 에서 제공하는 htmlhelp 용 XSL 을 이용해서 닥북 문서를
CHM 생성을 위한 원시 파일로 변환하고 다시 CHM 을 생성하는 과정을 살펴보았습니다.
이 작업은은 리눅스와 윈도우를 오가며 수행하지만 시스템 구성을 잘 할 경우
물론 아직까지 해결하지 못한 문제는 있지만 윈도우 또는 리눅스에서
일괄로 처리하는 것도 가능합니다.
비록 CHM 문서가 HTML 문서에 비해 범용성이 떨어지며 CHM 문서를 보기위해서는
별도의 프로그램이 필요하다는 단점은 있지만 압축을 하기 때문에 용량이 작고
하나의 파일로 구성되며 윈도우즈에서는 기본적으로 열리므로 사용자 설명서,
즉 도움말의 배포라는 측면에서는 괜찮은 방식이라고 할 수 있습니다.
또한 현재는 리눅스에서 역시 CHM 파일을 읽을 수 있으며 자체적으로 검색도
지원하므로 도움말 배포를 위해 한번쯤 고려해볼 만한 방식입니다.