PYRASIS.COM: 윈도우 프로젝트 필수 유틸리티 12장

책 또는 웹사이트의 내용을 복제하여 다른 곳에 게시하는 것을 금지합니다.
책 또는 웹사이트의 내용을 발췌, 요약하여 강의 자료, 발표 자료, 블로그 포스팅 등으로 만드는 것을 금지합니다.

12장 문서화

이재홍 http://www.pyrasis.com 2007.10.27 ~ 2008.04.20

Trac Wiki

Trac에는 위키 시스템이 포함되어 있습니다. 위키는 하나의 문서를 온라인상에서 여러 사람이 수정할 수 있도록 구현한 것입니다. 내용을 지우거나 덮어쓰더라도 이전 내용은 계속 저장되는 것이 특징입니다. 버전 관리 시스템과 비슷한 특성을 가지고 있습니다. 위키는 모든 내용을 일반 텍스트로 저장하지만, 위키 고유의 문법을 이용해서 글자 크기, 표, 그림, 소스코드, 링크 등을 넣을 수 있습니다.

지금까지 위키는 Trac 처럼 통합 환경이 아닌 단독 설치 형태로 많이 사용되어 왔습니다. http://c2.com/cgi/wiki에서 사용되고 있는 MoinMoin과 http://www.wikipedia.org에서 사용되고 있는 MediaWiki가 유명합니다. 이것 말고도 위키 시스템의 종류는 상당히 많으며, 국내에서는 MoniWiki(http://kldp.net/projects/moniwiki)를 많이 사용합니다. MoniWiki는 필자의 웹사이트인 http://www.pyrasis.com에서도 사용되고 있습니다. 위키 시스템의 종류가 상당히 많기 때문에 문법도 조금씩 차이가 나지만 대부분 큰 틀은 동일합니다. Trac 위키도 MoinMoin과 동일한 문법을 지원하고 있으며, Trac에 특화된 문법이 몇개 있습니다.

Trac 위키는 기술적인 메모, 소스코드 조각, 함수 사용 방법 설명, 완전한 스펙 또는 메뉴얼로 가기전의 임시 작업공간으로 적당합니다.

새 위키 페이지 만드는 방법

새 페이지를 만드는 방법은 매우 간단합니다. Trac 위키의 주소가 http://192.168.1.100/trac/example/wiki 라면 http://192.168.1.100/trac/example/wiki/NewPage 처럼 wiki/ 뒤에 만들고 싶은 페이지 이름을 입력하고, 그대로 접속하면 됩니다.

그림 12-1 새 페이지 만드는 방법

만약 NewPage라는 위키 페이지가 있으면 NewPage의 내용이 표시될 것이고, 페이지가 없다면 Create this page 버튼이 나옵니다. 이 버튼을 누르면 위키 페이지의 내용을 작성하는 화면이 나옵니다.

그림 12-2 새 페이지 내용 입력 화면

이제 내용을 입력합니다. 아래에 버튼이 3개 있습니다. Preview Page는 미리 보기 버튼인데, 위키 페이지를 저장하기 전에 위키 문법이 적용된 화면을 보여줍니다. 위키 문법을 사용했을 때 어떻게 표시될지 궁금하다면 Preview Page 버튼을 활용하면 됩니다. Review Changes 버튼은 현재 작성(수정)한 내용과 이전 저장되어 있던 내용을 비교해서 보여줍니다. Preview Page와 마찬가지로 저장은 하지 않습니다. Submit changes 버튼은 작성(수정)한 내용을 실제로 저장합니다. Cancel 버튼은 작성(수정)한 내용을 버리고 Create this page 버튼이 있던 곳으로 되돌아갑니다.

위키 문법

이번에는 글자에 효과를 주는 방법을 알아보겠습니다. 위키 페이지를 만들고 아래와 같이 입력합니다.

* '''굵게'''
* ''기울임''
* '''''굵게 기울임'''''
* __밑줄__
* {{{고정폭}}} or `고정폭 `
* ~~취소선~~
* ^윗첨자^ 
*,,아래첨자,,

페이지를 저장하면 아래와 같이 표시될 것입니다.

그림 12-3 글자에 효과 주기

다음은 제목를 표시하는 방법입니다. 단계가 깊어질 때마다 =가 하나씩 늘어납니다. 이것은 HTML의 <h1>, <h2>, <h3>, <h4>에 해당합니다.

