Eclipse에서 DocBook XML 구현하기 (한글)

문서 옵션 JavaScript가 필요한 문서 옵션은 디스플레이되지 않습니다. 영어원문  제안 및 의견 피드백

난이도 : 중급

Nathan A. Good, Author and Software Engineer, Alliance of Computer Professionals

2007 년 8 월 28 일

DocBook XML은 거의 모든 아웃풋을 생성하기 위해 스타일시트를 작성하는데 사용되는 표준 XML 태그 라이브러리입니다. DocBook은 역사가 깊기 때문에, 다양한 유형의 문서를 생성하는 스타일시트가 여럿 존재하고 있습니다. DocBook XML과 Eclipse IDE를 함께 사용하여 여러 포맷으로 쉽게 배포할 수 있고 재사용 가능한 기술 문서를 생성하는 방법을 배워봅시다.

시작하기

소셜 북마크 mar.gar.in Digg del.icio.us Slashdot

이 글에서는 DocBook XML과 Eclipse 통합 개발 환경을 함께 사용하여 많은 포맷으로 쉽게 분산되는 재사용 가능한 기술 문서를 생성하는 방법을 설명한다. DocBook XML은 아웃풋을 생성하는 스타일시트를 작성할 수 있는 표준 XML 태그들의 라이브러리이다. 하지만, DocBook은 거의 10년 동안 존재했기 때문에, HTML, 텍스트, PDF, man 페이지를 포함하여 많은 유형의 문서들을 생성하는 많은 스타일시트들이 이미 작성되었다.

이 글을 읽은 후에, 여러분도 HTML에 생성될 수 있고 하나의 XML 소스 파일에서 Eclipse Help 플러그인과 PDF에 사용될 수 있는 문서를 생성할 수 있게 된다. XML의 작동 방식에 대한 이해도 높아질 것이다. Eclipse와 Apache Ant 사용에도 익숙해 지고, Eclipse IDE에서 Ant 빌드 파일들을 실행하는 방법도 알게 될 것이다. Eclipse V3.2 또는 이후 버전, DocBook XML V4.x Document Type Definitions (DTDs), DocBook XSL stylesheets, Apache Xalan-Java™, Apache FOP (선택) 등이 필요하다. (참고자료)

DocBook XML 개요

DocBook XML은 문서를 작성하는 용도로 고안된 XML 라이브러리이다. DocBook에 사용할 수 있는 많은 태그들은 기술적인 문서들을 구현하는데 일반적으로 사용되고 있다. DocBook은 XML이기 때문에, 스타일시트를 사용하여 다른 많은 아웃풋 포맷으로 변형될 수 있다. 이러한 이유로 DocBook XML은 기술 문서를 작성하여 이들을 다양한 포맷으로 생성하는데 일반적으로 사용된다.

주: 이 글에 제공된 코드는 DocBook XML V4.5를 사용하여 작성되었다. V5.0은 이 글을 쓰고 있는 현재 릴리스 후보 상태이다.

위로

고급 엘리먼트

표 1은 DocBook XML 파일의 고급 엘리먼트로서 일반적으로 사용되는 것들이다.

위로

콘텐트용 엘리먼트

고급 엘리먼트 안에, 실제 콘텐트-문단, 테이블, 리스트, 코드 샘플 등 실제 콘텐트를 추가하고 싶을 수도 있다. 표 2는 콘텐트를 책, 챕터, 아티클에 추가하는데 사용되는 공통의 엘리먼트 리스트이다.

책과 표 2에 열거된 엘리먼트들 중 적어도 한 개를 포함하고 있는 샘플 문서는 다음과 같다.

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
    <title>My Example Book</title>
    <titleabbrev>Example</titleabbrev>
    <bookinfo>
        <author>
            <personname>
                <firstname>Nathan</firstname>
                <surname>Good</surname>
            </personname>
        </author>
    </bookinfo>
    <preface id="preface1">
        <title>Required Preface</title>
        <para>You will like my book (I think).</para>
    </preface>
    <chapter id="chapter1">
        <title>Your First Chapter</title>
        <para>You must include at least one chapter in your book.</para>
        <para>Here is another paragraph.</para>
        <important>
            <para>This is some really important text.</para>
        </important>
        <tip>
            <para>Look both ways before crossing the street!</para>
        </tip>
        <caution>
            <para>
                Liberal use of <code>new</code> in loops can cause performance issues!
            </para>
        </caution>
        <example>
            <title>Example 1</title>
            <programlisting>
String something = "Something";
            </programlisting>        
        </example>
    </chapter>
</book>

파일이 HTML로 생성되고 브라우저에서 렌더링 되면, 그림 1과 같은 모양이 된다.

DocBook XML 태그에 대한 자세한 내용은 매뉴얼을 참조하라. HTML 버전의 매뉴얼은 참고자료 섹션을 참조하라. DocBook XML에 관한 서적도 있다. 표 2에 리스팅 된 태그들로 시작해도 좋지만, 스크린샷, 명령어 프롬프트, 사용자 인풋, 트레이트마크, 인용 같은 것을 다룰 때에도 사용할 수 있다.

위로

환경 설정하기

