Windows TIPS
［Scripting］
　 → Windows TIPS TOPへ
→ Windows TIPS全リストへ

WSHスクリプトの仕様書を生成する

→ 解説をスキップして操作方法を読む

山田祥寛
2004/07/17		 　
対象OS
Windows NT
Windows 2000
Windows XP
Windows Server 2003
■ WSHが標準で生成するヘルプ・メッセージは、必ずしも使い勝手がよいものではない。
■ WshDocスクリプトを利用することで、より一覧性に富んだHTML形式のヘルプ・ドキュメントを生成することができる。
　
解説

　Windows TIPS「WSHスクリプトでヘルプ・メッセージを表示する」でも紹介したように、「.wsf」ファイルでは、現在のWSH（Windows Scripting Hosts）スクリプトに対して指定可能な引数の名前、必須／任意の区別、データ型などをタグの形式で宣言することができる。これら引数の宣言は必ずしも必須ではないが、あらかじめ定義しておくことで、WSHが自動的にオンライン・ヘルプを生成してくれる。特に、不特定多数の人間に配布するようなスクリプトの場合には、別途マニュアルなどを用意しなくても済むというメリットもあるので、引数情報の宣言は強くお勧めしたい。

　しかしこのオンライン・ヘルプは、必ずしも使い勝手のよいものとはいえない。というのも、ヘルプを参照するには、コマンド・プロンプトから「ファイル名 /?」の形式で呼び出す必要があるからだ。スクリプトの利用方法を知るのに、いちいちコマンド・プロンプトからコマンドを入力しなければならないのはなかなか面倒でもあるし、スクリプト・ファイルの数が多くなってくれば、それぞれのスクリプトの利用方法をまとめて参照したいというニーズも出てくるだろう。

　そこで本稿では、複数のWSHスクリプトに含まれる引数情報（<runtime>要素）を読み込み、まとめて1つのHTMLファイルとして出力するスクリプトWshDoc.wsfを紹介する。HTMLファイルは、一般ユーザーが見やすい形式であり、「.wsf」ファイルを配布する際に合わせて添付すると親切だろう。コードのメンテナンスや機能追加などで変更が生じた場合でも、コード内の<runtime>要素を修正すれば、ドキュメントの再生成は容易なので、積極的に活用してほしい。

wshdoc.wsfで作成したヘルプ・ドキュメント
wshdoc.wsfに対してドキュメント化したい「.wsf」ファイルを渡すと、該当ファイルに関するヘルプ・ドキュメントがHTML形式のファイルとして作成される。
　 スクリプト・ファイル名。
　 ヘルプ・ドキュメント。
　

 操作方法

手順1―テキスト・エディタでスクリプトのコードを入力する

　まずはテキスト・エディタ（メモ帳でも何でもよい）を開き、以下のコードを入力してwshdoc.wsfというファイルを作成する。ただし引用符（'）で始まる行はコードの意味を解説するためのコメント部分なので、省略してもよい。

※ファイルwshdoc.wsf

