前回は、XMLドキュメントコメントの書き方と、Sandcastleでリファレンスマニュアルのページ(HTML)を生成する仕組みを見てきました。今回は、そのHTMLからヘルプファイルを作成する手順について紹介します。

Sandcastleで出力できるヘルプの形式としては「HTML Help 1.x形式」「HTML Help 2.x形式」「Web形式」の3つがあります。といっても、Sandcastleにはヘルプファイルを生成するプログラムは含まれていません。そのため、ヘルプファイルを生成できるヘルプコンパイラを別途入手して、それをSandcastleから呼び出す必要があります。

ここでは、各ヘルプの形式と、それぞれの閲覧と生成に必要なプログラムについて見ていきます。

HTML Help 1.x形式(*.chm)

1997年に公開されたHTML Help 1.x形式(最新バージョンは1.4)は、複数のHTMLなどを1つのファイル(*.chm)にまとめて操作できるヘルプ形式です。Windowsプラットフォームであれば特別なソフトを必要とせずに、簡単に閲覧できるのが特徴です。

HTML Help1.x形式

HTML Help 1.x形式のヘルプを生成するには、HTML Help Workshopに含まれる「hhc.exe」が必要です。ビルドするコンピュータに「C:\Program Files\HTML Help Workshop」が存在しない場合は、HTML Help Workshopを、Microsoft Download Centerから入手してインストールしてください。

HTML Help 2.x形式(*.HxS)

2001年に公開されたHTML Help 2.x形式は、Visual StudioやOffice2007等で利用されているヘルプ形式です。 この形式のヘルプを閲覧するためには、HTML Help2.x名前空間への登録と、Microsoft Document Explorer(Visual Studioのヘルプビューア)が必要です。名前空間に登録せずに閲覧できるH2Viewerといったビューアや、名前空間への登録と閲覧の両方の機能を持つMicrosoft Namespace#2.0といったツールも存在します

HTML Help 2.x形式(Document Explorer)

ヘルプを生成するには、Visual Studio SDKに含まれる「hxcomp.exe」が必要です。Visual Studio SDKは無償で配布されていますが、導入する前提としてそのバージョンのVisual StudioのStandardエディション以上がインストールされている必要があります。 Visual Studio 2005 SDK Version4をインストールすると「C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Archive\HelpIntegration\」にhxcomp.exeが配置されます。その際に古いバージョンのSandcastleがインストールされ、ユーザ環境変数の「DXROOT」と「PATH」が設定されます。 Visual Studio 2008 SDK Version1の場合「C:\Program Files\Common Files\microsoft shared\Help 2.0 Compiler\」にhxcomp.exeが配置されます。2005同様に古いSandcastleがインストールされ、ユーザ環境変数の「PATH」が設定されます。 これらのインストールを行うとSandcastle関係のユーザ環境変数が設定されますので、これらを削除して元の「DXROOT」と「PATH」に戻しておくと良いでしょう。

Web形式(*.html)

HTMLとASP.NETによるWebサイト形式は、ブラウザさえあれば閲覧が可能です。Webサーバ側のドキュメントを更新すれば、個々の開発者がコピーやセットアップなどの作業を行う必要がないため、更新頻度が高いアセンブリでも低コストで最新の状態にて管理できます。

Webページ(Sandcastle Help File Builder ASP.NET版)

HTMLを表示するにはIIS(Webサーバ)が必要です。それ以外には取り立てて必要なものはありません。ASP.NET版の場合は、IISマネージャからweb.configが出力されたフォルダをサイトとして登録すれば、そのページを公開することができます。

AP Help形式

なお、VISTAで採用されている新しいヘルプ形式である「AP Help形式」と、その記述言語「Microsoft Assistance Markup Language (MAML)」については、現バージョンのSandcastleではサポートされていません。ただし、CodePlexのSandcastle Styles Projectにて、「Sandcastle MAML Guide」というドキュメントが公開されていますので、興味がある方は目を通して見るとよいでしょう。