툴을 사용하여 Extensible Stylesheet Transformation Language (XSLT) 변형을 수행하고, XSL 스타일시트를 사용하여 DocBook XML을 HTML 또는 PDF 같은 보다 유용한 포맷으로 변형해야 한다. 상용 XML을 사용하고 있다면, 고유의 스타일시트를 작성해야 한다. DocBook XML 같은 포맷을 사용하면 다른 사람들이 이미 작성한 스타일시트를 사용할 수 있다. 미리 작성된 스타일시트를 사용하려면 다운로드를 한다. (참고자료) 이 글을 쓰고 있는 현재 DocBook XML V4.5용 스타일시트는 DocBook XSL V1.72.0이다.

스타일시트

여러분이 다운로드 한 압축 파일에는 DocBook XSL (docbook-xsl-1.72.0.zip)이 포함되어 있고 여기에는 아웃풋 유형에 따라 구성된 디렉토리들에 스타일시트가 포함되어 있다. html 디렉토리에는 HTML을 출력하기 위한 스타일시트가 포함된다. fo 디렉토리에는 Formatting Objects (FO) 포맷으로 파일을 생성하기 위한 스타일시트가 포함되어 있다.

압축 파일을 다운로드 하고 이것을 기억하기 쉬운 장소에 저장한다. 압축 파일에서 파일을 추출할 필요가 없다. — Eclipse로 직접 반입할 수 있다.

Xalan 사용하기

이 글에서, 필자는 XSLT 프로세서로서 Xalan을 사용한다. Eclipse에 포함된 Ant와 함께 Xalan을 사용하는데 한 가지 문제가 있다. 이 버전은 오래되었고 XSL을 처리할 때 문제를 갖고 있다.

Xalan은 두 개의 하위 프로젝트, Xalan C++과 Xalan-Java로 사용할 수 있는 Apache 프로젝트이다. 머신에 없다면 Xalan-Java를 다운로드 한다. 파일을 다운로드 하면 이를 기억하기 쉬운 장소에 저장한다. 스타일시트를 포함하고 있는 압축 파일과 마찬가지로, 파일의 콘텐트를 추출할 필요가 없다.

위로

Eclipse 프로젝트 만들기

지금까지, 몇 가지 샘플 파일들을 보았고 최신 버전의 DocBook XSL 스타일시트와 최신 버전의 Xalan을 다운로드 했다. 또한 DocBook XML 스키마 파일도 다운로드 해야 한다. 이 압축 파일(docbook-xsl-1.72.0.zip, xalan-j_2_7_0_bin-2jars.zip, docbook-xml-4.5.zip)은 찾기 쉬운 장소에 저장되어야 한다.

모든 압축 파일들을 다운로드 및 저장했다면, Eclipse에서 새로운 프로젝트를 생성하고 DocBook XML과 DocBook XML을 다양한 포맷으로 변형 할 Ant 스크립트를 편집할 준비가 된 것이다.

Eclipse가 시작한 후에 File > New > Project를 선택하여 새로운 프로젝트를 생성한다. General 밑에서, Project를 클릭한 다음, Next를 클릭한다. 프로젝트 이름을 타이핑 한 후에, Finish를 클릭하여 워크스페이스에 새로운 프로젝트를 생성한다.

위로

압축 파일에서 파일 반입하기

Eclipse에 새로운 프로젝트를 생성했으니, DocBook XML을 구현할 때 사용할 파일들을 반입한다.

DTD 파일 반입하기

DocBook XML DTD 파일을 반입한다. File > Import를 선택하고 General 카테고리에서 Archive File을 선택한다. Import Wizard가 나타나면, Browse를 클릭하여 DocBook XML DTD 압축 파일(docbook-xml-4.5.zip)을 배치하는데 사용할 수 있는 파일 브라우저를 연다.

Into folder 박스에서, 프로젝트 이름 뒤에 /docbook-xml을 입력한다. / folder가 선택되었는지를 확인한다. 선택되지 않았다면 Select All을 클릭한 다음 Finish를 클릭한다. 압축 파일 내의 파일들은 프로젝트로 삽입된다.

XSL 스타일시트 반입하기

DocBook XML DTD 파일 반입을 끝마쳤으면, 같은 프로세스에 따라서 docbook-xsl-1.72.0.zip 파일의 콘텐트를 반입한다. 이번에는 Into folder 박스의 프로젝트 이름 다음에 폴더 이름을 지정할 필요가 없다. 압축 파일의 콘텐트는 이미 프로젝트 내 docbook-xsl-1.72.0 폴더에 놓일 것이기 때문이다.

XSL 스타일시트를 반입했기 때문에, Java Archive (JAR) 파일들을 반입한다. 이것은 Xalan 웹 사이트에서 다운로드 했던 압축 파일에 필요한 파일이다. 다른 압축 파일들을 반입할 때와 같은 프로세스를 따르지만, 이번에는 doc, license, samples directory를 제거했는지를 확인하여 프로젝트에 반입되지 않도록 한다. 이러한 디렉토리를 제거한 후에 Into folder 박스에 프로젝트 이름을 수정한다. /lib을 추가하면 된다.

