MFC14. HTML 도움말 작성법

도움말을 작성하는 방법에는 Word등에서 .rtf파일을 작성하여 만드는 고전적 방법이 있고, html파일을 만들어 HTML Help Workshop을 이용하여 만드는 방법 두가지가 있습니다. 요즈음 대부분 HTML 도움말을 사용하므로 이 방법에 대하여 설명합니다. HTML 도움말을 만들기 위해서는 HTML파일을 만들 수 있어야 하고 HTML Help Workshop을 사용할 수 있어야 합니다. 이곳에서는 HTML 파일 만드는 방법에 대해서는 설명하지 않고 HTML Help Workshop을 이용하여 HTML 도움말을 만드는 방법을 간략히 설명하고 실제 프로그램과 연계하는 방법에 대하여 설명합니다. 또한 도움말로부터 HWP 파일(메뉴얼)을 만드는 방법에 대하여 설명합니다.

HTML Help Workshop 설치 방법
HTML Help Workshop은 아래 파일을 다운받아 설치하면 됩니다.

HTMLHELP.zip

3.30MB

HTML Help Workshop 사용법
  여기에서는 HTML Help Workshop(향후 HHW라 명함)의 모든 내용을 다루지는 않고 프로젝트를 만들어 도움말을 만드는 방법을 간략히 설명합니다. 자세한 내용은 도움말을 참조하기 바랍니다.
  HTML 도움말을 만들기 위해서는 우선 HTML 파일을 모두 만들어야 합니다. HTML 파일을 만드는 방법은 여기에서 설명하지 않으며 책 또는 다른 사이트를 참조하기 바랍니다.
  우선 도움말을 만들고자 하는 아래 그림과 같이 디렉토리(여기서는 DeditorDemoHelp)를 생성하여 그 디렉토리에 Html이라는 디렉토리를 만들고 Html파일을 만들어 저장(여기에서 데모로 Start.htm, Dialog.htm 파일 제작)합니다. 그리고 Html 디렉토리 아래에 Images라는 디렉토리를 만들어 Html파일에서 사용하는 그림들을 넣습니다.

<그림 1>

  HHW를 실행하면 다음과 같은 대화 상자가 생성됩니다.

File 메뉴의 부메뉴 New를 실행하면 다음과 같은 대화 상자가 생성됩니다.

종류를 Project를 선택하고 OK를 선택하면 다음과 같은 대화 상자가 생성됩니다.

다음을 선택하면 대화 상자는 다음과 같이 바뀝니다.

<그림 2>

Browse...를 선택하면 다음과 같이 파일 열기 대화 상자가 생성되는데 <그림 1>에서 생성해 놓은 디렉토리로 맞추고 파일 이름을 입력합니다(생성될 도움말 파일 이름을 입력하면 됩니다).

열기를 선택하면 <그림 2>는 다음과 같이 바뀝니다.

다음을 선택하면 대화 상자는 다음과 같이 바뀝니다.

<그림 3>

HTML Help table of contents와 HTML Help index 체크버튼을 선택해야 되나 여기서 선택하는 것 보다 나중에 생성하도록 하는 것이 더 편하므로 체크하지 않습니다.

다음을 선택하면 대화 상자는 다음과 같이 바뀝니다.

마침을 선택하면 HHW화면이 다음과 같이 바뀝니다.

Contents 탭을 선택하면 다음과 같은 대화 상자가 생성되어 <그림 3>에서 생성하지 않은 HTML Help table of contents를 생성할 것인지를 묻습니다.

OK를 선택하면 TML Help table of contents를 생성하고 다음과 같이 HHW화면이 바뀝니다.

참고로 HTML Help index도 같은방법으로 Index 탭을 선택하면 생성됩니다.
 Contents 화면에서 Insert a Heading, Insert a Page, Edit Selection, Delete Selection 아이콘을 이용하여 HTML파일과 HTML 도움말을 연결합니다.

을 마우스로 클릭하면 다음과 같은 대화 상자가 생성됩니다.

Entry title에 트리에 나타날 명칭을 입력하고 Add버튼을 클릭하면 다음과 같은 대화 상자가 생성됩니다.

Browse..를 선택하여 연결하고자 하는 Html 파일을 선택하면 도움말 트리에 나타납니다.
Insert a Heading가 Insert a Page와 다른 점이라면 초기에 트리에 나타나는 Icon모양입니다.

수정하기 위한 버튼인 Edit Selection를 선택하여 다음그림과 같이 Advance 탭에서 Icon 모양을 바꿀 수 있습니다.

또한 아래의 화살표 키를 선택하여 트리에서의 위치를 맞출 수 있습니다.
다음 그림은 DialogDemo와 Dialog를 트리에 추가한 모양입니다.

HHW화면에서 Project를 선택하면 다음과 같이 화면에 나타납니다.

버튼을 선택하면 다음과 같은 대화 상자가 생성됩니다.

