ふにゃるんv2

もとは、http://d.hatena.ne.jp/Wacky/

2007/9月版のSandcastle Help File Builderのちょっとしたテクニック

.NET

ネットを探索していると、以前書いた以下の記事を参照して頂いている方が居られるようで、役に立っていると思うと非常に嬉しいです。


で、先日 新しいバージョンの Sandcastleがリリースされたようで、それに合わせて Sandcastle Help File Builderもバージョンアップされています。

まずは、Sandcastle 2007/9版の特徴から

2007/9版のSandcastleですが、"CHMBuilder"ってツールが追加されたのが、大きな目玉のようです。
どんなファイルが作られるかは、インストールディレクトリの下に、Examples/sandcastleフォルダが出来ているので簡単に確認する事ができます。


ところで、このサンプルなんですが、ビルドに時間のかかる設定になっているらしく、時間計測した所、以下の感じでした。

  • CPU：Pentium4 2.6GHz
  • ビルド時間：21分

正直言いまして、チューニングする気がないなら、Sandcastle Help File Builderを使った方がいいです。
同じソースを使って、Sandcastle Help File Builderの初期設定でビルドした所、以下の時間でした。

  • ビルド時間：3分

英語だめぽな私は、先人のおこぼれにあずかる事に決めました。(XML/XSLの設定の莫大さにも圧倒されたし…)

次に、Sandcastle Help File Builder Ver.1.6.0.0

Sandcastle Help File Builder Ver.1.6.0.0では、2007/9版のSandcastleに対応しています。

適当に画面をいじっていると、投稿されたオマケ機能を搭載していたりしているようで、高機能さに拍車がかかっているようです。
とりあえず、自分で調べてわかった点のみ、Tips形式で以下に紹介します。

Tips1：PresentationStyleは、"vs2005"にした方がいい

自分の環境だけかも知れませんが、以下の条件でビルド中にエラーが発生しました。

  • PresentationStyle: prototype
  • コンストラクタに複数パターンを定義

他に、"hana"というのがあるんですが、こっちは一部アイコンが化けました。Ouch!!

Tips2: Languageに、"日本語"を表示させる方法

通常状態では、Languageには、以下の言語しか選択肢に出てきません。おーまいがっ！
SHFB2
SHFB2 posted by (C)wacky

しかし、以下のように"C:\Program Files\EWSoftware\Sandcastle Help File Builder\SharedContent"フォルダに、"SharedBuilderContent_ja-JP.xml"ファイルを作ってやるだけで、"日本語"が選択肢に出てくるようになります。
SHFB3
SHFB3 posted by (C)wacky

上のようにするだけで、はい、以下の通り。
SHFB4
SHFB4 posted by (C)wacky

適当感ありまくりですが、HTML Help 1.0形式の設定ファイル(.hhk)に ちゃんと反映されるのを確認しています。(Tips3参照)

Tips3: 複数のネームスペースを扱うなら、RootNamespaceContainerをTrueにしましょう

複数のネームスペースを扱う場合、RootNamespaceContainerをTrueにした方が、目次の見栄えがよくなります。

以下がFalseの場合。
SHFB5
SHFB5 posted by (C)wacky
以下がTrueの場合。
SHFB1
SHFB1 posted by (C)wacky

ちなみに、以下のように設定します。(余談ですが、RootNamespaceTitleに日本語を付けると、Languageを"日本語"にしていないと文字化けします)
SHFB6
SHFB6 posted by (C)wacky

Tips4: ビルドを自動化したい場合は、"SandcastleBuilderConsole.exe"コマンドを使いましょう

バッチファイルなどで、ヘルプファイルを自動作成したい場合は、"SandcastleBuilderConsole.exe"コマンドを使うといいでしょう。
例えば、以下のように記述します。

time /T > t.txt
"C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe" "test.shfb"
time /T >> t.txt

Tips5: ネームスペース全体のsummaryは、どこで設定するか？

↓この腹立たしいメッセージを取り除くには、どうすればいいか？
SHFB7
SHFB7 posted by (C)wacky

実は簡単で、右上の"Namespaces"ボタンをクリックし、上のペインで編集したいネームスペースを選択し、下のペインに書き込みます。
SHFB8
SHFB8 posted by (C)wacky

上のように設定すると、ちゃんと腹立たしいメッセージが消えうせます。
SHFB9
SHFB9 posted by (C)wacky

最後に

個人的に気になっているのが、Visual Studio 2008にSandcastleは標準搭載されるのかどうか？って事です。
XMLドキュメントコメントだけじゃぁ、物足りないんですよねぇ。