カスタムドキュメンテーションの表示

概要

迈斯沃克^®製品で機能するツールボックスを作成する場合、それが数個の関数を含むだけであっても、カスタムドキュメンテーションを HTMLヘルプファイルの形式で含めることが可能です。ツールボックスのカスタムドキュメンテーションには、ツールボックスのヘルプをさらに使いやすくするために、図、スクリーンキャプチャ、方程式、書式設定などを含めることができます。

適切に表示するには、カスタムドキュメンテーションに以下のファイルが含まれていなければなりません。

HTMLヘルプファイル——これらのファイルには,カスタムドキュメンテーションの情報が含まれます。
info.xmlファイル——このファイルを使用して,MATLAB^®が HTMLヘルプファイルを検索して特定できます。
helptoc.xmlファイル— このファイルには、ヘルプブラウザーの[コンテンツ]ペインに表示されるドキュメンテーションの目次が含まれます。このファイルは,HTMLヘルプファイルを含むフォルダーに保存されていなければなりません。
検索データベース (オプション)——これらのファイルを使用すると,HTMLヘルプファイル内の検索が可能になります。

カスタムドキュメンテーションを表示するには、ヘルプブラウザーを開いてホームページに移動します。ホームページの下部にある[補助ソフトウェア]で,ツールボックスの名前をクリックします。ヘルプが現在のウィンドウに表示されます。

HTMLヘルプファイルの作成

HTMLヘルプファイルは,任意のテキストエディターまたはWebパブリッシュソフトウェアで作成できます。MATLABでヘルプファイルを作成するには,次の2つのうちいずれかの方法を使用します。

ライブスクリプト (*.mlx) を作成して HTMLにエクスポートします。詳細については、ライブスクリプトとライブ関数の共有を参照してください。
スクリプト(* 00)を作成してHTMLにパブリッシュします。詳細は,MATLABコードのパブリッシュと共有を参照してください。

すべての HTMLヘルプファイルを 1.つのフォルダー、たとえばツールボックスフォルダー内の超文本标记语言サブフォルダーに格納します。このフォルダーは次の場所になければなりません。

MATLAB検索パス上
matlabrootフォルダーの外
インストールされているハードウェアサポートパッケージのヘルプフォルダーの外

ドキュメンテーションセットには,一般的には以下のものが含まれます。

ロードマップページ(ドキュメンテーションを開いたときに最初に表示されるページ)
ツールボックスの使用方法を説明する例とトピック
関数やブロックのリファレンスページ

`info.xml`ファイルの作成

info.xmlファイルには、ドキュメンテーションの表示名など、カスタムドキュメンテーションの説明が含まれています。HTMLヘルプファイルとhelptoc.xmlファイルの格納場所も特定します。記述するツールボックスごとにinfo.xmlというファイルを作成します。

ツールボックスについて説明するinfo.xmlを作成するには,以下のテンプレートを利用できます。

R2016bMyToolboxtoolboxhtml

また,MATLABドキュメンテーションに含まれているテンプレートinfo_template.xmlを使用してinfo.xmlを作成することもできます。現在のフォルダー内でテンプレートファイルのコピーを作成して編集するには,コマンドウィンドウで以下のコードを実行します。

copyfile（完整文件（matlabroot、'help'、'techdoc'、'matlab_env'、…'examples'、'templates'、'info_template.xml'）、pwd）fileattrib（'info_template.xml'、'+w'）编辑（'info_template.xml'））

次の表では,info.xmlファイルの必須要素について説明します。

XMLタグ	説明	テンプレートの値	メモ:
`< matlabrelease >`	MATLABのリリース	`R2016b`	ヘルプファイルをいつ追加したかを示します。ブラウザーには表示されません。
	ツールボックスのタイトル	`我的工具箱`	ブラウザーの[コンテンツ]ペインに表示されるカスタムドキュメンテーションの名前。
