このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。
カスタム ドキュメンテーションの表示
概要
MathWorks® 製品で機能するツールボックスを作成する場合、それが数個の関数を含むだけであっても、カスタム ドキュメンテーションを HTML ヘルプ ファイルの形式で含めることが可能です。ツールボックスのカスタム ドキュメンテーションには、ツールボックスのヘルプをさらに使いやすくするために、図、スクリーン キャプチャ、方程式、書式設定などを含めることができます。
適切に表示するには、カスタム ドキュメンテーションに以下のファイルが含まれていなければなりません。
HTML ヘルプ ファイル — これらのファイルには、カスタム ドキュメンテーションの情報が含まれます。
info.xml
ファイル — このファイルを使用して、MATLAB® が HTML ヘルプ ファイルを検索して特定できます。helptoc.xml
ファイル — このファイルには、ヘルプ ブラウザーの [コンテンツ] ペインに表示されるドキュメンテーションの目次が含まれます。このファイルは、HTML ヘルプ ファイルを含むフォルダーに保存されていなければなりません。検索データベース (オプション) — これらのファイルを使用すると、HTML ヘルプ ファイル内の検索が可能になります。
カスタム ドキュメンテーションを表示するには、ヘルプ ブラウザーを開いてホーム ページに移動します。ホーム ページの下部にある [補助ソフトウェア] で、ツールボックスの名前をクリックします。ヘルプが現在のウィンドウに表示されます。
HTML ヘルプ ファイルの作成
HTML ヘルプ ファイルは、任意のテキスト エディターまたは Web パブリッシュ ソフトウェアで作成できます。MATLAB でヘルプ ファイルを作成するには、次の 2 つのうちいずれかの方法を使用します。
ライブ スクリプト (
*.mlx
) を作成して HTML にエクスポートします。詳細については、ライブ スクリプトと関数を共有およびエクスポートする方法を参照してください。スクリプト (
*.m
) を作成して HTML にパブリッシュします。詳細は、MATLAB コードのパブリッシュと共有を参照してください。
ツールボックス用のすべての HTML ヘルプ ファイルおよび追加のカスタム ドキュメンテーション ファイル (PNG ファイルや CSS ファイルなど) を 1 つのフォルダー、たとえばツールボックス フォルダー内の html
サブフォルダーに格納します。このフォルダーは次の場所になければなりません。
MATLAB 検索パス上
フォルダーの外matlabroot
インストールされているハードウェア サポート パッケージのヘルプ フォルダーの外
ドキュメンテーション セットには、一般的には以下のものが含まれます。
ロードマップ ページ (ドキュメンテーションを開いたときに最初に表示されるページ)
ツールボックスの使用方法を説明する例とトピック
関数やブロックのリファレンス ページ
info.xml
ファイルの作成
info.xml
ファイルには、ドキュメンテーションの表示名など、カスタム ドキュメンテーションの説明が含まれています。HTML ヘルプ ファイルと helptoc.xml
ファイルの格納場所も特定します。記述するツールボックスごとに info.xml
というファイルを作成します。
ツールボックスについて説明する info.xml
を作成するには、以下のテンプレートを利用できます。
<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="optional"> <?xml-stylesheet type="text/xsl"href="optional"?> <matlabrelease>R2016b</matlabrelease> <name>MyToolbox</name> <type>toolbox</type> <icon></icon> <help_location>html</help_location> </productinfo>
info_template.xml
を使用して info.xml
を作成することもできます。現在のフォルダー内でテンプレート ファイルのコピーを作成して編集するには、コマンド ウィンドウで以下のコードを実行します。copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',... 'examples','templates','info_template.xml'),pwd) fileattrib('info_template.xml','+w') edit('info_template.xml')
次の表では、info.xml
ファイルの必須要素について説明します。
XML タグ | 説明 | テンプレートの値 | メモ |
---|---|---|---|
<matlabrelease> | MATLAB のリリース | R2016b | ヘルプ ファイルをいつ追加したかを示します。ブラウザーには表示されません。 |
<name> | ツールボックスのタイトル | MyToolbox | ブラウザーの [コンテンツ] ペインに表示されるカスタム ドキュメンテーションの名前。 |
<type> | ツールボックス用のラベル | toolbox | 入力値は、matlab 、toolbox 、simulink 、blockset 、links_targets 、other です。 |
<icon> | [スタート] ボタンのアイコン (使用廃止) | なし | 現在は使用されていませんが、MATLAB で info.xml ファイルを解析するには <icon> 要素が引き続き必要です。 |
<help_location> | ヘルプ ファイルの位置 | html | ツールボックス用の helptoc.xml 、HTML ヘルプ ファイルおよびその他のカスタム ドキュメンテーション ファイル (PNG ファイルや CSS ファイルなど) を含むサブフォルダーの名前。ヘルプの位置が info.xml ファイルの場所のサブフォルダーでない場合、info.xml ファイルを基準とした help_location の相対パスを指定します。複数のツールボックスの HTML ヘルプ ファイルを提供する場合、各 info.xml 内の help_location が別々のフォルダーでなければなりません。 |
<help_contents_icon> | [コンテンツ] ペインに表示するアイコン | なし | 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
のコピーを作成して編集するには、コマンド ウィンドウで以下のコードを実行します。
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',... 'examples','templates','helptoc_template.xml'),pwd) fileattrib('helptoc_template.xml','+w') edit('helptoc_template.xml')
helptoc.xml
ファイルを、HTML ドキュメンテーション ファイルが含まれているフォルダーに入れます。このフォルダーは、info.xml
ファイル内で <help_location>
として参照されなければなりません。
helptoc.xml
ファイルの各 <tocitem>
エントリは、HTML ヘルプ ファイルのいずれかを参照します。helptoc.xml
ファイル内の最初の <tocitem>
エントリは、ドキュメンテーションのランディング ページとして機能します。
最上位の <toc>
要素内で、入れ子になった <tocitem>
要素で目次の構造を定義します。各 <tocitem>
要素にはファイル名を示す target
属性があります。ファイル名とパス名では大文字と小文字が区別されます。
helptoc.xml
ファイルを作成する際は、次を確認する必要があります。
helptoc.xml
ファイルの位置が、info.xml
ファイル内の<help_location>
としてリストされていることすべてのファイル名とパス名が、大文字と小文字の区別も含め、ファイルおよびフォルダーの名前と完全に一致していること
すべてのパス名で URL ファイル パスの区切り文字 (/) が使用されていること。Windows スタイルのファイル パス区切り文字 (
\
) を使用すると、目次が正しく表示されない可能性があります。たとえば、HTML ヘルプ ページfirstfx.html
が、メインのドキュメンテーション フォルダー内のrefpages
というサブフォルダーにある場合、そのページの<tocitem>
target
属性値はrefpages/firstfx.html
となります。
helptoc.xml
のサンプル ファイル
次の HTML ファイルを作成したとします。
ツールボックスのロードマップまたは開始ページ、
mytoolbox.html
。関数を一覧表示するページ、
funclist.html
。3 つの関数参照ページ、
firstfx.html
、secondfx.html
およびthirdfx.html
。例、
myexample.html
。
次のようにして、ファイル名と説明を helptoc.xml
ファイルに含めます。
<?xml version='1.0' encoding="utf-8"?> <toc version="2.0"> <tocitem target="mytoolbox.html">My Toolbox <tocitem target="funclist.html">Functions <tocitem target="firstfx.html">first</tocitem> <tocitem target="secondfx.html">second</tocitem> <tocitem target="thirdfx.html">third</tocitem> </tocitem> <tocitem target="myexample.html">My Example </tocitem> </tocitem> </toc>
この helptoc.xml
ファイルを適切に書式設定された info.xml
ファイルと組み合わせると、ヘルプ ブラウザーに次のような表示が生成されます。
検索データベースの構築
ドキュメンテーションを検索可能にするには、関数 builddocsearchdb
を使用して検索データベース (検索インデックスとも呼ばれる) を作成します。この関数を使用する場合、HTML ファイルを含むフォルダーへの絶対パスを指定します。
たとえば、HTML ファイルが C:\MATLAB\MyToolbox\html
にあるとします。次のコマンドは、これらのファイル用の検索可能なデータベースを作成します。
builddocsearchdb('C:\MATLAB\MyToolbox\html')
builddocsearchdb
は、helpsearch-v4
という C:\MATLAB\MyToolbox\html
のサブフォルダーを作成します。これにはデータベース ファイルが入っています。
ツールボックス内で用語を検索するには、ヘルプ ブラウザーを開いて、[ドキュメンテーションの検索] フィールドに、検索する用語を入力します。次に、ページの左側の [ソース別に絞り込む] の下で、[補助ソフトウェア] を選択してツールボックスの結果を表示します。
MATLAB R2014b から、検索インデックスを共存させて維持できるようになりました。特定のリリースでカスタム ツールボックスのドキュメンテーションを確実に検索可能にするには、そのリリースの MATLAB を使用して builddocsearchdb
をヘルプ ファイルに対して実行します。R2021b 以前のリリースを使用して builddocsearchdb
を実行すると、builddocsearchdb
は検索データベース ファイルを含むサブフォルダー helpsearch-v3
を作成します。helpsearch-v4
サブフォルダーと helpsearch-v3
サブフォルダーの両方を共存させて維持します。これにより、任意の MATLAB リリースの実行中に、ヘルプ ブラウザーはドキュメンテーションの検索に自動的に適切なデータベースを使用します。
info.xml
ファイル検証エラーの対処法
XML 検証エラーとは
MATLAB は検索パス上または現在のフォルダー内で info.xml
ファイルを見つけると、サポートされているスキーマに対してファイルを自動的に検証します。info.xml
ファイルに無効な構成がある場合、MATLAB はコマンド ウィンドウにエラーを表示します。エラーは一般的に以下の形式になります。
Warning: File <yourxmlfile.xml> did not validate. ...
MATLAB を開始したとき、あるいはフォルダーを検索パスに追加したときに、info.xml
の検証エラーが発生することがあります。
XML ファイル検証エラーの主な原因は次のとおりです。
info.xml
ファイル内のエンティティが欠落しているか順序が違っている。無関係の
info.xml
ファイルが存在する。info.xml
ファイル内に構文エラーがある。MATLAB が MathWorks 製品の古い
info.xml
ファイルにアクセスしようとしている。
info.xml
内のエンティティの欠落または順序違い
必要な XML 要素を指定の順序で並べなかった場合に、XML 検証エラーを受け取ります。
Often, errors result from incorrect ordering of XML tags. Correct the error by updating the info.xml file contents to follow the guidelines in the MATLAB help documentation.
info.xml
ファイルに必要な要素とその順序については、info.xml ファイルの作成を参照してください。無関係の info.xml
ファイル
カスタム ドキュメンテーションとは無関係の info.xml
という名前のファイルがあるとします。この info.xml
ファイルは無関係のファイルであるため、エラーの原因となった場合でも無視してもかまいません。エラー メッセージが再度発行されないようにするには、無関係の info.xml
ファイルの名前を変更します。または、そのファイルが検索パスまたは現在のフォルダーに無いようにします。
info.xml
ファイル内の構文エラー
エラー メッセージを使用して問題を特定するか、任意の XML スキーマ検証ソフトウェアを使用します。info.xml
ファイルの構造の詳細については、matlabroot
/sys/namespace/info/v1/info.xsd
にあるスキーマを参照してください。
MathWorks 製品の古い info.xml
ファイル
MATLAB の別のバージョンの info.xml
がある場合は、現在のバージョンでは使用できない構成を含んでいる場合があります。別のバージョンから info.xml
ファイルを特定するには、エラー メッセージに表示された絶対パス名を調べます。パス名には通常、version 番号が含まれています (...\MATLAB\R14\...
など)。この場合、エラーは実際には問題を引き起こしていないので、エラー メッセージを無視してもかまいません。エラーが再発しないようにするには、問題となっている info.xml
ファイルを削除します。あるいは、古い info.xml
ファイルを検索パスおよび現在のフォルダーから削除します。