필요한 모든 파일들을 반입한 후에, 프로젝트 내에 추가 파일을 만들고 src라는 이름을 짓는다. 이것은 모든 DocBook XML 파일용 기본 폴더가 될 것이다.

지금까지, 다음과 같은 폴더를 가진 프로젝트를 Eclipse 프로젝트를 만들었다.

• docbook-xml: DocBook XML DTD 포함
• docbook-xsl-1.72.0: DocBook XML XSL 스타일시트 포함
• lib: Xalan JAR 파일 포함
• src: 현재까지는 비어있는 상태

프로젝트에 이 모든 폴더가 생겼다면, Ant build.xml 파일을 추가하여 변형 프로세스를 실행 할 준비가 된 것이다.

Ant 스크립트 작성하기

Ant는 자바 기반 빌드 툴로서 XML 스크립트를 읽고 이 스크립트에 정의된 많은 태스크들을 수행한다. Ant에 익숙하지 않다면, 참고자료 섹션을 참조하라. 이 글에서는 Eclipse를 사용하여 Ant를 초기화 할 것이기 때문에, 명령행에서 이를 실행 할 필요는 없다. 또한, Eclipse IDE V3.2.x에 Ant가 포함되어 있으므로 Ant를 다운로드 및 설치할 필요도 없다. 현재 사용할 V1.65가 V1.7 보다 구버전이지만, 이 글에 사용해도 무방하다.

Ant V1.6.5에 포함된 Xalan 버전은 최신 DocBook XSL과 함께 실행할 때 잘 작동하지 않았다. 최신 버전의 Xalan(Xerces 포함)을 다운로드 하여 사용하는 것이 좋다.

위로

Ant에서 Xalan 사용하기

Ant에게 특정 버전의 Xalan을 사용하도록 명하는 여러 가지 방식들이 있고, 또는 Ant에 속한 기본 버전 대신에 다른 XSLT 프로세서를 사용할 수 있다. 이들 중 하나는 Ant용 classpath를 수정하는 것이다. Eclipse IDE 내에서 Ant를 사용한다면 매우 사용하기 쉽다. Window > Preferences를 선택하여 Ant/CLASSPATH 밑에 설정을 변경한다. CLASSPATH 탭의 Xalan 또는 Xerces에 대한 레퍼런스를 제거하고 이들을 다운로드 했던 버전으로 대체할 수 있다.

복구할 수 없는 변경 복구할 수 없는 변경에 대해 걱정하지 말라. Restore Default 버튼으로 Ant 설정을 처음 Eclipse를 다운로드 했을 때로 돌아가게 할 수 있다.

여러분이 변형을 수행하는 유일한 사람이라면 이 방식도 좋다. 여러분만이 Ant 설정을 변경하여 변형이 올바르게 수행될 수 있도록 할 수 있기 때문이다. 하지만, 팀원들과 함께 일한다면, 디렉토리(lib)에 있는 프로젝트에 Xalan과 Xerces JAR 파일들을 포함시키고 build.xml을 수정하여 xslt 태스크용 라이브러리를 사용하는 것도 좋다. 이 방식을 사용하여, Eclipse IDE 설정을 변경하지 않고, 소스 콘트롤에서 파일을 체크하거나 프로젝트를 분산하고 이를 실행한다.

JAR 파일을 xslt 태스크에 제공하는 예제는 아래 Ant 빌드 스크립트에 나타나 있다.

                
<?xml version="1.0"?>
<!--
  - Author:  Nathan A. Good <mail@nathanagood.com>
  -->
<project name="docbook-src" default="usage">
    
    <description>
            This Ant build.xml file is used to transform DocBook XML to various
    </description>

    <!--
      - Configure basic properties that will be used in the file.
      -->
    <property name="docbook.xsl.dir" value="docbook-xsl-1.72.0" />
    <property name="doc.dir" value="doc" />
    <property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
    <property name="xalan.lib.dir" value="lib/xalan-j_2_7_0" />

    <!--
      - Sets up the classpath for the Xalan and Xerces implementations
      - that are to be used in this script, since the versions that ship
      - with Ant may be out of date.
      -->
    <path id="xalan.classpath">
        <fileset dir="${xalan.lib.dir}" id="xalan.fileset">
            <include name="xalan.jar" />
            <include name="xercesImpl.jar" />
        </fileset>
    </path>

    <!--
      - target:  usage
      -->
    <target name="usage" description="Prints the Ant build.xml usage">
        <echo message="Use -projecthelp to get a list of the available targets." />
    </target>

    <!--
      - target:  clean
      -->
    <target name="clean" description="Cleans up generated files.">
        <delete dir="${doc.dir}" />
    </target>

    <!--
      - target:  depends
      -->
    <target name="depends">
        <mkdir dir="${doc.dir}" />
    </target>

    <!--
      - target:  build-html
      - description:  Iterates through a directory and transforms
      -     .xml files into .html files using the DocBook XSL.
      -->
    <target name="build-html" depends="depends" 
        description="Generates HTML files from DocBook XML">
        <xslt style="${html.stylesheet}" extension=".html" 
            basedir="src" destdir="${doc.dir}">
            <classpath refid="xalan.classpath" />
        </xslt>
    </target>
    