`<类型>`	ツールボックス用のラベル	`工具箱`	入力値は、`matlab`、`工具箱`、`金宝app`、`模块库`、`links_targets`、`其他`です。
	[スタート]ボタンのアイコン (使用廃止)	なし	現在は使用されていませんが、MATLABで`info.xml`ファイルを解析するには要素が引き続き必要です。
	ヘルプファイルの位置	`超文本标记语言`	ツールボックス用の`helptoc.xml`およびHTMLヘルプファイルを含むサブフォルダーの名前。ヘルプの位置が`info.xml`ファイルの場所のサブフォルダーでない場合,`info.xml`ファイルを基準とした`help_location`の相対パスを指定します。複数のツールボックスのHTMLヘルプファイルを提供する場合,各`info.xml`内の`help_location`が別々のフォルダーでなければなりません。
	[コンテンツ]ペインに表示するアイコン	なし	MATLAB R2015a以降では無視されます。`info.xml`ファイル内にあってもエラーの原因にはなりませんが,必須ではありません。

著作権や連絡先情報などのコメントをinfo.xmlファイルに含めることもできます。コメントを作成するには,1行のテキストを<！--と-->で囲みます。

info.xmlファイルを作成する際は、次を確認する必要があります。

必要なすべての要素を含めること
エントリは前記の表と同じ順序であること
XML内のファイル名とフォルダー名が,大文字と小文字の区別も含めて,使用するファイル名とフォルダー名と完全に一致していること
info.xmlファイルがMATLAB検索パス上のフォルダー内にあること

メモ

info.xmlを含むフォルダーをパスに追加すると、MATLABはinfo.xmlファイルを解析してドキュメンテーションを表示します。info.xmlファイルを既にパス上にあるフォルダー内に作成した場合は,そのフォルダーをパスから除外してください。次に,MATLABがファイルを解析できるよう,そのフォルダーを再度追加します。追加するフォルダーは必ず“現在のフォルダーではない”ようにしてください。

`helptoc.xml`ファイルの作成

helptoc.xmlファイルは、補助ソフトウェアのブラウザーの[コンテンツ]ペインに表示されるヘルプファイルの階層を定義します。

helptoc.xmlファイルは、MATLABドキュメンテーションに含まれているテンプレートを使用して作成できます。現在のフォルダー内でテンプレートファイルhelptoc_template.xmlのコピーを作成して編集するには、コマンドウィンドウで以下のコードを実行します。

拷贝文件(fullfile (matlabroot,‘帮助’,‘techdoc’,‘matlab_env’,……“例子”、“模板”,“helptoc_template.xml”),pwd) fileattrib(‘helptoc_template.xml’,‘+ w)编辑(“helptoc_template.xml”)

helptoc.xmlファイルを、HTMLドキュメンテーションファイルが含まれているフォルダーに入れます。このフォルダーは,info.xmlファイル内でとして参照されなければなりません。

helptoc.xmlファイルの各< tocitem >エントリは、HTMLヘルプファイルのいずれかを参照します。helptoc.xmlファイル内の最初の< tocitem >エントリは、ドキュメンテーションのランディングページとして機能します。

最上位の<目录>要素内で,入れ子になった< tocitem >要素で目次の構造を定義します。各< tocitem >要素にはファイル名を示す目标属性があります。ファイル名とパス名では大文字と小文字が区別されます。

helptoc.xmlファイルを作成する際は、次を確認する必要があります。

helptoc.xmlファイルの位置が、info.xmlファイル内のとしてリストされていること
すべてのファイル名とパス名が、大文字と小文字の区別も含め、ファイルおよびフォルダーの名前と完全に一致していること
すべてのパス名でURLファイルパスの区切り文字(/)が使用されていること。Windowsスタイルのファイルパス区切り文字(\) を使用すると、目次が正しく表示されない可能性があります。たとえば、HTMLヘルプページfirstfx.htmlが、メインのドキュメンテーションフォルダー内の参考页というサブフォルダーにある場合,そのページの< tocitem >目标属性値はrefpages/firstfx.htmlとなります。

`helptoc.xml`のサンプルファイル

次の HTMLファイルを作成したとします。

ツールボックスのロードマップまたは開始ページ、mytoolbox.html。
関数を一覧表示するページ、funclist.html。
3つの関数参照ページ,firstfx.html、secondfx.htmlおよびthirdfx.html。
例、myexample.html。

次のようにして、ファイル名と説明をhelptoc.xmlファイルに含めます。

我的工具箱函数>我的示例

