2012년 3월 10일 토요일

GeoServer의 문서관리


현재 GeoServer의 문서는 경량의 마크업 구문인 reStructuredText를 이용해 편집 후, 파이썬의 개발자들이 작성한 문서 프레임 워크인 Sphinx를 이용하여 HTML(http://docs.geoserver.org/stable/en/user/)과 PDF로 변환합니다.
또한, 현재 GeoServer의 도움말 다국어지원은 영문캐릭터(en)를 기준으로 작성되어 있으며, 에스파냐어(es), 프랑스어(fr) 로 사용자매뉴얼 일부를 지원하고 있는 실정입니다.
이 문서를 그대로 가져다가 한글화를 한 후 HTML 또는 PDF로 변환하는 경우 HTML은 한글이 깨지는 현상이 발생하고, PDF는 변환 자체가 실패하게 됩니다.
아래는 GeoServer의 도움말(사용자, 개발자)을 한글화하기 위한 방법을 설명합니다. 이 문서 역시 아래의 방법을 적용하여 작성했습니다.

Sphinx 프로그램 설치하기

Installing Sphinx
Windows 환경에서 Sphinx를 이용해 HTML/PDF 문서를 만들기 위해서는 아래 3가지 프로그램을 설치해야 합니다.:
  1. Python을 다운로드 후 설치합니다. 다양한 버전이 있으나, 여기에서는 official version 2.7.2 을 사용했습니다.
  2. setuptools for Python 2.5 을 다운로드 후 설치합니다.
  3. 환경설정의 Path에 python 과 setuptools 을 추가합니다. 위치는 제어판 ‣ 시스템 ‣ 고급설정 ‣ 환경변수 이며 PATH 시스템 변수에 추가하면 됩니다. 예를 들어, python 이 C:\Python 에 setuptools 이 C:\Python\scripts 에 설치되었다면 다음과 같이 추가합니다.
    ...;C:\Python;C:\Python\scripts
    
  4. 명령 프롬프트를 열고 다음을 실행하여 Sphinx를 설치합니다. Sphinx v1.1.2 버전이 설치됩니다.:
    easy_install sphinx
  5. GeoServer 문서 프로젝트 소스파일을 다운로드(SVN 또는 소스)합니다 .https://svn.codehaus.org/geoserver/trunk/doc/en 디렉터리는 다음과 같이 구성되어 있으며 개발자매뉴얼(developer), 문서작성가이드매뉴얼(docguide), 사용자매뉴얼(user), 문서작성템플릿(theme)을 포함합니다.
    developer/
    docguide/
    theme/
    user/
  6. GeoServer 문서 프로젝트는 모두 make.bat 파일을 포함하고 있습니다.
  7. 설치가 제대로 되었는지 테스트하기 위해 명령 프롬프트를 열고 GeoServer 소스 디렉터리(doc/en/user)로 이동하여 다음을 실행합니다.:
    make html
    위 명령어는 docenuser\build\html 디렉터리에 HTML 페이지를 생성합니다.

LaTeX full 버전 프로그램 설치하기

HTML 문서만 필요하고 PDF 변환이 필요없으면 이 섹션은 건너 뛰십시오. proTeXt(MiKTeX-based distribution for Windows)는 한글을 제대로 지원하지 않습니다.
여기에서는 한글 TeX 사용자 그룹인 KTUG 에서 ko.TeX Live 2011(KoTeXLive(표준한글TeX환경프로젝트) 를 다운받아야 합니다.
Installing KoTeXLive
한글텍사용자그룹의 설치과정<http://faq.ktug.or.kr/faq/KoTeXLive>을 참조하십시오. 설치 파일이 약 1.6 GB 정도 되고 설치 및 업데이트 시간이 상당히 오래 걸립니다. 인내심을 가지고 진행하십시오.
설치 후 시작-ko.TeX Live 2011-TL Update All 을 실행하여 TeX 시스템을 최신 파일들로 갱신합니다.
Installing TeXnicCenter
KoTeXLive의 TeXworks Editor 외에 TeX 파일 편집이 필요한 경우 http://www.texniccenter.org/에서 편집도구를 설치할 수 있습니다.

Sphinx에서 한글문제

아래 예는 사용자매뉴얼(user)의 환경을 설정하는 과정입니다.
자세한 내용은 http://sphinx.pocoo.org/config.html 를 참고하세요.
  1. doc/en/user/source/conf.py 파일을 텍스트 편집기에서 불러옵니다.
  2. General configuration 을 찾아 다음의 설정을 추가하거나 수정합니다.:
    source_encoding = 'utf-8-sig'
    language = 'ko'
    
  3. Options for HTML output 을 찾아 다음의 설정을 추가하거나 수정합니다.
    html_output_encoding = 'utf-8'
    
  4. 이 부분은 PDF 출력을 위한 옵션입니다. Options for LaTeX output 을 찾아 다음의 설정을 추가하거나 수정합니다.
    latex_elements = {
      'inputenc': '\\usepackage{kotex,xcolor}',
      'utf8extra': '',
      'fontenc': '',
      'fontpkg': '\\usepackage{times}',
      'fncychap': '\\usepackage[Sonny]{fncychap}',
      'releasename': 'Release',
      'preamble': #"""\\usepackage[parfill]{parskip}
      """
       \\hypersetup{
          colorlinks = true,
          linkcolor = [rgb]{0,0.46,0.63},
          anchorcolor = [rgb]{0,0.46,0.63},
          citecolor = blue,
          filecolor = [rgb]{0,0.46,0.63},
          pagecolor = [rgb]{0,0.46,0.63},
          urlcolor = [rgb]{0,0.46,0.63}
       }
    
    """
    }
    
HTML 도움말 컴파일
  1. 이제 명령 프롬프트를 열고 GeoServer 소스 디렉터리( doc/en/user )로 이동하여 다음을 실행합니다.:
    make html
    위 명령어는 doc\user\build\html 디렉터리에 HTML 페이지를 생성합니다.
PDF 도움말 컴파일
  1. 명령 프롬프트를 열고 GeoServer 소스 디렉터리( doc/en/user )로 이동하여 다음을 실행합니다.:
    make latex
    doc/en/user/build/latex 폴더에 *.tex를 포함한 파일들이 생성됩니다.
  2. 명령 프롬프트를 doc/en/user/build/latex 디렉터리로 이동한 후 다음을 실행합니다
    pdflatex [GeoServerProject].tex
    
    적절한 지시를 따라 계속 진행하고 문제가 없으면 GeoServerProject.pdf 파일이 같은 디렉터리에 생성될 것입니다.
    주석

    프로젝트의 이름에 따라 GeoServerProject 은 다를 수 있습니다. 간단히 .tex 확장자의 파일 이름을 디렉터리에서 확인 후 입력하면 됩니다.

더 나은 작업 환경을 위하여

도움말 작성은 reStructuredText(일반적으로 확장자가 *.rst)는 일반 텍스트 편집기에서 작업하면 됩니다.
생산성 향상을 위하여 Eclipse에서 ReST Editor 플러그인을 설치해 사용할 수 있습니다. 옵션의 Format on save 체크시 한글 길이 계산 문제가 있긴 하지만 오프 해 놓고 작업하면 됩니다.
Install Eclipse ReST Editor plugin
  1. Eclipse를 실행합니다.
  2. Help> Install new software를 실행 후 아래 사이트를 추가합니다. :
  3. ReST Editor plug-in을 선택하고 설치합니다. 자세한 내용은 http://resteditor.sourceforge.net/index.html를 참고하십시오.