한빛출판네트워크

저자: 김영익 / (주)콘델라

여러분 컴퓨터에는 수많은 프로그램들이 설치되어 있을 것이다. 이 기사를 보고 있다면 당연히 웹 브라우저가 설치 되어 있을 것이고 문서 편집기나 업무용, 혹은 잠시 휴식을 위한 게임 등등… 아마 양손을 다 사용해도 꼽을 수 없을 정도로 많을 것이다. 그렇다면 이 많은 프로그램들에 대해서 여러분은 사용법을 모두 숙지하고 있는가? 당연히 아닐 것이다. 그 많은 프로그램들의 기능을 다 사용하지 않을 것이고 머리 속에 넣어 둔다는 것 자체가 불가능하다. 이럴 때 필요한 것이 바로 프로그램에 대한 도움말이다. 지금 인터넷 익스플로러 브라우저를 사용하고 있다면 “F1” 키를 눌러 보기 바란다. 아래와 같은 도움말 화면이 나타날 것이다.



여러분이 자바 프로그래머라면 어떠한 방식으로 도움말을 제공하고 있는가? 본인이 경험한 프로젝트에서는 도움말을 HTML로 작성한 다음, 자바 프로그램에서 외부 프로세스로 브라우저를 실행할 때 작성된 HTML 파일을 열도록 작성했었다. 그러나 이런 방식으로 제공하는 도움말은 아주 제한적이고 프로그램으로 제어가 불가능하다. 쉬운 예를 들어 각 화면 별로 적당한 도움말을 보여주고 싶을 때 앞서 제시한 방법으로는 프로그램을 사용하는 사람이 직접 인덱스를 뒤져보거나 해당 화면에 도움말을 찾아봐야 할 것이다. 그러나 JavaHelp를 이용하여 도움말을 만든다면 원하는 대로 프로그램에서 제어가 가능하다. 과연 JavaHelp를 사용하여 얻는 장점은 무엇일까? 정답은 간단하다. 자바 자체가 가진 장점인 플랫폼에 무관하다는 것이 가장 큰 장점일 것이다. 위의 그림에 나오는 도움말처럼 대부분 윈도우에서 제공하는 도움말은 CHM(Compiled HTML) 파일 형태로 제공된다. 그렇다면 이 파일을 리눅스나 유닉스에서 사용할 수 있는가? 당연히 사용하지 못한다. JavaHelp는 HTML과 XML 기반으로 이루어져 있기 때문에 어떤 플랫폼에서도 사용 가능한 것이다. 아래 그림은 JavaHelp를 설치하고 난 후에 포함된 예제 도움말의 한 화면이다. 윈도우용 도움말과 크게 다를 바가 없는 친숙한 GUI를 제공하고 있는 것이다.



그럼 이제부터 도움말을 작성하고 자신이 만든 프로그램에서 작동하는 예제를 살펴보도록 하자.

• JavaHelp에 대한 공식 사이트와 더 많은 정보는 아래 링크를 참고하자.
  http://java.sun.com/products/javahelp
  Creating Effective JavaHelp
  
  
• JavaHelp에 사용될 도움말 자체를 편집하는 프로그램들에 대해서는 아래 링크를 참고하자. 아쉽게도 대부분 상용제품으로 보인다.
  http://java.sun.com/products/javahelp/industry.html
  

1. JavaHelp 설치

설치는 앞에 설명된 사이트에서 JavaHelp 2.0_01 버전의 zip 파일을 다운로드 받고 압축을 풀기만 하면 일단 끝이 난다.
설치가 정상적으로 이루어졌는지 확인하기 위해 JavaHelp에 포함된 예제를 실행시켜 보자.
본인이 설치한 JavaHelp 디렉토리 밑에서 demos/bin 디렉토리를 찾아 아래처럼 실행한다.

D:\javahelp-2_0_01\demos\bin>java -jar hsviewer.jar

그러면 아래 그림처럼 헬프셋 파일을 지정하라는 다이얼로그가 나타난다.



Browse 버튼을 누르고 데모 디렉토리를 적당히 뒤져보면 Merge 라는 데모 디렉토리 밑에   Master.hs 라는 헬프셋 파일이 있다. 선택하고 Display 버튼을 누르면 아래 그림과 같은 도움말이 나타난다. 트리에서 노드를 선택해보고 링크를 따라 가보기도 해보자. 사용하는데 크게 어려운 점은 없을 것이다.



설치 자체는 이렇게 허무하게 끝이 나며, 다른 자세한 사항은 다음으로 넘어가도록 하자.

2. JavaHelp와 함께 하는 한빛 도서 소개

어떤 것을 예제로 만들어야 할지 무척이나 고민했다. 실무에서 사용할만한 예제를 하자니 너무 복잡하고 내용이 길어질 것 같고… 고민 끝에 한빛미디어 도서 소개를 하는 프로그램으로 결정했다. 갑자기 왠 도서 소개 프로그램인지 묻지 않았으면 한다. 나름대로 생각 많이 했고 적당한 컨텐츠를 찾기도 힘들기에 한빛 사이트에서 대부분의 컨텐츠를 슬쩍(?) 해왔다. 한빛 담당자 분께서 넓은 아량으로 이해해주시길 바라며… ^^
아래 그림이 바로 우리가 만들 도움말 화면이다. 미리 보여주는 이유는 JavaHelp에 대한 기본 설명을 위해서이다. 화면 구성은 아래 그림의 설명을 참고하자.



