※ 개요
Sandcastle은 비주얼스튜디오를 통해 또는 컴파일러를 통해 생성된 DLL과 코멘트파일인 XML을 사용하여 Help File을 만들게 된다. 따라서 별도의 소스 코드는 필요가 없다.
Sandcastle은 ProductionTools폴더에 있는 프로그램들의 실행 조합으로 결과물을 만들 수 있도록 되어 있다. 설치된 폴더에 있는 sample batch파일만으로도 사용법은 쉽게 알 수 있다.
여기서는 batch파일을 사용하는 방법이 아닌, 제공되는 GUI 툴을 이용하는 방법을 설명한다.
사실 나중에 사용해보면 알겠지만, GUI툴도 batch파일의 내용을 그대로 따르는 것을 알게 된다.
GUI툴은 Help File생성을 위한 프로젝트 파일을 쉽게 관리할 수 있도록 해주고, 그를 토대로 각종 명령어를 수행하여 결과물을 만들어주는 툴에 불과하다.
설치 폴더(C:\Program Files\Sandcastle)에 가면 아래와 같은 폴더들이 생성된다.
C:\Program Files\Sandcastle
Data
Example
Presentation
ProductionTools
ProductionTransforms
Schemas
자세한 설명은 sandcastle 사이트를 참조하도록 하자…(설명하기 귀찮다는...ㅋㅋㅋ)
-. Data : .NET Framework에 들어있는 클래스들에 대한 정보가 있다.
-. Example : 간단한 샘플과 GUI 툴이 들어있다.
-. Presentation : Help File을 생성하기 위해 필요한 요소(설정, 이미지, 파일 등)들이 들어있다.
-. ProductionTools : 각종 실행파일들이 모여있다.
-. ProductionTransforms, Schemas : 생성될 문서들에 대한 xsl, schema 파일들이 있다.
※ GUI 실행 및 화면 설명
C:\Program Files\Sandcastle\Examples\generic폴더에 가면 "SandcastleGui.exe"란 프로그램이 있다.
이 프로그램은 같은 폴더에 있는 각종 설정 파일을 사용하게 되는데, 그 중 "Generic.targets"파일에 Sandcastle 프로그램의 실행 설정값들이 저장된다.
[그림 1. 실행 초기화면] : 엄청난 복고풍인가? 개발자의 게으름인가?
-. Assembly And Comment Files
작성할 Assembly에 대한 정보를 모아 놓게 된다.
■ Assemblies : 작성할 대상의 DLL을 설정한다. 한 개의 DLL 또는 다수의 DLL, 폴더를 통째로 지정할 수 있다.
■ Comments : DLL 생성시 같이 생성되는 XML 코멘트 파일을 설정한다. 단수, 복수, 폴더를 통째로 지정할 수 있다.
Comments파일을 지정하지 않더라도 Help File은 생성할 수 있지만, 이 경우 Syntax 외에 중요한 정보들은 Help File에 나타나지 않는다.
■ Dependent Assemblies : 해당 DLL에서 참조하는 DLL들을 지정한다. 참조하는 DLL을 지정하지 않을 경우 Help File은 생성되지 않는다.
-. Options
■ Name : Sandcastle 프로젝트 명이자, 출력될 폴더 명이 된다.
generic.targets파일내 <BuildDir>항목을 변경하여 출력 폴더를 변경할 수 있다.
■ Presentation Style : Help File의 출력 타입을 설정한다. 기본값인 vs2005만 사용해도 될 듯. hana, vs2005, prototype 세 가지가 있으며, 출력시 각각의 폴더에 출력된다.
■ Language ID : 생성될 Help File의 언어를 설정한다. 한국어는 1042
■ Default Targets : 출력할
-. Log : Build버튼을 눌러 실행하면 모든 로그가 이 항목에 나타난다.
Build가 실패할 경우 로그를 통해 그 원인을 알 수 있다.
[그림 2. 실행 예]
Add 버튼을 통해 각 파일들을 추가하고, 하단의 Build버튼을 클릭만 하면 된다.
※ 생성물들
Build가 완료되면 지정된 폴더에 Name항목에 설정한 폴더가 생성된다.
기본적으로 생성물은 C:\Program Files\Sandcastle\Examples 폴더아래에 Name에 설정한 폴더명으로 생성이 되며, generic.targets파일의 BuildDir 항목을 수정하여 변경할 수 있다.
기본적으로 Sandcastle은 사용되는 모든 파일을 복사하여 사용하고, 원본 파일은 사용하지 않는다.
■ comments : 화면에서 지정한 코멘트파일(XML)이 이 폴더에 자동 복사되어 진다.
■ dll : Assemblies 에서 지정한 DLL과 Dependent Assemblies 지정한 참조 파일들이
이 폴더에 자동으로 복사되어진다.
■ hana, vs2005, prototype : Presentation Style에서 지정한 Style 폴더가 생성되고
최종 결과물(.chm파일)은 이 폴더 하위의 chm 폴더에 생성된다.
※ Presentation Style별 출력물의 차이
여기서는 chm파일만을 비교해보겠다. 실제 내용들은 모두 같지만 각 Style에 따라 출력물의 모양이
다소 다르게 나타난다. 비주얼스튜디오 사용자라면 vs2005스타일이 가장 친근할 것이다.
[그림 3. Presentation Style : Hana]
[그림 4. Presentation Style : Prototype]
[그림 5. Presentation Style : chm]
