« Sandcastle を使用したドキュメント作成(1) | トップページ | 「ファイルを開く」「名前を付けて保存」ダイアログのコントロールID »

2010年11月 3日 (水)

Sandcastle を使用したドキュメント作成(2)

Sandcastle を使用したドキュメント作成(1)の続きです。

まずはお詫びから。前回使用した bnote の「Sandcastleでドキュメントを作成する」 からダウンロードしたバッチファイルですが、オリジナルである %DXROOT%\Examples\sandcastle\build_Sandcastle.bat を多少手直ししたものと思っていたのですが、結構違いました。Sandcastle のバージョン差異によるものでしょうか。とにかく、本来と動きと違うことが判明しました。オリジナルの方をそのまま動かしても、ヘルプの文字化けは発生するのですが、XMLコメントの内容が反映されない点は、解決しましたので報告します。

この回の記事は全面書き直しと記事アップロードの遅延となってしまいました。申し訳ありません。また、前回記事もこれに伴い、これから修正を入れる予定です。

では、本題に入りたいと思いますが、まずは記事修正に伴ない、バッチファイルの実行方法から、説明します。

オリジナルのバッチファイル %DXROOT%\Examples\sandcastle\build_Sandcastle.bat をドキュメントを作成したいアセンブリファイルとXMLファイルがあるフォルダにコピーします。
そして、コマンド プロンプトから、

build_Sandcastle.bat prototype CurrencyEdit

といった感じで実行すると、ドキュメントが生成されます。第1パラメータは、prototype / vs2005 / hana のうちどれかを指定します。これは作成されるヘルプの種類になります。第2パラメータは、アセンブリの名前です。
しかし、このまま実行すると、前回のローカライズを行っていれば、ヘルプ本文は日本語で表示される筈ですが、目次欄の各トピックは文字化けしています。

これは、build_Sandcastle.bat の中にもローカライズする部分があるからです。バッチファイル中の最後の方にある

ChmBuilder.exe /project:%2 /html:Output\html /lcid:1033 /toc:Toc.xml /out:Chm

DBCSFix.exe /d:Chm /l:1033 

の部分を、

ChmBuilder.exe /project:%2 /html:Output\html /lcid:1041 /toc:Toc.xml /out:Chm

DBCSFix.exe /d:Chm /l:1041 

と書き換えます。これで再実行すると、文字化けは解決します。

とりあえず、日本語ドキュメントを正しく生成できる様にはなりましたが、build_Sandcastle.bat は、もう少し修正したいと思います。というのは、最初の方で、環境変数 Path に、追加を行っています。複数回、このバッチを実行すると、その度に Path に同じフォルダを追加して、大きくなっていきます。これを防止するため、

REM ********** Set path for .net framework2.0, sandcastle,hhc,hxcomp****************************

set PATH=%windir%\Microsoft.NET\Framework\v2.0.50727;%DXROOT%\ProductionTools;%PATH%

の部分を、

REM ********** Set path for .net framework2.0, sandcastle,hhc,hxcomp****************************

set SAVEPATH=%PATH%
setlocal
set PATH=%windir%\Microsoft.NET\Framework\v2.0.50727;%DXROOT%\ProductionTools;%PATH%

に修正し、更に最終行に、

:End
set Path=%SAVEPATH%
set SAVEPATH=
endlocal

を追加します。要するに、バッチ実行中だけ追加パスを有効にします。(12/25:MASHERさんの御指摘により、setlocal/endlocalの記述に変更)

まだ気になる点はあるのですが、ひとまずここで一区切りしたいと思います。では、コマンドラインからの利用を前提にした環境設定上の注意をまとめてます。

  1. Sandcastle インストール後、設定された環境変数 DXROOT の最後の"\"を除去する。
  2. 日本語ローカライズの設定を行なう。このローカライズには、前回紹介した、 TimberLandChapel さんのブログの「Sandcastle January 2008 のローカライズ」からのダウンロードして、中の説明に従ってローカライズするのが良いと思います。
  3. build_Sandcastle.bat を上記の様に、書き換えたものを使用する。

なお、前回最新版(Version 2.6.1062.1)に、TimberLandChapel さんの日本語ローカライズが対応できるか不明としてましたが、そのままでは対応できそうにないです。オリジナルのファイルの中身が書き換わっています。今のところ、各ファイル個別に、対応していくしかなさそうです。

Sandcastle については、まだいろいろ研究部分はありそうなのですが、これでひとます終了します。追加情報については、別途記事にしたいと思います。

« Sandcastle を使用したドキュメント作成(1) | トップページ | 「ファイルを開く」「名前を付けて保存」ダイアログのコントロールID »

C#研究」カテゴリの記事

コメント

お邪魔します。
「バッチ実行中だけ追加パスを有効に」のくだりですが、

SETLOCAL
SET PATH=%windir%\Microsoft.NET\Framework\v2.0.50727;%DXROOT%\ProductionTools;%PATH%
...
ENDLOCAL

でOKだと思いますよ。

ご参考まで(^^)/

おおお、SETLOCALですか、知りませんでした。ん、どっかで見たような気もするけど...
基本的にコマンド系はMS-DOSの頃の知識で止まってたので、勉強になりました。

NTだと昔から存在していた様ですね。コマンドの性格上、多分Windows9X系は動作しないだろうけど、Sandcastle で使用する分には関係ないので、これ使う方がいいですね。

御指摘有り難うございました。

この記事へのコメントは終了しました。

トラックバック


この記事へのトラックバック一覧です: Sandcastle を使用したドキュメント作成(2):

« Sandcastle を使用したドキュメント作成(1) | トップページ | 「ファイルを開く」「名前を付けて保存」ダイアログのコントロールID »