</project>

<property> 태그로는 Xalan JAR 파일들의 위치를 지정할 수 있다. <path> 엘리먼트는 Ant 스크립트를 통해 재사용 할 수 있는 경로를 정의한다. refid 애트리뷰트를 사용하여 경로를 참조하는 대신, classpath 애트리뷰트를 사용하거나 classpath 엘리먼트 내에 이 경로를 지정함으로써 Xalan XSLT 프로세서에 대한 경로를 xslt 타겟으로 지정할 수 있다.

xslt 타겟은 basedir, extension, destdir 애트리뷰트로 디자인 되어 폴더를 반복적으로 실행하고 이 디렉토리에서 발견된 XML 파일들용 HTML 파일을 생성한다. 아웃풋은 나중에 HTML 소스로서 사용할 폴더에 저장된다.

위로

build.xml 파일 생성하기

File > New >File을 선택하여 build.xml 파일을 생성한다. 파일 이름으로 build.xml을 입력하고, 파일 배치 장소로 프로젝트를 선택한다. Finish를 클릭하여 Ant 파일을 생성한다.

Listing 2의 콘텐트를 새로운 빌드 파일에 놓는다. 여러분이 선택했던 디렉토리 이름이 여기에서 사용했던 것과 다르다면, property 엘리먼트의 일부 값을 조정한다.

Eclipse에서 직접 build.xml 파일을 실행할 수 있다. Eclipse는 Ant 빌드 스크립트를 실행하는 빌트인 후크가 있다. Ant를 사용하면 두 가지 추가 효과가 있다. 우선, 이것은 크로스 플랫폼이다. 자바 코드를 실행하는 어떤 OS에서도 같은 빌드 스크립트를 실행할 수 있다. 또 하나는 IDE와 독립적으로 빌드 스크립트를 실행할 수 있다. 따라서, 이것을 자동화된 빌드 프로세스에 쉽게 통합하거나, 명령행에서 이를 실행할 수 있다. 처음에는 Eclipse 프로퍼티를 설정하여 XSLT 프로세스를 외부 툴로서 실행하는 방법을 모색했으나(Run > External Tools), 이러한 혜택과 맞바꾸기로 했다.

위로

build-html 타겟 실행하기

build.xml 파일을 작성한 후에, build-html 타겟을 실행할 수 있다. 여러분은 어떤 DocBook XML 파일도 갖고 있지 않으므로, 이 타겟은 어떤 것도 수행하지 않는다. 하지만, 이 스크립트를 실행한다고 해서 에러가 생기는 것도 아니다.

Ant 타겟을 실행하는 가장 쉬운 방법 중 하나는 Outline 뷰에서 수행하면서, 빌드 파일을 에디터에서 여는 것이다. Outline 뷰 내에서, build-html 타겟의 이름을 오른쪽 클릭한 다음, Run As > Ant Build를 선택한다. Ant 빌드 스크립트에서 온 메시지가 Console 뷰에 나타난다.

위로

DocBook XML 파일 작성하기

Eclipse 프로젝트에, DocBook XML DTD 파일, DocBook XSL 파일, Xalan 라이브러리, build.xml 파일이 생겼다. 이제, DocBook XML 파일들을 구현하는데 필요한 모든 것을 갖추었다.

최초의 DocBook XML 파일 만들기

다음은 Eclipse에서 DocBook XML 파일을 생성하는 방법이다.

1. File > New > Other를 선택한다.
2. XML 카테고리에서 XML을 선택하고 Next를 클릭한다.
3. Create XML File 윈도우에서 Create XML file from a DTD file을 선택하고 Next를 클릭한다.
4. File name 박스에 chapter1.xml을 입력하고 프로젝트 내에 src 폴더가 선택 되었는지를 확인하고 Next를 클릭한다.
5. Select DTD File에서, 프로젝트의 docbook-xml 폴더에 있는 docbookx.dtd로 가서 Next를 클릭한다.
6. Select Root Element 윈도우가 나타나면, Root element에서 chapter를 선택한 다음 Create first choice of required choice 체크박스를 해제한다.
7. -//OASIS//DTD DocBook XML V4.5//EN을 입력하고 Finish를 클릭한다.

XML의 유효성 검사 DocBook XML 파일들은 Eclipse 내에서 유효성 검사를 받을 수 있다. Project Explorer에서 오른쪽 클릭하고, Validate를 클릭한다. 밸리데이션 에러가 발생하면, Errors 밑에 있는 IDE에 Problems 뷰에 나타난다. 에러 메시지를 더블 클릭하면, Eclipse IDE는 에러가 발생한 파일 위치를 보여준다.

XML 에디터에서 chapter1.xml 작업하기

Eclipse는 XML 에디터에서 chapter1.xml을 연다. Eclipse의 XML 에디터에는 두 가지 파일 뷰가 있다. Design과 Source이다. XML 파일의 Design 뷰는 파일의 엘리먼트를 그리드로 디스플레이 하고, 왼쪽 컬럼에는 엘리먼트 이름이, 왼쪽 컬럼에는 엘리먼트 내용이 있다. 파일을 오른쪽 클릭하고 Add Child, Add After 또는 Add Before를 선택하여 파일에 새로운 엘리먼트를 추가할 수 있다.

