Main Content

このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

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

概要

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

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

  • HTML ヘルプ ファイル — これらのファイルには、カスタム ドキュメンテーションの情報が含まれます。

  • info.xml ファイル — このファイルを使用して、MATLAB® が HTML ヘルプ ファイルを検索して特定できます。

  • helptoc.xml ファイル — このファイルには、ヘルプ ブラウザーの [コンテンツ] ペインに表示されるドキュメンテーションの目次が含まれます。このファイルは、HTML ヘルプ ファイルを含むフォルダーに保存されていなければなりません。

  • 検索データベース (オプション) — これらのファイルを使用すると、HTML ヘルプ ファイル内の検索が可能になります。

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

HTML ヘルプ ファイルの作成

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

ツールボックス用のすべての 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>
また、MATLAB ドキュメンテーションに含まれているテンプレート 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入力値は、matlabtoolboxsimulinkblocksetlinks_targetsother です。
<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.htmlsecondfx.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 ファイルを検索パスおよび現在のフォルダーから削除します。

参考

関連するトピック