Title에 도움말을 실행했을 때 나타나는 화면의 Title을 입력하고, Default file에 도움말 실행시 첫화면에 나타날 화면이름을 입력합니다(선택 버튼이 없어 수동으로 입력해야 합니다).
Default file을 입력하지 않으며 도움말을 실행했을 때 다음과 같이 화면에 나타납니다.

Index는 도움말의 색인을 꾸미는 화면인데 Contents와 거의 비슷하고 무조건 만들어야 하는 내용은 아니므로 여기서는 설명하지 않습니다.
편집을 모두 한 후 File메뉴의 부메뉴 Compile을 선택하면 프로젝트명.chm파일이 생성됩니다. 이 파일이 도움말 파일입니다.

프로그램과 연계
도움말을 작성하여 프로그램과 연계하는 방법에는 다음과 같이 3가지가 있습니다.
1. 메뉴에서 도움말을 선택했을 경우나 프로그램에서 F1키를 누르면 도움말의 처음 화면이 화면에 나타납니다.
2. 대화 상자에 도움말 버튼을 두어 그 버튼을 누르거나 대화 상자가 뜬 상황에서 F1키를 누르면 해당 대화 상자의 도움말이 화면에 나타납니다. 이 기능을 수행하기 위해서는 도움말을 조금 수정해야 하고 대화 상자 ID와 HTML 파일을 연결해야만 합니다.
3. 대화 상자에 ?버튼을 두어 선택한 후 각 개체(버튼, 리스트 박스 등)를 선택하면 해당 개체에 대한 박스 도움말이 생성됩니다. 이 기능을 구현하기 위해서는 너무 많은 노동력이 들어가고 그 노동력에 비해 필요성이 떨어 지므로 이 기능 구현에 대해서는 다루지 않습니다.

1. F1 키에 의한 도움말 실행

Application 파일(Doc-View구조에서 설명)을 열어 메시지 맵에 다음과 같이 추가하면 F1키에의해 도움말이 화면에 나타나야합니다.

        ON_COMMAND(ID_HELP, OnHelp)
        ON_COMMAND(ID_HELP_USING, OnHelpUsing)

그러나 도움말은 기본적으로 .rtf파일을 이용해서 만드는 .hlp파일을 지원하도록 되어있습니다. 따라서 HTML 도움말인 .chm파일을 지원하기 위해서는 몇가지 수정을 해주어야 합니다.

우선
C:\Program Files\HTML Help Workshop\lib\htmlHelp.lib
C:\Program Files\HTML Help Workshop\include\htmlhelp.h
파일을 Source가 있는 디렉토리에 복사합니다(가장 간단한 방법, 디렉토리 설정방식을 알고 있다면 그 방식에 따라 복사).
다음과 같이 Application파일에 #include를 해줍니다.
#include <HTMLHelp.h>           // HTML Help API header

그 다음 라이버러리 파일을 프로젝트에 추가합니다.
HtmlHelp.Lib

Application 파일의 InitInstance 함수에 다음을 추가(Template생성 바로전에 추가)하여 .hlp로 되어있는 도움말 파일을 .chm으로 바꾸고 도움말 Type을 HTMLHelp로 바꿉니다.

    CString strTmp;
    CString strHelpFile = m_pszHelpFilePath;
    strHelpFile.Replace(".HLP", ".chm");
    strcpy((char*)m_pszHelpFilePath, (char*)(LPCTSTR)strHelpFile);
    m_eHelpType = afxHTMLHelp;

ClassWizard를 실행하여 WinHelp라는 MFC 함수를 생성하여 다음과 같이 수정합니다.

void CResourceDemoApp::WinHelp(DWORD dwData, UINT nCmd)
{
       HtmlHelp(NULL, m_pszHelpFilePath, HH_DISPLAY_TOPIC, 0);
}

이제 F1키에 의한 도움말 실행은 됩니다.
메뉴에 의한 실행은 단지 도움말 메뉴를 ID_HELP로 만들어만 주면 실행됩니다.

2. 대화 상자와의 연동
먼저 대화 상자 ID와 HTML 파일을 연결하기 위해서 대화 상자 ID를 HTML 도움말 ID로 변환해야만 합니다. 이 기능을 수행하는 프로그램이 makehm.exe입니다.
makehm.exe을 아래에서 다운받아 Source 파일(resource.h)이 있는 디렉토리에 복사한 후 해당 디렉토리로 옮겨가 다음 명령어를 실행합니다.
makehm IDD_,HIDD_,0x20000 resource.h >> MyHelp.h

 

필자는 해당 명령어를 bat 파일로 만들어 실행하는 방법을 사용합니다. 참고로 앞에서 이야기한 makehm.exe 와 MakeMap.bat 파일은 아래에 올려두었습니다.

MakeHM.zip

0.00MB

생성된 MyHelp.h을 열어 각 라인의 앞에 #define을 추가합니다.
예를 들어 MyHelp.h파일의 내용이 다음과 같았다면

HIDD_NEW_ANIMATION               0x20082
HIDD_GRAPHIC_EDIT                  0x20085
HIDD_ANIMATION_INFO               0x20086

다음과 같이 변경합니다.