DTD를 사용하고 있다면 콘텍스트 메뉴의 메뉴 옵션은 유효한 엘리먼트만 추가하도록 제한한다. 이 기능으로 XML 파일에 생길 밸리데이션 오류의 위험을 줄인다.

위로

모듈식 문서 구현하기

많은 문서들을 생성할 때, 문서들 간 유사성이 생기기 마련이고, 특히 같은 사용자일 경우 그렇다. 예를 들어, 많은 기술 서적을 읽는다면, 거의 모든 것에 "Conventions Used in This Book" 섹션이나 힌트, 팁, 인라인 코드, 코드 리스팅이 포맷된 방법을 설명하는 챕터가 있기 마련이다.

DocBook XML 파일 나누기

DocBook XML을 사용하면 하나의 단위로 컴파일 될 수 있고 재사용 될 수 있는 파일들로 나눌 수 있다. 예를 들어, 책의 각 챕터를 개별 XML 문서에 놓는다. 다른 책에서 이들을 사용하거나 이들을 개별 파일들로 나누어서 관리하기 쉽도록 한다. 책에 챕터를 추가할 수 있고 스타일시트를 사용하여 이들을 처리할 수 있다.

Listing 3은 다른 DocBook XML 파일들을 동적으로 포함하고 있는 DocBook XML 문서를 구현하는 예제이다. 이 파일이 변형 동안 처리될 때, 파일 — chapter1.xml —은 &chap1;이 배치된 장소와 같다.

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "../docbook-xml/docbookx.dtd" [
    <!ENTITY chap1 SYSTEM "chapter1.xml">
    ]>
<book>
    &chap1;
</book>

이러한 방식을 취할 때 여러 가지를 살펴야 한다. 우선, chapter1.xml 파일을 수정하여 XML 프로세싱 명령어와 DOCTYPE 엘리먼트를 제거해야 한다. chapter1.xml의 콘텐트는 &chap1 엔터티가 배치된 장소에 놓이므로, book.xml에는 XML 프로세싱 명령어와 DOCTYPE 엘리먼트가 파일 중간에 포함되어, 무효로 만든다.

개별 챕터 파일들을 개별 HTML 파일들로 더 이상 처리하고 싶지 않다면, Ant 빌드 스크립트를 업데이트 하여 챕터 파일의 프로세싱을 무시한다. 다행히도, Ant의 xslt 태스크를 사용하면 변경은 매우 쉽다. xslt 태스크에는 Ant의 fileset 엘리먼트와 같은 엘리먼트가 포함되는데, 파일 리스트를 구현하여 쉽게 추가 또는 배제할 수 있다. Listing 4는 필수 추가 항목들을 포함시켜 <exclude> 엘리먼트를 사용하여 프로세싱에서 특정 파일들을 무시하는 방법을 보여주고 있다.

                
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />

    </xslt>
</target>

모든 문서를 구현하고 싶다면, 위 리스팅에서 exclude를 제거한다.

챕터와 책을 나누는 것으로만 제한되지 않는다. DocBook XML 파일들을 물리적으로 분할할 수 있다. 심지어, set 엘리먼트에 책을 포함시킬 수 있는데, 이는 고급 DocBook 엘리먼트이다.

Help 플러그인 구현하기

Eclipse 프레임웍의 강력한 기능 중 하나가 확장성이다. 기업이 특정 "승인된" 방식으로 데이터베이스를 연결하고, 트랜잭션을 처리하고, 에러를 처리하는 것을 볼 때, 왜 기업은 개발자로 하여금 자신들이 작업하는 환경 밖에서 문서를 찾도록 하는지 의문이다. 기업 인트라넷에서 사용할 수 있는 같은 HTML 문서를 구현하여 이를 IDE, 인덱스, 검색을 통해 쉽게 액세스 될 수 있는 Help의 형태로 개발자들에게 배포하면 안될까?

Eclipse IDE에는 HTML 파일의 형태로 Help를 포함하고 있는 플러그인 프로젝트를 빠르게 생성하는데 사용되는 템플릿이 있다. 다음 섹션에서는 그러한 플러그인 프로젝트를 구현하는 방법을 설명하겠다. 플러그인 프로젝트를 구현한 후에, DocBook XML 프로젝트에서 구현한 HTML 파일들을 추가시킨다.

위로

Help 플러그인 생성하기

Help 플러그인 생성하기:

1. File > New > Project를 선택하여 New Project Wizard를 시작한다.
2. 마법사 리스트에서, Plug-in Development 카테고리에서 Plug-in Project를 선택한 다음, Next를 클릭한다.
3. Project name 박스에서 MyHelpPlugin을 입력하고 Next를 클릭한다.
4. 그림 4와 같은 윈도우에서 Next를 클릭한다
   
   그림 4. 새로운 플러그인 프로젝트
   
   
   
5. Available Templates 리스트에서, Plug-in with sample help content를 선택하고 Next를 클릭한다.
6. 다음 윈도우에서 Finish를 클릭한다. Plug-in Development 퍼스펙티브로 바꾼다. 퍼스펙티브에는 Help를 구현할 때 도움이 될 뷰가 자동으로 포함되기 때문에 Yes를 클릭한다.