このhelptoc.xmlファイルを適切に書式設定されたinfo.xmlファイルと組み合わせると,ヘルプブラウザーに次のような表示が生成されます。

検索データベースの構築

ドキュメンテーションを検索可能にするには,builddocsearchdbコマンドを使用して検索データベース (検索インデックスとも呼ばれる) を作成します。このコマンドを使用する場合、HTMLファイルを含むフォルダーへの絶対パスを指定します。

たとえば、HTMLファイルがC:\MATLAB\MyToolbox\htmlにあるとします。次のコマンドは,これらのファイル用の検索可能なデータベースを作成します。

builddocsearchdb('C:\MATLAB\MyToolbox\html')

builddocsearchdbは,帮助搜索-v3というC:\MATLAB\MyToolbox\htmlのサブフォルダーを作成します。これにはデータベースファイルが入っています。

ツールボックス内で用語を検索するには,ヘルプブラウザーを開いて,[ドキュメンテーションの検索]フィールドに,検索する用語を入力します。次に,ページの左側の[ソース別に絞り込む]の下で,[補助ソフトウェア]を選択してツールボックスの結果を表示します。

MATLAB R2014bから,検索インデックスを並べて維持できるようになりました。たとえば,MATLAB R2014a以前の検索インデックスが既にある場合,MATLAB R2014bを使用してbuilddocsearchdbをヘルプファイルに対して実行します。これにより,任意のMATLABリリースの実行中に,ヘルプブラウザーはドキュメンテーションデータベースの検索に自動的に適切なインデックスを使用します。

`info.xml`ファイル検証エラーの対処法

XML検証エラーとは

MATLABは検索パス上または現在のフォルダー内でinfo.xmlファイルを見つけると、サポートされているスキーマに対してファイルを自動的に検証します。info.xmlファイルに無効な構成がある場合、MATLABはコマンドウィンドウにエラーを表示します。エラーは一般的に以下の形式になります。

警告：文件未验证。。。

MATLABを開始したとき,あるいはフォルダーを検索パスに追加したときに,info.xmlの検証エラーが発生することがあります。

XMLファイル検証エラーの主な原因は次のとおりです。

info.xmlファイル内のエンティティが欠落しているか順序が違っている。
無関係のinfo.xmlファイルが存在する。
info.xmlファイル内に構文エラーがある。
MATLABがMathWorks製品の古いinfo.xmlファイルにアクセスしようとしている。

`info.xml`内のエンティティの欠落または順序違い

必要な XML要素を指定の順序で並べなかった場合に、XML検証エラーを受け取ります。

通常，错误是由于XML标记的顺序不正确造成的。通过更新info.xml文件内容来纠正错误，以遵循MATLAB帮助文档中的指导方针。

info.xmlファイルに必要な要素とその順序については,info.xmlファイルの作成を参照してください。

無関係の`info.xml`ファイル

カスタムドキュメンテーションとは無関係のinfo.xmlという名前のファイルがあるとします。このinfo.xmlファイルは無関係のファイルであるため,エラーの原因となった場合でも無視してもかまいません。エラーメッセージが再度発行されないようにするには,無関係のinfo.xmlファイルの名前を変更します。または、そのファイルが検索パスまたは現在のフォルダーに無いようにします。

`info.xml`ファイル内の構文エラー

エラーメッセージを使用して問題を特定するか,任意のXMLスキーマ検証ソフトウェアを使用します。info.xmlファイルの構造の詳細については、matlabroot/ sys /命名空间/信息/ v1 / info.xsdにあるスキーマを参照してください。

迈斯沃克製品の古い`info.xml`ファイル

MATLABの別のバージョンのinfo.xmlがある場合は、現在のバージョンでは使用できない構成を含んでいる場合があります。別のバージョンからinfo.xmlファイルを特定するには、エラーメッセージに表示された絶対パス名を調べます。パス名には通常、版本番号が含まれています (…\MATLAB\R14\。。。など)。この場合、エラーは実際には問題を引き起こしていないので、エラーメッセージを無視してもかまいません。エラーが再発しないようにするには、問題となっているinfo.xmlファイルを削除します。あるいは,古いinfo.xmlファイルを検索パスおよび現在のフォルダーから削除します。