아래 그림을 보면 여러 디렉토리와 파일들이 있다. 예제를 위해서 여러분도 같은 구조로 디렉토리와 파일을 생성해야 한다. 이미지 파일들은 적당히 구해서 이름을 변경해서 사용해도 괜찮겠다.



각 파일들의 내용은 다음과 같으며 주의할 것은 id 로 지정되는 스트링 값들이다. 아래의 모든 파일들에서 사용되며 볼드체로 표시했다.

[ HelpSet.hs 의 내용 ]

〈?xml version="1.0" encoding="euc-kr" ?〉
〈!DOCTYPE helpset   
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
"http://java.sun.com/products/javahelp/helpset_1_0.dtd"〉

〈helpset version="1.0" xml:lang="kr"〉

   〈!-- title --〉
   〈title〉한빛미디어〈/title〉

   〈!-- maps --〉
   〈maps〉
      〈!--기본으로 지정될 타겟의 ID--〉
      〈homeID〉overview〈/homeID〉
      〈mapref location="Map.jhm"/〉
   〈/maps〉

   〈view〉
      〈name〉TOC〈/name〉
      〈label〉Table Of Contents〈/label〉
      〈type〉javax.help.TOCView〈/type〉
      〈data〉TOC.xml〈/data〉
   〈/view〉

   〈view〉
      〈name〉Index〈/name〉
      〈label〉Index〈/label〉
      〈type〉javax.help.IndexView〈/type〉
      〈data〉Index.xml〈/data〉
   〈/view〉
〈/helpset〉

[ Index.xml의 내용 ]

〈?xml version="1.0" encoding="euc-kr" ?〉
〈!DOCTYPE index
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
"http://java.sun.com/products/javahelp/index_1_0.dtd"〉

〈index version="1.0"〉
   〈indexitem text="C++" target="c++"/〉
   〈indexitem text="데이터베이스" target="database" /〉
   〈indexitem text="오라클" target="database" /〉
   〈indexitem text="자바" target="java"/〉
   〈indexitem text="JSP" target="java"/〉
〈/index〉

[ Map.jhm의 내용 ]

〈?xml version="1.0" encoding="euc-kr" ?〉
〈!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd"〉

〈map version="1.0"〉
   〈mapID target="overview" url="topics/overview.html" /〉
   〈mapID target="java" url="topics/java/java.html" /〉
   〈mapID target="c++" url="topics/c++/c++.html" /〉
   〈mapID target="database" url="topics/database/database.html" /〉
〈/map〉

[ TOC.xml의 내용 ]

〈?xml version="1.0" encoding="euc-kr" ?〉
〈!DOCTYPE toc
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
"http://java.sun.com/products/javahelp/toc_1_0.dtd"〉
〈toc version="1.0"〉
   〈tocitem text="한빛미디어"〉
      〈tocitem text="소개" target="overview"/〉
      〈tocitem text="Java" target="java"/〉
      〈tocitem text="C++" target="c++"/〉
      〈tocitem text="Database" target="database"/〉
   〈/tocitem〉
〈/toc〉

파일이 많아서 처음엔 귀찮지만 조금만 익숙해지면 단순 작업이므로 크게 걱정할 필요가 없다. 각 토픽에 해당하는 c++.html , java.html , database.html 파일의 내용에 대해서는 생략하기로 하자. 여러분들이 적당히 편집해서 사용하면 되겠다. 단, 주의할 점은 JavaHelp에서 지원하는 HTML 버전에 맞추어야 하므로 일단은 예제를 위해서 단순한 것만 사용하도록 하자.
파일들을 모두 생성했으면 정확한 도움말이 보이는지 확인하도록 하자. 확인 방법은 처음 설치 후에 확인했던 것처럼 실행해서 확인하면 된다. 본인은 아래와 같이 실행했다. 여러분은 설치 디렉토리와 파일들의 위치를 고려해서 변경하면 될 것이다.

D:\javahelp\demos\bin>java -jar hsviewer.jar -helpset D:\javahelp-2_0_01\my_sample\HelpSet.hs

실행하면 앞서 보인 화면이 나타난다. 이리 저리 클릭해보자. 제법 그럴싸하게 동작하는 것을 확인할 수 있다. 각각의 파일에 대한 자세한 설명은 설치 디렉토리 안에 포함된 사용자 가이드나 스펙을 참고하기 바란다.

3. 도움말과 프로그램을 연동하자

앞에서는 도움말 파일을 작성해 보았다. 도움말 자체로는 사실 큰 의미가 없다. 우리에게 필요한 것은 자신이 만든 프로그램과 연동되어 내 마음대로 도움말을 제어하는 것이다.
이번엔 아래 자바 소스 코드를 살펴보자.