새로운 프로젝트에는 html이라고 하는 폴더와, 그 폴더 안에는 샘플 HTML 파일들이 포함된다. 이러한 파일들을 DocBook 프로젝트에서 생성된 HTML 파일로 대체한다.

프로그레스 체크하기

수정하지 않고, Run > Run As > Eclipse Application을 선택하여 Eclipse의 인스턴스로 플러그인을 실행하여 Help가 어떤 모습인지를 본다. Eclipse의 새로운 인스턴스가 시작한다. Eclipse가 시작한 후에, Help > Help Contents를 선택하여 플러그인이 실행되는 모습을 본다. 수정하지 않았다면, 콘텐트에 Test TOC가 리스팅 된다.

DocBook XML 프로젝트에서 HTML 만들기

새로운 Help 플러그인의 기본 콘텐트를 보았으므로, 앞서 구현했던 DocBook XML 프로젝트에서 HTML을 생성할 차례이다. 새로운 플러그인 프로젝트에서 HTML 아웃풋을 복사해야 하지만, 매번 직접 수행할 필요가 없다. 수동 프로세스만 남겨져 있다면, 실수하기 쉽고, 플러그인을 구현하는 과정에서 이를 빼먹기 쉽다.

Ant 파일 추가하기

HTML 파일들을 자동으로 복사하는 첫 번째 단계는 Ant 파일을 구현하는 것이다. Ant 파일은 DocBook XML 프로젝트에서 플러그인 프로젝트의 html 폴더로 HTML 파일들을 복사하면 된다. Ant 파일은 Eclipse가 프로젝트를 구현할 때마다 실행될 것이다.

Ant 파일의 콘텐트는 아래 나타나 있다. 이 파일은 단 하나의 타겟 — prepare — 을 갖고 있는데, 이는 빌드 파일의 기본 타겟이다. 이 빌드 파일은 Eclipse에 의해서만 호출되므로, 기본 타겟을 prepare로서 남겨두었다.

                
<?xml version="1.0"?>
<project name="MyHelpPlugin" default="prepare">
    <description>
        Prepares the Help plug-in project by copying the HTML help files
        from the DocBook XML project into this one.
    </description>
    
    <property name="docbook.project.dir" value="../myProject" />
    <property name="html.dir" value="html" />
    <property name="html.src.dir" value="${docbook.project.dir}/doc" />
    
    <fileset id="html-files" dir="${html.src.dir}">
        <include name="**/*.html" />
        <include name="**/*.css" />
    </fileset>
    
    <target name="prepare">
        <copy todir="${html.dir}">
            <fileset refid="html-files" />
        </copy>
    </target>
</project>

빌더 정의하기

이러한 프로그램들을 빌더(builders.)라고 한다. 프로젝트의 이름을 오른쪽 클릭하고, Project > Properties를 선택하여 빌더를 수정할 수 있다. Builders 밑에, 이 프로젝트를 위해 이미 설정된 빌더를 볼 수 있다. Java Builder, Plug-in Manifest Builder, Extension Point Schema Builder이다. Eclipse에서 Ant 스크립트를 실행하여 HTML 파일을 플러그인 프로젝트에 복사한다.

1. Builders 프로퍼티 페이지에서 New를 클릭한다.
2. 리스트에서 Ant Build를 선택하고 OK를 클릭한다.
3. Ant Builder 같은 새로운 빌더 이름을 입력한다.
4. Buildfile 밑에, Browser Workspace를 클릭하여 워크스페이스 내에 Ant 파일을 배치한다.
5. Targets 탭을 클릭하고, After a "Clean"과 Manual Build 타겟이 <default target selected>를 뜻하는지를 확인한다.
6. OK를 클릭하여 빌더를 저장한다.
7. Builders 페이지에서, 새로운 Ant 빌더를 선택한 다음 빌더가 리스트의 첫 번째 것이 될 때까지 Up을 클릭한다. 추가 작업을 수행하기 전에 파일들을 플러그인 프로젝트에 복사해야 하므로 이를 수행해야 한다.

새로운 빌더를 설정한 후에, Project > Clean 또는 Project > Build를 선택하여 프로젝트를 지우거나 구현한다. Ant 빌더는 실행되고, DocBook XML 프로젝트에서 HTML 파일들을 자동으로 가져온다.

프로젝트 구현 순서 프로젝트가 워크스페이스에서 구현되는 순서를 수정하여 DocBook 문서를 포함하고 있는 프로젝트가 Help 플러그인 전에 구현되도록 해야 한다. 프로젝트 구현 순서를 변경하려면, Window > Preferences를 선택한다. General/Workspace/Build Order 밑에, 프로젝트 리스트가 보인다. Use default build order 체크박스를 비우고, Up과 Down 버튼을 사용하여 프로젝트의 순서를 바꾼다.

빌더 추가하기는 DocBook XML 프로젝트에도 적용된다. Ant 빌더를 DocBook XML 프로젝트에 추가하면서, 프로젝트를 지우거나 구현할 때 타겟들 중 하나를 실행 타겟으로 설정한다. (usage 타겟은 기본이었다.)