<?xml version="1.0" encoding="Shift_JIS" standalone="yes" ?>
<package>
  <job id="WshDoc">
  <?job error="true" debug="true" ?>
  <object id="objFs" progid="Scripting.FileSystemObject" />
  <object id="objXml" progid="Msxml2.DOMDocument.4.0" />
  <script language="VBScript">
  <![CDATA[
  ' ヘルプドキュメントの出力先として、output.htmlを生成する
  Set objOut=objFs.CreateTextFile("C:\output.html",True)
  objOut.WriteLine("<html>")
  objOut.WriteLine("<head>")
  objOut.WriteLine("<title>Windows Scripting Hostsドキュメント</title>")
  objOut.WriteLine("</head>")
  objOut.WriteLine("<body>")
  objOut.WriteLine("<h1>Windows Scripting Hostsドキュメント</h1>")
  objOut.WriteLine("<table cellspacing='0' cellpadding='4' border='1' style='background-color:White;border-color:#CC9966;border-width:1px;'>")
  ' WshDoc.wsfに対して渡された一連のWSHスクリプト（ファイルパス）を取得
  Set objArgs=WScript.Arguments
  ' 取得したWSHスクリプトを順に読み込み、引数情報を元にドキュメントを生成
  For i=0 To objArgs.Count-1
    objXml.async=False
    objXml.Load(objArgs(i))
    ' WSHスクリプトに含まれる<description>、<example>、<named>、<unnamed>、<usage>要素を取得（各要素の意味については、別稿「WSHスクリプトでヘルプ・メッセージを表示する」を参照いただきたい）。
    Set descript=objXml.selectSingleNode("//description")
    Set example=objXml.selectSingleNode("//example")
    Set named=objXml.selectNodes("//named")
    Set unnamed=objXml.selectNodes("//unnamed")
    Set usage=objXml.selectSingleNode("//usage")
    ' ファイル名、概要、使用例などの情報を出力
    objOut.WriteLine("<tr>")
    objOut.WriteLine("<th valign='top' align='left'>" & objFs.GetFileName(objArgs(i)) & "</th>")
    objOut.WriteLine("<td valign='top'>")
    objOut.WriteLine("<dl><dt><b> " & descript.Text & "</b></dt>")
    objOut.WriteLine("<dd>")
    objOut.WriteLine("使用例） " & example.Text & "<p />")
    ' <named>要素（名前付き引数）に含まれる情報を順番に出力
    For j=0 To named.Length-1
      Set tmp=named.item(j)
      objOut.WriteLine(tmp.getAttribute("name") & " -> ")
      ' required属性がTrueの場合には、引数が必須であることを意味する
      If tmp.getAttribute("required")="True" Then
        objOut.WriteLine("必須。")
      End If
      objOut.WriteLine(tmp.getAttribute("helpstring"))
      ' type属性がNullである場合にはデフォルト値として「（simple）」を、そうでない場合には指定された値を出力
      If IsNull(tmp.getAttribute("type")) Then
        objOut.WriteLine("（simple）")
      Else
        objOut.WriteLine("（" & tmp.getAttribute("type") & "）")
      End If
      objOut.WriteLine("<br />")
    Next
    ' <unnamed>要素（名前なし引数）に含まれる情報を順番に出力
    For j=0 To unnamed.Length-1
      Set tmp=unnamed.item(j)
      ' 名前なし引数を出力する場合には、ドキュメント上、名前付き引数と区別するために名前の後ろに「*」を付加
      objOut.WriteLine(tmp.getAttribute("name") & "* -> ")
      ' required属性がTrueの場合には、引数が必須であることを意味する
      If tmp.getAttribute("required")="True" Then
        objOut.WriteLine("必須。")
      End If
      ' many属性がTrueである場合には、引数を複数個指定できることを意味する
      If tmp.getAttribute("many")="True" Then
        objOut.WriteLine("複数回指定可。")
      End If
      objOut.WriteLine(tmp.getAttribute("helpstring"))
      objOut.WriteLine("<br />")
    Next
    objOut.WriteLine("</dd></dl>")
    objOut.WriteLine("</dl>")
    objOut.WriteLine("</td>")
    objOut.WriteLine("</tr>")
  Next
  objOut.WriteLine("</table></body></html>")
  objOut.Close
  ]]>
  </script>
  </job>
</package>
  • サンプル・ファイルのダウンロード
    （注：サンプルwshdoc.wsfを実行するには、上のサンプル・ファイルを右クリックしてwshdoc.wsfというファイル名で保存する）

　WSHの実行ファイルは拡張子「.wsf」とする必要がある。ファイル名自体は何でもよいが、ここでは「wshdoc.wsf」としておく。

手順2―WSHのコードを実行する

　wshdoc.wsfを実行するには、ドキュメント化の対象となる「.wsf」ファイル（群）をWshDoc.wsfのアイコンにドラッグ＆ドロップするだけでよい。その際、対象となる「.wsf」ファイルには必ずドキュメントの仕様を示した<runtime>要素が含まれている必要があるので、注意すること。

　テスト用としてconvert.wsf、mail.wsfを用意したので（これらは、ヘルプ・テキストのみを含むダミーのスクリプト・ファイル）、これらを使ってwshdoc.wsfの動作を確認していただきたい。

  • サンプル・ファイル：convert.wsf／mail.wsfをダウンロードするには、ファイル名を右クリックして、保存する。

　.wsfファイルをドラッグ＆ドロップすると、c:\にoutput.htmlというファイルが作成される。これをInternet Explorerなどで開けば冒頭のようなHTMLドキュメントになっているはずだ。なお本サンプルでは、コード簡素化のために、1ファイル中に複数のジョブが存在するケースや、<usage>要素には未対応であるが、修正はさほどに難しいことではないので、必要に応じて適宜修正して活用していただきたい。End of Article

この記事と関連性の高い別の記事

このリストは、デジタルアドバンテージが開発した自動関連記事探索システム Jigsaw（ジグソー） により自動抽出したものです。

generated byJigsaw
「Windows TIPS」


Windows Server Insider フォーラム 新着記事
＠ITメールマガジン　新着情報やスタッフのコラムがメールで届きます（無料）

注目のテーマ

Windows Server Insider 記事ランキング

本日 月間
＠IT