import javax.swing.*;
import java.awt.event.*;
import java.awt.*;
import java.net.*;
import java.io.*;
import javax.help.*;
import javax.swing.event.*;

public class HanbitHelp extends JFrame {
   JMenuBar menuBar = new JMenuBar();

   JMenu fileMenu = new JMenu();
   JMenu editMenu = new JMenu();
   JMenu helpMenu = new JMenu();

   JMenuItem exitItem = new JMenuItem();
   JMenuItem helpItem = new JMenuItem();

   HelpSet helpSet;
   HelpBroker helpBroker;

   BorderLayout borderLayout1 = new BorderLayout();
   JTabbedPane tabbedPane = new JTabbedPane();
   JPanel javaPanel = new JPanel();
   JPanel cppPanel = new JPanel();
   JPanel dbPanel = new JPanel();

   public HanbitHelp() {
      try {
         jbInit();
         setSize(500, 300);
         setVisible(true);
      }
      catch (Exception e) {
         e.printStackTrace();
      }
   }

   private void jbInit() throws Exception {
      this.setJMenuBar(menuBar);
      this.setTitle("JavaHelp");
      this.getContentPane().setLayout(borderLayout1);
      fileMenu.setText("File");
      editMenu.setText("Edit");
      helpMenu.setText("Help");
      exitItem.setText("Exit");
      helpItem.setText("Contents");
      menuBar.add(fileMenu);
      menuBar.add(editMenu);
      menuBar.add(helpMenu);
      fileMenu.add(exitItem);
      helpMenu.add(helpItem);
      this.getContentPane().add(tabbedPane, BorderLayout.CENTER);
      tabbedPane.add(javaPanel, "Java");
      tabbedPane.add(cppPanel, "C++");
      tabbedPane.add(dbPanel, "Database");

      initHelp();

      helpItem.addActionListener(new ActionListener() {
         public void actionPerformed(ActionEvent e) {
            new CSH.DisplayHelpFromSource(helpBroker);
            // 반드시 true로 호출해야만 보인다
            helpBroker.setDisplayed(true);
         }
      });

      exitItem.addActionListener(new ActionListener() {
         public void actionPerformed(ActionEvent e) {
            System.exit(0);
         }
      });

      tabbedPane.addChangeListener(new javax.swing.event.ChangeListener() {
         public void stateChanged(ChangeEvent e) {
            tabbedPane_stateChanged(e);
         }
      });

   }

   private void initHelp() {
      try {
         // 헬프셋 파일을 지정한다
         File file = new File("D:\\javahelp-2_0_01\\my_sample\\HelpSet.hs");
         URL hsURL = file.toURL();
         helpSet = new HelpSet(null, hsURL);
      }
      catch (Exception ex) {
         ex.printStackTrace();
         System.out.println("Cannot find helpset file");
      }
      helpBroker = helpSet.createHelpBroker();
      helpBroker.setSize(new Dimension(500, 500));
      // 기본값 id를 지정
      helpBroker.enableHelpKey(getRootPane(), "overview", helpSet);
   }

   // 선택된 탭의 위치에 따라 다른 도움말 내용이 변하도록 처리
   void tabbedPane_stateChanged(ChangeEvent e) {
      JTabbedPane comp = (JTabbedPane) e.getSource();
      int index = comp.getSelectedIndex();
      if (index == 0) {
         // 맵 파일에 정의된 id를 설정한다
         helpBroker.setCurrentID("java");
      }
      else if (index == 1) {
         helpBroker.setCurrentID("c++");
      }
      else {
         helpBroker.setCurrentID("database");
      }
   }

   public static void main(String[] args) {
      HanbitHelp help = new HanbitHelp();
   }

}

프로그램에서 크게 어려운 부분은 없다. initHelp 라는 메소드에서 헬프시스템을 위한 설정 과 인스턴스를 생성하고 메뉴의 리스너에서는 선택된 탭에 대한 id를 지정하게 된다.
프로그램을 실행하면 아래 화면이 나타나고 Help 메뉴의 Contents를 선택해보자.



아까 생성했던 도움말이 나타난다. 도움말 창을 닫지 말고 메인 프로그램의 탭을 클릭해보자. Java , C++, Database 를 마음대로 선택하면 도움말의 내용이 바뀌는 것을 볼 수 있다.



이런 기능을 확장하면 자신의 프로그램에서 어떠한 화면이 보이더라도 원하는 도움말을 보여줄 수 있게 된다.

4. 마치면서

간단한 예제를 통해 JavaHelp가 어떤 것인지 살펴 보았다. 사실 이런 기능 이외에도 JavaHelp에서 지원하는 기능은 더 다양하다. 예를 들어 웹 프로그램에서 애플릿을 도움말 프로그램으로 사용하는 것도 가능하며, 도움말 파일들이 반드시 로컬 컴퓨터에만 있어야 하는 것이 아니라 도움말 서버를 이용해서 리모트 도움말 시스템을 구축하는 것도 가능하다.
여러분도 자신이 원하는 도움말 시스템을 JavaHelp와 함께 멋지게 작성해서 뽐내보도록 하자 ^^