[Doxygen] HTMLHelp로 chm파일 만들기(+ 목차 한글 깨짐 해결 방법)

Doxygen 사용을 위한 본문은 아래 링크를 참고하세요.

[Doxygen] 독시젠으로 코드 문서 만들기 총정리 (예제 포함)

[Doxygen] 독시젠으로 코드 문서 만들기 총정리 (예제 포함)

chm 파일이란?

chm은 Microsoft Compiled HTML Help의 약자로, 마이크로소프트에서 개발한 도움말 포맷입니다. 이 chm은 HTML 페이지 모음과 목차, 색인, 검색 등의 기능을 제공하는데요. 주로 제작사 측에서 SDK 전반적인 내용과 Library Reference 자료를 포함하여 배포합니다.

아래 그림은 Omron Sentech SDK의 chm 파일 메인 화면입니다. 좌측 목차에는 각종 정보가 담겨있는 페이지가 표시되고, 색인에서는 키워드로 원하는 정보를 빠르게 찾을 수 있습니다. 물론 검색 탭에서도 단어로 검색하여 원하는 정보를 찾을 수 있지요.

Omron sentech SDK chm 파일

이러한 chm 파일은 Doxygen에서도 생성할 수 있습니다. Doxygen은 기본적으로 HTML 파일을 생성하는데, chm 생성을 위한 옵션 몇 가지를 추가하면 간단히 생성됩니다.

Doxygen에서 chm 파일 생성을 위한 설정 방법

chm 파일을 생성하기 위해서는 HTML Help Workshop의 hhc.exe 파일이 필요합니다. 자신의 컴퓨터에 아래의 파일이 있는지 확인합니다.

C:\Program Files (x86)\HTML Help Workshop\hhc.exe

만약 없다면, 아래에 첨부된 파일을 설치합니다.

htmlhelp.zip

3.30MB

위 파일은 Micorosft Download Center의 파일 경로가 만료되어, Q&A 링크에서 다운로드한 파일입니다.

https://docs.microsoft.com/en-us/answers/questions/265752/htmlhelp-workshop-download-for-chm-compiler-instal.html

HTMLHelp Workshop - download for CHM compiler installation failed - Microsoft Q&A

Doxygen GUI를 실행한 후 Wizard > Output 메뉴에서 'prepare for compressed HTML (.chm)' 항목을 선택합니다.

Output 탭에서 chm 항목 선택하기

다음으로 Expert > HTML 메뉴에서 아래와 같이 설정합니다.

HTML 탭에서 설정

항목	설명
GENERATE_HTMLHELP	chm 생성 여부를 체크합니다.
CHM_FILE	생성될 chm 파일의 이름을 설정합니다. 만약, 지정하지 않는다면 index.chm 파일이 기본으로 생성됩니다.
HHC_LOCATION	hhc.exe의 경로를 선택합니다. 기본 경로는 다음과 같습니다. C:\Program Files (x86)\HTML Help Workshop\hhc.exe

Doxygen GUI에서 chm 생성하기

위와 같이 설정을 모두 마쳤다면, Run 탭에서 Run doxygen 버튼을 클릭하여 빌드합니다.

Run doxygen 클릭하여 빌드하기

빌드가 끝나면 Destination directory 경로에 chm 파일이 생성됩니다.

Doxygen 빌드 생성 경로 확인

아래와 같이 설정한 이름으로 파일이 존재합니다.

chm 생성 확인

doc.chm을 실행하면 아래와 같이 우리가 흔히 보던 그 형식입니다. 그런데 본문은 한글이 잘 표시되는데 목차 부분의 한글은 깨져있습니다.

한글이 깨진 채 생성된 chm 파일

만약, 모든 목차를 영문으로 작성한다면 문제가 없겠지만 한글이 포함된 경우에는 다음의 방식을 추가해야 합니다.

doxygen chm 한글 깨짐 해결 방법

chm 파일의 목차를 생성하기 위해서는 index.hhc 파일을 사용하게 됩니다. 그런데 이 파일이 UTF-8 형식으로 작성되어 있다 보니 이와 같이 한글이 깨지게 되는 것입니다. 즉, index.hhc 파일을 CP949 형식으로 변환만 해주면 해결이 됩니다.

index.hhc 파일을 CP949로 변환하기 위해서 iconv라는 프로그램을 사용합니다. 인터넷에 있는 링크나 아래의 첨부된 파일을 사용합니다.

iconv-1.9.2.win32.zip

1.25MB

그리고 아래의 배치 파일도 다운로드합니다. 압축 파일을 해제하면 hhc converter.bat 파일이 있습니다.

hhc converter.zip

0.00MB

이 배치 파일은 Doxygen GUI로 chm 파일을 빌드하는 과정 중에 생성되는 index.hhc 파일의 형식을 CP949로 변환해주는 명령어가 포함되어 있습니다. 나중에 설명할 HHC_LOCATION에 이 배치 파일을 선택하면 자동으로 형식을 변환하여 한글이 깨지지 않게 됩니다.

배치 파일의 내용을 설명하겠습니다.

C:\Users\Gg\Downloads\iconv-1.9.2.win32\bin\iconv.exe -f UTF-8 -t CP949 index.hhc > temp.hhc
del index.hhc
move temp.hhc index.hhc
"C:\Program Files (x86)\HTML Help Workshop\hhc.exe" "%1"

첨부된 iconv-1.9.2.win32.zip 파일에는 bin, include, lib 폴더가 있고, bin 폴더에는 iconv.exe 파일이 있습니다. 첫 줄의 C:\Users\Gg\Downloads\iconv-1.9.2.win32\bin\iconv.exe는 iconv.exe 경로를 의미합니다.

-f UTF-8 -t CP949 index.hhc는 index.hhc 파일을 UTF-8 포맷에서 CP949 포맷으로 변환하겠다는 의미이며, > temp.hhc는 결과물로 temp.hhc 파일을 생성하겠다는 의미입니다.

del index.hhc는 변환 전의 index.hhc 파일을 삭제하겠다는 의미이고, move temp.hhc index.hhc는 temp.hhc 파일 이름을 index.hhc 파일 이름으로 변경하겠다는 의미입니다.

마지막으로 "C:\Program Files (x86)\HTML Help Workshop\hhc.exe" "%1"은 hhc.exe를 실행한다는 의미입니다.

따라서, 이 글을 보고 따라 하실 경우 배치 파일의 iconv.exe 경로를 수정하셔야 합니다. 배치 파일 수정이 완료되면 HHC_LOCATION에서 배치 파일을 지정합니다.

배치 파일이 지정된 모습

그리고 아래와 같이 설정되어 있는지 확인합니다.

위치	항목	값
Expert > Project	DOXYFILE_ENCODING	CP949
	OUTPUT_LANGUAGE	Korean
Expert > Input	INPUT_ENCODING	CP949
Expert > HTML	GENERATE_HTMLHELP	체크
	HHC_LOCATION	배치 파일 경로

위와 같이 설정하여 빌드하면 chm 파일의 목차가 모두 정상적으로 표시됩니다.

정상적으로 한글이 표시되는 모습