= 제목 =
== 제목 2 ==
=== 제목 3 ===
==== 제목 4 ====

그림 12-4 제목 표시 하기

위키 페이지에서는 줄바꿈이 일반 워드프로세스와 차이가 있습니다. 줄바꿈을 하되 바로 아래 글자를 표시하려면 [[BR]]을 사용해야 합니다. 두 번 줄바꿈을 하면 줄간격이 조금 떨어져서 표시됩니다.

줄바꿈[[BR]]
입니다.

줄바꿈

입니다.

그림 12-5 줄바꿈하기

이번에는 목록을 표시하는 방법입니다. *을 사용하는 방법과 영문, 숫자를 사용하는 방법이 있습니다. 들여쓰기를 할 수록 하위 목목이 됩니다. 주의할 점은 가장 처음 항목이라도 *이나 1. 앞에는 빈칸이 한 칸 들어가야 합니다. 하위 목록의 들여쓰기는 2칸씩 합니다.

* 항목 1
   * 항목 1.1
 * 항목 2

 1. 항목 1
   a. 항목 1.a
   a. 항목 1.b
      i. 항목 1.b.i
      i. 항목 1.b.ii
 1. 항목 2
중간에 다른 내용이 있을 때
3. 항목 3
1. 항목 4

1. 처럼 숫자로 목록을 표시 할 때 중간에 다른 내용이 있으면 목록이 끊어집니다. 이럴 때에는 3. 처럼 해당 목록의 순서를 지정해주면, 1. 2. 3.으로 연결됩니다. 1.로 하면 1. 부터 다시 시작하게 됩니다. 3. 뒤에는 다시 4. 5.으로 하지 않고 1.으로 해도 정상적으로 연결이 됩니다.

그림 12-6 항목 표시하기

용어를 정리할 때에는 다음과 같이 합니다. 주의할 점은 제목:: 앞에는 빈칸을 한칸 띄워야 하며 내용은 3칸을 띄웁니다.

Apache::
   Apache Software Foundation에서 제작한 오픈소스 웹 서버

IIS::
   Microsoft Windows에 포함된 웹 서버

그림 12-7 용어 정리하기

소스 코드를 표시하려면 다음과 같이 합니다. enscript가 설치되어 있고 설정이 되어 있다면 문법 강조가 되어 각 요소들이 컬러로 표시 될 것입니다. 소스 코드를 {{{ }}}로 둘러 싸면 됩니다. 주의할 점은 #!c와 같이 언어를 설정해줘야 합니다. #!python, #!cpp, #!perl, #!html, #!sql, #!java 등과 같이 설정해주면 됩니다.

{{{
#!c
#include <stdio.h>

int main()
{
    printf("Hello World\n");
}
}}}

그림 12-8 소스 코드 표시하기

이메일 스타일의 토론 형식도 표현할 수 있습니다. >를 하나씩 늘여나가는 방식입니다. 외국에서 많이 사용하는 스타일입니다.

>> 크리스마스가 내일모레입니다. 외롭지 않아요?
> 네. 정말 외로워요.
책이나 쓰세요!

그림 12-9 이메일 스타일의 토론 형식 표시하기

표를 그리는 것도 가능합니다. 표는 ||을 조합해서 만들 수 있습니다.

|| 표 || 1 || 2 || 3 ||
|| 그리기 || 4 || 5 || 6 ||

그림 12-10 표 그리기

위키의 특징은 여러 가지 스타일의 링크를 지원한다는 것입니다. 아래와 같이 NewPage를 그대로 적으면 해당 위키 페이지의 링크가 생성됩니다. 하지만 해당하는 페이지가 없을 때에는 물음표가 붙고 링크의 색이 연한 노란색으로 표시됩니다. 이것은 위키의 자동 링크 기능입니다. 하지만 그냥 단어를 적고 저장을 했는데 자동 링크 기능 때문에 링크가 생성되면 상당히 보기가 좋지 않습니다. 이럴 때에는 단어 앞에 !를 붙여주면 링크가 생성되지 않습니다. [ ] 대괄호를 이용하면 링크에 이름을 지정해 줄 수 있습니다.