위로

Help TOC 파일

HTML Help 파일용 콘텐트 테이블(TOC)는 플러그인 프로젝트에 포함된 두 개의 XML 파일에 있다. 파일들은 아래와 같다.

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Test TOC">
    <link toc="toc.xml" />
</toc>

testTOC.xml 파일(Listing 6)에는 Help 윈도우의 Contents 페인에 나타나는 헤딩의 이름이 포함되어 있다. toc.xml 파일로 연결하는 일만 한다.

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents">
    <topic label="Main Topic" href="html/book.html"> 
    </topic>
</toc>

toc.xml 파일에는 주요 토픽 밑에 나타나는 메인 토픽이 포함된다. 이러한 메인 토픽들은 href 애트리뷰트와 함께 HTML 페이지로 연결된다. (Listing 7)

Help를 하나의 통합된 파일(책)으로 구현할 수 있고, 이 파일을 가리키는 단 하나의 메인 토픽을 가질 수 있다. 하지만, 문서를 toc.xml 파일에 색인될 수 있는 개별 챕더틀로 나누지만, 원한다면 하나의 책으로 구현할 수 있다. "모듈식의 문서 구현하기"에서 문서를 여러 물리적 파일로 나누는 방법을 참조하기 바란다.

위로

DocBook 아웃풋 커스터마이징

지금까지 DocBook XML을 Eclipse 플러그인 내에서 Help로서 사용되는 일반 HTML로 변형해 보았다. 변형으로 생긴 HTML의 모양을 바꾸고 싶다면?

다행히도, 직접 XSL 스타일시트를 작성하여 HTML에 개인화 또는 커스텀 포맷팅을 추가할 필요가 없다. 대신, 변수를 XSLT 변형 단계로 전달하여 Cascading Style Sheet (CSS)에 할당하여 HTML을 포맷팅 한다.

위로

CSS stylesheet에 할당하기

DocBook XML을 HTML로 변형하는 XSL 스타일시트는 html.stylesheet라고 하는 변수를 검사한다. 변수에 값이 포함된다면, 이 값은 HTML의 link 엘리먼트에 사용되어 여러분이 지정한 스타일시트로 연결한다.

Listing 8은 두 개의 클래스(important와 caution)을 가진 CSS를 보여준다. 이 CSS는 이러한 클래스들용 텍스트 색상을 바꾼다. 페이지가 디스플레이 될 때, 이러한 클래스들은 <important>와 <caution> 태그 내의 콘텐트에 상응한다.

                
body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }

위로

Ant 빌드 파일 수정하기

Listing 8에 나타난 CSS를 DocBook XML 프로젝트의 lib 디렉토리에 style.css라는 이름을 가진 파일에 저장한다. 파일을 저장한 후에, Ant 빌드 파일을 수정하여 CSS 파일의 이름을 xslt 타겟에 전달하고, CSS 파일을 lib 폴더에서 나머지 HTML 아웃풋과 같은 폴더에 복사한다. Listing 9는 변경 사항들이다.

                
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />
        <param name="html.stylesheet" expression="style.css" />
    </xslt>
    <!-- Copy the stylesheet to the same directory as the HTML files -->
    <copy todir="${doc.dir}">
        <fileset dir="lib">
            <include name="style.css" />
        </fileset>
    </copy>
</target>

수정한 후에, DocBook XML 프로젝트에서 Ant 빌드 스크립트를 재실행 한다. 아웃풋 HTML 파일을 보면, 폰트가 변경되고, "Important"와 "Caution" 부분에 새로운 폰트 색상을 볼 수 있다.

위로

PDF 생성하기

지금까지, DocBook XML에서 다양한 툴을 사용하여 인트라넷 사이트를 통해 배포되고 Eclipse Help 플러그인에 포함될 수 있는 HTML을 생성해 보았다. 하지만, 같은 DocBook XML 소스 파일을 사용하여 PDF도 만들 수 있다. DocBook XML에서 PDF를 생성하기 위해서는 추가 툴이 필요하다. Apache XML Graphics Project의 FOP 라이브러리이다. (참고자료).

FOP 라이브러리에는 기존의 Ant 빌드 파일을 DocBook XML 프로젝트에 직접 놓을 수 있는 Ant 태스크가 포함된다. Ant 태스크 fop는 FO 파일들을 변형하면서, DocBook XSL에 포함된 FO 스타일시트로 구현된다.

위로

FOP 라이브러리를 사용하여 PDF 만들기

FOP 라이브러리를 사용하려면, 웹 사이트에서 바이너리 배포판(fop-0.93-bin-jdk1.4.zip)이 포함된 ZIP 파일을 다운로드 한다. ZIP 파일의 이름이 Java 2 Platform, Standard Edition (J2SE), Development Kit (JDK) V1.4용으로 특별히 구현되었다고 나타나 있지만, Java V5에서도 무리 없이 작동한다. 다른 압축 파일들과 마찬가지로, 아직 파일을 추출하지 않아도 된다.

Eclipse에서, File > Import를 선택한 다음, "압축 파일에서 파일 반입하기" 때와 같은 프로세스를 거친다. 이번에는, build와 lib 폴더만 선택한다.

