HelpBook.osax

HelpBook.osax とは ?

任意のバンドル内の Help Book を ヘルプビューアへ登録、表示を行うスクリプティング機能追加です。

macOS では、アプリケーションなどでは、そのバンドル内の HTML で書かれたヘルプファイル(Help Book といいます)をヘルプビューアで表示させることができます。アプリケーションとそのヘルプファイルをひとまとめにして扱うことが できますので、非常にスマートな方法だと思います。

このスクリプティング機能追加は、AppleScript から次の様なことをできるようにします。

ヘルプビューアに Help Book を登録すると、ヘルプビューアの高度な検索機能やAppleScript の実行機能が使えるようになります。普通の HTML ファイルでヘルプを提供するより、使いやすい説明書を作れます。

必要なシステム

インストール

インストーラ Install HelpBook.pkg を実行すると、スクリプティング機能追加 HelpBook.osax は、

/Library/ScriptingAdditions/

もしくは、

ホームフォルダ/Library/ScriptingAdditions/

にインストールされます。

アプリケーションの Help Book を表示する

HelpBook.osax は任意のバンドル内の Help Book を表示させることができます。 例えば、アプリケーションを起動せずに、アプリケーションのヘルプを確認できます。

次のスクリプトは メール.app のヘルプをアプリケーションを起動せずに表示させます。

show helpbook "/Applications/Mail.app"

次の例は、リストから選択したアプリケーションのヘルプを表示させます。

show helpbook ¬
(choose application with title "Open a help book" as alias)

AppleScript アプレット/バンドルに Help Book をセットアップする

AppleScript アプリケーション(アプレットやスクリプトバンドル)に Help Book を含めて、

に表示させると、分かりやすいアプリケーションになると思います。

バンドルに Help Book を含める方法の詳細は、Apple のドキュメント(Apple Help Programming Guide)を参照してください。 ここでは、最低限のことを説明します。

Help Book バンドルを用意する

まずは、ヘルプビューアに表示させたい HTML ファイルを用意しましょう。 それを「index.html」とします。 Help Book そのものも独立したバンドルとして、構成されます。 バンドル名を「SampleAppletHelp」としましょう。 フォルダ「SampleAppletHelp」をつくり、以下のようにフォルダとファイルを配置します。

SampleAppletHelp Bundle

Resources フォルダの中に、Help Book の内容となる HTMLファイルを配置します。Contents フォルダ以下に Info.plist ファイルを配置します。

Info.plist は次のようは XML ファイルです。任意のテキストエディタで編集できますが、Xcode を使うのがオススメです。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>en_US</string>
	<key>CFBundleIdentifier</key>
	<string>net.script-factory.HelpBookOSAXSampleApplet.help</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundleName</key>>
	<string>SampleAppletHelp</string>
	<key>CFBundlePackageType</key>
	<string>BNDL</string>
	<key>CFBundleShortVersionString</key>
	<string>4.0</string>
	<key>CFBundleSignature</key>
	<string>hbwr</string>
	<key>CFBundleVersion</key>
	<string>4.0</string>
	<key>HPDBookAccessPath</key>
	<string>index.html</string>
	<key>HPDBookIndexPath</key>
	<string>search.helpindex</string>
	<key>HPDBookKBProduct</key>
	<string>SampleApplet</string>
	<key>HPDBookTitle</key>
	<string>SampleApplet Help</string>
	<key>HPDBookType</key>
	<string>3</string>
</dict>
</plist>

新しい Help Book を作成する時は、赤字のところを適当に変更する必要があります。 キー値の意味は次の通りになります。

キー 意味
CFBundleIdentifier Help Book バンドルの固有の ID
CFBundleName Help Book バンドルの名前。フォルダ名と同じにするのが良いでしょう。
HPDBookAccessPath Help Book のトップページになる HTML ファイルの Resources フォルダからの相対パス。
HPDBookIndexPath インデックスファイルの相対パス
HPDBookTitle Help Book のタイトル。ヘルプビューアのウインドウのタイトルに表示されます。

Info.plist ファイルが出来上がったら、インデックスファイルを作成します。 Resources フォルダをカレントディレクトリとしたターミナルで、次のコマンドを実行します。

hiutil -Cf search.helpindex ./

Resources フォルダ以下に 「search.helpindex」というファイルが生成されます。

Help Book バンドルを設定する

前項でつくった Help Book バンドルを AppleScript アプレットに設定します。

まずは、AppleScript アプレットを作りましょう。 次の AppleScript をアプリケーションとして保存します。 このスクリプトは、アプリケーション自身のバンドル内の Help Book を表示するスクリプトです。 show helpbook コマンドを、path to me を引数にして実行しています。

on run
set a_result to display alert "Choose a task" buttons {"Run", "Help"}
if button returned of a_result is "Help" then
show helpbook (path to me)
else
display alert "Finished a great task"
end if
end run

アプリケーションとして保存します。スクリプトバンドルとして保存しても同じです。

AppleScript アプレットのリソースに先ほど作成した、Help Book バンドルをコピーします。

 

次に、AppleScript アプレットの Info.plist を編集します。

  1. SampleApplet.app のパッケージの内容を表示させる。
  2. SampleApplet.app/Contents/Info.plist をテキストエディタで開く。
  3. 次のサンプルのように、以下のキー値を追加する。
    • CFBundleHelpBookFolder : Help Book バンドルのフォルダ名
    • CFBundleHelpBookName : Help Book バンドルの CFBundleIndentifier
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleHelpBookFolder</key>
	<string>SampleAppletHelp</string>
	<key>CFBundleHelpBookName</key>
	<string>net.script-factory.HelpBookOSAXSampleApplet.help</string>
	<key>CFBundleAllowMixedLocalizations</key>
	<true/>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleExecutable</key>
	<string>applet</string>
	<key>CFBundleIconFile</key>
	<string>applet</string>
	<key>CFBundleIdentifier</key>
	<string>com.apple.ScriptEditor.id.SampleApplet</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundleName</key>
	<string>SampleApplet</string>
	<key>CFBundlePackageType</key>
	<string>APPL</string>
	<key>CFBundleShortVersionString</key>
	<string>1.0</string>
	<key>CFBundleSignature</key>
	<string>aplt</string>
	<key>LSMinimumSystemVersionByArchitecture</key>
	<dict>
		<key>x86_64</key>
		<string>10.6</string>
	</dict>
	<key>LSRequiresCarbon</key>
	<true/>
	<key>WindowState</key>
	...
</dict>
</plist>

以上で、Help Book の設定は完了です。 アプレットを起動すると、次のようなダイアログが表示されます。

ここで、「Help」を押してください。次のようなヘルプビューアが表示されるはずです。

コマンドリファレンス

register helpbook

register helpbook [bundle_path] [recovering InfoPlist boolean]

bundle_path で指定されたバンドル内の Help Book をヘルプビューアに登録します。

recovering InfoPlist に ture をあたえると、Help Book の登録した場合、Info.plist の不十分だと考えて、Resources フォルダにある recover-Info.plist から復旧します。 スクリプトバンドル(.scptd)の Info.plist は、しばしばスクリプトエディタ/Script Debugger で保存すると、消去されることがあります。 Info.plist のバックアップを Resources フォルダに recover-Info.plist として用意しておくと、自動的に復旧することができます。

Parameters

Result

show helpbook

show helpbook [bundle_path] [recovering InfoPlist boolean]

bundle_path で指定されたバンドル内の Help Book をヘルプビューアに登録して、表示します。

Parameters

Result

更新履歴