#define HIDD_NEW_ANIMATION               0x20082
#define HIDD_GRAPHIC_EDIT                  0x20085
#define HIDD_ANIMATION_INFO               0x20086

WinHelp함수를 다음과 같이 수정합니다.

#define HELPID_COUNT            3
void CAniEditApp::WinHelp(DWORD dwData, UINT nCmd)
{
        static DWORD dwHelpIDs[HELPID_COUNT] = {HIDD_NEW_ANIMATION, HIDD_GRAPHIC_EDIT, HIDD_ANIMATION_INFO};

        for(int i = 0; i < HELPID_COUNT; i++){
                if(dwHelpIDs[i] == dwData){
                        HtmlHelp(NULL, m_pszHelpFilePath, HH_HELP_CONTEXT, dwData);
                        return ;
                }
        }
        HtmlHelp(NULL, m_pszHelpFilePath, HH_DISPLAY_TOPIC, 0);
}

각 대화 상자에 IDHELP라는 ID로 도움말 버턴을 만들어 그 버튼을 클릭되었을 때 메시지에 다음과 같이 해당 ID로 도움말을 호출합니다.

void CNewAnimationDlg::OnHelp()
{
        AfxGetApp()->WinHelp(HIDD_NEW_ANIMATION);
}

HTML 도움말 ID 사용하는 Source에 다음을 추가합니다.
# Include "MyHelp.h"

 

프로그램 연계를 위한 도움말 수정
앞에서 작성한 도움말 프로젝트 파일(.hhp)을 열면 다음과 같이 화면에 나타납니다.

위 화면에서 Html API Information 아이콘을 클릭하면 다음과 같은 대화 상자가 생성됩니다.

Header file버튼을 선택하여 MyHelp.h를 선택하고, Alias탭을 선택하여 Add버턴을 선택하면 다음과 같은 대화 상자가 생성됩니다.

첫 번째 Editor : MyHelp.h에 있는 HTML 도움말 ID를 입력합니다.
두번째 Editor : 도움말 프로젝트 파일이 있는 디렉토리를 기준으로 상대 위치와 파일명을 입력합니다. 만약 프로젝트 디렉토리에 html이라는 디렉토리를 만들고 그 디렉토리에 dialog.htm 파일을 작성하여 ID와 연결하고자 한다면 html\dialog.htm이라고 입력합니다.
해당 대화 상자 도움말 HTML 파일 마다 이 방식을 이용하여 HTML 도움말 ID와 연결한 후 컴파일을 하고, 컴파일된 도움말 파일을 실행 파일이 있는 디렉토리에 Help라는 디렉토리를 만들고 그 위치에 복사하면 도움말 지원이 완료됩니다.

매뉴얼 만들기
이전의 도움말 작성은(.rtf파일 이용) 파일 내에 그림파일이 많으면 컴파일이 되지 않는 버그가 있었습니다. 따라서 대부분 도움말 내용(대략 설명)과 매뉴얼 내용(자세히 설명)이 서로 다르게 제작되었습니다. 그러나 HTML 도움말은 이런 버그가 없으므로 도움말을 매뉴얼 수준으로 자세히 작성하고 그 도움말을 이용하여 매뉴얼을 생성합니다.
도움말은 대부분 작은 파일 단위로 만들고 Link기능을 이용하여 각 파일들을 옮겨 다닐 수 있도록 구성합니다. 따라서 각 HTML 파일을 순서대로 HWP 파일로 변환(한글에서 읽으면 자동변환됨)하여 하나의 파일로 만드는 것도 대단히 힘든 작업입니다.
따라서 약간의 편법을 이용하면 만들어진 도움말을 열어 왼쪽에 나타난 트리에서 커서를 가장 상단에 두고 인쇄를 선택하여 나타난 대화 상자에서 '현재 제목에 포함된 모든 항목 인쇄'를 선택하고 인쇄를 선택하면 인쇄 대화 상자가 생성됩니다.

이 상황에서 Temp 디렉토리에서 날짜별로 정렬하여 생성된 날짜가 가장 마지막인 .htm파일을 한글에서 열어보면 HTML 파일 트리 순서대로 하나의 파일로 만들어져 있는 것을 알 수 있습니다. MS WORD 또는 아래아 한글에서 읽어 약간 편집하여 저장하면 매뉴얼이 됩니다(실제 배포시는 대부분 다른이름으로 저장을 하여 PDF로 저장한 후 배포합니다).
참조 : Temp 디렉토리(다음 세가지 중 하나의 위치에 존재)
- C:\사용자\사용자명\AppData\Local\Temp (AppData디렉토리는 숨겨진 디렉토리로 되어 있으므로 탐색기 옵션에서 숨김 파일, 폴더 및 드라이브 표시가 되도록 설정한 후에 보입니다)
- C:\Documents and Settings\사용자명\Local Settings\Temp (Local Settings디렉토리는 숨겨진 디렉토리로 되어 있으므로 탐색기 옵션에서 숨김 파일, 폴더 및 드라이브 표시가 되도록 설정한 후에 보입니다)
- C:\Temp