파일 반입을 마친 후에, Ant 빌드 스크립트를 수정하여 fop 타겟을 설정하고, 이를 새로운 build-pdf 타겟에서 호출한다.

                
<!--
    - target:  build-pdf
    - description:  Iterates through a directory and transforms
    -     .xml files into .fo files which can then be turned into DocBook XML
    -     files.
    -->>
<target name="build-pdf" depends="depends" 
    description="Generates PDF files from DocBook XML">>
    <xslt style="${fo.stylesheet}" extension=".fo" 
        basedir="${source.dir}" destdir="${fo.dir}">>
        <classpath refid="xalan.classpath" />>
        <include name="book.xml" />>
    </xslt>>

    <property name="fop.home" value="lib/fop-0.93" />>

    <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">>
        <classpath>>
            <fileset dir="${fop.home}/lib">>
                <include name="*.jar" />>
            </fileset>>
            <fileset dir="${fop.home}/build">>
                <include name="fop.jar" />>
                <include name="fop-hyph.jar" />>
            </fileset>>
        </classpath>>
    </taskdef>>

    <fop format="application/pdf" fofile="${fo.dir}/book.fo" 
        outfile="${dist.dir}/book.pdf" />>
</target>>

타겟을 설정한 후에, Eclipse IDE에서 build-pdf 타겟을 실행한다. 이번에는 dist 디렉토리에, book.pdf가 나타난다.

요약

DocBook XML은 HTML과 PDF 같은 다양한 아웃풋으로 생성될 수 있는 기술 문서를 구현하는 강력한 포맷이다. 이 포맷을 사용하면 여러분은 문서의 콘텐트에 집중할 수 있고, 스타일링은 신경 쓰지 않아도 된다. 많은 툴들을 사용하여 DocBook XML에서 문서를 편집 및 구현할 수 있다.

Eclipse IDE에는 XML 문서의 작성 및 유효성 검사용 에디터가 포함된다. Eclipse는 Ant와도 통합되어, Eclipse의 정식 빌더로서 실행될 수 있은 강력한 빌드 파일들을 생성할 수 있다. 게다가, Eclipse에 포함된 템플릿들은 플러그인 프로젝트를 빠르게 구현할 수 있고, 여기에는 Eclipse의 Help에 사용할 수 있는 HTML 파일도 포함된다.

이 모든 툴들을 사용하여 한 장소에서 기술 문서를 작성할 수 있고 다양한 포맷으로 다양한 독자들에게 배포할 수 있다.

참고자료

• DocBook: 확실한 가이드.
  
  
• Apache Ant 매뉴얼.
  
  
• "Eclipse 추천 도서 리스트 (한글)."
  
  
• Eclipse 기술자료 (한국 developerWorks).
  
  
• Eclipse 프로젝트 리소스 시작하기 (한글).
  
  
• 한국 IBM developerWorks Eclipse 프로젝트 리소스 (한글).
  
  
• developerWorks podcasts.
  
  
• "Eclipse Platform 시작하기 (한글)."
  
  
• developerWorks 기술 이벤트와 웹캐스트.
  
  
• developerWorks On demand 데모.
  
  
• IBM 오픈 소스 개발자를 위한 컨퍼런스, 트레이드 쇼, 웹캐스트, 이벤트.
  
  
• 한국 developerWorks 오픈 소스 존
  
  

• Eclipse.org: 이클립스 다운로드.
  
  
• Download Apache FOP for converting FO files to various formats, including PDF, from the Apache FOP 사이트: 다운로드 Apache FOP
  
  
• DocBook XML DTD files 다운로드.
  
  
• DocBook XSL stylesheets
  
  
• 최신 버전 Xalan-Java 다운로드.
  
  
• 최신 Eclipse technology 다운로드 (IBM alphaWorks).
  
  
• IBM 제품 평가판 다운로드 : DB2®, Lotus®, Rational®, Tivoli®, WebSphere®.
  
  
• IBM 시험판 소프트웨어를 다운로드하여 차기 개발 프로젝트에 활용해보라(다운로드 또는 DVD 제공)

• Eclipse Platform 뉴스그룹
  
  
• Eclipse 뉴스그룹
  
  
• developerWorks 블로그와 커뮤니티 참여하기.
  
  

필자소개

		Nathan Good은 미네소타의 Twin Cities에 거주하고 있다. 소프트웨어를 만들지 않을 때에는 PC와 서버 구현을 하거나, 신기술 관련 책을 읽고, 오픈 소스 소프트웨어를 연구한다. 컴퓨터를 사용하지 않을 때에는, 가족과 시간을 보내거나, 교회에 가거나 영화를 본다. 필자 웹사이트.

기사에 대한 평가

보다 나은 서비스를 제공하기 위함이오니 잠시 짬을 내어 이 양식을 제출하여 주십시오. 귀하께서 원하시는 정보를 얻었습니까? 예 아니오 잘 모르겠음   이 페이지 개선을 위한 의견을 주십시오:   이 정보가 얼마나 유용했습니까? (1 = 전혀 도움이 되지 않음, 5 = 매우 유용함) 1 2 3 4 5

위로