Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

显示自定义文档

概述

如果您创建一个使用 MathWorks® 产品的工具箱(即使它只包含一些函数),则可以包含 HTML 帮助文件格式的自定义文档。您的工具箱的自定义文档可以包括图窗、图表、屏幕捕获、方程和格式设置,以使您的工具箱帮助更实用。

要正常显示,您的自定义文档必须包含以下文件:

  • HTML 帮助文件 - 这些文件包含您的自定义文档信息。

  • info.xml 文件 - 此文件使 MATLAB® 能够查找并标识您的 HTML 帮助文件。

  • helptoc.xml 文件 - 此文件包含您的文档的目录,该目录显示在帮助浏览器的目录窗格中。此文件必须存储在包含您的 HTML 帮助文件的文件夹中。

  • 搜索数据库(可选)- 这些文件用于在您的 HTML 帮助文件中进行搜索。

要查看您的自定义文档,请打开帮助浏览器并导航到主页。在主页底部的补充软件下面,点击您的工具箱的名称。您的帮助将在当前窗口中打开。

创建 HTML 帮助文件

您可以在任何文本编辑器或 Web 发布软件中创建 HTML 帮助文件。要在 MATLAB 中创建帮助文件,请使用以下两种方法之一:

将工具箱的所有 HTML 帮助文件和任何其他自定义文档文件(如 PNG 和 CSS 文件)存储在一个文件夹中,如工具箱文件夹中的一个 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 仍然需要使用 <icon> 元素来解析 info.xml 文件。
<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 文件中包括注释,例如版权和联系信息。通过将某行上的文本放在 <!----> 之间来创建注释。

当您创建 info.xml 文件时,请确保:

  • 包括所有必需元素。

  • 这些条目的排列顺序与上表相同。

  • XML 中的文件和文件夹名称与您的文件和文件夹的名称完全匹配并使用完全相同的大小写。

  • info.xml 文件所在的文件夹位于 MATLAB 搜索路径上。

    注意

    MATLAB 解析 info.xml 文件并在您向该路径中添加包含 info.xml 的文件夹时显示您的文档。如果您在已位于该路径上的文件夹中创建了 info.xml 文件,请从该路径中删除该文件夹。然后重新添加该文件夹,以便 MATLAB 解析该文件。确保您要添加的文件夹是您的当前文件夹。

创建 helptoc.xml 文件

helptoc.xml 文件用于定义补充软件浏览器的目录窗格中显示的帮助文件层次结构。

您可以使用 MATLAB 文档随附的模板来创建 helptoc.xml 文件。要在当前文件夹中创建并编辑模板文件 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

  • 三个函数参考页:firstfx.htmlsecondfx.htmlthirdfx.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 会在 C:\MATLAB\MyToolbox\html 中创建一个名为 helpsearch-v4 的子文件夹,其中包含数据库文件。

要搜索工具箱中的术语,请打开帮助浏览器,并在搜索文档字段中,输入要搜索的术语。然后,在页的左侧,在按来源细分下,选择补充软件以查看工具箱的结果。

从 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 文件过时

如果您的 info.xml 文件来自不同版本的 MATLAB,该文件中包含的构造可能对您的版本无效。要识别来自另一版本的 info.xml 文件,请查看错误消息中报告的完整路径名。该路径通常包含版本号,例如 ...\MATLAB\R14\...。在本例中,该错误实际上不会产生任何问题,因此您完全可以忽略该错误消息。为确保错误不反复出现,请删除产生问题的 info.xml 文件。或者,从搜索路径和当前文件夹中删除已过时的 info.xml 文件。

另请参阅

相关主题