If you create a toolbox that works with MathWorks® products, even if it only contains a few functions, you can include custom documentation in the form of HTML help files. Custom documentation for your toolbox can include figures, diagrams, screen captures, equations, and formatting to make your toolbox help more usable.
To display properly, your custom documentation must contain these files:
HTML help files — These files contain your custom documentation information.
info.xml file —
This file enables MATLAB® to find and identify your HTML help
helptoc.xml file —
This file contain the Table of Contents for your documentation that
displays in the Contents pane of the Help browser.
This file must be stored in the folder that contains your HTML help
Search database (optional) — These files enable searching in your HTML help files.
To view your custom documentation, open the Help browser and navigate to the home page. At the bottom right of the home page, under Supplemental Software, click the name of your toolbox. Your help opens in the current window.
You can create HTML help files in any text editor or web publishing software. To create help files in MATLAB, use either of these two methods:
Store all your HTML help files in one folder, such as an
in your toolbox folder. This folder must be:
On the MATLAB search path
Outside any installed hardware support package help 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
info.xml file describes your custom documentation,
including the name to display for your documentation. It also identifies
where to find your HTML help files and the
Create a file named
info.xml for each toolbox you
info.xml to describe your toolbox,
you can adapt this template:
<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.xmlby using the template
info_template.xmlincluded with the MATLAB documentation. To create and edit a copy of the template file in your current folder, run this code in the command window:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',... 'examples','templates','info_template.xml'),pwd) fileattrib('info_template.xml','+w') edit('info_template.xml')
The following table describes the required elements of the
|XML Tag||Description||Value in Template||Notes|
|Release of MATLAB||Indicates when you added help files. Not displayed in the browser.|
|Title of toolbox||The name to display for your custom documentation in the browser Contents pane.|
|Label for the toolbox||Allowable values: |
|Icon for the Start button (not used)||none||No longer used, but the |
|Location of help files||Name of the subfolder containing |
|Icon to display in Contents pane||none||Ignored in MATLAB R2015a and later. Does not cause error
if it appears in the |
You also can include comments in your
such as copyright and contact information. Create comments by enclosing
the text on a line between
When you create the
info.xml file, make sure
You include all required elements.
The entries are in the same order as in the preceding table.
File and folder names in the XML exactly match the names of your files and folders and are capitalized identically.
info.xml file is in a folder
on the MATLAB search path.
MATLAB parses the
info.xml file and
displays your documentation when you add the folder that contains
the path. If you created an
info.xml file in a
folder already on the path, remove the folder from the path. Then
add the folder again, so that MATLAB parses the file. Make sure
that the folder you are adding is not your current
helptoc.xml file defines the hierarchy
of help files displayed in the Contents pane
of the Supplemental Software browser.
You can create a
helptoc.xml file by using
the template included with the MATLAB documentation. To create
and edit a copy of the template file
your current folder, run this code in the Command Window:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',... 'examples','templates','helptoc_template.xml'),pwd) fileattrib('helptoc_template.xml','+w') edit('helptoc_template.xml')
helptoc.xml file in the folder
that contains your HTML documentation files. This folder must be referenced
<help_location> in your
<tocitem> entry in the
references one of your HTML help files. The first
helptoc.xml file serves as the initial landing
page for your documentation.
Within the top-level
<tocitem> elements define the
structure of your table of contents. Each
target attribute that provides the file name.
File and path names are case-sensitive.
When you create the
helptoc.xml file, make
The location of the
is listed as the
<help_location> in your
All file and path names exactly match the names of the files and folders, including capitalization.
All path names use URL file path separators (/). Windows
style file path separators (
\) can cause the table
of contents to display incorrectly. For example, if you have an HTML
firstfx.html located in a subfolder called
the main documentation folder, the
value for that page would be
Suppose that you have created the following HTML files:
A roadmap or starting page for your toolbox,
A page that lists your functions,
Three function reference pages:
Include file names and descriptions in a
<?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 file, paired with a properly
info.xml file, produced this display
in the Help browser.
To make your documentation searchable, create a search database,
also referred to as a search index, using the
When using this command, specify the complete path to the folder that
contains your HTML files.
For example, suppose that your HTML files are in
This command creates a searchable database for those files:
builddocsearchdb creates a subfolder of
which contains the database files.
You can search for terms in your toolbox from the Search Documentation field in the Help browser.
Beginning with MATLAB R2014b, you can maintain search indexes
side by side. For instance, if you already have a search index for MATLAB R2014a
or earlier, run
builddocsearchdb against your
help files using MATLAB R2014b. Then, when you run any MATLAB release,
the help browser automatically uses the appropriate index for searching
your documentation database.
When MATLAB finds an
on the search path or in the current folder, it automatically validates
the file against the supported schema. If there is an invalid construct
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. ...
info.xml validation error can occur when
you start MATLAB or add folders to the search path.
The primary causes of an XML file validation error are:
Entities are missing or out of order in the
info.xml file exists.
Syntax errors in the
MATLAB is trying to access an outdated
for a MathWorks product.
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.
info.xmlfile and their required ordering, see Create info.xml File.
Suppose that you have a file named
has nothing to do with custom documentation. Because this
is an unrelated file, if it causes an error, you can safely ignore
it. To prevent the error message from reoccurring, rename the unrelated
Alternatively, ensure that the file is not on the search path or in
the current folder.
Use the error message to isolate the problem or use any XML
schema validator. For more information about the structure of the
consult its schema at
info.xmlFile for a MathWorks Product
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
from another version, look at the full path names reported in the
error message. The path usually includes a version number, for example,
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
Alternatively, remove the outdated
from the search path and out of the current folder.