Store 
| Products & Services | Solutions | Academia | Support | User Community | Company |
 |
Download Product Updates | | |  |
Get Pricing | | | |
Trial Software |
| Documentation → MATLAB |
| Products & Services | Solutions | Academia | Support | User Community | Company |
|
Download Product Updates | | | |
Get Pricing | | | |
Trial Software |
| Documentation → MATLAB |
| Contents | Index |
| Learn more about MATLAB |
| On this page… |
|---|
A toolbox is a collection of files for use with MathWorks products that a user creates and provides to other users. For toolboxes you create, you can provide HTML help files and demos.
If you want your users to access the help files and demos in the Help browser, add them to the Help browser using special XML files.
You can also provide access to your help files and demos from the Start button
Creating HTML help files for your toolbox allows you to include more than the text information that you can include with M-file help. For example, in HTML help files, you can use figures, illustrations, screen captures, equations, and formatting to make your help more usable.
To create HTML help files, use the MATLAB Editor, another text editor, or an HTML editing tool. If you use the Editor, use syntax highlighting and indenting features for HTML and related files. To customize the syntax highlighting and indenting in the Editor, select File > Preferences > Editor/Debugger > Language, and choose HTML.
To view an HTML help file that you created, use the web function. in MATLAB. For example, display my_help_file.html in the MATLAB Web browser:
web('I:\my_matlab_files\my_help_file.html')To display the file in the Help browser, use the web function with the -helpbrowser option:
web('fullpath/filename.html', '-helpbrowser')Include a link from M-file help for a function to an HTML help file. MATLAB M-file help includes a link to the HTML reference page for the function. To create this link in the M-file help, use a matlabcolon statement (matlab:) with the web statement.
Add HTML help files for your own toolbox to the Help browser so users can access them using the Help browser Contents pane. Optionally, provide a search database for your help files so users can find information in your help files using the Help browser search features.
The Help browser determines what to display using info.xml files on the search path. For the Help browser to display your HTML files in the Help browser:
Create an info.xml file for your toolbox, which includes a pointer to your HTML help files.
Provide the info.xml file to your toolbox users, along with the other help files for the toolbox.
Instruct your toolbox users add the info.xml file to a folder on their search path so they can view the help files in the Help browser.
If you also want to include your toolbox on the Start button, put the Help browser and Start button information into a single info.xml file.
Follow these instructions to add your own HTML help files to the Help browser. Use the example files provided for the SpecSim (Example) Toolbox.
First, follow the procedure using the example files to see how it works. Then customize all the names and content for your files, or repeat the procedure for your files and delete the example files and folders.
Create or choose a folder for storing your help files. You must have write access to the folder. For this example, the folder name is specsim_example.
Add the folder to the search path. For the example, add specsim_example to the search path.
Create your info.xml file:
Copy matlabroot/help/techdoc/matlab_env/examples/helpinfo_specsim.xml to the folder. For the example, copy the file to specsim_example.
Rename helpinfo_specsim.xml to info.xml. In the example, rename helpinfo_specsim.xml in the specsim_example folder to info.xml.
Follow these steps to prepare the Help Contents pane and your HTML files:
In the folder containing your info.xml file, create a subfolder for your help files. For the example, in specsim_example, create specsim_example_helpfiles.
From matlabroot/help/techdoc/matlab_env/examples, copy helptoc_specsim.xml and helpfuncbycat_specsim.xml to the folder for your help files. For the example, copy the files to specsim_example_helpfiles.
In the folder containing your files, rename helptoc_specsim.xml to helptoc.xml, and helpfuncbycat_specsim.xml to helpfuncbycat.xml. In the example, rename the files in specsim_example_helpfiles.
Put your HTML help files in the same folder as your helptoc.xml. For the example, copy specsimicon.gif and the set of specsim_... HTML files from matlabroot/help/techdoc/matlab_env/examples to specsim_example_helpfiles.
In the Editor, open, modify, and save your info.xml, helptoc.xml, and helpfuncbycat.xml files:
In helptoc.xml, change the value in <tocreference target=> from "helpfunctbycat_specsim.xml" to "helpfunctbycat.xml".
Make other changes to helptoc.xml, info.xml, and helpfuncbycat.xml files for your toolbox. For details, see File Descriptions for Adding Your Help Files. For the example, make no other changes.
Select your toolbox in the Help browser product filter so that the Help browser displays it. Use Preferences > Help to access the product filter.
View your HTML help files in the Help browser Contents pane.
Note When navigating among the HTML help files you add, the Help browser Contents might not refresh to synchronize with the page displayed. |
Description of the info.xml File. The info.xml file adds the HTML help files to the Help browser. The table describes the example info.xml file provided for the SpecSim (Example) Toolbox, matlabroot/help/techdoc/matlab_env/examples/helpinfo_specsim.xml.
XML Tag | Description | Value in Example | Notes |
|---|---|---|---|
Not currently used. | |||
Title of toolbox. | The name of your toolbox that appears in the Help browser Contents pane. | ||
Determines the toolbox location in the Help browser Contents. | Allowable values: matlab, toolbox, simulink, blockset, links_targets, other. SpecSim (Example) Toolbox appears with other toolboxes. The entry has the icon for toolboxes, an orange book. | ||
Icon for your toolbox help in the Start button. | If you put your toolbox on the Start button and include a help entry there, specify an image to use for it. In this example, the Start button is not used. | ||
Location of help files | Location of helptoc.xml and HTML help files you provide for your toolbox. Specify the path to help_location relative to the location of the info.xml file. If you provide HTML help files for multiple toolboxes, each help_location must be unique. | ||
<listitem> ... | Entries for Start button | None | If you also want your toolbox to appear in the Start button, add at least one listitem. For details, see Adding Your Own Toolboxes to the Start Button. |
Help Files to Include in <help_location> in the info.xml File. Put these help files into the folder you specified for help_location in the info.xml file.
File Name | Required or Optional | Description |
|---|---|---|
Required | The file that the Help browser displays in the Contents pane. It shows your toolbox at the top level and defines the hierarchical entries within it. It references your HTML help files. A helptoc.xml file provided for the example, helptoc_specsim.xml, illustrates the structure. If you include icons, provide them in a folder within matlabroot/help and specify their path using $help/..., as shown in the example. You can also specify a full path. | |
HTML help files | Required | Help files you created for your toolbox. helptoc.xml references at least one of these files. |
helpfuncbycat.xml helpblockbycat.xml | Optional | Referenced by helptoc.xml, provide a Functions category and Blocks category in the Help browser Content for your toolbox. A file provided for the example, helpfuncbycat_specsim.xml, illustrates the structure. Include this entry only if you provide the necessary files. See Including Function and Block Entries in the Contents Pane. |
helpsearch folder containing files for search database | Optional | Allows the Help browser search to find your pages. Include this entry only if you provide the necessary files. See Making Your Help Files Searchable. |
Including Function and Block Entries in the Contents Pane. To include a Functions and Blocks listing for your toolbox in the Help browser Contents pane:
Create an HTML help file for each function or block in your toolbox. Store them in the same location as the helptoc.xml file for the toolbox. For the example, copy the files matlabroot/help/techdoc/matlab_env/examples/specsim_f1.html through specsim_f3.html to specsim_example_helpfiles.
Create a function summary or block summary HTML file. In the file, provide helpful information, such as category names and functions in the category. You can include links to the function or block documentation like the MATLAB functions by category page does. For the example, copy the file matlabroot/help/techdoc/matlab_env/specsim_function_list.html to specsim_example_helpfiles.
Include a helpfuncbycat.xml, helpblockbycat.xml, or both in the same location as your helptoc.xml file. For the example, copy matlabroot/help/techdoc/matlab_env/examples/helpfuncbycat_specsim.xml to specsim_example_helpfiles.
In helptoc.xml for the toolbox, include a tocreference entry for functions, blocks, or both:
<tocreference target="helpfuncbycat.xml"></tocreference> <tocreference target="helpblockbycat.xml"></tocreference>
See this entry in the example file, helptoc_specsim.xml.
More Examples of info.xml Files. For additional examples, see the info.xml files for MathWorks products:
Select Start > Desktop Tools > View Start Button Configuration Files files.
From the resulting Start Button Configuration Files dialog box, select a product.
Click Open to view the info.xml file.
Note The info.xml files for MathWorks products contain some custom constructs. You might not be able to implement everything you see in info.xml files from The MathWorks. |
The builddocsearchdb function creates a searchable database that the Help browser search requires to find your help files. Build the database after creating the info.xml file for your toolbox, and after storing your HTML help files in the help_location specified in the info.xml file. This example uses the info.xml file for the SpecSim (Example) toolbox with the help_location specified as I:\my_matlab_files\specsim_example_helpfiles.
Add the folder containing your info.xml file to the search path.
For the example, add I:\my_matlab_files\specsim_example\specsim_example_helpfiles to the path.
Create a searchable database by running builddocsearchdb('full_path to_help_location'). For the example, run:
builddocsearchdb ('I:\my_matlab_files\specsim_example\specsim_example_helpfiles')Running builddocsearchdb creates a folder named helpsearch in the help_location folder. For the example, it creates I:\my_matlab_files\specsim_example_helpfiles\helpsearch.
The function also creates three files in helpsearch. It creates the deletable and segments file names each time you run builddocsearchdb. The name of the third file it creates varies, but always has the cfs extension.
Test the search features for your files.
Set the product filter to only your toolbox. To access the product filter, select File > Preferences > Help.
Use the search field in the Help browser to search for any words in the HTML help files that you provided in the help_location folder. This example shows a search of SpecSim (Example) HTML help files for the term specsim gui.
You can provide demos and related files of any file type for your toolbox.
One way to produce demos is with the cell-publishing feature, available in the Editor. It creates a demo file to run in MATLAB and an HTML file that describes how the demo works. For more information, see Overview of Publishing M-Files.
Add demos for your own toolbox to the Help browser so users can access them using the Help browser Contents pane. The Help browser determines the demos to display using demos.xml files on the search path. For the Help browser to display your demos in the Help browser:
Create a demos.xml file for your toolbox, which includes pointers to your demo files.
Provide the demos.xml file to your toolbox users, along with the demos files for your toolbox.
Instruct your toolbox users to add the demos.xml file to a folder on their MATLAB search path. Then, they can access your demos from the Help browser Contents pane.
Follow these instructions to add your own demos files to the Help browser. Example files are provided for the SpecSim (Example) Toolbox.
Create or choose a folder for storing your demos files. You must have write access to the folder. For this example, the folder name is I:/my_matlab_files/specsim_demo
Add the folder for your demos files to the search path. The folder cannot be the current folder when you add it to the path.
Get an example demos.xml file to use as the basis for your own file. Copy matlabroot/help/techdoc/matlab_env/examples/demos_specsim.xml to the folder for your demos files. For the example, copy it to I:/my_matlab_files/specsim_demo.
Rename the copy of the file to demos.xml. For the example, rename the demos_specsim.xml file in I:/my_matlab_files/specsim_demo to demos.xml.
View the example demos.xml file in the Help browser. A new node, Other Demos, appears at the end of the Help browser Contents pane. Expand it to view the entry just added, SpecSim (Example) Toolbox.
In the Editor, open the demos.xml file. For the example, open I:/my_matlab_files/specsim_demo/demos.xml.
Change the demos.xml file to include the information for your toolbox, and save the changes.
For details, see File Description for demos.xml.
Refresh the Help browser to see your demos in Other Demos. Remove the folder containing the demos.xml file from the search path, and then add it to the search path. For the example, remove I:/my_matlab_files/specsim_demo from the search path, and then add I:/my_matlab_files/specsim_demo to the search path.
Note The product filter does not provide an entry for Other Demos and the toolbox demos you add. The Help browser always shows them. |
File Description for demos.xml. Within the demos.xml file, the root tag is <demos> and it includes one <name>, <type>, <icon> and <description> for your toolbox demos.
Include a <demoitem> for each demo you provide. Or, to provide categories of demos, include a <demosection> for each category, which contains <demoitem> entries. If you use any categories, then all demos must be in categories. In other words, if there is even one <demosection>, then all demoitem tags must be within demosection tags.
When MATLAB finds an info.xml file on the search path or in the current folder, it tries to add information to the Help browser or Start button. MATLAB 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:
XML-file failed validation against schema located in ... XML-file name: full path to...\info.xml
An info.xml validation error can occur when you start MATLAB, press the Start button, or under certain other circumstances.
See these causes of the XML file validation error and what to do:
If you have an info.xml file from a different version of MATLAB, it 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\... . The error is not actually causing any problems and you can safely ignore it. To ensure that the error does not occur, remove the offending info.xml file, or ensure that it is not on the search path or in the current folder.
If the info.xml is an unrelated file, and not intended to add information to the Start button or Help browser, the validation error is irrelevant. In this case, the error is not actually causing any problems and you can safely ignore it. To ensure that the error does not occur, rename the offending info.xml file, or ensure that it is not on the search path or in the current folder.
If the purpose of the info.xml file is to add information to the Start button or Help browser, 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.
 | Providing Your Own Help and Demos | Additional Resources |  |
Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.
| © 1984-2009- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