NewPage HelloPage !HelloPage

 * http://www.pyrasis.com
 * [http://www.pyrasis.com PYRASIS.COM]
 * wiki:NewPage
 * [wiki:NewPage 새 페이지]

그림 12-11 링크 만들기

Trac 위키에서는 위키 페이지, URL뿐만 아니라 저장소의 파일, 티켓, 리비전 로그, 마일스톤, 체인지셋, 파일 비교 등의 링크도 만들 수 있습니다.

 * 티켓: #1 또는 ticket:1
 * 티켓의 답글: comment:ticket:1:2 
 * 리포트: {1} 또는 report:1
 * 체인지셋: r1, [1], changeset:1, [1/trunk], changeset:1/trunk
 * 리비전 로그: r1:3, [1:3], log:@1:3, log:trunk@1:3
 * 비교1: diff:@1:3, diff:tags/example-0.1/example.cpp//tags/example-0.2/example.cpp
 * 비교2: diff:trunk/example/example.cpp@3//trunk/example/example.cpp@5
 * 마일스톤: milestone:1.0
 * 첨부파일: attachment:ticket:1:hello.txt
 * 저장소의 파일: source:trunk/example/example.cpp
 * 특정 리비전의 파일: source:/trunk/example/example.cpp@5
 * 특정 리비전의 파일에서 특정 행번호의 내용 표시: source:/trunk/example/example.cpp@5#L10

그림 12-12 저장소의 파일, 티켓, 리비전 로그, 마일스톤, 체인지셋, 파일 비교 링크 만들기

그림을 표시할 수도 있습니다. 그림을 표시하려면 먼저 Attach file 버튼으로 그림 파일을 위키 페이지에 첨부 파일로 올려 주어야 합니다.

[[Image(flower.jpg)]]

그림 12-13 그림 표시하기

내용과 내용 사이를 구분 하기 위한 가로 선도 표시할 수 있습니다.

---

그림 12-14 가로선 넣기

Doxygen으로 소스 코드 문서화 하기

Doxygen은 소스 코드를 문서화 하는 도구입니다. Doxygen으로 만든 문서는 최종 사용자가 보는 것이 아닌, 개발자가 보는 것입니다. 즉 라이브러리를 만들고 그 라이브러리의 사용법을 문서화 하는 것입니다. Doxygen은 소스 코드를 읽어, 함수, 구조체, 클래스별로 정리를 하게 됩니다. 그리고 해당 함수에 대한 설명은 함수의 주석 부분을 가져와서 사용합니다. 그렇기 때문에 주석을 작성할 때 Doxygen이 인식 할 수 있는 형태로 작성해야 합니다.

Doxygen 설치

doxygen-1.5.4-setup.exe는 다음 URL에서 받을 수 있으며, 부록 CD에도 포함되어 있습니다.

다운로드 주소 : http://www.stack.nl/~dimitri/doxygen
부록 CD 경로 : Applications/Doxygen

doxygen-1.5.4-setup.exe를 실행합니다. Doxygen 설치 마법사가 실행되면 Next를 눌러 넘어갑니다.

그림 12-15 Doxygen 설치 마법사
라이센스에 관한 설명이 나오면 I accept the agreement 선택하고 Next를 누릅니다.

그림 12-16 라이센스 동의
Doxygen 설치 디렉터리 지정 화면이 나타납니다. 기본설정대로 설치합니다.

그림 12-17 Doxygen 설치 디렉터리 지정 화면
구성 요소를 선택하는 화면입니다. 기본 설정인 Full Installation으로 설치합니다.

그림 12-18 Doxygen 구성 요소 선택 화면
시작 프로그램에 등록할 이름을 지정하는 화면입니다. 기본설정대로 설치합니다.

그림 12-19 시작 프로그램 등록 설정
Install을 눌러 설치를 시작합니다.

그림 12-20 Doxygen 설치 준비
파일 복사 화면이 나타납니다.

그림 12-21 Doxygen 파일 복사 화면
릴리스 노트입니다. Next를 눌러 넘어갑니다.

그림 12-22 Doxygen 릴리스 노트
Finish를 눌러 설치를 완료합니다.

그림 12-23 Doxygen 설치 완료

Graphviz 설치

Doxygen에서는 함수의 호출 상황과 헤더 파일의 포함 관계를 그림 파일로 표시해 줄 수 있습니다. 이 기능을 사용하려면 graphviz-2.16.1.exe를 설치해야 합니다.

다운로드 주소 : http://www.graphviz.org/Download_windows.php
부록 CD 경로 : Applications/Doxygen

graphviz-2.16.1.exe를 실행한 다음 Install을 눌러 설치를 시작합니다.

그림 12-24 Graphviz 설치 시작
디렉터리 생성 경고 메시지가 나타나면 Yes를 누릅니다.

그림 12-25 디렉터리 생성 경고 메시지
Graphviz 파일 복사 화면이 나타납니다.

그림 12-26 Graphviz 파일 복사 화면
Close를 눌러 설치를 완료합니다.

그림 12-27 Graphviz 설치 완료

Doxygen으로 문서화하기

문서화 할 소스 코드는 지금까지 사용해왔던 example 프로젝트를 사용하겠습니다. C:\build\example\example\example.cpp 파일을 열고 다음과 같이 수정합니다. sum 함수는 Doxygen에서 인식 할 수 있도록 주석을 작성한 것입니다.

C:\build\example\example\example.cpp

// example.cpp : Defines the entry point for the console application.
//

#include "stdafx.h"

/**
  @brief   덧셈 함수
  @return  op1과 op2의 합
 */
int sum(
    int op1,    /**< 더할 숫자 1 */
    int op2     /**< 더할 숫자 2 */
    )
{
    return op1 + op2;
}

int _tmain(int argc, _TCHAR* argv[])
{
    int *hello = NULL;

    *hello = 10;

    sum(2, 5);

    return 0;
}

Doxygen에서 인식할 수 있는 주석은 /** 으로 시작합니다. 그리고 @brief는 함수에 대한 간단한 설명, @return은 리턴 값에 대한 설명입니다. 각 매개변수 마다 /**< */을 이용하여 설명을 적어줍니다.

시작 → 모든 프로그램 → doxygen → Doxywizard을 실행합니다. 그리고 Wizard... 버튼을 누릅니다.

그림 12-28 Doxygen 실행 화면
Wizard 버튼을 누르면 다음과 같은 창이 나옵니다. Project name:에는 example을 입력합니다. 그리고 Source code directory:에는 Select... 버튼을 눌러 C:\build\example 디렉터리를 선택합니다. 디렉터리를 선택하면 C:/build/example 형태로 입력됩니다. Destination directory:은 완성된 문서가 생성될 디렉터리를 지정하는 부분입니다. C:/build/example/doc를 입력합니다.

그림 12-29 Project 탭
Mode 탭으로 이동합니다. All entities를 선택하고 Include cross-referenced source code in the output에 체크합니다. 언어는 C++을 사용하고 있으므로 Optimize for C++ output을 선택합니다.

그림 12-30 Mode 탭
Output 탭으로 이동합니다. HTML에 체크하고 LaTeX는 체크를 해제합니다.

그림 12-31 Output 탭
Diagrams 탭으로 이동합니다. 기본적으로 Use dot tool from the GraphViz package to generate가 선택되어 있을 것입니다. 맨 마지막의 Call graphs를 체크합니다. 그리고 OK 버튼을 눌러 설정을 완료합니다.

그림 12-32 Diagrams 탭
이번에는 Expert... 버튼을 누릅니다.

그림 12-33 Doxygen GUI frontend
OUTPUT_LANGUAGE는 어떤 언어로 문서화를 할지 설정하는 부분입니다. 여기서는 Korean으로 선택합니다. 이 부분은 Korea으로 선택하면 생성 결과물의 메뉴도 한글로 생성됩니다. [그림 12-42]를 보면 "메인 페이지", "파일들" 같은 메뉴가 한글로 표시되는 것을 볼 수 있습니다.

그림 12-34 Project 탭
Input 탭으로 이동합니다. INPUT_ENCODING은 처리할 소스 코드가 어떤 인코딩으로 되어 있는지 알려주는 부분입니다. 인코딩에 따라 CP949, EUC-KR, UTF-8 등을 선택할 수 있습니다. 여기서는 CP949를 입력합니다. 만약 소스 코드를 UTF-8로 인코딩으로 작성했다면 때에는 UTF-8을 입력합니다.

그림 12-35 Input 탭
Dot 탭으로 이동합니다. DOT_PATH에는 Folder... 버튼을 눌러(Folder... 버튼이 보이지 않을 때에는 창의 크기를 오른쪽으로 조금 늘리면 보입니다.) C:\Program Files\Graphviz2.16\bin을 선택합니다. OK를 눌러 설정을 저장합니다.

그림 12-36 Dot 탭
Save... 버튼을 눌러 설정 파일을 저장합니다.

그림 12-37 Doxygen GUI frontend
Doxyfile 파일을 C:\build\example에 저장합니다.

그림 12-38 Doxyfile 저장 화면
Working directory:에는 Select 버튼을 눌러 C:\build\example을 지정합니다. 그리고 Start 버튼을 누르면 문서를 생성합니다.

그림 12-39 문서 생성 화면
이제 C:\Build\example\doc\html 디렉터리로 이동합니다. html 파일과 여러가지 파일들이 만들어져 있는 것을 볼 수 있습니다. index.html 파일을 더블클릭하여 웹 브라우저로 열어봅니다.

그림 12-40 생성된 문서 파일
생성된 문서가 보입니다. 상단의 파일들 탭을 누릅니다.

그림 12-41 index.html의 내용
파일 목록이 표시되는데 example.cpp를 누릅니다.

그림 12-42 프로젝트의 파일 목록
example.cpp의 헤더 파일 포함 관계를 표시해주고 있습니다. example.cpp는 stdafx.h를 포함하고 있고 stdafx.h는 stdio.h와 tchar.h를 포함하고 있다는 것을 알 수 있습니다.

그림 12-43 example.cpp에 대한 헤더 파일 의존 그래프
스크롤을 하여 약간 밑으로 내려오면 함수의 목록과 main 함수 부분을 볼 수 있습니다. main 함수에서 sum 함수를 호출했다는 것을 그림으로 알 수 있습니다.

그림 12-44 함수 호출 그래프
조금 더 내려오면 sum 함수 부분을 볼 수 있습니다. @brief로 설정한 "덧셈 함수"는 맨 위에 표시되고 있고, @return으로 설정한 "op1과 op2의 합"이 반환값 부분에 표시되고 있습니다. 각 매개변수 마다 /**< */으로 설정한 "더할 숫자 1", "더할 숫자 2"는 매개변수 부분에 표시되는 것을 볼 수 있습니다.

그림 12-45 소스 코드에 미리 설정해둔 sum 함수의 주석

기타 doxygen용 주석 작성 방식

다음은 Doxygen에서 인식할 수 있는 주석들의 형태입니다. 아래와 같이 설명을 주석 형태로 작성하면 Doxygen에서 문서로 생성합니다.

/*!
 * 설명
 */

/*!
 설명
*/

///
/// 설명
///

//!
//! 설명
//!

/***********************************************
 * 설명
 ***********************************************/

/////////////////////////////////////////////////
/// 설명
/////////////////////////////////////////////////

/*! \brief 간단한 설명.
 *         설명 계속...
 *
 *  자세한 설명.
 */

/** 간단한 설명은 마침표 까지. 여기서 부터 자세한
 *  설명.
 */

/// 간단한 설명은 마침표 까지. 여기서 부터 자세한
/// 설명.

/// 간단한 설명.
/** 자세한 설명. */

//! 간단한 설명.

//! 자세한 설명은 여기서 부터
//! 시작

/*! \fn int read(int fd,char *buf,size_t count)
    \brief 파일 디스크립터로부터 파일을 읽는 함수.
    \param fd 읽을 파일 디스크립터.
    \param buf 읽기 버퍼.
    \param count 읽은 크기.
*/
int read(int fd,char *buf,size_t count);

주석에 대한 더 자세한 내용은 http://www.stack.nl/~dimitri/doxygen/docblocks.html에서 확인 할 수 있습니다.

윈도우 도움말 파일(CHM) 만들기

이제 HTML 파일이 아닌 윈도우 도움말 파일(CHM) 파일을 만들어보겠습니다. HTML로 문서를 생성하면 HTML 파일 뿐만 아니라 각종 이미지, CSS 파일들이 함께 있어 상당히 복잡합니다. 이것을 CHM 파일 하나로 만들면 매우 편리하게 문서를 배포할 수 있습니다.

HTML Help 파일 설치

htmlhelp.exe

다운로드 주소 : http://msdn2.microsoft.com/en-us/library/ms669985.aspx
부록 CD 경로 : Applications/Doxygen

libiconv-1.9.2-1.exe

다운로드 주소 : http://sourceforge.net/projects/gnuwin32
부록 CD 경로 : Applications/Doxygen

htmlhelp.exe를 실행합니다. 라이센스 동의화면이 나타나면 Yes를 누릅니다.

그림 12-46 라이센스 동의 화면
HTML Help Workshop을 설치할 것인지 뭍는 대화상자가 나타나면 예(Y)를 누릅니다.

그림 12-47 HTML Help Workshop 설치 시작
HTML Help Workshop을 설치할 디렉터리를 지정하는 화면입니다. 기본 설정대로 설치합니다.

그림 12-48 설치 디렉터리 지정 화면
예(Y)를 눌러 설치 디렉터리를 생성합니다.

그림 12-49 설치 디렉터리 생성 경고 메시지
설치가 완료되었습니다.

그림 12-50 설치 완료 메시지

libiconv-1.9.2-1.exe는 기본 설정대로 설치합니다.

index.chm 파일 생성

이제 환경 변수의 PATH에 C:\Program Files\GnuWin32\bin가 추가되어 있는지 반드시 확인합니다. 없다면 추가합니다. C:\Program Files\HTML Help Workshop에 hhc.cmd 라는 파일을 아래와 같은 내용으로 만듭니다.

C:\Program Files\HTML Help Workshop\hhc.cmd

iconv -f UTF-8 -t CP949 index.hhc > index.hhc.tmp
del index.hhc
rename index.hhc.tmp index.hhc
"C:\Program Files\HTML Help Workshop\hhc.exe" "%1"

시작 → 모든 프로그램 → doxygen → Doxywizard을 실행합니다. 이 창을 닫았다면 Load... 버튼을 눌러 C:\build\example\Doxyfile을 불러옵니다. 그리고 Wizard.. 버튼을 누르고 Output 탭으로 이동합니다. prepare for compressed HTML (.chm)을 선택하고 OK 버튼을 누릅니다.

그림 12-51 Output 탭
이번에는 Expert... 버튼을 누르고 HTML 탭으로 이동합니다. HHC_LOCATION에는 File... 버튼을 눌러 방금 만들었던 C:\Program Files\HTML Help Workshop\hhc.cmd를 지정합니다. 그리고 OK 버튼을 누릅니다. Save... 버튼을 눌러 C:\build\example에 Doxyfile을 저장합니다.

그림 12-52 HTML 탭
Start 버튼을 누르면 문서가 생성됩니다. Running html help compiler... 라는 문장이 보이면 CHM 파일이 만들어 진 것입니다.

그림 12-53 문서 생성
탐색기에서 C:\build\example\doc\html으로 이동합니다. index.chm 파일이 생성되었습니다.

그림 12-54 index.chm 파일이 생성됨
index.chm 파일을 열어보면 도움말 형식으로 만들어진 문서를 확인할 수 있습니다. 내용은 HTML로 만들었던 문서와 동일합니다.

그림 12-55 index.chm 파일의 내용
CruiseControl.NET을 이용하여 자동으로 문서를 만드는 것도 가능합니다.

<project name="example-doc">
    <!-- 매일 20:00에 자동 빌드 하도록 설정 -->
    <triggers>
        <scheduleTrigger time="20:00" buildCondition="ForceBuild" name="Scheduled" />
    </triggers>

    <tasks>
        <!-- doxygen을 실행하여 소스 코드를 문서화 -->
        <exec>
            <executable>C:\Program Files\doxygen\bin\doxygen.exe</executable>
            <baseDirectory>C:\build</baseDirectory>
            <buildArgs>C:\build\example\Doxyfile</buildArgs>
        </exec>

        <!-- doxygen으로 생성된 html 파일을 C:\Releases 디렉터리 아래 문서 디렉터리(doc)로 복사 -->
        <buildpublisher>
            <sourceDir>C:\build\example\doc\html</sourceDir>
            <publishDir>C:\Releases\doc\example</publishDir>
            <useLabelSubDirectory>false</useLabelSubDirectory>
        </buildpublisher>
    </tasks>
</project>