|On this page…|
If you create a toolbox that works with MathWorks® products—even if it only contains a few functions—you can include with it HTML documentation files. Providing HTML files for your toolbox allows you to include figures, diagrams, screen captures, equations, and formatting to make your toolbox help more usable.
To display custom documentation:
Create HTML help files. Store these files in a common folder, such as an html subfolder relative to your primary program files. This folder must be on the MATLAB® search path, but outside the matlabroot folder.
Documentation sets often contain:
A roadmap page (that is, an initial landing page for the documentation)
Examples and topics that explain how to use the toolbox
Function or block reference pages
You can create HTML files in any text editor or Web publishing software. MATLAB includes functionality to convert .m files to formatted HTML files. For more information, see Publishing MATLAB Code.
Create an info.xml file, which enables MATLAB to find and identify your documentation files.
Create a helptoc.xml file, which creates a Table of Contents for your documentation to display in the Contents pane of the Supplemental Software browser. Store this file in the folder that contains your HTML files.
Optionally, create a search database for your HTML help files using the builddocsearchdb function.
View your documentation.
In the Help browser, navigate to the home page.
At the bottom of the home page, click Supplemental Software.
The Supplemental Software browser opens in a new window.
The info.xml file specifies the name and icon to display for your documentation set. It also identifies where to find your HTML help files and the helptoc.xml file. You must create a file named info.xml for each toolbox you document.
The following listing is a template for info.xml that you can adapt to describe your toolbox:
<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="optional"> <?xml-stylesheet type="text/xsl"href="optional"?> <matlabrelease>2012b</matlabrelease> <name>MyToolbox</name> <type>toolbox</type> <icon></icon> <help_location>html</help_location> <help_contents_icon>$toolbox/matlab/icons/bookicon.gif</help_contents_icon> </productinfo>
The following table describes required elements of the info.xml file.
|XML Tag||Description||Value in Template||Notes|
|<matlabrelease>||Release of MATLAB||R2012b||Not displayed in the browser, but indicates when you added help files.|
|<name>||Title of toolbox||MyToolbox||The name of your toolbox that appears in the browser Contents pane.|
|<type>||Label for the toolbox||toolbox||Allowable values: matlab, toolbox, simulink, blockset, links_targets, other.|
|<icon>||Icon for the Start button (obsolete)||No longer used, but the <icon> element is required to parse the info.xml file.|
|<help_location>||Location of help files||html||Name of subfolder containing helptoc.xml and HTML help files you provide for your toolbox. If not a subfolder, specify the path to help_location relative to the info.xml file. If you provide HTML help files for multiple toolboxes, each help_location must be a different folder.|
|<help_contents_icon>||Icon to display in Contents pane||$toolbox/matlab/|
When you define the info.xml file, make sure that:
You include all required elements.
The entries are in the same order as in the preceding list.
File and folder names in the XML exactly match the names of your files and folders and use upper and lower case letters identically.
The info.xml file is in a folder on the MATLAB search path.
Note: MATLAB parses the info.xml file and displays your documentation when you add the folder that contains info.xml to the path. If you created an info.xml file in a folder already on the path, remove the folder from the path and then add it again, so that MATLAB parses the file. Make sure that the folder you are adding is not your current folder.
You can include comments in your info.xml file, such as copyright and contact information. Create comments by enclosing the text on a line with between <!-- and --> markup.
The helptoc.xml file defines a hierarchy of entries within the Contents pane of the Supplemental Software browser. Each <tocitem> entry in the helptoc.xml file references one of your HTML help files.
Place the helptoc.xml file in the folder that contains your HTML documentation files. This folder is designated as <help_location> in your info.xml file.
For example, suppose you have created the following HTML files:
A roadmap or starting page for your toolbox, mytoolbox.html.
A page that lists your functions, funclist.html.
Three function reference pages: firstfx.html, secondfx.html, and thirdfx.html.
An example, myexample.html.
Include file names and descriptions in a helptoc.xml file as follows:
<?xml version='1.0' encoding="utf-8"?> <toc version="2.0"> <tocitem target="mytoolbox.html">My Toolbox <tocitem target="funclist.html" image="HelpIcon.FUNCTION">Functions <tocitem target="firstfx.html">first</tocitem> <tocitem target="secondfx.html">second</tocitem> <tocitem target="thirdfx.html">third</tocitem> </tocitem> <tocitem target="myexample.html" image="HelpIcon.EXAMPLES">My Example </tocitem> </tocitem> </toc>
Within the top-level <toc> element, the nested <tocitem> elements define the structure of your table of contents. Each <tocitem> element has a target attribute that provides the file name. <tocitem> elements also can include an image attribute to specify icons. Be sure that file and path names exactly match those of the files and folders, including upper- and lower-case letters.
The elements in the previous helptoc.xml and info.xml files correspond to the following display in the browser.
If your HTML pages include anchor elements, you can refer to an anchor in the target attribute of a <tocitem> element. In HTML files, anchors are of the form <a name="anchorid">Any content</a>. In the helptoc.xml file, you can create a link to that anchor using a pound sign (#), such as
<tocitem target="mypage.html#anchorid">Descripive text</tocitem>
You can display icons for your Contents pane entries within your toolbox. To use standard MathWorks icons, include any of the following icons as image attributes for <tocitem> elements.
|Icon||Use For||Image Tag String|
|Getting Started Guides||HelpIcon.GETTING_STARTED|
Include the icons as image attributes in top-level TOC entries. If you provide a roadmap page, also include icons for second-level TOC entries under the roadmap.
A complete template for helptoc.xml files that includes <tocitem> elements for all standard content types, such as Getting Started, User Guide, and Release Notes, is located in an examples folder included with the MATLAB documentation. To copy the template file, helptoc_template.xml, to your current folder and edit the copy, click hereclick here or run the following code:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', ... 'examples','templates','helptoc_template.xml'),pwd), ... fileattrib('helptoc_template.xml','+w') edit('helptoc_template.xml')
To support searches of your documentation, create a search database using the builddocsearchdb function. When using this function, specify the complete path to the folder that contains your HTML files.
For example, suppose your HTML files are in C:\MATLAB\MyToolbox\html. This command creates a searchable database:
builddocsearchdb creates a subfolder of C:\MATLAB\MyToolbox\html named helpsearch, which contains three files:
A file called deletable.
A file called segments.
A file having a cfs extension with a name that varies.
You can search for terms in your toolbox from the search bar of the Supplemental Software browser.
When MATLAB finds an info.xml file on the search path or in the current folder, it automatically validates the file against the supported schema. If there is an invalid construct in the info.xml file, MATLAB displays an error in the Command Window. The error is typically of the form:
Warning: File <yourxmlfile.xml> did not validate. ...
An info.xml validation error can occur when you start MATLAB or add folders to the search path.
The following sections describe the primary causes of an XML file validation error and information to address them.
If you do not list required XML elements in the prescribed order, you receive an XML validation error:
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.
For a description of the elements you need in an info.xml file and their required ordering, see Identify Your Documentation (info.xml).
Suppose you have a file named info.xml that has nothing to do with custom documentation. Because this info.xml file is an unrelated file, if the file causes an error, the validation error is irrelevant. In this case, the error is not actually causing any problems, so you can safely ignore it. To prevent the error message from reoccurring, rename the offending info.xml file, or ensure that the file is not on the search path or in the current folder.
If the purpose of the info.xml file is to display custom documentation, correct the reported problem. Use the message in the error to isolate the problem or use any validator. One validator you can use is from the W3C® at http://www.w3.org/2001/03/webdata/xsv. For more information about the structure of the info.xml file, consult its schema, located at matlabroot/sys/namespace/info/v1/info.xsd.
If you have an info.xml file from a different version of MATLAB, that file could contain constructs that are not valid with your version. To identify an info.xml file from another version, look at the full path names reported in the error message. The path usually includes a version number, for example, ...\MATLAB\R14\.... In this situation, the error is not actually causing any problems, so you can safely ignore the error message. To ensure that the error does not reoccur, remove the offending info.xml file, or ensure that the file is not on the search path or in the current folder.